チュートリアル:Table API を使って Azure Cosmos DB に対するクエリを実行する

適用対象: Table API

Azure Cosmos DB Table API では、キー/値 (テーブル) データに対する OData クエリと LINQ クエリがサポートされます。

この記事に含まれるタスクは次のとおりです。

  • Table API を使用してデータのクエリを実行する

この記事のクエリは、次の People サンプル テーブルを使用します。

パーティション キー 行キー Email 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

Table API を使用してクエリを実行する方法の詳細については、テーブルおよびエンティティのクエリに関するページを参照してください。

Azure Cosmos DB が提供する Premium 機能の詳細については、Azure Cosmos DB: Table API に関するページや Table API を使用した .NET での開発に関するページをご覧ください。

前提条件

クエリを実行するには、Azure Cosmos DB アカウントがあり、コンテナーにエンティティ データがあることが必要です。 どちらもない場合には、 5 分でできるクイックスタート開発者向けチュートリアルを実行して、アカウントを作成し、データベースにデータを設定します。

PartitionKey と RowKey のクエリ

PartitionKey プロパティと RowKey プロパティによってエンティティの主キーが構成されるため、次のような特別な構文を使用すると、エンティティを特定できます。

クエリ

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

結果

パーティション キー 行キー Email PhoneNumber
Harp Walter Walter@contoso.com 425-555-0104

または、次のセクションで説明するように、これらのプロパティを $filter オプションに含めて指定することもできます。 キーのプロパティ名と定数値では大文字と小文字が区別されます。 PartitionKey プロパティと RowKey プロパティはいずれも文字列型です。

OData フィルターを使用したクエリ

フィルター文字列を指定するときは、次のルールに注意してください。

  • OData プロトコル仕様で定義された論理演算子を使用して、プロパティと値を比較します。 プロパティは動的な値とは比較できないので注意してください。 式の片方は、定数である必要があります。
  • プロパティ名、演算子、および定数値は、URL でエンコードされた空白で区切る必要があります。 空白は URL エンコードでは %20 となります。
  • フィルター文字列のすべての要素は大文字と小文字が区別されます。
  • フィルターで有効な結果を得るためには、定数値をプロパティと同じデータ型にする必要があります。 サポートされているプロパティ型の詳細については、 Table サービス データ モデルに関するページを参照してください。

OData $filter を使用して、PartitionKey と Email プロパティによってフィルター処理する方法を、次のサンプル クエリで示します。

クエリ

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

さまざまなデータ型のフィルター式の作成方法の詳細については、「Querying Tables and Entities (テーブルとエンティティのクエリ)」をご覧ください。

結果

パーティション キー 行キー Email PhoneNumber
Smith Ben Ben@contoso.com 425-555-0102

datetime プロパティに対するクエリでは、Azure Cosmos DB の Table API で実行された場合、データは返されません。 Azure Table Storage では、日付の値がティックの時間粒度で格納されますが、Azure Cosmos DB の Table API では _ts プロパティが使用されます。 _ts プロパティは、OData フィルターではなく、粒度が 2 番目のレベルにあります。 そのため、timestamp プロパティに対するクエリは Azure Cosmos DB によってブロックされます。 回避策として、カスタムの datetime または long データ型プロパティを定義し、クライアントから日付値を設定できます。

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 });

次のステップ

このチュートリアルでは、次の手順を行いました。

  • Table API を使用してクエリを実行する方法を学習しました。

次のチュートリアルに進んで、データをグローバルに分散する方法について学習できます。