Share via

2.2.3.6.1.8 Top System Query Option ($top)

  • Article

A data service URI with a $top system query option identifies a subset of the entities in the collection of entities, identified by the resource path section of the URI. This subset is formed by selecting only the first N items of the set, where N is a positive integer specified by this query option.

The value of this query option, referred to as N in the preceding paragraph, MUST be an integer greater than or equal to zero. If a value less than 0 is specified, the URI is considered to be malformed.

If the data service URI contains a $top query option, but does not contain an $orderby option, then the entities in the set MUST first be fully ordered by the data service. Such a full order SHOULD be obtained by sorting the entities based on their EntityKey values. While no ordering semantics are mandated, a data service MUST always use the same semantics to obtain a full ordering across requests.

The syntax of the top system query option is defined as follows.

 topQueryOp = "$top=" 1*DIGIT

Examples:

 http://host/service.svc/Orders?$orderby=ShippedDate desc&$top=20

The first 20 Order entity instances returned in descending order when sorted by the ShippedDate property.

 http://host/service.svc/Orders?$top=20

The first 20 Order entity instances returned in order of a sorting scheme determined by the data service.