2.2.3.6.1.11 Select System Query Option ($select)

  • Article

Applies to the OData 2.0 and OData 3.0 protocols

A data service URI with a $select system query option identifies the same set of entities as a URI without a $select query option; however, the presence of a $select query option specifies that a response from the data service SHOULD return a subset, as identified by the value of the $select query option, of the properties that would have been returned had the URI not included a $select query option. A data service MAY return properties of the resources identified by the request URI beyond those identified by the $select query option.

The following rules supplement the following grammar that represents the syntax of this system query option. The select system query option is supported only in the OData 2.0 and OData 3.0 protocols.

 selectQueryOp  = "$select=" selectClause
 selectClause   = [WSP] selectItem [[WSP] "," selectClause] [WSP]
 selectItem     = star / ["/"namespaceQualifiedEntityType](selectedProperty / selectedNamedStream /  selectedAction / selectedFunction / (selectedNavProperty ["/" selectItem]))
 selectedProperty = entityProperty / entityComplexProperty 
 selectedNamedStream = entityNamedStream
  
 selectedAction = allActions / individualAction
 individualAction = ecQualifiedActionName ; section 2.2.1.3.1.
 allActions = entityContainer ".*" ; section 2.2.1.3.1
  
 selectedFunctions = allFunctions / individualFunction
 individualFunction = ecQualifiedFunctionName; section 2.2.1.4.1.
 allFunctions = functions ".*"
  
 selectedNavProperty = entityNavProperty-es / entityNavProperty-et 
 star           = "*"

  • The left most selectedProperty, selectedNamedStream, or selectedNavProperty in a selectClause MUST be a star or represent a member that is defined in the EntityType, or a subtype thereof, that is identified by the resource path section of the URI.

  • A subsequent selectedProperty or selectedNavProperty in the same selectClause MUST represent a property defined on the EntityType, or a subtype thereof, that is represented by the prior navigation property in the selectClause.

  • For AtomPub formatted responses: The value of a selectQueryOp applies only to the properties returned within the m:properties element as specified in section 2.2.6.2.2. For example, if a property of an entity type is mapped with the attribute KeepInContent=false, according to Customizable Feeds (section 2.2.6.2.2.1), to an element or attribute in the response, then that property MUST always be included in the response according to its customizable feed mapping.

  • For JSON formatted responses: See [ODataJSON4.0] section 6.

  • For Verbose JSON formatted responses: The value of a selectQueryOp applies only to the name/value pairs with a name that does not begin with two consecutive underscore characters.

  • If a property is not requested as a selectItem (explicitly or via a star), it SHOULD NOT be included in the response.

  • If a selectedProperty appears alone as a selectItem in a request URI, then the response MUST contain the value of the property as per the serialization rules defined in sections 2.2.6.2.2 and 2.2.6.3.3.

  • If a star appears alone in a selectClause, all properties on the EntityType within the collection of entities identified by the last path segment in the request URI MUST be included in the response.

  • If a star appears in a selectItem following a selectedNavProperty, all non-navigation properties of the entity or entities represented by the prior selectedNavProperty MUST be included in the response.

  • If a navigation property appears as the last segment of a selectItem and does not appear in an $expand query option, the entity or collection of entities identified by the navigation property MUST be represented as deferred content as described in sections 2.2.6.2.6 and 2.2.6.3.9.

  • If a navigation property appears as the last segment of a selectItem and the same property is specified as a segment of a path in an $expand query option, then all the properties of the entity identified by the selectItem MUST be in the response. In addition, all the properties of the entities identified by segments in the $expand path after the segment that matched the selectItem MUST also be included in the response.

  • If multiple selectClause instances exist in a $select query option, then the total set of property values to be returned is equal to the union of the set of properties identified by each selectClause.

  • Redundant selectClause rules on the same URI MAY be considered valid, but MUST NOT alter the meaning of the URI.

  • The presence of a selectClause means that both actions and functions SHOULD be omitted from the response, unless they are reintroduced explicitly by using a selectedAction or selectedFunction clause. A star SHOULD NOT reintroduce actions or functions.

    The individualAction clause requests a single action by name.

    The allActions clause requests all actions that are known to the server and that are bindable to the entities in the response.

    If an action is requested as a selectItem, either explicitly by using an individualAction clause or implicitly by using an allActions clause, the server MUST include in the response information about how to invoke that action (sections 2.2.6.2.2.2 and 2.2.6.3.3.1) for each of the entities identified by the last path segment in the request URI, if and only if the action can be bound to those entities.

    If an action that is requested by an individualAction clause cannot be bound to the entities requested, the server MUST ignore the individualAction clause.

    The individualFunction clause requests a single function by name.

    The allFunctions clause requests all functions that are known to the server and that are bindable to the entities in the response.

    If a function is requested as a selectItem, either explicitly by using an individualFunction clause or implicitly by using an allFunctions clause, the server MUST include in the response information about how to invoke that function (sections 2.2.6.2.2.3 and 2.2.6.3.3.2) for each of the entities that are identified by the last path segment in the request URI, if and only if the function can be bound to those entities.

    If a function requested by an individualFunction clause cannot be bound to the entities that are requested, the server MUST ignore the individualFunction clause.

    The selectClause does not provide a way to request actions or functions that are bound to the feed definition.

