教程:使用表 API 查询 Azure Cosmos DBTutorial: Query Azure Cosmos DB by using the Table API

Azure Cosmos DB 表 API 支持针对键/值(表)数据进行 OData 和 LINQ 查询。The Azure Cosmos DB Table API supports OData and LINQ queries against key/value (table) data.

本文涵盖以下任务:This article covers the following tasks:

  • 使用表 API 查询数据Querying data with the Table API

本文中的查询使用如下示例 People 表:The queries in this article use the following sample People table:

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
HarpHarp WalterWalter Walter@contoso.com 425-555-0101425-555-0101
SmithSmith BenBen Ben@contoso.com 425-555-0102425-555-0102
SmithSmith JeffJeff Jeff@contoso.com 425-555-0104425-555-0104

有关如何使用表 API 执行查询的详细信息,请参阅查询表和实体See Querying Tables and Entities for details on how to query by using the Table API.

有关 Azure Cosmos DB 所提供的高级功能的详细信息,请参阅 Azure Cosmos DB 表 API使用 .NET 通过表 API 进行开发For more information on the premium capabilities that Azure Cosmos DB offers, see Azure Cosmos DB Table API and Develop with the Table API in .NET.

先决条件Prerequisites

若要使这些查询生效,必须拥有 Azure Cosmos DB 帐户,且容器中必须包含实体数据。For these queries to work, you must have an Azure Cosmos DB account and have entity data in the container. 没有这些内容?Don't have any of those? 请学习五分钟快速入门或者开发人员教程,创建帐户并填充数据库。Complete the five-minute quickstart or the developer tutorial to create an account and populate your database.

根据 PartitionKey 和 RowKey 查询Query on PartitionKey and RowKey

由于 PartitionKey 和 RowKey 属性构成实体的主键,因此可以使用以下特殊语法来识别实体:Because the PartitionKey and RowKey properties form an entity's primary key, you can use the following special syntax to identify the entity:

查询Query

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

结果Results

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
HarpHarp WalterWalter Walter@contoso.com 425-555-0104425-555-0104

或者,可将这些属性指定为 $filter 选项的一部分,如以下部分中所示。Alternatively, you can specify these properties as part of the $filter option, as shown in the following section. 请注意,键属性名称和常量值区分大小写。Note that the key property names and constant values are case-sensitive. PartitionKey 和 RowKey 属性皆为 String 类型。Both the PartitionKey and RowKey properties are of type String.

使用 OData 筛选器进行查询Query by using an OData filter

构造筛选器字符串时,请记住以下规则:When you're constructing a filter string, keep these rules in mind:

  • 使用由 OData 协议规范定义的逻辑运算符比较属性和值。Use the logical operators defined by the OData Protocol Specification to compare a property to a value. 请注意,不能将属性与动态值进行比较。Note that you can't compare a property to a dynamic value. 表达式的一侧必须是常量。One side of the expression must be a constant.
  • 必须使用 URL 编码空格分隔属性名称、运算符和常量值。The property name, operator, and constant value must be separated by URL-encoded spaces. 空格经 URL 编码后为 %20A space is URL-encoded as %20.
  • 筛选器字符串的所有部分都区分大小写。All parts of the filter string are case-sensitive.
  • 常量值的数据类型必须与属性的类型相同,这样筛选器才能返回有效的结果。The constant value must be of the same data type as the property in order for the filter to return valid results. 有关支持的属性类型的详细信息,请参阅 Understanding the Table Service Data Model(了解表服务数据模型)。For more information about supported property types, see Understanding the Table Service Data Model.

以下示例查询演示如何使用 OData $filter 按 PartitionKey 和 Email 属性进行筛选。Here's an example query that shows how to filter by the PartitionKey and Email properties by using an OData $filter.

查询Query

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

有关如何对不同数据类型构造筛选表达式的详细信息,请参阅 Querying Tables and Entities(查询表和实体)。For more information on how to construct filter expressions for various data types, see Querying Tables and Entities.

结果Results

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
SmithSmith BenBen Ben@contoso.com 425-555-0102425-555-0102

在 Azure Cosmos DB 的表 API 中执行查询时,对 datetime 属性的查询不返回任何数据。The queries on datetime properties don't return any data when executed in Azure Cosmos DB's Table API. 虽然 Azure 表存储使用时钟周期的时间粒度存储日期值,但 Azure Cosmos DB 中的表 API 使用 _ts 属性。While the Azure Table storage stores date values with time granularity of ticks, the Table API in Azure Cosmos DB uses the _ts property. _ts 属性处于第二个粒度级别,它不是 OData 筛选器。The _ts property is at a second level of granularity, which isn't an OData filter. 因此,Azure Cosmos DB 阻止了有关 timestamp 属性的查询。So, the queries on timestamp properties are blocked by Azure Cosmos DB. 解决方法是,可以定义自定义日期/时间或长数据类型属性,并设置客户端的日期值。As a workaround, you can define a custom datetime or long data type property and set the date value from the client.

使用 LINQ 进行查询Query by using LINQ

还可使用 LINQ 进行查询,这会转换为相应的 OData 查询表达式。You can also query by using LINQ, which translates to the corresponding OData query expressions. 以下示例演示如何使用 .NET SDK 生成查询。Here's an example of how to build queries by using the .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 });

后续步骤Next steps

在本教程中已完成以下操作:In this tutorial, you've done the following:

  • 已了解如何使用表 API 进行查询Learned how to query by using the Table API

现可继续学习下一教程,了解如何多区域分发数据。You can now proceed to the next tutorial to learn how to distribute your data multiple-regionally.