$select$select
+$expand
$expand.
Example 37:
GET http://host/service/Products?$expand=Category($select=Name)$select and $compute for complex properties, plus $filter, $search, $count, $orderby, $skip, and $top for collection-valued properties. A property MUST NOT have select options specified in more than one place in a request and MUST NOT have both select options and expand options specified.
+If the selected property represents a collection of primitive or complex values, then the count segment (/$count), optionally followed by the Select Options $filter and/or $search, can be appended to the path in order to return only the count of the matching items.
Example 40: for each customer, return the ID and the count of addresses starting with the letter ‘H’.
+GET http://host/service/Customers?$select=ID,Addresses/$count(startswith(City,'H'))If the $select query option is not specified, the service returns the full set of properties or a default set of properties. The default set of properties MUST include all key properties. Services may change the default set of properties returned. This includes returning new properties by default and omitting properties previously returned by default. Clients that rely on specific properties in the response MUST use $select with the required properties or with *.
If the service returns less than the full set of properties, either because the client specified a select or because the service returned a subset of properties in the absence of a select, the context URL MUST reflect the set of selected properties and projected expanded navigation properties.
+Query options can be applied to a selected property by appending a semicolon-separated list of query options, enclosed in parentheses, to the property. Allowed system query options are $select and $compute for complex properties, plus $filter, $search, $count, $orderby, $skip, and $top for collection-valued properties. A property MUST NOT have select options specified in more than one place in a request and MUST NOT have both select options and expand options specified.
$expandExample 40: for each customer entity within the Customers entity set the value of all related Orders will be represented inline
+Example 41: for each customer entity within the Customers entity set the value of all related Orders will be represented inline
GET http://host/service.svc/Customers?$expand=OrdersExample 41: for each customer entity within the Customers entity set the references to the related Orders will be represented inline
+Example 42: for each customer entity within the Customers entity set the references to the related Orders will be represented inline
GET http://host/service.svc/Customers?$expand=Orders/$refExample 42: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline
+Example 43: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline
GET http://host/service.svc/Customers?$expand=PhotoIf the expand item represents a collection of entities, then the count segment (/$count), optionally followed by the Expand Options $filter and/or $search, can be appended to the expand item in order to return only the count of matching items.
Example 44: for each Category, return the Name and the count of Products starting with the letter ‘H’.
GET http://host/service/Categories?$select=Name&$expand=Products/$count(startswith(Name,'H'))The set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see OData-URL, section 5.1.3.
Allowed system query options are $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
Example 43: for each customer entity within the Customers entity set, the value of those related Orders whose Amount is greater than 100 will be represented inline
Example 45: for each customer entity within the Customers entity set, the value of those related Orders whose Amount is greater than 100 will be represented inline
GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)Example 44: for each order within the Orders entity set, the following will be represented inline:
Example 46: for each order within the Orders entity set, the following will be represented inline:
Items related to the Orders identified by the resource path section of the URL and the products related to each order item.Customer related to each order returned.GET http://host/service.svc/Orders?$expand=Items($expand=Product),CustomerExample 45: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)
Example 47: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)
GET http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff$compute system query option allows clients to define computed properties that can be used in a $select or within a $filter or $orderby expression.
Computed properties SHOULD be included as dynamic properties in the result and MUST be included if $select is specified with the computed property name, or star (*).
Example 47: compute total price for order items (line breaks only for readability)
+Example 49: compute total price for order items (line breaks only for readability)
GET http://host/service/Customers
?$filter=Orders/any(o:o/TotalPrice gt 100)
&$expand=Orders($compute=Price mult Qty as TotalPrice
@@ -1884,12 +1901,12 @@
-Example 48: return all Products whose Price is less than $10.00
+Example 50: return all Products whose Price is less than $10.00
GET http://host/service/Products?$filter=Price lt 10.00
The $count segment may be used within a $filter expression to limit the items returned based on the exact count of related entities or items within a collection-valued property.
Example 49: return all Categories with less than 10 products
+Example 51: return all Categories with less than 10 products
GET http://host/service/Categories?$filter=Products/$count lt 10The value of the $filter option is a Boolean expression as defined in OData-ABNF.
$compute, $filter or $orderby expression. Parameters aliases are names beginning with an at sign (@).
Actual parameter values are specified as query options in the query part of the request URL. The query option name is the name of the parameter alias, and the query option value is the value to be used for the specified parameter alias.
Example 50: returns all employees whose Region property matches the string parameter value WA
Example 52: returns all employees whose Region property matches the string parameter value WA
GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'Parameter aliases allow the same value to be used multiple times in a request and may be used to reference primitive, structured, or collection values.
@@ -1997,7 +2014,7 @@Example 51: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports
Example 53: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports
GET http://host/service.svc/Employees?$expand=Manager(@m=$this;$expand=DirectReports($filter=@m/FirstName eq FirstName))Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
Values of type Edm.Stream or any of the Geo types cannot be sorted.
Example 52: return all Products ordered by release date in ascending order, then by rating in descending order
+Example 54: return all Products ordered by release date in ascending order, then by rating in descending order
GET http://host/service/Products?$orderby=ReleaseDate asc, Rating descRelated entities may be ordered by specifying $orderby within the $expand clause.
Example 53: return all Categories, and their Products ordered according to release date and in descending order of rating
+Example 55: return all Categories, and their Products ordered according to release date and in descending order of rating
GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)$count may be used within a $orderby expression to order the returned items according to the exact count of related entities or items within a collection-valued property.
Example 54: return all Categories ordered by the number of Products within each category
+Example 56: return all Categories ordered by the number of Products within each category
GET http://host/service/Categories?$orderby=Products/$count$orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.
If \(A\) contains more than \(n\) instances, the result of \({\tt \$top}=n\) consists of the first \(n\) instances in \(A\). Otherwise, the result equals \(A\). The instances in the result are in the same order as they occur in \(A\).
Example 55: return only the first five products of the Products entity set
+Example 57: return only the first five products of the Products entity set
GET http://host/service/Products?$top=5$orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.
If \(A\) contains \(n\) or fewer instances, the result of \({\tt \$skip}=n\) is empty. Otherwise, the first \(n\) instances in \(A\) are omitted from the result and all remaining instances are kept in the same order as they occur in \(A\).
Example 56: return products starting with the 6th product of the Products entity set
Example 58: return products starting with the 6th product of the Products entity set
GET http://host/service/Products?$skip=5Where $top and $skip are used together, $skip MUST be applied before $top, regardless of the order in which they appear in the request.
Example 57: return the third through seventh products of the Products entity set
Example 59: return the third through seventh products of the Products entity set
GET http://host/service/Products?$top=5&$skip=2If no unique ordering is imposed through an $orderby query option, the service MUST impose a stable ordering across requests that include $skip.
Example 58: return, along with the results, the total number of products in the collection
+Example 60: return, along with the results, the total number of products in the collection
GET http://host/service/Products?$count=trueThe count of related entities can be requested by specifying the $count query option within the $expand clause.
Example 59:
+Example 61:
GET http://host/service/Categories?$expand=Products($count=true)A $count query option with a value of false (or not specified) hints that the service SHOULD NOT return a count.
Example 60: return all Products that match the search term bike
Example 62: return all Products that match the search term bike
GET http://host/service/Products?$search=bikeThe search expression can contain phrases, enclosed in double-quotes.
Example 61: return all Products that match the phrase mountain bike
Example 63: return all Products that match the phrase mountain bike
GET http://host/service/Products?$search="mountain bike"The upper-case keyword NOT restricts the set of entities to those that do not match the specified term.
Example 62: return all Products that do not match clothing
Example 64: return all Products that do not match clothing
GET http://host/service/Products?$search=NOT clothingMultiple terms within a search expression are separated by a space (implicit AND) or the upper-case keyword AND, indicating that all such terms must be matched.
Example 63: return all Products that match both mountain and bike
Example 65: return all Products that match both mountain and bike
GET http://host/service/Products?$search=mountain AND bikeThe upper-case keyword OR is used to return entities that satisfy either the immediately preceding or subsequent expression.
Example 64: return all Products that match mountain or bike
Example 66: return all Products that match mountain or bike
GET http://host/service/Products?$search=mountain OR bikeParentheses within the search expression group together multiple expressions.
Example 65: return all Products that match mountain or bike and do not match clothing
Example 67: return all Products that match mountain or bike and do not match clothing
GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothingThe operations within a search expression MUST be evaluated in the following order: grouping operator, NOT operator, AND operator, OR operator
Entities are stably addressable using their canonical URL and are not accessible using an ordinal index.
Example 66: the first address in a list of addresses for MainSupplier
Example 68: the first address in a list of addresses for MainSupplier
GET http://host/service/MainSupplier/Addresses/0If the relationship terminates on a single entity, the response MUST be the format-specific representation of the related single entity. If no entity is related, the service returns 204 No Content.
Example 67: return the supplier of the product with ID=1 in the Products entity set
Example 69: return the supplier of the product with ID=1 in the Products entity set
GET http://host/service/Products(1)/SupplierETag header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.
If the resource path terminates on a single entity and no such entity exists, the service returns either 204 No Content or 404 Not Found.
Example 68: collection with an entity reference for each Order related to the Product with ID=0
Example 70: collection with an entity reference for each Order related to the Product with ID=0
GET http://host/service/Products(0)/Orders/$refGET request to the $entity resource located at the URL $entity relative to the service root. The entity-id MUST be specified using the system query option $id.
Example 69: return the entity representation for a given entity-id
+Example 71: return the entity representation for a given entity-id
GET http://host/service/$entity?$id=http://host/service/Products(0)A type segment following the $entity resource casts the resource to the specified type. If the identified entity is not of the specified type, or a type derived from the specified type, the service returns 404 Not Found.
After applying a type-cast segment to cast to a specific type, the system query options $select and $expand can be specified in GET requests to the $entity resource.
Example 70: return the entity representation for a given entity-id and specify properties to return
+Example 72: return the entity representation for a given entity-id and specify properties to return
GET http://host/service/$entity/Model.Customer
?$id=http://host/service/Customers('ALFKI')
&$select=CompanyName,ContactName
@@ -2179,27 +2196,27 @@ $filter or $search system query options, formatted as a simple primitive integer value with media type text/plain. Clients SHOULD NOT combine the system query options $top, $skip, $orderby, $expand, and $format with the path suffix /$count. The result of such a request is undefined.
-Example 71: return the number of products in the Products entity set
+Example 73: return the number of products in the Products entity set
GET http://host/service/Products/$count
With 4.01 services the /$count segment MAY be used in combination with the /$filter path segment to count the items in the filtered collection.
-Example 72: return the number of products whose Price is less than $10.00
+Example 74: return the number of products whose Price is less than $10.00
GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00
For backwards compatibility, the /$count suffix MAY be used in combination with the $filter system query option.
-Example 73: return the number of products whose Price is less than $10.00
+Example 75: return the number of products whose Price is less than $10.00
GET http://host/service/Products/$count?$filter=Price lt 10.00
The $filter system query option MUST NOT be used in conjunction with a both a /$count path segment and a /$filter path segment.
The /$count suffix can also be used in path expressions within system query options, e.g. $filter.
-Example 74: return all customers with more than five interests
+Example 76: return all customers with more than five interests
GET http://host/service/Customers?$filter=Interests/$count gt 5
-Example 75: return all categories with more than one product over $5.00
+Example 77: return all categories with more than one product over $5.00
GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1
@@ -2211,12 +2228,12 @@ OData-JSON, but format parameters MUST NOT be appended to the format abbreviations.
-Example 76: the request
+Example 78: the request
GET http://host/service/Orders?$format=application/json;metadata=full
is equivalent to a request with an Accept header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in OData-JSON, section 3.1.2.
-Example 77: the request
+Example 79: the request
GET http://host/service/Orders?$format=json
is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON, section 3.1.1.
@@ -2350,29 +2367,29 @@
-Example 78: using the JSON format, 4.0 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by applying the odata.bind annotation to the Manager and DirectReports navigation properties
-{
- "@type": "#Northwind.Manager",
- "ID": 1,
- "FirstName": "Pat",
- "LastName": "Griswold",
- "Manager@odata.bind": "http://host/service/Employees(0)",
- "DirectReports@odata.bind": [
- "http://host/service/Employees(5)",
- "http://host/service/Employees(6)"
- ]
-}
-
Example 79: using the JSON format, 4.01 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids within the Manager and DirectReports navigation properties
{
- "@type": "#Northwind.Manager",
- "ID": 1,
- "FirstName": "Pat",
- "LastName": "Griswold",
- "Manager": { "@id": "Employees(0)" },
- "DirectReports": [{ "@id": "Employees(5)" }, { "@id": "Employees(6)" }]
-}Example 80: using the JSON format, 4.0 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by applying the odata.bind annotation to the Manager and DirectReports navigation properties
{
+ "@type": "#Northwind.Manager",
+ "ID": 1,
+ "FirstName": "Pat",
+ "LastName": "Griswold",
+ "Manager@odata.bind": "http://host/service/Employees(0)",
+ "DirectReports@odata.bind": [
+ "http://host/service/Employees(5)",
+ "http://host/service/Employees(6)"
+ ]
+}Example 81: using the JSON format, 4.01 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids within the Manager and DirectReports navigation properties
{
+ "@type": "#Northwind.Manager",
+ "ID": 1,
+ "FirstName": "Pat",
+ "LastName": "Griswold",
+ "Manager": { "@id": "Employees(0)" },
+ "DirectReports": [{ "@id": "Employees(5)" }, { "@id": "Employees(6)" }]
+}Upon successful completion of the operation, the service creates the requested entity and relates it to the requested existing entities.
If the target URL for the collection the entity is created in and binding information provided in the POST body contradicts the implicit binding information provided by the request URL, the request MUST fail, and the service responds with 400 Bad Request.
If a navigation property is absent from a PUT or PATCH request payload, the referenced or contained entity, or the collection thereof, remains unchanged by a successful update.
Example 80: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
{
- "@type": "#Northwind.Manager",
- "FirstName": "Patricia",
- "DirectReports": [
- {
- "@id": "Employees(5)"
- },
- {
- "@id": "Employees(6)",
- "LastName": "Smith"
- },
- {
- "FirstName": "Suzanne",
- "LastName": "Brown"
- }
- ]
-}Example 82: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
{
+ "@type": "#Northwind.Manager",
+ "FirstName": "Patricia",
+ "DirectReports": [
+ {
+ "@id": "Employees(5)"
+ },
+ {
+ "@id": "Employees(6)",
+ "LastName": "Smith"
+ },
+ {
+ "FirstName": "Suzanne",
+ "LastName": "Brown"
+ }
+ ]
+}If the nested collection is represented as a delta annotation on the navigation property, then the collection contains members to be added or changed and MAY include deleted entities for entities that are no longer part of the collection, using the delta payload format. If the deleted entity specifies a reason as deleted, then the entity is both removed from the collection and deleted, otherwise it is removed from the collection and only deleted if the relationship is contained. Non-key properties of the deleted entity are ignored. Nested collections MUST NOT contain added or deleted links. If the request contains nested delta collections, then the PATCH verb must be specified.
If a nested entity has the same id or key fields as an existing entity, the existing entity is updated according to the semantics of the PUT or PATCH request. Nested entities that have no id or key fields, or for which the id or key fields do not match existing entities, are treated as inserts. If the nested collection does not represent a containment relationship and has no navigation property binding, then such entities MUST include a context URL specifying the entity set in which the new entity is to be created. If any nested entities contain both id and key fields, they MUST identify the same entity, or the request is invalid.
Example 81: using the JSON format, a 4.01 PATCH request can specify a nested delta representation to:
Example 83: using the JSON format, a 4.01 PATCH request can specify a nested delta representation to:
{
- "@type": "#Northwind.Manager",
- "FirstName": "Patricia",
- "DirectReports@delta": [
- {
- "@removed": {
- "reason": "deleted"
- },
- "@id": "Employees(3)"
- },
- {
- "@removed": {
- "reason": "changed"
- },
- "@id": "Employees(4)"
- },
- {
- "@id": "Employees(5)"
- },
- {
- "@id": "Employees(6)",
- "LastName": "Smith"
- },
- {
- "FirstName": "Suzanne",
- "LastName": "Brown"
- }
- ]
-}Example 82: When updating an entity with a 4.01 PUT request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see OData-JSON, section 14), without specifying all its structural properties in PUT semantics.
{
+ "@type": "#Northwind.Manager",
+ "FirstName": "Patricia",
+ "DirectReports@delta": [
+ {
+ "@removed": {
+ "reason": "deleted"
+ },
+ "@id": "Employees(3)"
+ },
+ {
+ "@removed": {
+ "reason": "changed"
+ },
+ "@id": "Employees(4)"
+ },
+ {
+ "@id": "Employees(5)"
+ },
+ {
+ "@id": "Employees(6)",
+ "LastName": "Smith"
+ },
+ {
+ "FirstName": "Suzanne",
+ "LastName": "Brown"
+ }
+ ]
+}Example 84: When updating an entity with a 4.01 PUT request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see OData-JSON, section 14), without specifying all its structural properties in PUT semantics.
The following JSON payload changes the name of a category and the products belonging to it. (Compare this to OData-JSON, example 22.) The effect would be the same if the @context was omitted from the request.
Request
-PUT http://host/service/Categories(6)?$expand=Products
-Content-Type: application/json
-
-{
- "Name": "UpdatedCategory",
- "Products": [
- {
- "@context": "$metadata#$ref",
- "@id": "Products(57)"
- }
- ]
-}Response
-{
- "@context": "$metadata#Categories/$entity",
- "CategoryID": 6,
- "Name": "UpdatedCategory",
- "Products": [
- {
- "ProductID": 57,
- "Name": "Widgets"
- }
- ]
-}If Products was a containment navigation property, the request and response would be the same, except that the @id would likely be relative to the category, for example, Categories(6)/Products(57).
If the targeted entity in the payload contains some structural properties, PUT resets all its other structural properties. The following alternative payload resets the product name. The effect would be the same if the @id was omitted from the request.
If Products was a containment navigation property, the request and response would be the same, except that the @id would likely be relative to the category, for example, Categories(6)/Products(57).
If the targeted entity in the payload contains some structural properties, PUT resets all its other structural properties. The following alternative payload resets the product name. The effect would be the same if the @id was omitted from the request.
PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@id": "Products(57)",
+ "ProductID": 57
+ }
+ ]
+}{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": null
+ }
+ ]
+}Clients MAY associate an id with individual nested entities in the request by using the Core.ContentID term defined in OData-VocCore. Services that respond with 200 OK SHOULD annotate the entities in the response using the same Core.ContentID value as specified in the request. Services SHOULD advertise support for deep updates, including support for returning the Core.ContentID, through the Capabilities.DeepUpdateSupport term, defined in OData-VocCap.
The continue-on-error preference is not supported for deep update operations.
On failure, the service MUST NOT apply any of the changes specified in the request.
@@ -2650,22 +2667,22 @@$expand. Instead, the values are generally read or written through URLs.
Example 83: read an entity and select a stream property
+Example 85: read an entity and select a stream property
GET http://host/service/Products(1)?$select=Thumbnailwould only include control information for the stream property, not the stream data itself
-{
- "@context": "http://host/service/$metadata#Products/$entity",
- …
- "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
- "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
- …
-}{
+ "@context": "http://host/service/$metadata#Products/$entity",
+ …
+ "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
+ "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
+ …
+}The stream data can then be requested using the media read link:
GET http://server/Thumbnail546.jpgServices SHOULD support direct property access to a stream property’s canonical URL. The response MAY be a redirect to the media read link of the stream property if the media read link is different from the canonical URL.
Example 84: directly read a stream property of an entity
+Example 86: directly read a stream property of an entity
GET http://host/service/Products(1)/Thumbnailcan return 200 OK and the stream data (see section 11.2.4.1), or a 3xx Redirect to the media read link of the stream property.
Example 85: delete the stream value using the media edit link retrieved in example 83
+Example 87: delete the stream value using the media edit link retrieved in example 85
DELETE http://server/uploads/Thumbnail546.jpgAttempting to request a stream property whose value is null results in 204 No Content.
Core.PositionalInsert term (see OData-VocCore) support inserting items at a specific location via POST requests to the collection URL using the $index system query option. The value of the $index system query option is the zero-based ordinal position where the item is to be inserted. The ordinal positions of items within the collection greater than or equal to the inserted position are increased by one. A negative ordinal number indexes from the end of the collection, with -1 representing an insert as the last item in the collection.
Example 86: Insert a new email address at the second position
-POST /service/Customers('ALFKI')/EmailAddresses?$index=1
-Content-Type: application/json
-
-{
- "value": "alfred@futterkiste.de"
-}Example 88: Insert a new email address at the second position
+POST /service/Customers('ALFKI')/EmailAddresses?$index=1
+Content-Type: application/json
+
+{
+ "value": "alfred@futterkiste.de"
+}For collections of structured type, the body of the request MUST be a full or partial representation of an instance of the collection’s structured type. Each member of the potentially filtered collection is updated using PATCH semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in Update a Collection of Entities applies.
Example 87: change the color of all beige-brown products
-PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
-Content-Type: application/json
-
-{
- "Color": "taupe"
-}Example 89: change the color of all beige-brown products
+PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
+Content-Type: application/json
+
+{
+ "Color": "taupe"
+}The response, if requested, is a collection payload containing the updated representation of each member identified by the request. If the update payload includes nested collections or nested delta collections, then they MUST be included in the response, as described in Update a Collection of Entities.
Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.
@@ -2828,7 +2845,7 @@DELETE request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.
The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.
Example 88: delete all products older than 3
+Example 90: delete all products older than 3
DELETE /service/Products/$filter(Age gt 3)/$eachIf the path identifies a collection of entities and if the service returns a representation, then the response is a delta response containing a representation of a deleted entity for each deleted member.
@@ -2847,25 +2864,25 @@The namespace- or alias-qualified name of a bound operation may be appended to any URL that identifies a resource whose type matches, or is derived from, the type of the binding parameter. The resource identified by that URL is used as the binding parameter value. Only aliases defined in the metadata document of the service can be used in URLs.
Example 89: the function MostRecentOrder can be bound to any URL that identifies a SampleModel.Customer
<Function Name="MostRecentOrder" IsBound="true">
- <Parameter Name="customer" Type="SampleModel.Customer" />
- <ReturnType Type="SampleModel.Order" />
-</Function>Example 91: the function MostRecentOrder can be bound to any URL that identifies a SampleModel.Customer
<Function Name="MostRecentOrder" IsBound="true">
+ <Parameter Name="customer" Type="SampleModel.Customer" />
+ <ReturnType Type="SampleModel.Order" />
+</Function>Example 90: invoke the MostRecentOrder function with the value of the binding parameter customer being the entity identified by http://host/service/Customers(6)
Example 92: invoke the MostRecentOrder function with the value of the binding parameter customer being the entity identified by http://host/service/Customers(6)
GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()Example 91: the function Comparison can be bound to any URL that identifies a collection of entities
<Function Name="Comparison" IsBound="true">
- <Parameter Name="in" Type="Collection(Edm.EntityType)" />
- <ReturnType Type="Diff.Overview" />
-</Function>Example 93: the function Comparison can be bound to any URL that identifies a collection of entities
<Function Name="Comparison" IsBound="true">
+ <Parameter Name="in" Type="Collection(Edm.EntityType)" />
+ <ReturnType Type="Diff.Overview" />
+</Function>Example 92: invoke the Comparison function on the set of red products
Example 94: invoke the Comparison function on the set of red products
GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()Example 93: invoke the MostRecentOrder function on each entity in the entity set Customers
Example 95: invoke the MostRecentOrder function on each entity in the entity set Customers
GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()The client MAY specify the continue-on-error preference, in which case the service MAY continue processing actions after a failure. In this case, the service MUST, regardless of the return preference, return a response containing at least the members identified by the request for which the action failed. Such members MUST be annotated with the term Core.DataModificationException with a failedOperation value of invoke.
Example 94: given a GET request to http://host/service/Customers('ALFKI'), the service might respond with a Customer that includes the SampleEntities.MostRecentOrder function bound to the entity
{
- "@context": …,
- "CustomerID": "ALFKI",
- "CompanyName": "Alfreds Futterkiste",
- "#SampleEntities.MostRecentOrder": {
- "title": "Most Recent Order",
- "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
- },
- …
-}Example 96: given a GET request to http://host/service/Customers('ALFKI'), the service might respond with a Customer that includes the SampleEntities.MostRecentOrder function bound to the entity
{
+ "@context": …,
+ "CustomerID": "ALFKI",
+ "CompanyName": "Alfreds Futterkiste",
+ "#SampleEntities.MostRecentOrder": {
+ "title": "Most Recent Order",
+ "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
+ },
+ …
+}An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL, section 4.5.
Services can advertise that a function or action is not available for a particular instance by setting its value to null.
Example 95: the SampleEntities.MostRecentOrder function is not available for customer ALFKI
{
- "@context": …,
- "CustomerID": "ALFKI",
- "CompanyName": "Alfreds Futterkiste",
- "#SampleEntities.MostRecentOrder": null,
- …
-}Example 97: the SampleEntities.MostRecentOrder function is not available for customer ALFKI
{
+ "@context": …,
+ "CustomerID": "ALFKI",
+ "CompanyName": "Alfreds Futterkiste",
+ "#SampleEntities.MostRecentOrder": null,
+ …
+}If the function is composable, additional path segments may be appended to the URL that identifies the composable function (or function import) as appropriate for the type returned by the function (or function import). The last path segment determines the system query options and HTTP verbs that can be used with this this URL, e.g. if the last path segment is a multi-valued navigation property, a POST request may be used to create a new entity in the identified collection.
Example 96: add a new item to the list of items of the shopping cart returned by the composable MyShoppingCart function import
Example 98: add a new item to the list of items of the shopping cart returned by the composable MyShoppingCart function import
POST http://host/service/MyShoppingCart()/Items
…Example 97: invoke a Sales.EmployeesByManager function which takes a single ManagerID parameter via the function import EmployeesByManager
Example 99: invoke a Sales.EmployeesByManager function which takes a single ManagerID parameter via the function import EmployeesByManager
GET http://host/service/EmployeesByManager(ManagerID=3)Example 98: return all Customers whose City property returns Western when passed to the Sales.SalesRegion function
Example 100: return all Customers whose City property returns Western when passed to the Sales.SalesRegion function
GET http://host/service/Customers?
$filter=Sales.SalesRegion(City=$it/City) eq 'Western'A parameter alias can be used in place of an inline parameter value. The value for the alias is specified as a separate query option using the name of the parameter alias.
Example 99: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter
Example 101: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter
GET http://host/service/EmployeesByManager(ManagerID=@p1)?@p1=3Services MAY in addition allow implicit parameter aliases for function imports and for functions that are the last path segment of the URL. An implicit parameter alias is the parameter name, optionally preceded by an at (@) sign. When using implicit parameter aliases, parentheses MUST NOT be appended to the function (import) name. The value for each parameter MUST be specified as a separate query option with the name of the parameter alias. If a parameter name is identical to a system query option name (without the optional $ prefix), the parameter name MUST be prefixed with an at (@) sign.
Example 100: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter using the implicit parameter alias
Example 102: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter using the implicit parameter alias
GET http://host/service/EmployeesByManager?ManagerID=3Non-binding parameters annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter.
204 No Content on success.
To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.
Example 101: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
-If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
-Content-Type: application/json
-
-{
- "items": [
- { "product": 4001, "quantity": 2 },
- { "product": 7062, "quantity": 1 },
- ],
- "discountCode": "BLACKFRIDAY"
-}Example 103: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
+If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
+Content-Type: application/json
+
+{
+ "items": [
+ { "product": 4001, "quantity": 2 },
+ { "product": 7062, "quantity": 1 },
+ ],
+ "discountCode": "BLACKFRIDAY"
+}Content-Type header specifying a content type of multipart/mixed and a boundary parameter as defined in RFC2046.
Example 102: multipart batch request
+Example 104: multipart batch request
POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.0
@@ -3060,7 +3077,7 @@
-Example 103: JSON batch request
+Example 105: JSON batch request
POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.01
@@ -3087,7 +3104,7 @@ 11.7.4 Referencing Returned Entities
-Entities created by an insert request or an action can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. Services MUST treat this segment like the URL in the Location header of the response to the request identified by the segment. If the Location header in the response to the subsequent request contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference. See example 108.
+Entities created by an insert request or an action can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. Services MUST treat this segment like the URL in the Location header of the response to the request identified by the segment. If the Location header in the response to the subsequent request contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference. See example 110.
If the $-prefixed request identifier is identical to the name of a top-level system resource ($batch, $crossjoin, $all, $entity, $root, $id, $metadata, or other system resources defined according to the OData-Version of the protocol specified in the request), then the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.
Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the ReferencesInRequestBodiesSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.
@@ -3121,25 +3138,25 @@ Absolute URI with schema, host, port, and absolute resource path.
-Example 104:
+Example 106:
GET https://host:1234/path/service/People(1) HTTP/1.1
- Absolute resource path and separate
Host header
-Example 105:
-PATCH /path/service/People(1) HTTP/1.1
-Host: myserver.mydomain.org:1234
-Content-Type: application/json
-
-{ "Name": "Peter" }
+Example 107:
+PATCH /path/service/People(1) HTTP/1.1
+Host: myserver.mydomain.org:1234
+Content-Type: application/json
+
+{ "Name": "Peter" }
- Resource path relative to the batch request URI.
-Example 106:
+Example 108:
DELETE People(1) HTTP/1.1
Services MUST support all three formats for URLs of individual requests.
@@ -3151,7 +3168,7 @@
Processors of batch requests MAY choose to disallow additional HTTP constructs in HTTP requests serialized within body parts. For example, a processor may choose to disallow chunked encoding to be used by such HTTP requests.
-Example 107: a batch request that contains the following individual requests in the order listed
+Example 109: a batch request that contains the following individual requests in the order listed
- A query request
- A change set that contains the following requests:
@@ -3217,7 +3234,7 @@
insert request or an action can be referenced in the request URL of subsequent requests within the same change set. Services MAY also support referencing across change sets, in which case they SHOULD advertise this support by specifying the ReferencesAcrossChangeSetsSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.
-Example 108: a batch request that contains the following operations in the order listed:
+Example 110: a batch request that contains the following operations in the order listed:
A change set that contains the following requests:
- Insert a new entity (with
Content-ID = 1)
@@ -3277,54 +3294,54 @@ example 105). This gives the effective second request URL http://host/service/Customers('ALFKI')/Orders as base URI for the second Location URL, which therefore resolves to http://host/service/Customers('ALFKI')/Orders(1).
+
The second Location URL Orders(1) is relative with its base URI being the second request URL $1/Orders. To get an absolute base URI, the client must replace the $1 with the first Location URL Customers('ALFKI') and resolve the resulting URL Customers('ALFKI')/Orders(1) relative to its base URI, which is http://host/service/Customers (determined from the first request URL /service/Customers and the Host: host header as in example 107). This gives the effective second request URL http://host/service/Customers('ALFKI')/Orders as base URI for the second Location URL, which therefore resolves to http://host/service/Customers('ALFKI')/Orders(1).
11.7.7.3 Referencing an ETag
-Example 109: a batch request that contains the following operations in the order listed:
+Example 111: a batch request that contains the following operations in the order listed:
- Get an employee (with
Content-ID = 1)
- Update the salary only if the employee has not changed
-POST /service/$batch HTTP/1.1
-Host: host
-OData-Version: 4.0
-Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Length: ###
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 1
-
-GET /service/Employees(0) HTTP/1.1
-Host: host
-Accept: application/json
-
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 2
-
-PATCH /service/Employees(0) HTTP/1.1
-Host: host
-Content-Type: application/json
-Content-Length: ###
-If-Match: $1
-
-{
- "Salary": 75000
-}
---batch_36522ad7-fc75-4b56-8c71-56071383e77b--
+POST /service/$batch HTTP/1.1
+Host: host
+OData-Version: 4.0
+Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Length: ###
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 1
+
+GET /service/Employees(0) HTTP/1.1
+Host: host
+Accept: application/json
+
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 2
+
+PATCH /service/Employees(0) HTTP/1.1
+Host: host
+Content-Type: application/json
+Content-Length: ###
+If-Match: $1
+
+{
+ "Salary": 75000
+}
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b--
11.7.7.4 Referencing Response Body Values
-Example 110: a batch request that contains the following operations in the order listed:
+Example 112: a batch request that contains the following operations in the order listed:
- Get an employee (with
Content-ID = 1)
- Get all employees residing in the same building
@@ -3373,9 +3390,9 @@ Asynchronously processed batch requests can return interim results and end with a 202 Accepted as the last part of the multipart response. Therefore, the respond-async preference MUST NOT be applied to individual requests within a batch if the batch response is a multipart response.
The body of a multipart response to a JSON batch request contains one body part for each processed or accepted request. The order of the body parts is insignificant as each body part MUST contain the Content-ID header with the value of the id name/value pair of the corresponding request object.
-A response to an operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in the corresponding subsections of chapter Data Service Requests. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see example 108). URLs in responses MUST NOT contain $-prefixed request identifiers.
+A response to an operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in the corresponding subsections of chapter Data Service Requests. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see example 110). URLs in responses MUST NOT contain $-prefixed request identifiers.
-Example 111: referencing the batch request example 107 above, assume all the requests except the final query request succeed. In this case the response would be
+Example 113: referencing the batch request example 109 above, assume all the requests except the final query request succeed. In this case the response would be
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
@@ -3429,7 +3446,7 @@ A service MAY return interim results to an asynchronously executing batch. It does this by responding with 200 OK to a GET request to the monitor resource and including a 202 Accepted response as the last part of the multipart response. The client can use the monitor URL returned in this 202 Accepted response to continue processing the batch response.
Since a change set is executed atomically, 202 Accepted MUST NOT be returned within a change set.
-Example 112: referencing the example 107 above again, assume that
+Example 114: referencing the example 109 above again, assume that
HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
Retry-After: ###
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 7f74b4f5..7fe82c91 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -212,6 +212,7 @@ For complete copyright information please see the full Notices section in an App
- [11.2.4.2 Requesting a Raw Value using `$value`](#RequestingaRawValueusingvalue)
- [11.2.5 Specifying Properties to Return](#SpecifyingPropertiestoReturn)
- [11.2.5.1 System Query Option `$select`](#SystemQueryOptionselect)
+ - [11.2.5.1.1 Select Options](#SelectOptions)
- [11.2.5.2 System Query Option `$expand`](#SystemQueryOptionexpand)
- [11.2.5.2.1 Expand Options](#ExpandOptions)
- [11.2.5.2.1.1 Expand Option `$levels`](#ExpandOptionlevels)
@@ -2914,7 +2915,7 @@ GET http://host/service/Products?$select=*
:::
Properties of related entities can be specified by including the
-`$select` query option within the `$expand`.
+`$select` [option](#ExpandOptions) within the `$expand`.
::: example
Example 37:
@@ -2948,19 +2949,14 @@ GET http://host/service/Products?$select=DemoService.*
```
:::
-Query options can be applied to a selected property by appending a
-semicolon-separated list of query options, enclosed in parentheses, to
-the property. Allowed system query options are
-[`$select`](#SystemQueryOptionselect) and
-[`$compute`](#SystemQueryOptioncompute) for complex properties, plus
-[`$filter`](#SystemQueryOptionfilter),
-[`$search`](#SystemQueryOptionsearch),
-[`$count`](#SystemQueryOptioncount),
-[`$orderby`](#SystemQueryOptionorderby),
-[`$skip`](#SystemQueryOptionskip), and [`$top`](#SystemQueryOptiontop)
-for collection-valued properties. A property MUST NOT have select
-options specified in more than one place in a request and MUST NOT have
-both select options and expand options specified.
+If the selected property represents a collection of primitive or complex values, then the [count segment](#RequestingtheNumberofItemsinaCollection) (`/$count`), optionally followed by the [Select Options](#SelectOptions) [`$filter`](#SystemQueryOptionfilter) and/or [`$search`](#SystemQueryOptionsearch), can be appended to the path in order to return only the count of the matching items.
+
+::: example
+Example 40: for each customer, return the ID and the count of addresses starting with the letter 'H'.
+```
+GET http://host/service/Customers?$select=ID,Addresses/$count(startswith(City,'H'))
+```
+:::
If the `$select` query option is not specified, the service returns
the full set of properties or a default set of properties. The default
@@ -2978,6 +2974,22 @@ the [context URL](#ContextURL) MUST reflect the set of selected
properties and projected [expanded](#SystemQueryOptionexpand) navigation
properties.
+##### 11.2.5.1.1 Select Options
+
+Query options can be applied to a selected property by appending a
+semicolon-separated list of query options, enclosed in parentheses, to
+the property. Allowed system query options are
+[`$select`](#SystemQueryOptionselect) and
+[`$compute`](#SystemQueryOptioncompute) for complex properties, plus
+[`$filter`](#SystemQueryOptionfilter),
+[`$search`](#SystemQueryOptionsearch),
+[`$count`](#SystemQueryOptioncount),
+[`$orderby`](#SystemQueryOptionorderby),
+[`$skip`](#SystemQueryOptionskip), and [`$top`](#SystemQueryOptiontop)
+for collection-valued properties. A property MUST NOT have select
+options specified in more than one place in a request and MUST NOT have
+both select options and expand options specified.
+
#### 11.2.5.2 System Query Option `$expand`
The `$expand` system query option indicates the related entities and
@@ -2992,7 +3004,7 @@ For a full description of the syntax used when building requests, see
[OData-URL, section 5.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand).
::: example
-Example 40: for each customer entity within the Customers entity set the
+Example 41: for each customer entity within the Customers entity set the
value of all related Orders will be represented inline
```
GET http://host/service.svc/Customers?$expand=Orders
@@ -3000,7 +3012,7 @@ GET http://host/service.svc/Customers?$expand=Orders
:::
::: example
-Example 41: for each customer entity within the Customers entity set the
+Example 42: for each customer entity within the Customers entity set the
references to the related Orders will be represented inline
```
GET http://host/service.svc/Customers?$expand=Orders/$ref
@@ -3008,13 +3020,22 @@ GET http://host/service.svc/Customers?$expand=Orders/$ref
:::
::: example
-Example 42: for each customer entity within the Customers entity set the
+Example 43: for each customer entity within the Customers entity set the
media stream representing the customer photo will be represented inline
```
GET http://host/service.svc/Customers?$expand=Photo
```
:::
+If the expand item represents a collection of entities, then the [count segment](#RequestingtheNumberofItemsinaCollection) (`/$count`), optionally followed by the [Expand Options](#ExpandOptions) [`$filter`](#SystemQueryOptionfilter) and/or [`$search`](#SystemQueryOptionsearch), can be appended to the expand item in order to return only the count of matching items.
+
+::: example
+Example 44: for each Category, return the `Name` and the count of `Products` starting with the letter 'H'.
+```
+GET http://host/service/Categories?$select=Name&$expand=Products/$count(startswith(Name,'H'))
+```
+:::
+
##### 11.2.5.2.1 Expand Options
The set of expanded entities can be further refined through the
@@ -3036,7 +3057,7 @@ Allowed system query options are
for collection-valued navigation properties.
::: example
-Example 43: for each customer entity within the `Customers` entity set,
+Example 45: for each customer entity within the `Customers` entity set,
the value of those related `Orders` whose `Amount` is greater than 100
will be represented inline
```
@@ -3045,7 +3066,7 @@ GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)
:::
::: example
-Example 44: for each order within the `Orders` entity set, the following
+Example 46: for each order within the `Orders` entity set, the following
will be represented inline:
- The `Items` related to
the `Orders` identified by the resource path section of the URL and the
@@ -3057,7 +3078,7 @@ GET http://host/service.svc/Orders?$expand=Items($expand=Product),Customer
:::
::: example
-Example 45: for each customer entity in the Customers entity set, the
+Example 47: for each customer entity in the Customers entity set, the
value of all related InHouseStaff will be represented inline if the
entity is of type VipCustomer or a subtype of that. For entities that
are not of type `VipCustomer`, or any of its subtypes, that entity may
@@ -3087,7 +3108,7 @@ in cases were a circular reference would occur otherwise.
manner. Clients that want to work with 4.0 services MUST use lower case.
::: example
-Example 46: return each employee from the Employees entity set and, for
+Example 48: return each employee from the Employees entity set and, for
each employee that is a manager, return all direct reports, recursively
to four levels
```
@@ -3107,7 +3128,7 @@ result and MUST be included if `$select` is specified with the computed
property name, or star (`*`).
::: example
-Example 47: compute total price for order items (line breaks only for
+Example 49: compute total price for order items (line breaks only for
readability)
```
GET http://host/service/Customers
@@ -3143,7 +3164,7 @@ return [`501 Not Implemented`](#ResponseCode501NotImplemented).
The `$filter` system query option restricts the set of items returned.
::: example
-Example 48: return all Products whose `Price` is less than $10.00
+Example 50: return all Products whose `Price` is less than $10.00
```
GET http://host/service/Products?$filter=Price lt 10.00
```
@@ -3154,7 +3175,7 @@ The [`$count`](#SystemQueryOptioncount) segment may be used within a
count of related entities or items within a collection-valued property.
::: example
-Example 49: return all Categories with less than 10 products
+Example 51: return all Categories with less than 10 products
```
GET http://host/service/Categories?$filter=Products/$count lt 10
```
@@ -3278,7 +3299,7 @@ alias, and the query option value is the value to be used for the
specified parameter alias.
::: example
-Example 50: returns all employees whose Region property matches the
+Example 52: returns all employees whose Region property matches the
string parameter value `WA`
```
GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'
@@ -3305,7 +3326,7 @@ MAY be nested within `$expand` and
`$select`, in which case they are evaluated relative to the resource context of the `$expand` or `$select`.
::: example
-Example 51: returns all employees, expands their manager, and expands
+Example 53: returns all employees, expands their manager, and expands
all direct reports with the same first name as the manager, using a
parameter alias for `$this` to pass the manager into the filter on the
expanded direct reports
@@ -3352,7 +3373,7 @@ see [OData-VocCore](#ODataVocCore).
Values of type `Edm.Stream` or any of the `Geo` types cannot be sorted.
::: example
-Example 52: return all Products ordered by release date in ascending
+Example 54: return all Products ordered by release date in ascending
order, then by rating in descending order
```
GET http://host/service/Products?$orderby=ReleaseDate asc, Rating desc
@@ -3363,7 +3384,7 @@ Related entities may be ordered by specifying `$orderby` within the
`$expand` clause.
::: example
-Example 53: return all Categories, and their Products ordered according
+Example 55: return all Categories, and their Products ordered according
to release date and in descending order of rating
```
GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)
@@ -3375,7 +3396,7 @@ returned items according to the exact count of related entities or items
within a collection-valued property.
::: example
-Example 54: return all Categories ordered by the number of Products
+Example 56: return all Categories ordered by the number of Products
within each category
```
GET http://host/service/Categories?$orderby=Products/$count
@@ -3398,7 +3419,7 @@ consists of the first $n$ instances in $A$. Otherwise, the result equals $A$.
The instances in the result are in the same order as they occur in $A$.
::: example
-Example 55: return only the first five products of the Products entity
+Example 57: return only the first five products of the Products entity
set
```
GET http://host/service/Products?$top=5
@@ -3422,7 +3443,7 @@ from the result and all remaining instances are kept in the same order as
they occur in $A$.
::: example
-Example 56: return products starting with the 6th product of the
+Example 58: return products starting with the 6th product of the
`Products` entity set
```
GET http://host/service/Products?$skip=5
@@ -3434,7 +3455,7 @@ Where [`$top`](#SystemQueryOptiontop) and `$skip` are used together,
they appear in the request.
::: example
-Example 57: return the third through seventh products of the `Products`
+Example 59: return the third through seventh products of the `Products`
entity set
```
GET http://host/service/Products?$top=5&$skip=2
@@ -3452,7 +3473,7 @@ the total count of items within a collection matching the request be
returned along with the result.
::: example
-Example 58: return, along with the results, the total number of products
+Example 60: return, along with the results, the total number of products
in the collection
```
GET http://host/service/Products?$count=true
@@ -3463,7 +3484,7 @@ The count of related entities can be requested by specifying
the `$count` query option within the `$expand` clause.
::: example
-Example 59:
+Example 61:
```
GET http://host/service/Categories?$expand=Products($count=true)
```
@@ -3495,7 +3516,7 @@ those items *matching* the specified search expression. The definition
of what it means to match is dependent upon the implementation.
::: example
-Example 60: return all Products that match the search term `bike`
+Example 62: return all Products that match the search term `bike`
```
GET http://host/service/Products?$search=bike
```
@@ -3504,7 +3525,7 @@ GET http://host/service/Products?$search=bike
The search expression can contain phrases, enclosed in double-quotes.
::: example
-Example 61: return all Products that match the phrase `mountain bike`
+Example 63: return all Products that match the phrase `mountain bike`
```
GET http://host/service/Products?$search="mountain bike"
```
@@ -3514,7 +3535,7 @@ The upper-case keyword `NOT` restricts the set of entities to those that
do not match the specified term.
::: example
-Example 62: return all Products that do not match `clothing`
+Example 64: return all Products that do not match `clothing`
```
GET http://host/service/Products?$search=NOT clothing
```
@@ -3525,7 +3546,7 @@ Multiple terms within a search expression are separated by a space
such terms must be matched.
::: example
-Example 63: return all Products that match both `mountain` and
+Example 65: return all Products that match both `mountain` and
`bike`
```
GET http://host/service/Products?$search=mountain AND bike
@@ -3536,7 +3557,7 @@ The upper-case keyword `OR` is used to return entities that satisfy
either the immediately preceding or subsequent expression.
::: example
-Example 64: return all Products that match `mountain` or
+Example 66: return all Products that match `mountain` or
`bike`
```
GET http://host/service/Products?$search=mountain OR bike
@@ -3547,7 +3568,7 @@ Parentheses within the search expression group together multiple
expressions.
::: example
-Example 65: return all Products that match `mountain` or
+Example 67: return all Products that match `mountain` or
`bike` and do not match clothing
```
GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothing
@@ -3603,7 +3624,7 @@ Entities are stably addressable using their canonical URL and are not
accessible using an ordinal index.
::: example
-Example 66: the first address in a list of addresses for `MainSupplier`
+Example 68: the first address in a list of addresses for `MainSupplier`
```
GET http://host/service/MainSupplier/Addresses/0
```
@@ -3631,7 +3652,7 @@ entity is related, the service returns
[`204 No Content`](#ResponseCode204NoContent).
::: example
-Example 67: return the supplier of the product with `ID=1` in the
+Example 69: return the supplier of the product with `ID=1` in the
Products entity set
```
GET http://host/service/Products(1)/Supplier
@@ -3670,7 +3691,7 @@ exists, the service returns either
[`404 Not Found`](#ResponseCode404NotFound).
::: example
-Example 68: collection with an entity reference for each Order related
+Example 70: collection with an entity reference for each Order related
to the Product with `ID=0`
```
GET http://host/service/Products(0)/Orders/$ref
@@ -3686,7 +3707,7 @@ the URL `$entity` relative to the service root. The entity-id MUST be
specified using the system query option `$id`.
::: example
-Example 69: return the entity representation for a given entity-id
+Example 71: return the entity representation for a given entity-id
```
GET http://host/service/$entity?$id=http://host/service/Products(0)
```
@@ -3703,7 +3724,7 @@ system query options [`$select`](#SystemQueryOptionselect) and
to the `$entity` resource.
::: example
-Example 70: return the entity representation for a given entity-id and
+Example 72: return the entity representation for a given entity-id and
specify properties to return
```
GET http://host/service/$entity/Model.Customer
@@ -3733,7 +3754,7 @@ SHOULD NOT combine the system query options
The result of such a request is undefined.
::: example
-Example 71: return the number of products in the Products entity set
+Example 73: return the number of products in the Products entity set
```
GET http://host/service/Products/$count
```
@@ -3744,7 +3765,7 @@ the `/$filter` path segment to count the items in the filtered
collection.
::: example
-Example 72: return the number of products whose `Price` is less than
+Example 74: return the number of products whose `Price` is less than
$10.00
```
GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00
@@ -3756,7 +3777,7 @@ combination with the [`$filter`](#SystemQueryOptionfilter) system query
option.
::: example
-Example 73: return the number of products whose `Price` is less than
+Example 75: return the number of products whose `Price` is less than
$10.00
```
GET http://host/service/Products/$count?$filter=Price lt 10.00
@@ -3771,14 +3792,14 @@ The `/$count` suffix can also be used in path expressions within system
query options, e.g. [`$filter`](#SystemQueryOptionfilter).
::: example
-Example 74: return all customers with more than five interests
+Example 76: return all customers with more than five interests
```
GET http://host/service/Customers?$filter=Interests/$count gt 5
```
:::
::: example
-Example 75: return all categories with more than one product over $5.00
+Example 77: return all categories with more than one product over $5.00
```
GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1
```
@@ -3801,7 +3822,7 @@ In addition, format-specific abbreviations may be used, e.g. `json` for
MUST NOT be appended to the format abbreviations.
::: example
-Example 76: the request
+Example 78: the request
```
GET http://host/service/Orders?$format=application/json;metadata=full
```
@@ -3813,7 +3834,7 @@ media type including full metadata, as defined in
[OData-JSON, section 3.1.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull).
::: example
-Example 77: the request
+Example 79: the request
```
GET http://host/service/Orders?$format=json
```
@@ -4239,7 +4260,7 @@ request body.
The representation for referencing related entities is format-specific.
::: example
-Example 78: using the JSON format, 4.0 clients can create a new manager
+Example 80: using the JSON format, 4.0 clients can create a new manager
entity with links to an existing manager (of managers) and to two existing employees by applying the `odata.bind`
annotation to the `Manager` and `DirectReports` navigation properties
@@ -4260,7 +4281,7 @@ annotation to the `Manager` and `DirectReports` navigation properties
:::
::: example
-Example 79: using the JSON format, 4.01 clients can create a new manager
+Example 81: using the JSON format, 4.01 clients can create a new manager
entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids
within the `Manager` and `DirectReports` navigation properties
@@ -4472,7 +4493,7 @@ If a navigation property is absent from a `PUT` or `PATCH` request payload, the
or contained entity, or the collection thereof, remains unchanged by a successful update.
::: example
-Example 80: using the JSON format, a 4.01 `PATCH` request can update a
+Example 82: using the JSON format, a 4.01 `PATCH` request can update a
manager entity. Following the update, the manager has three direct
reports; two existing employees and one new employee named
`Suzanne Brown`. The `LastName` of employee 6 is updated to `Smith`.
@@ -4522,7 +4543,7 @@ entity is to be created. If any nested entities contain both id and key
fields, they MUST identify the same entity, or the request is invalid.
::: example
-Example 81: using the JSON format, a 4.01 `PATCH` request can specify a
+Example 83: using the JSON format, a 4.01 `PATCH` request can specify a
nested delta representation to:
- delete employee 3 and
@@ -4570,7 +4591,7 @@ nested delta representation to:
:::
::: example
-Example 82: When updating an entity with a 4.01 `PUT` request, the target of a
+Example 84: When updating an entity with a 4.01 `PUT` request, the target of a
non-containment navigation property can be replaced if the targeted entity is specified
by an entity reference (see [OData-JSON, section 14](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#EntityReference)), without specifying all
its structural properties in `PUT` semantics.
@@ -4898,7 +4919,7 @@ payload unless explicitly requested with [`$expand`](#SystemQueryOptionexpand).
Instead, the values are generally read or written through URLs.
::: example
-Example 83: read an entity and select a stream property
+Example 85: read an entity and select a stream property
```
GET http://host/service/Products(1)?$select=Thumbnail
@@ -4929,7 +4950,7 @@ The response MAY be a redirect to the media read link of the stream property
if the media read link is different from the canonical URL.
::: example
-Example 84: directly read a stream property of an entity
+Example 86: directly read a stream property of an entity
```
GET http://host/service/Products(1)/Thumbnail
@@ -4980,7 +5001,7 @@ attempts to set the property to null and results in an error if the
property is non-nullable.
::: example
-Example 85: delete the stream value using the media edit link retrieved in [example 83](#entityWithStreamProperty)
+Example 87: delete the stream value using the media edit link retrieved in [example 85](#entityWithStreamProperty)
```
DELETE http://server/uploads/Thumbnail546.jpg
@@ -5134,7 +5155,7 @@ ordinal number indexes from the end of the collection, with -1
representing an insert as the last item in the collection.
::: example
-Example 86: Insert a new email address at the second position
+Example 88: Insert a new email address at the second position
```json
POST /service/Customers('ALFKI')/EmailAddresses?$index=1
@@ -5301,7 +5322,7 @@ semantics described in [Update a Collection of
Entities](#UpdateaCollectionofEntities) applies.
::: example
-Example 87: change the color of all beige-brown products
+Example 89: change the color of all beige-brown products
```json
PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
@@ -5347,7 +5368,7 @@ The request resource path of the collection MAY contain type-cast or
filter segments to subset the collection.
::: example
-Example 88: delete all products older than 3
+Example 90: delete all products older than 3
```
DELETE /service/Products/$filter(Age gt 3)/$each
@@ -5399,7 +5420,7 @@ by that URL is used as the *binding parameter value*. Only aliases
defined in the metadata document of the service can be used in URLs.
::: example
-Example 89: the function `MostRecentOrder` can be bound to any URL that
+Example 91: the function `MostRecentOrder` can be bound to any URL that
identifies a `SampleModel.Customer`
```xml
@@ -5410,7 +5431,7 @@ identifies a `SampleModel.Customer`
:::
::: example
-Example 90: invoke the `MostRecentOrder` function with the value of the
+Example 92: invoke the `MostRecentOrder` function with the value of the
binding parameter `customer` being the entity identified by
`http://host/service/Customers(6)`
```
@@ -5419,7 +5440,7 @@ GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()
:::
::: example
-Example 91: the function `Comparison` can be bound to any URL that
+Example 93: the function `Comparison` can be bound to any URL that
identifies a collection of entities
```xml
@@ -5430,7 +5451,7 @@ identifies a collection of entities
:::
::: example
-Example 92: invoke the `Comparison` function on the set of red products
+Example 94: invoke the `Comparison` function on the set of red products
```
GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()
```
@@ -5453,7 +5474,7 @@ result type of the bound operation. If the bound operation returns a
collection, the response is a collection of collections.
::: example
-Example 93: invoke the `MostRecentOrder` function on each entity in the
+Example 95: invoke the `MostRecentOrder` function on each entity in the
entity set `Customers`
```
GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()
@@ -5481,7 +5502,7 @@ or entity collection within the payload. The representation of an action
or function depends on the [format](#Formats).
::: example
-Example 94: given a `GET` request to
+Example 96: given a `GET` request to
`http://host/service/Customers('ALFKI')`, the service might respond with
a Customer that includes the `SampleEntities.MostRecentOrder` function
bound to the entity
@@ -5508,7 +5529,7 @@ Services can advertise that a function or action is not available for a
particular instance by setting its value to null.
::: example
-Example 95: the `SampleEntities.MostRecentOrder` function is not
+Example 97: the `SampleEntities.MostRecentOrder` function is not
available for customer `ALFKI`
```json
{
@@ -5592,7 +5613,7 @@ segment is a multi-valued navigation property, a `POST` request may be
used to create a new entity in the identified collection.
::: example
-Example 96: add a new item to the list of items of the shopping cart
+Example 98: add a new item to the list of items of the shopping cart
returned by the composable `MyShoppingCart` function import
```
POST http://host/service/MyShoppingCart()/Items
@@ -5641,7 +5662,7 @@ Each parameter value is represented as a name/value pair in the format
and `Value` is the parameter value.
::: example
-Example 97: invoke a `Sales.EmployeesByManager` function which takes a
+Example 99: invoke a `Sales.EmployeesByManager` function which takes a
single `ManagerID` parameter via the function import
`EmployeesByManager`
```
@@ -5650,7 +5671,7 @@ GET http://host/service/EmployeesByManager(ManagerID=3)
:::
::: example
-Example 98: return all Customers whose `City` property returns
+Example 100: return all Customers whose `City` property returns
`Western` when passed to the `Sales.SalesRegion` function
```
GET http://host/service/Customers?
@@ -5663,7 +5684,7 @@ parameter value. The value for the alias is specified as a separate
query option using the name of the parameter alias.
::: example
-Example 99: invoke a `Sales.EmployeesByManager` function via the
+Example 101: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter
```
@@ -5683,7 +5704,7 @@ optional `$` prefix), the parameter name MUST be prefixed with an at
(`@`) sign.
::: example
-Example 100: invoke a `Sales.EmployeesByManager` function via the
+Example 102: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter using the implicit parameter alias
```
@@ -5823,7 +5844,7 @@ collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
collection response.
::: example
-Example 101: invoke the `SampleEntities.CreateOrder` action using
+Example 103: invoke the `SampleEntities.CreateOrder` action using
`Customers('ALFKI')` as the customer (or binding parameter). The values
`2` for the `quantity` parameter and `BLACKFRIDAY` for the
`discountCode` parameter are passed in the body of the request. Invoke
@@ -5972,7 +5993,7 @@ format](#MultipartBatchFormat) MUST contain a
[RFC2046](#rfc2046).
::: example
-Example 102: multipart batch request
+Example 104: multipart batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -5987,7 +6008,7 @@ A batch request using the JSON batch format MUST contain a
`Content-Type` header specifying a content type of `application/json`.
::: example
-Example 103: JSON batch request
+Example 105: JSON batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -6042,7 +6063,7 @@ the request URL. Services MUST treat this segment like the URL in the
[`Location`](#HeaderLocation) header of the response to the request identified by the segment.
If the `Location` header in the response to the subsequent request contains a relative URL,
clients MUST be able to resolve it relative to the request's URL even if
-that contains such a reference. See [example 108](#batchcontentid).
+that contains such a reference. See [example 110](#batchcontentid).
If the `$`-prefixed request identifier is identical to the name of a
top-level system resource (`$batch`, `$crossjoin`, `$all`, `$entity`,
@@ -6143,7 +6164,7 @@ set can use one of the following three formats:
- Absolute URI with schema, host, port, and absolute resource path.
::: example
-Example 104:
+Example 106:
```
GET https://host:1234/path/service/People(1) HTTP/1.1
```
@@ -6152,7 +6173,7 @@ GET https://host:1234/path/service/People(1) HTTP/1.1
- Absolute resource path and separate `Host` header
::: example
-Example 105:
+Example 107:
```json
PATCH /path/service/People(1) HTTP/1.1
Host: myserver.mydomain.org:1234
@@ -6165,7 +6186,7 @@ Content-Type: application/json
- Resource path relative to the batch request URI.
::: example
-Example 106:
+Example 108:
```
DELETE People(1) HTTP/1.1
```
@@ -6190,7 +6211,7 @@ processor may choose to disallow chunked encoding to be used by such
HTTP requests.
::: example
-Example 107: a batch request that contains the following individual
+Example 109: a batch request that contains the following individual
requests in the order listed
1. A query request
@@ -6269,7 +6290,7 @@ which case they SHOULD advertise this support by specifying the
term applied to the entity container, see [OData-VocCap](#ODataVocCap).
::: example
-Example 108: a batch request that contains the following operations in
+Example 110: a batch request that contains the following operations in
the order listed:
A change set that contains the following requests:
@@ -6341,7 +6362,7 @@ request URL `$1/Orders`. To get an absolute base URI, the client must replace th
resulting URL `Customers('ALFKI')/Orders(1)` relative to its base URI, which is
`http://host/service/Customers` (determined from the
first request URL `/service/Customers` and the `Host: host` header
-as in [example 105](#batchhost)). This gives the effective second request URL
+as in [example 107](#batchhost)). This gives the effective second request URL
`http://host/service/Customers('ALFKI')/Orders` as base URI for the second `Location`
URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(1)`.
:::
@@ -6349,7 +6370,7 @@ URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(
#### 11.7.7.3 Referencing an ETag
::: example
-Example 109: a batch request that contains the following operations in
+Example 111: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6390,7 +6411,7 @@ If-Match: $1
#### 11.7.7.4 Referencing Response Body Values
::: example
-Example 110: a batch request that contains the following operations in
+Example 112: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6483,11 +6504,11 @@ A response to an operation in a batch MUST be formatted exactly as it
would have appeared outside of a batch as described in the corresponding
subsections of chapter [Data Service Requests](#DataServiceRequests).
Relative URLs in each individual response are relative to the request
-URL of the corresponding individual request (see [example 108](#batchcontentid)).
+URL of the corresponding individual request (see [example 110](#batchcontentid)).
URLs in responses MUST NOT contain `$`-prefixed request identifiers.
::: example
-Example 111: referencing the batch request [example 107](#batchRequest) above, assume all
+Example 113: referencing the batch request [example 109](#batchRequest) above, assume all
the requests except the final query request succeed. In this case the
response would be
```
@@ -6563,7 +6584,7 @@ Since a change set is executed atomically,
a change set.
::: example
-Example 112: referencing the [example 107](#batchRequest) above again, assume that
+Example 114: referencing the [example 109](#batchRequest) above again, assume that
```
HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html
index 147e9a2b..b8e50abb 100644
--- a/docs/odata-url-conventions/odata-url-conventions.html
+++ b/docs/odata-url-conventions/odata-url-conventions.html
@@ -379,8 +379,14 @@ Table of Contents
- 5.1.1.18 Numeric Promotion
- 5.1.2 System Query Option
$filter
-- 5.1.3 System Query Option
$expand
-- 5.1.4 System Query Option
$select
+- 5.1.3 System Query Option
$expand
+
+- 5.1.4 System Query Option
$select
+
- 5.1.5 System Query Option
$orderby
- 5.1.6 System Query Options
$top and $skip
- 5.1.7 System Query Option
$count
@@ -2251,7 +2257,7 @@ type-cast segment to expand only related entities of that derived type or one of its sub-types, optionally followed by /$ref to expand only entity references.
+
- a navigation property to expand the related entity or entities, optionally followed by a type-cast segment to expand only related entities of that derived type or one of its sub-types, optionally followed by
/$ref to expand only entity references, or /$count, optionally with expand options, to return only the count of matching entities.
- an entity-valued instance annotation to expand the related entity or entities, optionally followed by a type-cast segment to expand only related entities of that derived type or one of its sub-types.
If a structured type traversed by the path supports neither dynamic properties nor instance annotations, then a corresponding property segment MUST specify a declared property of that structured type. Otherwise, if a traversed type does support dynamic navigation properties or instance annotations and the corresponding property segment does not specify a declared property, then the expanded property appears only for those instances on which it has a value.
@@ -2264,59 +2270,63 @@ $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
-
-Example 124: all categories and for each category all related products with a discontinued date equal to null
-http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
-
-
The $count segment can be appended to a navigation property name or type-cast segment following a navigation property name to return just the count of the related entities. The $filter and $search system query options can be used to limit the number of related entities included in the count.
+The $count segment can be appended to a navigation property name or type-cast segment following a collection-valued navigation property name to return just the count of the related entities. The $filter and $search Expand Options can be used to limit the number of related entities included in the count.
-Example 125: all categories and for each category the number of all related products
+Example 124: all categories and for each category the number of all related products
http://host/service/Categories?$expand=Products/$count
-Example 126: all categories and for each category the number of all related blue products
+Example 125: all categories and for each category the number of all related blue products
http://host/service/Categories?$expand=Products/$count($search=blue)
-To retrieve entity references instead of the related entities, append /$ref to the navigation property name or type-cast segment following a navigation property name. The system query options $filter, $search, $skip, $top, and $count can be used to limit the number of expanded entity references.
+To retrieve entity references instead of the related entities, append /$ref to the navigation property name or type-cast segment following a navigation property name. The Expand Options $filter, $search, $skip, $top, and $count can be used to include the count of expanded entity references.
-Example 127: all categories and for each category the references of all related products
+Example 126: all categories and for each category the references of all related products
http://host/service/Categories?$expand=Products/$ref
-Example 128: all categories and for each category the references of all related products of the derived type Sales.PremierProduct
+Example 127: all categories and for each category the references of all related products of the derived type Sales.PremierProduct
http://host/service/Categories?$expand=Products/Sales.PremierProduct/$ref
-Example 129: all categories and for each category the references of all related premier products with a current promotion equal to null
+Example 128: all categories and for each category the references of all related premier products with a current promotion equal to null
http://host/service/Categories
?$expand=Products/Sales.PremierProduct/$ref($filter=CurrentPromotion eq null)
-Cyclic navigation properties (whose target type is identical or can be cast to its source type) can be recursively expanded using the special $levels option. The value of the $levels option is either a positive integer to specify the number of levels to expand, or the literal string max to specify the maximum expansion level supported by that service. A $levels option with a value of 1 specifies a single expand with no recursion.
-
-Example 130: all employees with their manager, manager’s manager, and manager’s manager’s manager
-http://host/service/Employees?$expand=ReportsTo($levels=3)
-
-It is also possible to expand all declared and dynamic navigation properties using a star (*). To retrieve references to all related entities use */$ref, and to expand all related entities with a certain distance use the star operator with the $levels option. The star operator can be combined with explicitly named navigation properties, which take precedence over the star operator.
+It is also possible to expand all declared and dynamic navigation properties using a star (*). To retrieve references to all related entities use */$ref, and to expand all related entities with a certain distance use the star operator with the $levels Expand Option. The star operator can be combined with explicitly named navigation properties, which take precedence over the star operator.
The star operator does not implicitly include stream properties.
-Example 131: expand Supplier and include references for all other related entities
+Example 129: expand Supplier and include references for all other related entities
http://host/service/Categories?$expand=*/$ref,Supplier
-
-Example 132: expand all related entities and their related entities
-http://host/service/Categories?$expand=*($levels=2)
-
Specifying a stream property includes the media stream inline according to the specified format.
-Example 133: include Employee’s Photo stream property along with other properties of the customer
+Example 130: include Employee’s Photo stream property along with other properties of the customer
http://host/service/Employees?$expand=Photo
Specifying $value for a media entity includes the media entity’s stream value inline according to the specified format.
-Example 134: Include the Product’s media stream along with other properties of the product
+Example 131: Include the Product’s media stream along with other properties of the product
http://host/service/Products?$expand=$value
+
+5.1.3.1 Expand Options
+
+Query options can be applied to an expanded navigation property by appending a semicolon-separated list of query options, enclosed in parentheses, to the navigation property name. The system query option, irrespective of casing or whether or not it is prefixed with a $, MUST NOT be specified more than once in the list. Allowed system query options are $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
+
+Example 132: all categories and for each category all related products with a discontinued date equal to null
+http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
+
+Cyclic navigation properties (whose target type is identical or can be cast to its source type) can be recursively expanded using the special $levels expand option. The value of the $levels expand option is either a positive integer to specify the number of levels to expand, or the literal string max to specify the maximum expansion level supported by that service. A $levels option with a value of 1 specifies a single expand with no recursion.
+
+Example 133: all employees with their manager, manager’s manager, and manager’s manager’s manager
+http://host/service/Employees?$expand=ReportsTo($levels=3)
+
+
+Example 134: expand all related entities and their related entities
+http://host/service/Categories?$expand=*($levels=2)
+
+
5.1.4 System Query Option $select
@@ -2326,14 +2336,14 @@ OData-ABNF select syntax rule defines the formal grammar of the $select query option.
The value of $select is a comma-separated list of select items. Each select item is one of the following:
-- a path, to include a property,
+- a path, optionally followed by a count segment or select options
- a star (
*), to include all declared or dynamic properties of the type, or
- a qualified schema name followed by a dot (
.) followed by a star (*) to request all applicable actions or functions from that schema
A path consists of segments separated by a forward slash (/). Segments are either names of single- or collection-valued complex properties, instance annotations, or type-cast segments consisting of the qualified name of a structured type that is derived from the type identified by the preceding path segment to reach properties defined on the derived type.
A path can end with
-- the name of a property or non-entity-valued instance annotation of the identified instance of a structured type,
+- the name of a property or non-entity-valued instance annotation of the identified instance of a structured type
- the qualified name of a bound action,
- the qualified name of a bound function to include all matching overloads, or
- the qualified name of a bound function followed by parentheses containing the comma-separated lists of non-binding parameters identifying a single overload.
@@ -2365,13 +2375,14 @@ System Query Options, with the exception of $expand. The same property MUST NOT have select options specified in more than one place in a request and MUST NOT be specified in more than one expand.
+
If the path ends in a collection of primitive or complex values, then the count segment (/$count), optionally followed by the Select Options $filter and/or $search, can be appended to the path in order to return only the count of the matching items.
-Example 139: select up to five addresses whose City starts with an H, sorted, and with the Country expanded
-http://host/service/Customers
- ?$select=Addresses($filter=startswith(City,'H');$top=5;
- $orderby=Country/Name,City,Street)
- &$expand=Addresses/Country
+Example 139: for each Customer, return the ID and the count of Addresses
+http://host/service/Customers?$select=ID,Addresses/$count
+
+
+Example 140: for each Customer, return the ID and the count of Addresses whose City starts with ‘H’
+http://host/service/Customers?$select=ID,Addresses/$count($filter=startswith(City,'H'))
Any structural property, non-expanded navigation property, or operation not requested as a select item (explicitly or via a star) SHOULD be omitted from the response.
Annotations requested in $select MUST be included in the response; $select overrules the include-annotations preference (see OData-Protocol, section 8.2.8.4) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via $select. The Preference-Applied response header only reflects the set of annotations included due to the include-annotations preference and not those only included due to $select.
@@ -2379,10 +2390,27 @@
-Example 140: the ID property, the ActionName action defined in Model and all actions and functions defined in the Model2 for each product if those actions and functions can be bound to that product
+Example 141: the ID property, the ActionName action defined in Model and all actions and functions defined in the Model2 for each product if those actions and functions can be bound to that product
http://host/service/Products?$select=ID,Model.ActionName,Model2.*
When multiple select item exist in a $select clause, then the total set of properties, open properties, navigation properties, actions and functions to be returned is equal to the union of the set of those identified by each select item.
+
+5.1.4.1 SelectOptions
+
+Query options can be applied to a select item that is a path to a single complex value or a collection of primitive or complex values by appending a semicolon-separated list of query options, enclosed in parentheses, to the select item. The allowed system query options depend on the type of the resource identified by the select item, see section System Query Options, with the exception of $expand. The same property MUST NOT have select options specified in more than one place in a request and MUST NOT be specified in more than one expand.
+If the select item is a complex type, or collection of complex types, then it can include a nested select.
+
+Example 142: return the City from the Address complex type
+http://host/service/Customers?$select=Address($select=City)
+
+
+Example 143: select up to five addresses whose City starts with an H, sorted, and with the Country expanded
+http://host/service/Customers
+ ?$select=Addresses($filter=startswith(City,'H');$top=5;
+ $orderby=Country/Name,City,Street)
+ &$expand=Addresses/Country
+
+
5.1.5 System Query Option $orderby
@@ -2411,7 +2439,7 @@ $filter are applied to the same request, the results include only those items that match both criteria.
The OData-ABNF search syntax rule defines the formal grammar of the $search query option.
-Example 141: all products that are blue or green. It is up to the service to decide what makes a product blue or green.
+Example 144: all products that are blue or green. It is up to the service to decide what makes a product blue or green.
http://host/service/Products?$search=blue OR green
Clients should be aware that services MAY implement search based on a different syntax provided they advertise this with the annotation SearchRestrictions/SearchSyntax defined in OData-VocCap. Services MAY treat keywords defined in the standard OData-ABNF $search syntax as terms to be matched if they are listed in SearchRestrictions/UnsupportedExpressions.
@@ -2447,7 +2475,7 @@ The OData-ABNF compute syntax rule defines the formal grammar of the $compute query option.
Computed properties SHOULD be included as dynamic properties in the result and MUST be included if $select is specified with the computed property name, or star (*).
-Example 142: compute total price for order items
+Example 145: compute total price for order items
http://host/service/Orders(10)/Items
?$select=Product/Description,Total
&$filter=Total gt 100
@@ -2474,7 +2502,7 @@ OData-ABNF.
Custom query options MUST NOT begin with a $ or @ character.
-Example 143: service-specific custom query option debug-mode
+Example 146: service-specific custom query option debug-mode
http://host/service/Products?debug-mode=true
@@ -2485,15 +2513,15 @@
Parameter aliases MUST start with an @ character, see rule parameterAlias in OData-ABNF.
The semantics of parameter aliases are covered in OData-Protocol, section 11.2.6.1.3. The OData-ABNF rule aliasAndValue defines the formal grammar for passing parameter alias values as query options.
-Example 144:
+Example 147:
http://host/service/Movies?$filter=contains(@word,Title)&@word='Black'
-Example 145:
+Example 148:
http://host/service/Movies?$filter=Title eq @title&@title='Wizard of Oz'
-Example 146: JSON array of strings as parameter alias value — note that [, ], and " need to be percent-encoded in real URLs, the clear-text representation used here is just for readability
+Example 149: JSON array of strings as parameter alias value — note that [, ], and " need to be percent-encoded in real URLs, the clear-text representation used here is just for readability
http://host/service/Products/Model.WithIngredients(Ingredients=@i)
?@i=["Carrots","Ginger","Oranges"]
diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md
index 3ed0a793..26da05b1 100644
--- a/docs/odata-url-conventions/odata-url-conventions.md
+++ b/docs/odata-url-conventions/odata-url-conventions.md
@@ -220,7 +220,9 @@ For complete copyright information please see the full Notices section in an App
- [5.1.1.18 Numeric Promotion](#NumericPromotion)
- [5.1.2 System Query Option `$filter`](#SystemQueryOptionfilter)
- [5.1.3 System Query Option `$expand`](#SystemQueryOptionexpand)
+ - [5.1.3.1 Expand Options](#ExpandOptions)
- [5.1.4 System Query Option `$select`](#SystemQueryOptionselect)
+ - [5.1.4.1 SelectOptions](#SelectOptions)
- [5.1.5 System Query Option `$orderby`](#SystemQueryOptionorderby)
- [5.1.6 System Query Options `$top` and `$skip`](#SystemQueryOptionstopandskip)
- [5.1.7 System Query Option `$count`](#SystemQueryOptioncount)
@@ -3589,7 +3591,7 @@ properties of the identified instances of a structured type, optionally followed
related entity or entities, optionally followed by a [type-cast segment](#AddressingDerivedTypes)
to expand only related entities of that derived type or one of its
sub-types, optionally followed by `/$ref` to expand only entity
-references.
+references, or `/$count`, optionally with expand options, to return only the count of matching entities.
- an entity-valued instance annotation to
expand the related entity or entities, optionally followed by a
[type-cast segment](#AddressingDerivedTypes) to expand only related entities of that derived type
@@ -3619,39 +3621,14 @@ http://host/service/Customers?$expand=Addresses/Country
A path MUST NOT appear in more than one expand item.
-Query options can be applied to an expanded navigation property by
-appending a semicolon-separated list of query options, enclosed in
-parentheses, to the navigation property name.
-The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
-MUST NOT be specified more than once in the list.
-Allowed system query options are
-[`$compute`](#SystemQueryOptioncompute),
-[`$select`](#SystemQueryOptionselect),
-`$expand`, and
-[`$levels`](#ExpandOptionlevels) for all navigation properties, plus
-[`$filter`](#SystemQueryOptionfilter),
-[`$orderby`](#SystemQueryOptionorderby),
-[`$skip`](#SystemQueryOptionstopandskip), [`$top`](#SystemQueryOptionstopandskip),
-[`$count`](#SystemQueryOptioncount), and
-[`$search`](#SystemQueryOptionsearch)
-for collection-valued navigation properties.
-
-::: example
-Example 124: all categories and for each category all related products
-with a discontinued date equal to `null`
-```
-http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
-```
-:::
-
The `$count` segment can be appended to a navigation property name or
-[type-cast segment](#AddressingDerivedTypes) following a navigation
+[type-cast segment](#AddressingDerivedTypes) following a collection-valued navigation
property name to return just the count of the related entities. The
-`$filter` and `$search` system query options can be used to limit the
-number of related entities included in the count.
+[`$filter`](#SystemQueryOptionfilter) and [`$search`](#SystemQueryOptionsearch) [Expand Options](#ExpandOptions)
+can be used to limit the number of related entities included in the count.
::: example
-Example 125: all categories and for each category the number of all
+Example 124: all categories and for each category the number of all
related products
```
http://host/service/Categories?$expand=Products/$count
@@ -3659,7 +3636,7 @@ http://host/service/Categories?$expand=Products/$count
:::
::: example
-Example 126: all categories and for each category the number of all
+Example 125: all categories and for each category the number of all
related blue products
```
http://host/service/Categories?$expand=Products/$count($search=blue)
@@ -3668,15 +3645,15 @@ http://host/service/Categories?$expand=Products/$count($search=blue)
To retrieve entity references instead of the related entities, append
`/$ref` to the navigation property name or [type-cast segment](#AddressingDerivedTypes) following a navigation property name.
-The system query options [`$filter`](#SystemQueryOptionfilter),
+The [Expand Options](#ExpandOptions) [`$filter`](#SystemQueryOptionfilter),
[`$search`](#SystemQueryOptionsearch),
[`$skip`](#SystemQueryOptionstopandskip),
[`$top`](#SystemQueryOptionstopandskip), and
-[`$count`](#SystemQueryOptioncount) can be used to limit the number of
+[`$count`](#SystemQueryOptioncount) can be used to include the count of
expanded entity references.
::: example
-Example 127: all categories and for each category the references of all
+Example 126: all categories and for each category the references of all
related products
```
http://host/service/Categories?$expand=Products/$ref
@@ -3684,7 +3661,7 @@ http://host/service/Categories?$expand=Products/$ref
:::
::: example
-Example 128: all categories and for each category the references of all
+Example 127: all categories and for each category the references of all
related products of the derived type `Sales.PremierProduct`
```
http://host/service/Categories?$expand=Products/Sales.PremierProduct/$ref
@@ -3692,7 +3669,7 @@ http://host/service/Categories?$expand=Products/Sales.PremierProduct/$ref
:::
::: example
-Example 129: all categories and for each category the references of all
+Example 128: all categories and for each category the references of all
related premier products with a current promotion equal to `null`
```
http://host/service/Categories
@@ -3700,51 +3677,27 @@ http://host/service/Categories
```
:::
-[Cyclic navigation properties]{id=ExpandOptionlevels} (whose target type is identical or can be
-cast to its source type) can be recursively expanded using the special
-`$levels` option. The value of the `$levels` option is either a positive
-integer to specify the number of levels to expand, or the literal string
-`max` to specify the maximum expansion level supported by that service.
-A `$levels` option with a value of 1 specifies a single expand with no
-recursion.
-
-::: example
-Example 130: all employees with their manager, manager's manager, and
-manager's manager's manager
-```
-http://host/service/Employees?$expand=ReportsTo($levels=3)
-```
-:::
-
It is also possible to expand all declared and dynamic navigation
properties using a star (`*`). To retrieve references to all related
entities use `*/$ref`, and to expand all related entities with a certain
-distance use the star operator with the `$levels` option. The star
-operator can be combined with explicitly named navigation properties,
+distance use the star operator with the `$levels` [Expand Option](#ExpandOptionlevels). The star operator can be combined with explicitly named navigation properties,
which take precedence over the star operator.
The star operator does not implicitly include stream properties.
::: example
-Example 131: expand `Supplier` and include references for all other
+Example 129: expand `Supplier` and include references for all other
related entities
```
http://host/service/Categories?$expand=*/$ref,Supplier
```
:::
-::: example
-Example 132: expand all related entities and their related entities
-```
-http://host/service/Categories?$expand=*($levels=2)
-```
-:::
-
Specifying a stream property includes the media stream inline according
to the specified format.
::: example
-Example 133: include Employee's `Photo` stream property along with other
+Example 130: include Employee's `Photo` stream property along with other
properties of the customer
```
http://host/service/Employees?$expand=Photo
@@ -3755,13 +3708,63 @@ Specifying `$value` for a media entity includes the media entity's
stream value inline according to the specified format.
::: example
-Example 134: Include the Product's media stream along with other
+Example 131: Include the Product's media stream along with other
properties of the product
```
http://host/service/Products?$expand=$value
```
:::
+#### 5.1.3.1 Expand Options
+
+Query options can be applied to an expanded navigation property by
+appending a semicolon-separated list of query options, enclosed in
+parentheses, to the navigation property name.
+The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
+MUST NOT be specified more than once in the list.
+Allowed system query options are
+[`$compute`](#SystemQueryOptioncompute),
+[`$select`](#SystemQueryOptionselect),
+`$expand`, and
+[`$levels`](#ExpandOptionlevels) for all navigation properties, plus
+[`$filter`](#SystemQueryOptionfilter),
+[`$orderby`](#SystemQueryOptionorderby),
+[`$skip`](#SystemQueryOptionstopandskip), [`$top`](#SystemQueryOptionstopandskip),
+[`$count`](#SystemQueryOptioncount), and
+[`$search`](#SystemQueryOptionsearch)
+for collection-valued navigation properties.
+
+::: example
+Example 132: all categories and for each category all related products
+with a discontinued date equal to `null`
+```
+http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
+```
+:::
+
+[Cyclic navigation properties]{id=ExpandOptionlevels} (whose target type is identical or can be
+cast to its source type) can be recursively expanded using the special
+`$levels` expand option. The value of the `$levels` expand option is either a positive
+integer to specify the number of levels to expand, or the literal string
+`max` to specify the maximum expansion level supported by that service.
+A `$levels` option with a value of 1 specifies a single expand with no
+recursion.
+
+::: example
+Example 133: all employees with their manager, manager's manager, and
+manager's manager's manager
+```
+http://host/service/Employees?$expand=ReportsTo($levels=3)
+```
+:::
+
+::: example
+Example 134: expand all related entities and their related entities
+```
+http://host/service/Categories?$expand=*($levels=2)
+```
+:::
+
### 5.1.4 System Query Option `$select`
The `$select` system query option allows clients to request a specific
@@ -3779,7 +3782,7 @@ grammar of the `$select` query option.
The value of `$select` is a comma-separated list of select items. Each
select item is one of the following:
-- a path, to include a property,
+- a path, optionally followed by a count segment or select options
- a star (`*`), to include all declared or
dynamic properties of the type, or
- a qualified schema name followed by a
@@ -3796,7 +3799,7 @@ properties defined on the derived type.
A path can end with
- the name of a property or
non-entity-valued instance annotation of the identified
-instance of a structured type,
+instance of a structured type
- the qualified name of a bound action,
- the qualified name of a bound function
to include all matching overloads, or
@@ -3866,8 +3869,8 @@ in order to select a property defined on a type derived from the type of
the resource segment.
A select item that is a complex type or collection of complex type can
-be followed by a forward slash, an optional [type-cast segment](#AddressingDerivedTypes), and the name of a property of the
-complex type (and so on for nested complex types).
+be followed by a forward slash, an optional [type-cast segment](#AddressingDerivedTypes),
+and the name of a property of the complex type (and so on for nested complex types).
::: example
Example 138: the `AccountRepresentative` property of any supplier that
@@ -3881,24 +3884,20 @@ http://host/service/Suppliers
```
:::
-Query options can be applied to a select item that is a path to a single
-complex value or a collection of primitive or complex values by
-appending a semicolon-separated list of query options, enclosed in
-parentheses, to the select item. The allowed system query options depend
-on the type of the resource identified by the select item, see section
-[System Query Options](#SystemQueryOptions), with the exception of
-[`$expand`](#SystemQueryOptionexpand). The same property MUST NOT have
-select options specified in more than one place in a request and MUST
-NOT be specified in more than one expand.
+If the path ends in a collection of primitive or complex values, then the count segment (`/$count`), optionally followed by the [Select Options](#SelectOptions) [`$filter`](#SystemQueryOptionfilter)
+and/or [`$search`](#SystemQueryOptionsearch), can be appended to the path in order to return only the count of the matching items.
::: example
-Example 139: select up to five addresses whose `City` starts with an
-`H`, sorted, and with the `Country` expanded
+Example 139: for each `Customer`, return the `ID` and the count of `Addresses`
```
-http://host/service/Customers
- ?$select=Addresses($filter=startswith(City,'H');$top=5;
- $orderby=Country/Name,City,Street)
- &$expand=Addresses/Country
+http://host/service/Customers?$select=ID,Addresses/$count
+```
+:::
+
+::: example
+Example 140: for each `Customer`, return the `ID` and the count of `Addresses` whose `City` starts with 'H'
+```
+http://host/service/Customers?$select=ID,Addresses/$count($filter=startswith(City,'H'))
```
:::
@@ -3929,7 +3928,7 @@ qualified name and that operation cannot be bound to the entities
requested, the service MUST ignore the select item.
::: example
-Example 140: the `ID` property, the `ActionName` action defined in
+Example 141: the `ID` property, the `ActionName` action defined in
`Model` and all actions and functions defined in the `Model2` for each
product if those actions and functions can be bound to that product
```
@@ -3942,6 +3941,39 @@ of properties, open properties, navigation properties, actions and
functions to be returned is equal to the union of the set of those
identified by each select item.
+#### 5.1.4.1 SelectOptions
+
+Query options can be applied to a select item that is a path to a single
+complex value or a collection of primitive or complex values by
+appending a semicolon-separated list of query options, enclosed in
+parentheses, to the select item. The allowed system query options depend
+on the type of the resource identified by the select item, see section
+[System Query Options](#SystemQueryOptions), with the exception of
+[`$expand`](#SystemQueryOptionexpand). The same property MUST NOT have
+select options specified in more than one place in a request and MUST
+NOT be specified in more than one expand.
+
+If the select item is a complex type, or collection of complex types, then
+it can include a nested select.
+
+::: example
+Example 142: return the City from the Address complex type
+```
+http://host/service/Customers?$select=Address($select=City)
+```
+:::
+
+::: example
+Example 143: select up to five addresses whose `City` starts with an
+`H`, sorted, and with the `Country` expanded
+```
+http://host/service/Customers
+ ?$select=Addresses($filter=startswith(City,'H');$top=5;
+ $orderby=Country/Name,City,Street)
+ &$expand=Addresses/Country
+```
+:::
+
### 5.1.5 System Query Option `$orderby`
The `$orderby` system query option allows clients to request resources
@@ -3994,7 +4026,7 @@ The [OData-ABNF](#ODataABNF) `search` syntax rule defines the formal
grammar of the `$search` query option.
::: example
-Example 141: all products that are blue or green. It is up to the
+Example 144: all products that are blue or green. It is up to the
service to decide what makes a product blue or green.
```
http://host/service/Products?$search=blue OR green
@@ -4088,7 +4120,7 @@ result and MUST be included if `$select` is specified with the computed
property name, or star (`*`).
::: example
-Example 142: compute total price for order items
+Example 145: compute total price for order items
```
http://host/service/Orders(10)/Items
?$select=Product/Description,Total
@@ -4132,7 +4164,7 @@ custom query option is any query option of the form shown by the rule
Custom query options MUST NOT begin with a `$` or `@` character.
::: example
-Example 143: service-specific custom query option `debug-mode`
+Example 146: service-specific custom query option `debug-mode`
```
http://host/service/Products?debug-mode=true
```
@@ -4154,21 +4186,21 @@ The semantics of parameter aliases are covered in
values as query options.
::: example
-Example 144:
+Example 147:
```
http://host/service/Movies?$filter=contains(@word,Title)&@word='Black'
```
:::
::: example
-Example 145:
+Example 148:
```
http://host/service/Movies?$filter=Title eq @title&@title='Wizard of Oz'
```
:::
::: example
-Example 146: JSON array of strings as parameter alias value --- note that
+Example 149: JSON array of strings as parameter alias value --- note that
`[`, `]`, and `"` need to be percent-encoded in real URLs, the
clear-text representation used here is just for readability
```
diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md
index 229b5547..d664373b 100644
--- a/odata-protocol/11 Data Service Requests.md
+++ b/odata-protocol/11 Data Service Requests.md
@@ -336,7 +336,7 @@ GET http://host/service/Products?$select=*
:::
Properties of related entities can be specified by including the
-`$select` query option within the `$expand`.
+`$select` [option](#ExpandOptions) within the `$expand`.
::: example
Example ##ex:
@@ -370,19 +370,19 @@ GET http://host/service/Products?$select=DemoService.*
```
:::
-Query options can be applied to a selected property by appending a
-semicolon-separated list of query options, enclosed in parentheses, to
-the property. Allowed system query options are
-[`$select`](#SystemQueryOptionselect) and
-[`$compute`](#SystemQueryOptioncompute) for complex properties, plus
-[`$filter`](#SystemQueryOptionfilter),
-[`$search`](#SystemQueryOptionsearch),
-[`$count`](#SystemQueryOptioncount),
-[`$orderby`](#SystemQueryOptionorderby),
-[`$skip`](#SystemQueryOptionskip), and [`$top`](#SystemQueryOptiontop)
-for collection-valued properties. A property MUST NOT have select
-options specified in more than one place in a request and MUST NOT have
-both select options and expand options specified.
+If the selected property represents a collection of primitive or complex values,
+then the [count segment](#RequestingtheNumberofItemsinaCollection) (`/$count`),
+optionally followed by the [Select Options](#SelectOptions) [`$filter`](#SystemQueryOptionfilter)
+and/or [`$search`](#SystemQueryOptionsearch), can be appended to the path in order
+to return only the count of the matching items.
+
+::: example
+Example ##ex: for each customer, return the ID and the count of addresses
+starting with the letter 'H'.
+```
+GET http://host/service/Customers?$select=ID,Addresses/$count(startswith(City,'H'))
+```
+:::
If the `$select` query option is not specified, the service returns
the full set of properties or a default set of properties. The default
@@ -400,6 +400,22 @@ the [context URL](#ContextURL) MUST reflect the set of selected
properties and projected [expanded](#SystemQueryOptionexpand) navigation
properties.
+##### ##subsubsubsubsec Select Options
+
+Query options can be applied to a selected property by appending a
+semicolon-separated list of query options, enclosed in parentheses, to
+the property. Allowed system query options are
+[`$select`](#SystemQueryOptionselect) and
+[`$compute`](#SystemQueryOptioncompute) for complex properties, plus
+[`$filter`](#SystemQueryOptionfilter),
+[`$search`](#SystemQueryOptionsearch),
+[`$count`](#SystemQueryOptioncount),
+[`$orderby`](#SystemQueryOptionorderby),
+[`$skip`](#SystemQueryOptionskip), and [`$top`](#SystemQueryOptiontop)
+for collection-valued properties. A property MUST NOT have select
+options specified in more than one place in a request and MUST NOT have
+both select options and expand options specified.
+
#### ##subsubsubsec System Query Option `$expand`
The `$expand` system query option indicates the related entities and
@@ -437,6 +453,20 @@ GET http://host/service.svc/Customers?$expand=Photo
```
:::
+If the expand item represents a collection of entities, then the
+[count segment](#RequestingtheNumberofItemsinaCollection) (`/$count`), optionally followed by
+the [Expand Options](#ExpandOptions) [`$filter`](#SystemQueryOptionfilter) and/or
+[`$search`](#SystemQueryOptionsearch), can be appended to the expand item in order to
+return only the count of matching items.
+
+::: example
+Example ##ex: for each Category, return the `Name` and the count of `Products`
+starting with the letter 'H'.
+```
+GET http://host/service/Categories?$select=Name&$expand=Products/$count(startswith(Name,'H'))
+```
+:::
+
##### ##subsubsubsubsec Expand Options
The set of expanded entities can be further refined through the
@@ -452,7 +482,8 @@ Allowed system query options are
for all navigation properties, plus
[`$filter`](#SystemQueryOptionfilter),
[`$orderby`](#SystemQueryOptionorderby),
-[`$skip`](#SystemQueryOptionskip), [`$top`](#SystemQueryOptiontop),
+[`$skip`](#SystemQueryOptionskip),
+[`$top`](#SystemQueryOptiontop),
[`$count`](#SystemQueryOptioncount), and
[`$search`](#SystemQueryOptionsearch)
for collection-valued navigation properties.
diff --git a/odata-url-conventions/5 Query Options.md b/odata-url-conventions/5 Query Options.md
index d82a7de5..60cb84db 100644
--- a/odata-url-conventions/5 Query Options.md
+++ b/odata-url-conventions/5 Query Options.md
@@ -2017,7 +2017,8 @@ properties of the identified instances of a structured type, optionally followed
related entity or entities, optionally followed by a [type-cast segment](#AddressingDerivedTypes)
to expand only related entities of that derived type or one of its
sub-types, optionally followed by `/$ref` to expand only entity
-references.
+references, or `/$count`, optionally with expand options, to return only the count of
+matching entities.
- an entity-valued instance annotation to
expand the related entity or entities, optionally followed by a
[type-cast segment](#AddressingDerivedTypes) to expand only related entities of that derived type
@@ -2047,36 +2048,12 @@ http://host/service/Customers?$expand=Addresses/Country
A path MUST NOT appear in more than one expand item.
-Query options can be applied to an expanded navigation property by
-appending a semicolon-separated list of query options, enclosed in
-parentheses, to the navigation property name.
-The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
-MUST NOT be specified more than once in the list.
-Allowed system query options are
-[`$compute`](#SystemQueryOptioncompute),
-[`$select`](#SystemQueryOptionselect),
-`$expand`, and
-[`$levels`](#ExpandOptionlevels) for all navigation properties, plus
-[`$filter`](#SystemQueryOptionfilter),
-[`$orderby`](#SystemQueryOptionorderby),
-[`$skip`](#SystemQueryOptionstopandskip), [`$top`](#SystemQueryOptionstopandskip),
-[`$count`](#SystemQueryOptioncount), and
-[`$search`](#SystemQueryOptionsearch)
-for collection-valued navigation properties.
-
-::: example
-Example ##ex: all categories and for each category all related products
-with a discontinued date equal to `null`
-```
-http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
-```
-:::
-
The `$count` segment can be appended to a navigation property name or
-[type-cast segment](#AddressingDerivedTypes) following a navigation
+[type-cast segment](#AddressingDerivedTypes) following a collection-valued navigation
property name to return just the count of the related entities. The
-`$filter` and `$search` system query options can be used to limit the
-number of related entities included in the count.
+[`$filter`](#SystemQueryOptionfilter) and [`$search`](#SystemQueryOptionsearch)
+[Expand Options](#ExpandOptions)
+can be used to limit the number of related entities included in the count.
::: example
Example ##ex: all categories and for each category the number of all
@@ -2096,11 +2073,11 @@ http://host/service/Categories?$expand=Products/$count($search=blue)
To retrieve entity references instead of the related entities, append
`/$ref` to the navigation property name or [type-cast segment](#AddressingDerivedTypes) following a navigation property name.
-The system query options [`$filter`](#SystemQueryOptionfilter),
+The [Expand Options](#ExpandOptions) [`$filter`](#SystemQueryOptionfilter),
[`$search`](#SystemQueryOptionsearch),
[`$skip`](#SystemQueryOptionstopandskip),
[`$top`](#SystemQueryOptionstopandskip), and
-[`$count`](#SystemQueryOptioncount) can be used to limit the number of
+[`$count`](#SystemQueryOptioncount) can be used to include the count of
expanded entity references.
::: example
@@ -2128,27 +2105,11 @@ http://host/service/Categories
```
:::
-[Cyclic navigation properties]{id=ExpandOptionlevels} (whose target type is identical or can be
-cast to its source type) can be recursively expanded using the special
-`$levels` option. The value of the `$levels` option is either a positive
-integer to specify the number of levels to expand, or the literal string
-`max` to specify the maximum expansion level supported by that service.
-A `$levels` option with a value of 1 specifies a single expand with no
-recursion.
-
-::: example
-Example ##ex: all employees with their manager, manager's manager, and
-manager's manager's manager
-```
-http://host/service/Employees?$expand=ReportsTo($levels=3)
-```
-:::
-
It is also possible to expand all declared and dynamic navigation
properties using a star (`*`). To retrieve references to all related
entities use `*/$ref`, and to expand all related entities with a certain
-distance use the star operator with the `$levels` option. The star
-operator can be combined with explicitly named navigation properties,
+distance use the star operator with the `$levels` [Expand Option](#ExpandOptionlevels).
+The star operator can be combined with explicitly named navigation properties,
which take precedence over the star operator.
The star operator does not implicitly include stream properties.
@@ -2161,13 +2122,6 @@ http://host/service/Categories?$expand=*/$ref,Supplier
```
:::
-::: example
-Example ##ex: expand all related entities and their related entities
-```
-http://host/service/Categories?$expand=*($levels=2)
-```
-:::
-
Specifying a stream property includes the media stream inline according
to the specified format.
@@ -2190,6 +2144,56 @@ http://host/service/Products?$expand=$value
```
:::
+#### ##subsubsubsec Expand Options
+
+Query options can be applied to an expanded navigation property by
+appending a semicolon-separated list of query options, enclosed in
+parentheses, to the navigation property name.
+The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
+MUST NOT be specified more than once in the list.
+Allowed system query options are
+[`$compute`](#SystemQueryOptioncompute),
+[`$select`](#SystemQueryOptionselect),
+`$expand`, and
+[`$levels`](#ExpandOptionlevels) for all navigation properties, plus
+[`$filter`](#SystemQueryOptionfilter),
+[`$orderby`](#SystemQueryOptionorderby),
+[`$skip`](#SystemQueryOptionstopandskip), [`$top`](#SystemQueryOptionstopandskip),
+[`$count`](#SystemQueryOptioncount), and
+[`$search`](#SystemQueryOptionsearch)
+for collection-valued navigation properties.
+
+::: example
+Example ##ex: all categories and for each category all related products
+with a discontinued date equal to `null`
+```
+http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
+```
+:::
+
+[Cyclic navigation properties]{id=ExpandOptionlevels} (whose target type is identical or can be
+cast to its source type) can be recursively expanded using the special
+`$levels` expand option. The value of the `$levels` expand option is either a positive
+integer to specify the number of levels to expand, or the literal string
+`max` to specify the maximum expansion level supported by that service.
+A `$levels` option with a value of 1 specifies a single expand with no
+recursion.
+
+::: example
+Example ##ex: all employees with their manager, manager's manager, and
+manager's manager's manager
+```
+http://host/service/Employees?$expand=ReportsTo($levels=3)
+```
+:::
+
+::: example
+Example ##ex: expand all related entities and their related entities
+```
+http://host/service/Categories?$expand=*($levels=2)
+```
+:::
+
### ##subsubsec System Query Option `$select`
The `$select` system query option allows clients to request a specific
@@ -2207,7 +2211,7 @@ grammar of the `$select` query option.
The value of `$select` is a comma-separated list of select items. Each
select item is one of the following:
-- a path, to include a property,
+- a path, optionally followed by a count segment or select options
- a star (`*`), to include all declared or
dynamic properties of the type, or
- a qualified schema name followed by a
@@ -2224,7 +2228,7 @@ properties defined on the derived type.
A path can end with
- the name of a property or
non-entity-valued instance annotation of the identified
-instance of a structured type,
+instance of a structured type
- the qualified name of a bound action,
- the qualified name of a bound function
to include all matching overloads, or
@@ -2294,8 +2298,8 @@ in order to select a property defined on a type derived from the type of
the resource segment.
A select item that is a complex type or collection of complex type can
-be followed by a forward slash, an optional [type-cast segment](#AddressingDerivedTypes), and the name of a property of the
-complex type (and so on for nested complex types).
+be followed by a forward slash, an optional [type-cast segment](#AddressingDerivedTypes),
+and the name of a property of the complex type (and so on for nested complex types).
::: example
Example ##ex: the `AccountRepresentative` property of any supplier that
@@ -2309,24 +2313,23 @@ http://host/service/Suppliers
```
:::
-Query options can be applied to a select item that is a path to a single
-complex value or a collection of primitive or complex values by
-appending a semicolon-separated list of query options, enclosed in
-parentheses, to the select item. The allowed system query options depend
-on the type of the resource identified by the select item, see section
-[System Query Options](#SystemQueryOptions), with the exception of
-[`$expand`](#SystemQueryOptionexpand). The same property MUST NOT have
-select options specified in more than one place in a request and MUST
-NOT be specified in more than one expand.
+If the path ends in a collection of primitive or complex values,
+then the count segment (`/$count`), optionally followed by the
+[Select Options](#SelectOptions) [`$filter`](#SystemQueryOptionfilter)
+and/or [`$search`](#SystemQueryOptionsearch), can be
+appended to the path in order to return only the count of the matching items.
::: example
-Example ##ex: select up to five addresses whose `City` starts with an
-`H`, sorted, and with the `Country` expanded
+Example ##ex: for each `Customer`, return the `ID` and the count of `Addresses`
```
-http://host/service/Customers
- ?$select=Addresses($filter=startswith(City,'H');$top=5;
- $orderby=Country/Name,City,Street)
- &$expand=Addresses/Country
+http://host/service/Customers?$select=ID,Addresses/$count
+```
+:::
+
+::: example
+Example ##ex: for each `Customer`, return the `ID` and the count of `Addresses` whose `City` starts with 'H'
+```
+http://host/service/Customers?$select=ID,Addresses/$count($filter=startswith(City,'H'))
```
:::
@@ -2370,6 +2373,39 @@ of properties, open properties, navigation properties, actions and
functions to be returned is equal to the union of the set of those
identified by each select item.
+#### ##subsubsubsec SelectOptions
+
+Query options can be applied to a select item that is a path to a single
+complex value or a collection of primitive or complex values by
+appending a semicolon-separated list of query options, enclosed in
+parentheses, to the select item. The allowed system query options depend
+on the type of the resource identified by the select item, see section
+[System Query Options](#SystemQueryOptions), with the exception of
+[`$expand`](#SystemQueryOptionexpand). The same property MUST NOT have
+select options specified in more than one place in a request and MUST
+NOT be specified in more than one expand.
+
+If the select item is a complex type, or collection of complex types, then
+it can include a nested select.
+
+::: example
+Example ##ex: return the City from the Address complex type
+```
+http://host/service/Customers?$select=Address($select=City)
+```
+:::
+
+::: example
+Example ##ex: select up to five addresses whose `City` starts with an
+`H`, sorted, and with the `Country` expanded
+```
+http://host/service/Customers
+ ?$select=Addresses($filter=startswith(City,'H');$top=5;
+ $orderby=Country/Name,City,Street)
+ &$expand=Addresses/Country
+```
+:::
+
### ##subsubsec System Query Option `$orderby`
The `$orderby` system query option allows clients to request resources