Query records operation

Article
05/31/2016

The query operation returns items from a table.

Note

By default, Mobile Services returns only 50 records in a query. Use paging in the request to return more. For more information, see Add paging to your queries.

Request

The request may be specified as follows. Replace <service_name> with your mobile service name and <table_name> with the name of the table to access.

HTTP Verb	Request URI	HTTP Version
GET	https://<service_name>.azure-mobile.net/tables/<table_name>	HTTP/1.1

URI Parameters

Microsoft Azure Mobile Services supports the following subset of the query option parameters defined by the Open Data Protocol (OData).

URI Parameter	Required	Description
$filter	No	Restricts returned items based on a filter predicate.
$inlinecount	No	Returns a count of all items that could be returned in the base query without paging applied. You must specify a value of allpages for this parameter.
$orderby	No	Orders the returned items by one or more columns. Ordering can be specified as ascending (asc), which is the default, or descending (desc)
$select	No	Defines a new projection of data by specifying the columns included in the returned data.
$skip	No	Specifies the number of records from the base query to skip before returning items. This is used for paging results. For more information, see Add paging to your queries.
$top	No	Specifies the number of items to include in response. This is used for paging results. For more information, see Add paging to your queries.

The noscript parameter is also supported:

URI Parameter	Required	Description
noscript	No	When a value of true is supplied, the execution of registered scripts is suppressed. To suppress script execution, you must also supply the service master key in the X-ZUMO-MASTER header.
__includeDeleted	No	When a value of true is supplied with a table that has soft delete enabled, rows with the __deleted system property set to true will be included in the response. Otherwise, those rows will not be returned when soft delete is enabled. Example: `__includeDeleted=true`
__systemproperties	No	A comma delimited list of the system properties to be includes in the response. System properties from the following list are accepted: __createdAt: system created to track the creation of the record. __updatedAt: sssystem created to track the last update to the record. __version: version used to support concurrency. __deleted: system created to support soft delete. Example: `__systemproperties=version,deleted`

URI Parameter

Required

Description

noscript

When a value of true is supplied, the execution of registered scripts is suppressed. To suppress script execution, you must also supply the service master key in the X-ZUMO-MASTER header.

__includeDeleted

When a value of true is supplied with a table that has soft delete enabled, rows with the __deleted system property set to true will be included in the response. Otherwise, those rows will not be returned when soft delete is enabled.

Example:

__includeDeleted=true

__systemproperties

A comma delimited list of the system properties to be includes in the response. System properties from the following list are accepted:

__createdAt: system created to track the creation of the record.
__updatedAt: sssystem created to track the last update to the record.
__version: version used to support concurrency.
__deleted: system created to support soft delete.

Example:

__systemproperties=version,deleted

Request Headers

The following table describes the request headers.

Accept

Set this header to application/json.

X-ZUMO-APPLICATION

Conditional

The application key of the mobile service. You must specify a valid application key when required to access the table operation. This is the default table operation access permission.

X-ZUMO-AUTH

Conditional

The service-generated authentication token for an authenticated user. You must specify a token for an authenticated user when required to access the table operation.

X-ZUMO-MASTER

Conditional

The service master key. You should only include this key when administrator access is required to access the table operation.

Security Note
The service master key is a critical security credential that provides administrator access to your data service. Do not share this secret with anyone or distribute it with your app. This key must always be securely distributed over an encrypted channel.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

A successfully operation returns status code 200 (OK).

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
Content-Length	The length of the response body.
Content-Type	Header set to application/json.
x-zumo-version	Indicates which version of the runtime executed the request.

Response Body

The JSON representation of the query result. Results are represented as a single JSON object or a collection of JSON objects.

Note

When you include the $inlinecount parameter in your query, the JSON in the response is wrapped by a new JSON object with a results property, which includes the results data as a collection of JSON objects, and a count property, which is the total count.

Authorization

Authorization depends on the access permission requirements for the table operation, which are summarized as follows:

Table operation access permission	Required authorization header
Everyone	None
Anybody with the application key	X-ZUMO-APPLICATION
Only Authenticated Users	X-ZUMO-AUTH
Only Scripts and Admins	X-ZUMO-MASTER

Access permissions for individual table operations are set in the Windows Azure Management Portal. For more information, see Permissions.

Sample Requests and Responses

Filtered query request

The following example URI returns JSON objects from the TodoItem table, where the complete property is false.

GET https://todolist.azure-mobile.net/tables/TodoItem?$filter=(complete%20eq%20false)

The request is sent with the following headers.

Accept: application/json
X-ZUMO-APPLICATION: UzMAOXRlJdZyqibeUqCMoZZMrUXIRs92
Host: todolist.azure-mobile.net

After the request has been sent, the following response is returned.

HTTP/1.1 200 OK
Content-Type: application/json
x-zumo-version: Zumo.Main.0.1.6.527.Runtime
Date: Thu, 20 Sep 2012 05:59:27 GMT
Content-Length: 188

[{"id":1,"text":"Sign-up for the free trial","complete":false},{"id":2,"text":"Create the mobile service","complete":false },
    {"id":3,"text":"Complete the quickstart","complete":false}]

Filtered query request that includes total count

The following example URI returns the same filtered query, including the total count value, which in this case is 3.

GET https://todolist.azure-mobile.net/tables/TodoItem?$filter=(complete%20eq%20false)&$inlinecount=allpages

The request is sent with the following headers.

Accept: application/json
X-ZUMO-APPLICATION: UzMAOXRlJdZyqibeUqCMoZZMrUXIRs92
Host: todolist.azure-mobile.net

After the request has been sent, the following response is returned.

HTTP/1.1 200 OK
Content-Type: application/json
x-zumo-version: Zumo.Main.0.1.6.527.Runtime
Date: Thu, 20 Sep 2012 05:59:27 GMT
Content-Length: 211

{"results": [{"id":1,"text":"Sign-up for the free trial","complete":false},{"id":2,"text":"Create the mobile service","complete":false },
    {"id":3,"text":"Complete the quickstart","complete":false}],"count":3}

Query records operation

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Authorization

Sample Requests and Responses

Filtered query request

Filtered query request that includes total count

See Also

Additional resources