Consultando tabelas e entidades

  • Artigo

A consulta tabelas e entidades no serviço Tabela exige a construção cuidadosa do URI de solicitação. As seções a seguir descrevem opções de consulta e demonstram alguns cenários comuns.

Sintaxe básica de consulta

Para retornar todas as tabelas em uma determinada conta de armazenamento, execute uma GET operação no recurso Tabelas, conforme descrito na operação Tabelas de Consultas . O URI básico para usar o recurso Tabelas é o seguinte:

https://myaccount.table.core.windows.net/Tables

Para retornar uma única tabela nomeada, especifique essa tabela da seguinte forma:

https://myaccount.table.core.windows.net/Tables('MyTable')

Para retornar todas as entidades de uma tabela, especifique o nome da tabela no URI, sem o recurso Tabelas:

https://myaccount.table.core.windows.net/MyTable()

Os resultados da consulta são classificados por PartitionKey e, em seguida, por RowKey. A classificação dos resultados de qualquer outro modo não tem suporte no momento.

Você pode especificar opções adicionais para limitar o conjunto de tabelas ou entidades retornadas, como descrito na seção Opções de consulta com suporte.

Observação

O número de entidades retornadas para uma única solicitação poderá ser delimitado, se a consulta exceder o número máximo de entidades, exceder o intervalo de tempo limite ou ultrapassar o limite de uma partição. Para obter mais informações, consulte Tempo limite e paginação de consulta.

Opções de consulta com suporte

O serviço Tabela dá suporte às seguintes opções de consulta, que estão em conformidade com a Especificação do Protocolo OData. Você pode usar essas opções para limitar o conjunto de tabelas, entidades ou propriedades da entidade retornadas por uma consulta.

Opção de consulta do sistema Descrição
$filter Retorna apenas tabelas ou entidades que satisfazem o filtro especificado.

Observe que não são permitidas mais do que 15 comparações discretas em uma cadeia de caracteres $filter.
$top Retorna somente as principais tabelas ou entidades n do conjunto.
$select Retorna as propriedades desejadas de uma entidade do conjunto. Essa opção de consulta tem suporte apenas para solicitações que usam a versão 2011-08-18 ou mais recente. Para obter mais informações, consulte Escrevendo consultas LINQ no serviço tabela.

Observação

Uma solicitação que retorna mais do que o máximo padrão ou o número máximo especificado de resultados retorna um token de continuação para executar a paginação. Ao fazer solicitações subsequentes que incluem tokens de continuação, não deixe de passar o URI original na solicitação. Por exemplo, se você tiver especificado uma $filteropção de consulta , $selectou $top como parte da solicitação original, você desejará incluir essa opção em solicitações subsequentes. Caso contrário, suas solicitações subsequentes poderão retornar resultados inesperados. Consulte Tempo limite de consulta e paginação para obter informações adicionais.

Observe que a opção $top de consulta no caso em que os resultados são paginados especifica o número máximo de resultados por página, não o número máximo de resultados em todo o conjunto de respostas.

As opções de consulta adicionais definidas por OData não têm suporte no serviço Tabela.

Operadores de comparação com suporte

Em uma cláusula $filter, você pode usar operadores de comparação para especificar os critérios segundo os quais filtrar os resultados da consulta.

Para todos os tipos de propriedade, os seguintes operadores de comparação são compatíveis:

Operador expressão URI
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

Além disso, os seguintes operadores têm suporte para propriedades boolianas:

Operador expressão URI
And and
Not not
Or or

Para obter mais informações sobre a sintaxe de filtro, consulte a Especificação do protocolo OData.

Codificação da cadeia de caracteres de consulta

Os seguintes caracteres deverão ser codificados se forem usados em uma cadeia de caracteres de consulta:

  • Barra (/)
  • Ponto de interrogação (?)
  • Dois-pontos (:)
  • Símbolo de arroba (@)
  • E comercial (&)
  • Sinal de igual (=)
  • Sinal de adição (+)
  • Vírgula (,)
  • Sinal de dólar ($)

