2.2.3.6.1 System Query Options
System query options in a data service URI, defined in URI Format: Resource Addressing Rules (section 2.2.3) are directives that are defined by this document that a client MAY specify to control the amount and order of the data that a data service returns for the resource identified by the URI. The names of all system query options are prefixed with a "$" character.
A data service MAY<6> support some or all of the system query options defined in this document. If a data service does not support a system query option, it MUST reject any requests which contain the unsupported option, as seen in Message Processing Events and Sequencing Rules (section 3.2.5) for HTTP-specific server details.
The following table summarizes the system query options defined in this document.
If a system query option is included in a data service URI identifying a resource that is incompatible with the query option, as shown in the following system query options supported per URI table, the URI MUST be considered malformed.
|
System query option |
Description |
Additional details |
|---|---|---|
|
$expand |
This option indicates entities that are associated with the EntityType instance or EntitySet, identified by the resource path section of the URI, and represented inline in the data service's response, as opposed to being represented with Deferred Content markers in Deferred Content (section 2.2.6.2.6) and Deferred Content (section 2.2.6.3.9). |
See Expand System Query Option ($expand) (section 2.2.3.6.1.3). |
|
$filter |
This option specifies a predicate used to filter the elements from the EntitySet identified by the resource path section of the URI. |
See Filter System Query Option ($filter) (section 2.2.3.6.1.4). |
|
$orderby |
This option specifies the sort properties and sort direction (ascending or descending) that the data service is to use to order the entities in the EntitySet, identified by the resource path section of the URI. |
See OrderBy System Query Option ($orderby) (section 2.2.3.6.1.6). |
|
$format |
This option specifies the media type that is acceptable in a response. If present, this value takes precedence over the value(s) specified in an Accept (section 2.2.5.1) request header. |
See Format System Query Option ($format) (section 2.2.3.6.1.5). |
|
$skip |
This option specifies a positive integer N that represents the number of entities, counted from the first entity in the EntitySet and ordered as specified by the $orderby option, that the data service is to skip when returning the entities in the EntitySet, which is identified by the resource path section of the URI. The data service is to return all subsequent entities, starting from the one in position N+1. |
|
|
$top |
This option specifies a positive integer N that is the maximum number of entities in the EntitySet, identified by the resource path section of the URI, that the data service is to return. |
|
|
$skiptoken |
The value of a $skiptoken query option is an opaque token which identifies an index into the collection of entities identified by the URI containing the $skiptoken parameter. |
See Skip Token Query Option ($skiptoken) (section 2.2.3.6.1.9) |
|
$inlinecount |
For a value of "allpages", this option indicates that the response to the request has to include the count of the number of entities in the EntitySet, identified by the resource path section of the URI, after all $filter system query options have been applied. For a value of "none", this option indicates that the response to the request is not to include the count value. |
See InlineCount System Query Option ($inlinecount) (section 2.2.3.6.1.10) |
|
$select |
This option is used to specify that a subset of the properties of the entities that are identified by the path of the request URI and $expand query option are to be returned in the response from the data service. |
Table: Summary of Supported System Query Options
In the following table, the row labels (URI1, URI2, and so on) refer to the resource path semantics table in URI types defined by the grammar rules in Resource Path: Semantics (section 2.2.3.5). A cell value of "Yes" indicates the system query option MAY be used with the URI type associated with the row. A blank cell indicates that if the system query option is present on a URI of the form indicated by the associated row, the URI is to be considered malformed.
|
|
$expand |
$filter |
$format |
$orderby |
$skip |
$top |
$skiptoken |
$inlinecount (Note 3) |
$select (Note 3) |
|---|---|---|---|---|---|---|---|---|---|
|
URI1 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI2 |
Yes |
|
Yes |
|
|
|
|
|
Yes |
|
URI3 |
|
Yes |
Yes |
|
|
|
|
|
|
|
URI4 |
|
|
Yes |
|
|
|
|
|
|
|
URI5 |
|
|
Yes |
|
|
|
|
|
|
|
URI6 (Note 1) |
Yes |
Yes |
Yes |
|
|
|
|
|
Yes |
|
URI6 (Note 2) |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI7 |
|
|
Yes |
|
Yes |
Yes |
Yes |
Yes |
|
|
URI8 |
|
|
|
|
|
|
|
|
|
|
URI9 |
|
|
|
|
|
|
|
|
|
|
URI10 |
|
|
Yes |
|
|
|
|
|
|
|
URI11 |
|
|
Yes |
|
|
|
|
|
|
|
URI12 |
|
|
Yes |
|
|
|
|
|
|
|
URI13 |
|
|
Yes |
|
|
|
|
|
|
|
URI14 |
|
|
Yes |
|
|
|
|
|
|
|
URI15 |
Yes |
Yes |
|
Yes |
Yes |
|
|
|
|
|
URI16 |
Yes |
Yes |
|
|
|
|
|
|
|
|
URI17 |
|
|
Yes |
|
|
|
|
|
|
|
URI18 |
|
|
|
|
|
|
|
|
Yes |
|
URI19 |
|
|
Yes |
|
|
|
|
|
|
|
URI20 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI21 |
Yes |
|
Yes |
|
|
|
|
|
Yes |
|
URI22 |
Yes |
|
Yes |
|
|
|
|
|
Yes |
|
URI23 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI24 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI25 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI26 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
URI27 |
|
|
Yes |
|
|
|
|
|
|
|
URI28 |
|
|
Yes |
|
|
|
|
|
|
Table: System Query Options Supported Per URI
Note 1: Applies when the NavigationProperty in the final path segment of the URI identifies a single EntityType instance.
Note 2: Applies when the NavigationProperty in the final path segment of the URI identifies a set of entities.
Note 3: The $inlinecount and $select system query options are supported in the OData 2.0 and OData 3.0 protocols.