Tutorial: Consultar o Azure Cosmos DB usando a API de Tabela
APLICA-SE AO: Table
O Azure Cosmos DB for Table dá suporte a consultas OData e LINQ em dados de chave/valor (tabela).
Este artigo aborda as seguintes tarefas:
- Consultar dados com a API de Tabela
As consultas neste artigo usam a seguinte tabela de exemplo People
:
PartitionKey | RowKey | PhoneNumber | |
---|---|---|---|
Harp | Walter | Walter@contoso.com | 425-555-0101 |
Smith | Ben | Ben@contoso.com | 425-555-0102 |
Smith | Jeff | Jeff@contoso.com | 425-555-0104 |
Para obter detalhes de como consultar usando a API for Table, veja Consultando tabelas e entidades.
Pré-requisitos
Para essas consultas funcionarem, você deve ter uma conta do Azure Cosmos DB e ter dados de entidade no contêiner. Se você não tiver uma conta ou dados, conclua o Guia de início rápido: Azure Cosmos DB for Table para .NET para criar uma conta e popular o banco de dados.
Consultar em PartitionKey e RowKey
Como as propriedades PartitionKey e RowKey formam a chave primária de uma entidade, é possível utilizar a seguinte sintaxe especial para identificar a entidade:
Consulta
https://<mytableendpoint>/People(PartitionKey='Harp',RowKey='Walter')
Resultados
PartitionKey | RowKey | PhoneNumber | |
---|---|---|---|
Harp | Walter | Walter@contoso.com | 425-555-0104 |
Como alternativa, você pode especificar essas propriedades como parte da opção $filter
, conforme mostra a seção a seguir. Os nomes de propriedade de chave e os valores de constantes diferenciam maiúsculas de minúsculas. As propriedades PartitionKey e RowKey são do tipo String.
Consultar utilizando um filtro OData
Ao construir uma cadeia de caracteres de filtro, lembre-se destas regras:
- Use os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade a um valor. Você não pode comparar uma propriedade com um valor dinâmico. Um lado da expressão deve ser uma constante.
- Os espaços codificados em URL precisam separar o nome da propriedade, o operador e o valor da constante. 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, confira Noções básicas sobre o modelo de dados do serviço Tabela.
Veja um exemplo de consulta que mostra como filtrar por PartitionKey e as propriedades de Email usando um OData $filter
.
Consulta
https://<mytableapi-endpoint>/People()?$filter=PartitionKey%20eq%20'Smith'%20and%20Email%20eq%20'Ben@contoso.com'
Para obter mais informações sobre como construir expressões de filtro para vários tipos de dados, consulte Consultar tabelas e entidades.
Resultados
PartitionKey | RowKey | PhoneNumber | |
---|---|---|---|
Smith | Ben | Ben@contoso.com | 425-555-0102 |
As consultas nas propriedades de datetime não retornam dados quando são executadas na API de Tabela do Azure Cosmos DB. Enquanto o armazenamento de Tabelas do Azure armazena valores de data com granularidade de tempo de tiques, a API de Tabela no Azure Cosmos DB usa a propriedade _ts
. A propriedade _ts
está em um segundo nível de granularidade, que não é um filtro OData. O Azure Cosmos DB bloqueia as consultas em propriedades de carimbo de data/hora. Como alternativa, você pode definir uma propriedade de tipo de dados Long ou datetime personalizada e definir o valor de data do cliente.
Consultar utilizando LINQ
Você também pode consultar utilizando o LINQ, o que resulta em expressões de consulta Odata correspondentes. Veja um exemplo de como criar consultas usando o SDK do .NET.:
IQueryable<CustomerEntity> linqQuery = table.CreateQuery<CustomerEntity>()
.Where(x => x.PartitionKey == "4")
.Select(x => new CustomerEntity() { PartitionKey = x.PartitionKey, RowKey = x.RowKey, Email = x.Email });
Próximas etapas
Agora você pode prosseguir para o próximo tutorial e aprender a distribuir seus dados globalmente.