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.

See Skip System Query Option ($skip) (section 2.2.3.6.1.7).

$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.

See Top System Query Option ($top) (section 2.2.3.6.1.8).

$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.

See Select System Query Option (section 2.2.3.6.1.11)

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.

Show: