.NET を使用して Azure Cosmos DB for NoSQL の項目のクエリを実行する

[アーティクル]
08/15/2024

適用対象: NoSQL

Azure Cosmos DB 内の項目は、コンテナー内に格納されているエンティティを表します。 NoSQL 用 API では、項目は一意の識別子を含む JSON 形式のデータから成ります。 NoSQL 用 API を使用してクエリを発行すると、JSON ドキュメントの JSON 配列として結果が返されます。

SQL を使用して項目のクエリを実行する

Azure Cosmos DB for NoSQL では、構造化照会言語 (SQL) を使用してコンテナー内の項目に対してクエリを実行できます。 SELECT * FROM products などの単純な SQL クエリは、コンテナーからすべての項目とプロパティを返します。クエリは、さらに複雑にして、特定のフィールドプロジェクション、フィルター、およびその他の一般的な SQL 句を含めることができます。

SELECT 
    p.name, 
    p.description AS copy
FROM 
    products p 
WHERE 
    p.price > 500

Azure Cosmos DB for NoSQL の SQL 構文の詳細については、「SQL クエリの使用を開始する」を参照してください。

項目にクエリを実行する

注意

この記事の例は、Product という名前のデータを表すために C# 型が既に定義されていることを前提としています。

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

コンテナー内の項目に対してクエリを実行するには、次のいずれかのメソッドを呼び出します。

GetItemQueryIterator<>
GetItemLinqQueryable<>

SQL クエリを使用して項目のクエリを非同期的に実行する

この例では、単純な文字列を使用して SQL クエリを作成し、フィード反復子を取得してから、入れ子になったループを使用して結果を反復処理します。外側の while ループは結果ページを反復処理し、内側の foreach ループはページ内の結果を反復処理します。

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products p WHERE p.quantity > 10"
);

// Iterate query result pages
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Container.GetItemQueryIterator<> メソッドにより、複数ページの結果を反復処理するために使用する FeedIterator<> が返されます。 HasMoreResults プロパティは、それ以上の結果ページが残っているかどうかを示します。 ReadNextAsync メソッドにより、結果の次のページが列挙可能として取得され、ループで結果を反復処理するために使用されます。

または、QueryDefinition を使用して、パラメーター化された入力を使用して SQL クエリを作成します。

// Build query definition
var parameterizedQuery = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.quantity > @quantity"
)
    .WithParameter("@quantity", 10);

// Query multiple items from container
using FeedIterator<Product> filteredFeed = container.GetItemQueryIterator<Product>(
    queryDefinition: parameterizedQuery
);

// Iterate query result pages
while (filteredFeed.HasMoreResults)
{
    FeedResponse<Product> response = await filteredFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

ヒント

パラメーター化された入力値は、多くの一般的な SQL クエリインジェクション攻撃を防ぐのに役立ちます。

LINQ を使用して項目のクエリを非同期的に実行する

この例では、IQueryable<> オブジェクトを使用して、言語統合クエリ (LINQ) を作成します。その後、結果がフィード反復子を使用して反復処理されます。

// Get LINQ IQueryable object
IOrderedQueryable<Product> queryable = container.GetItemLinqQueryable<Product>();

// Construct LINQ query
var matches = queryable
    .Where(p => p.quantity > 10);

// Convert to feed iterator
using FeedIterator<Product> linqFeed = matches.ToFeedIterator();

// Iterate query result pages
while (linqFeed.HasMoreResults)
{
    FeedResponse<Product> response = await linqFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Matched item:\t{item.name}");
    }
}

Container.GetItemLinqQueryable<> メソッドにより、LINQ クエリを作成する IQueryable が作成されます。その後、ToFeedIterator<> メソッドを使用して LINQ クエリ式を FeedIterator<> に変換します。

ヒント

IQueryable<> を反復処理する間、この操作は同期的です。非同期的に結果を収集するには、ToFeedIterator<> メソッドを使用してください。

次のステップ

複数の項目に対してクエリを実行したので、NoSQL 用 API を使用したエンドツーエンドのチュートリアルのいずれかを試してみます。

Azure Cosmos DB for NoSQL にクエリを実行しデータを追加するアプリをビルドする

次の方法で共有