チュートリアル: Table 用 API を使用して Azure Cosmos DB のクエリを実行する

[アーティクル]
03/22/2023

適用対象: Table

Azure Cosmos DB for Table では、キー/値 (テーブル) データに対する 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 アカウントがあり、コンテナーにエンティティデータがあることが必要です。アカウントまたはデータがない場合は、「クイックスタート: .NET 用 Azure Cosmos DB for Table」を完了して、アカウントを作成し、データベースにデータを入力します。

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

Azure Cosmos DB の Table 用 API で実行された場合、datetime プロパティに対するクエリからはデータは返されません。 Azure Table Storage では、日付の値がティックの時間粒度で格納されますが、Azure Cosmos DB の Table 用 API では _ts プロパティが使用されます。 _ts プロパティは、OData フィルターではなく、粒度が 2 番目のレベルにあります。 Azure Cosmos DB は、timestamp プロパティに対するクエリをブロックします。回避策として、カスタムの 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 });

次のステップ

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

テーブル用 API を使用して Azure Cosmos DB グローバル分散を設定する