2.2.3.6.1.6 OrderBy System Query Option ($orderby)

  • Article

A data service URI with a $orderby system query option specifies an expression for determining what values are used to order the entities in the EntitySet, identified by the resource path section of the URI.

The syntax of the OrderBy system query option is defined as:

 orderByQueryOption = "$orderby" [WSP] "=" [WSP] commonExpression [WSP] [asc / desc]
                      *( "," [WSP]  commonExpression [WSP] [asc / desc])
 

If supported, the data service MUST return the entities, in order, based on the expression specified. If multiple expressions are specified and a data service supports sorting based on multiple values, then a data service MUST return the entities ordered by a secondary sort for each additional expression specified.

If the expression includes the optional asc clause or if no option is specified, the entities MUST be returned in ascending order. If the expression includes the optional desc clause, the entities MUST be returned in descending order. Actual ordering of results is data service specific and no semantics for doing so are mandated. However, a data service MUST always use the same semantics when ordering the results of a URI request.

Examples:

 http://host/service.svc/Orders?$orderby=ShipCountry

The set of Order entity instances returned in ascending order of the ShipCountry property.

 http://host/service.svc/Orders?$orderby = ShipCountry ne 'France' desc

The set of Order entity instances returned in descending order of the ShipCountry property not equal to the value "France".

The syntax, construction, and evaluation rules for commonExpression are defined in Common Expression Syntax (section 2.2.3.6.1.1).

The OData 3.0 protocol supports specifying the namespace-qualified EntityType of the property that is used in the order by clause.

 http://host/service.svc/Customers?$orderby =SampleModel.VipCustomer/CreditPurchases/CreditLimit desc
 

The set of Customer entity instances returned in descending order CreditLimit if the instance is of type VipCustomer. If the entity instance is not of type VipCustomer, or any of its subtypes, the order for that entity instance is undefined. Actual ordering of such entity instances is specific to the data service and no semantics for doing so are mandated; however, a data service MUST always use the same semantics when ordering the results for such a URI request.