Query Entities

The Query Entities operation queries entities in a table and includes the $filter and $select options.

Request

For requests that use the $select query option, you must use version 2011-08-18 or later. In addition, the DataServiceVersion and MaxDataServiceVersion headers must be set to 2.0.

To use projection, you must make the request by using version 2013-08-15 or later. The DataServiceVersion and MaxDataServiceVersion headers must be set to 3.0. For more information, see Set the OData data service version headers.

You can construct the Query Entities request as follows. We recommend HTTPS. Replace myaccount with the name of your storage account, and replace mytable with the name of your table.

The address of the entity set to be queried might take various forms on the request URI. For more information, see Query tables and entities.

Emulated storage service URI

When you're making a request against the emulated storage service, specify the emulator's host name and the table service's port as 127.0.0.1:10002. Follow that information with the name of the emulated storage account.

The Table service in the storage emulator differs from Azure Table Storage in several ways. For more information, see Differences between the storage emulator and Azure Storage services.

URI parameters

The Query Entities operation supports the query options that the OData protocol specification defines.

Request headers

The following table describes required and optional request headers:

Request body

None.

Sample request

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  

Response

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

Status code

A successful operation returns status code 200 (OK).

For information about status codes, see Status and error codes and Table Storage error codes.

Response headers

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

Sample response

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close  

Response body

The Query Entities operation returns the list of entities in a table as an OData entity set. The list of entities is in either a JSON format or an Atom feed, depending on the Accept header of the request.

JSON (version 2013-08-15 and later)

Here's a sample request URI for a Query Entities operation on a table of customers:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  

Here's the response payload in JSON with no metadata:

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}  

Here's the response payload in JSON with minimal metadata:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}  

Here's the response payload in JSON with full metadata:

{  
   "odata.metadata":" https://myaccount.table.core.windows.net/metadata#Customers",  
   "value":[  
      {  
         "odata.type":"myaccount.Customers",  
         "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}  

Atom feed (versions before 2015-12-11)

Here's a sample request URI for a Query Entities operation on a table of customers:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  

Here's a sample Atom response for the Query Entities operation:

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>  

Authorization

This operation can be performed by the account owner and by anyone with a shared access signature that has permission to perform this operation.

Remarks

A query against Table Storage can return a maximum of 1,000 entities at one time and can run for a maximum of five seconds. The response includes custom headers that contain a set of continuation tokens in any of the following cases:

• The result set contains more than 1,000 entities.
• The query didn't finish within five seconds.
• The query crosses the partition boundary.

You can use the continuation tokens to construct a subsequent request for the next page of data. For more information about continuation tokens, see Query timeout and pagination.

For projection requests that use the $select query option, the version must be 2011-08-18 or later. The maximum number of returned properties is 255. The response body includes all projected properties, even if properties aren't part of the returned entity.

For example, if the request includes a property that the projected entity does not contain, the missing property is marked with a null attribute. The preceding sample response body includes the Address property, which is not part of the projected entity. The value of the property is therefore null: <d:Address m:null="true" />.

The total time allotted to the request for scheduling and processing the query is 30 seconds. That total includes the five seconds for query execution.

Note that the right side of a query expression must be a constant. You can't reference a property on the right side of the expression. For details on constructing query expressions, see Query tables and entities.

A query expression can't contain null values. The following characters must be encoded if you use them in a query string:

• Forward slash (/)

• Question mark (?)

• Colon (:)

• At sign (@)

• Ampersand (&)

• Equal sign (=)

• Plus sign (+)

• Comma (,)

• Dollar sign ($)

Any application that can authorize and send an HTTP GET request can query entities in a table.

For more information about supported query operations against Table Storage through LINQ, see Query operators supported for Table Storage and Write LINQ queries against Table Storage.

See also

Table Storage error codes
Authorize requests to Azure Storage
Status and error codes
Addressing Table Storage resources
Query tables and entities
Set the OData data service version headers
Insert Entity
Update Entity
Delete Entity