教學課程：使用資料表 API 查詢 Azure Cosmos DB

  • 發行項

適用於： Table

Azure Cosmos DB for Table 支援對索引鍵/值 (資料表) 資料進行 OData 和 LINQ 查詢。

本文涵蓋下列工作：

  • 使用資料表 API 來查詢資料

本文中的查詢使用下列範例 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 進行查詢的詳細資料，請參閱查詢資料表和實體。

必要條件

若要讓這些查詢能夠運作，您必須具備 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'

如需如何針對各種資料類型建構篩選條件運算式的詳細資訊，請參閱查詢資料表和實體。

結果

PartitionKey RowKey 電子郵件 PhoneNumber
Smith Ben Ben@contoso.com 425-555-0102

在 Azure Cosmos DB 的資料表 API 中執行時，針對日期時間屬性所做的查詢不會傳回任何資料。 儘管 Azure 資料表儲存體會儲存具有時間細微性刻度的日期值，Azure Cosmos DB 中的資料表 API 仍會使用 _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 });

下一步

您現在可以繼續進行到下一個教學課程，以了解如何全域散發您的資料。