The following set of examples use the data model described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) and describe the semantics for a base set of data service URIs using the $select system query option. From these base cases, the semantics of longer URIs are defined by composing the following rules.

Examples:

 http://host/service.svc/Customers?$select=CustomerID,CompanyName,Address

In a response from a data service, only the CustomerID, CompanyName, and Address property values are returned for each customer entity within the Customers EntitySet. When a complex type is selected, all properties defined on that complex type property MUST be returned.

 http://host/service.svc/Customers?$select=CustomerID,Orders

In a response from a data service, only the CustomerID property value and a link to the collection of related entities identified by the Orders navigation property SHOULD be returned for each customer entity within the Customers EntitySet. Note: For the Orders navigation property referenced in the above URI, the $select option only states a link to the corresponding collection of orders will be returned.

 http://host/service.svc/Customers?$select=CustomerID,Orders&$expand=Orders/OrderDetails

In a response from a data service, only the CustomerID property of the customer's entities SHOULD be returned, but all the properties of the entities identified by the Orders and OrderDetails navigation properties SHOULD be returned.

 http://host/service.svc/Customers?$select=*

In a response from a data service, all properties are returned for each customer entity within the Customers EntitySet. Note: The star syntax is used to refer to all properties of the entity that are identified by the path of the URI or all properties of a navigation property, but does not refer to actions or functions. In other words, the * syntax causes all properties on an entity to be included without traversing associations or including information about actions or functions.

 http://host/service.svc/$select=CustomerID,Orders/*&$expand=Orders/OrderDetails

In a response from a data service, the CustomerID is included, along with the Order entities and all properties of the Order entities. But rather than including the fully expanded Order Detail entities referenced in the expand clause, each Order will contain a link that references the corresponding collection of Order Detail entities.

 http://host/service.svc/Photos/?$select=Name,Thumbnail

In a response from a data service, only the Name property and the thumbnail named resource stream are included.

The OData 3.0 protocol supports specifying the namespace-qualified EntityType in conjunction with $select.

 http://host/service.svc/Customers/SampleModel.VipCustomer/?$select=Logo

In a response from a data service, only the logo named resource stream is included for all VipCustomer EntityTypes or its subtypes.

 http://host/service.svc/Customers/?$select= SampleModel.VipCustomer/Logo

In a response from a data service, only the logo named resource stream is included for all VipCustomer EntityTypes or its subtypes, with empty content for non-VipCustomers.

 http://host/service.svc/Customers('ALFKI2')/?$select=SampleModel.VipCustomer/Logo

In a response from a data service, only the logo named resource stream is included for the single VipCustomer type identified.

 http://host/service.svc/Customers/?$select=CustomerID,CompanyName,$actions.CreateOrder

In a response from a data service, only the CustomerID and CompanyName properties are included for all Customer EntityType and/or subtypes. Additionally, the CreateOrders action is included for each customer if and only if the action is bindable to that customer. All other actions and functions are omitted.