OData Query Options

To retrieve data from an OData service, a URI is constructed that specifies the resources that you are interested in—for example, Products—and you restrict the items returned by the service using various query options.

The following are the three types of OData query string options:

System query options—System query options are used to control the amount and order of the data that an OData service returns for the resource identified by the URI. The names of all System Query Options are prefixed with a “$” character. Not all system query options need to be supported by a producer. If not supported, the server should return an HTTP status code 405 (Method Not Allowed). The following is a summary list of OData system query options defined by the standard:

$orderby—This option allows you to order the results of a query by an entity property. For example, to retrieve the list of eBay product categories, ordered by Name, the following query could be used: http://ebayodata.cloudapp.net/Categories?$orderby=Name.

$top—This option allows you to select the first N items from a result set, where N is a positive integer specified in the query. For example, the following query selects the first five items from the complete list of eBay items: http://ebayodata.cloudapp.net/Items?$top=5.

$skip—This option allows you to select items that occur after a particular index in the result set and is useful when performing paging. By default, an OData service usually limits the number of items returned at any one time. In the case of the eBay OData service, this limit is 500 items. The $skip option, in conjunction with the $top option, can be used to page through results.

$filter—This option allows you to restrict the results to those matching the specified criteria. The $filter option supports various logical, arithmetic, and grouping operators, as well as a set of functions, such as substringof. See the OData website http://www.odata.org/developers/protocols/uri-conventions#QueryStringOptions for more information on the $filter option.

$expand—This option allows you to retrieve a graph of entities. For example, rather than retrieving the first three product categories and then the products within those three categories in another query, by using the $expand option you are able to retrieve them all at once. This is done as shown in the following example: http://services.odata.org/OData/OData.svc/Categories?$top=3&$expand=Products.

The syntax of a $expand query option is a comma-separated list of navigation properties. Additionally, each navigation property can be followed by a forward slash and another navigation property to enable identifying a multilevel relationship.

$format—This option allows you to specify the format of the response. Valid $format values include Atom, XML, and JSON. The $format value may also be set to a custom value specific to a particular OData service.

$select—This option allows you to retrieve only the data that you are interested in and can be important for performance when working with OData on the phone. The value of a $select option is a comma-separated list of selection clauses. Each selection clause may be a property name, navigation property name, or the “*” character. To select only the names of the top five search results for the phrase phone, the following query could be used: http://ebayodata.cloudapp.net/Items?search=phone&$top=5&$select=Title.

$inlinecount—This option allows you to retrieve a count of the number of items in a result set, along with the entity elements. When combined with a $top option of 0 (specified by &$top=0), you can retrieve the number of items in a set without having to go to the trouble of downloading unnecessary bytes.

Custom query options—Custom query options are specific to the OData service that uses them. They differ in that they are not prefixed by a $ symbol. The following is an example of a custom query option, where xname is the parameter name, and xvalue is its value: http://services.odata.org/OData/OData.svc/Products?xname=xvalue.

Service operation parameters—A service operation is a function specific to the particular OData service. Service operation parameters work much like custom query options, where key/value pairs are provided to a custom function as arguments. For example, a service operation exists on the OData sample website that retrieves all products with a particular rating. The rating is specified using the rating service operation parameter, as shown: http://services.odata.org/OData/OData.svc/GetProductsByRating?rating=5.