Query Entities

Artikkeli
06/27/2023

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.

Method	Request URI	HTTP version
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

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.

Method	Request URI	HTTP version
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

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 header	Description
`Authorization`	Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
`Date` or `x-ms-date`	Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
`x-ms-version`	Optional. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
`Accept`	Optional. Specifies the accepted content type of the response payload. Possible values are: - `application/atom+xml` (versions before 2015-12-11 only) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` For more information, see Payload format for Table Storage operations.
`x-ms-client-request-id`	Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives.

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.

Response header	Description
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	Indicates that: - The number of entities to be returned exceeds 1,000. - The server timeout interval is exceeded. - A server boundary is reached, if the query returns data that's spread across multiple servers. For more information about using the continuation tokens, see Query timeout and pagination.
`x-ms-request-id`	Uniquely identifies the request that was made. You can use it to troubleshoot the request. For more information, see Troubleshoot API operations.
`x-ms-version`	Indicates the version of Table Storage that was used to execute the request. This header is returned for requests made against version 2009-09-19 and later.
`Date`	A UTC date/time value that indicates the time at which the service sent the response.
`Content-Type`	Indicates the content type of the payload. The value of this header depends on the value of the `Accept` request header. Possible values are: - `application/atom+xml` (versions before 2015-12-11 only) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` For more information about valid content types, see Payload format for Table Storage operations.
`x-ms-client-request-id`	Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the `x-ms-client-request-id` header, if it's present in the request and the value is at most 1,024 visible ASCII characters. If the `x-ms-client-request-id` header is not present in the request, this header won't be present in the response.

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.

Note

We recommend JSON as the payload format. It's the only supported format for version 2015-12-11 and later.

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.

Note

When you're making subsequent requests that include continuation tokens, be sure to pass the original URI on the request. For example, if you've specified a $filter, $select, or $top query option as part of the original request, include that option on subsequent requests. Otherwise, your subsequent requests might return unexpected results.

The $top query option in this case specifies the maximum number of results per page. It doesn't specify the maximum number of results in the whole response set.

For more information, see Query tables and entities.

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.

Jaa