教程:使用表的 API 查询 Azure Cosmos DB

适用对象:

Azure Cosmos DB for Table 支持对键/值(表)数据进行 OData 和 LINQ 查询。

本文涵盖以下任务:

  • 使用 API for Table 查询数据

本文中的查询使用如下示例 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

若要详细了解如何使用 API for Table 执行查询,请参阅查询表和实体

先决条件

若要使这些查询生效,必须拥有 Azure Cosmos DB 帐户,且容器中必须包含实体数据。 如果没有帐户或数据,请完成快速入门:适用于 .NET 的 Azure Cosmos DB for Table 以创建帐户并填充数据库。

根据 PartitionKey 和 RowKey 查询

由于 PartitionKey 和 RowKey 属性构成实体的主键,因此可以使用以下特殊语法来识别实体:

查询

https://<mytableendpoint>/People(PartitionKey='Harp',RowKey='Walter')

结果

PartitionKey RowKey 电子邮件 PhoneNumber
Harp Walter Walter@contoso.com 425-555-0104

或者,可将这些属性指定为 $filter 选项的一部分,如以下部分中所示。 键属性名称和常量值区分大小写。 PartitionKey 和 RowKey 属性皆为 String 类型。

使用 OData 筛选器进行查询

构造筛选器字符串时,请记住以下规则:

  • 使用由 OData 协议规范定义的逻辑运算符比较属性和值。 不能将属性比作动态值。 表达式的一侧必须是常量。
  • URL 编码空格必须分隔属性名称、运算符和常量值。 空格经 URL 编码后为 %20
  • 筛选器字符串的所有部分都区分大小写。
  • 常量值的数据类型必须与属性的类型相同,这样筛选器才能返回有效的结果。 如需详细了解受支持的属性类型,请参阅了解表服务数据模型

以下示例查询演示如何使用 OData $filter 按 PartitionKey 和 Email 属性进行筛选。

查询

https://<mytableapi-endpoint>/People()?$filter=PartitionKey%20eq%20'Smith'%20and%20Email%20eq%20'Ben@contoso.com'

有关如何对不同数据类型构造筛选表达式的详细信息,请参阅 Querying Tables and Entities(查询表和实体)。

结果

PartitionKey RowKey 电子邮件 PhoneNumber
Smith Ben Ben@contoso.com 425-555-0102

在 Azure Cosmos DB 的 API for Table 中执行查询时,针对 datetime 属性的查询不返回任何数据。 虽然 Azure 表存储使用时钟周期的时间粒度存储日期值,但 Azure Cosmos DB 中的 API for Table 使用 _ts 属性。 _ts 属性处于第二个粒度级别,它不是 OData 筛选器。 Azure Cosmos DB 会阻止有关时间戳属性的查询。 解决方法是,可以定义自定义日期/时间或长数据类型属性,并设置客户端的日期值。

使用 LINQ 进行查询

还可使用 LINQ 进行查询,这会转换为相应的 OData 查询表达式。 以下示例演示如何使用 .NET SDK 生成查询。

IQueryable<CustomerEntity> linqQuery = table.CreateQuery<CustomerEntity>()
            .Where(x => x.PartitionKey == "4")
            .Select(x => new CustomerEntity() { PartitionKey = x.PartitionKey, RowKey = x.RowKey, Email = x.Email });

后续步骤

现可继续学习下一教程,了解如何多区域分发数据。