Aspas simples (')

Aspas simples em cadeias de caracteres de consulta devem ser representadas como duas aspas simples consecutivas (''). Por exemplo, "o'clock" seria:

o''clock

Exemplos de expressão de consulta

Os exemplos a seguir mostram como construir o URI de solicitação para algumas consultas de entidade típicas usando a sintaxe REST. As mesmas consultas podem ser elaboradas com a sintaxe LINQ. Para obter mais informações, consulte Escrevendo consultas LINQ no serviço tabela.

Observe que as opções $top e $filter também podem ser usadas para filtrar em nomes de tabela, usando a sintaxe mostrada para filtrar em propriedades do tipo String.

Retornando as principais entidades n

Para retornar as principais entidades n para qualquer consulta, especifique a opção de consulta $top. O exemplo a seguir retorna as 10 principais entidades de uma tabela denominada Clientes:

https://myaccount.table.core.windows.net/Customers()?$top=10

Filtrando nas propriedades PartitionKey e RowKey

Como as propriedades PartitionKey e RowKey formam a chave primária de uma entidade, você pode usar uma sintaxe especial para identificar a entidade, da seguinte forma:

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')

Como alternativa, você pode especificar essas propriedades como parte da opção $filter, conforme mostra a seção a seguir.

Observe que os nomes de propriedade de chave e valores constantes diferenciam maiúsculas de minúsculas. As propriedades PartitionKey e RowKey são do tipo String.

Construindo cadeias de caracteres de filtro

Ao construir uma cadeia de caracteres de filtro, lembre-se destas regras:

  • Use os operadores lógicos definidos pela Especificação de Protocolo OData para comparar uma propriedade com um valor. Observe que não é possível comparar uma propriedade a um valor dinâmico; um lado da expressão deve ser uma constante.

  • O nome da propriedade, o operador e um valor constante devem ser separados por espaços codificados por URL. Um espaço é codificado por URL como %20.

  • Todas as partes da cadeia de caracteres de filtro diferenciam maiúsculas de minúsculas.

  • O valor da constante deve ser do mesmo tipo de dados como a propriedade para que o filtro retorne resultados válidos. Para obter informações sobre tipos de propriedades com suporte, consulte Noções básicas sobre o modelo de dados do serviço Tabela.

Observação

Verifique se uma propriedade foi tipada explicitamente antes de considerá-la de outro tipo que não seja cadeia de caracteres. Se uma propriedade tiver sido tipada explicitamente, o tipo será indicado na resposta quando a entidade for retornada. Se a propriedade não tiver sido tipada explicitamente, ela será do tipo String, e o tipo não será indicado na resposta quando a entidade for retornada.

Filtrando nas propriedades de cadeia de caracteres

Ao filtrar em propriedades de cadeia de caracteres, insira a constante de cadeia de caracteres entre aspas simples.

O exemplo a seguir filtra nas propriedades PartitionKey e RowKey; propriedades adicionais que não sejam de chave também podem ser adicionadas à cadeia de caracteres da consulta.

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'

O exemplo a seguir filtra em um propriedades FirstName e LastName:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'

Observe que o serviço Tabela não oferece suporte a consultas de curingas. No entanto, você pode executar correspondência de prefixo usando os operadores de comparação no prefixo desejado. O exemplo a seguir retorna entidades com uma propriedade LastName começando com a letra “A”:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'

Filtrando em propriedades numéricas

Para filtrar em um valor inteiro ou um número de ponto flutuante, especifique o valor constante no URI sem aspas.

Este exemplo retorna todas as entidades com uma propriedade Age cujo valor é maior que 30:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030

Este exemplo retorna todas as entidades com uma propriedade AmountDue cujo valor é menor ou igual a 100,25:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20

Filtrando em Propriedades Boolianas

Para filtrar em um valor booliano, especifique true ou false sem aspas.

O exemplo a seguir retorna todas as entidades nas quais a propriedade IsActive está definida como true:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true

Filtrando em Propriedades DateTime

Para filtrar em um valor de DateTime, especifique a palavra-chave datetime no URI, seguido pela constante de data/hora entre aspas simples. A constante de data/hora deve estar no formato UTC combinado, conforme descrito em Formatação de valores DateTime.

O exemplo a seguir retorna as entidades nas quais a propriedade CustomerSince é igual a 10 de julho de 2008:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'

Filtrando em propriedades de GUID

Para filtrar em um valor de GUID, especifique a palavra-chave guid no URI, seguido pela constante de guid entre aspas simples.

O exemplo a seguir retorna as entidades nas quais a propriedade GuidValue é igual a:

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'

Consulte Também

Conceitos do Serviço da Tabela
Noções básicas sobre o modelo de dados de serviço de tabela
Endereçando recursos de serviço de tabela
Tempo limite e paginação de consulta
Gravando consultas LINQ no serviço Tabela