Azure Cosmos DB のインデックス作成メトリック

適用対象: NoSQL

Azure Cosmos DB には、使用されたインデックス付きパスと推奨されるインデックス付きパスの両方を示すためのインデックス作成メトリックが用意されています。 インデックス作成メトリックを使用すると、特にインデックス作成ポリシーを変更する方法がわからない場合に、クエリのパフォーマンスを最適化できます。

サポートされる SDK バージョン

インデックス作成メトリクスがサポートされている SDK バージョン: | SDK | サポートされているバージョン | | --- | --- | | .NET SDK v3 | >= 3.21.0 | | Java SDK v4 | >= 4.19.0 | | Python SDK | >= 4.6.0 |

インデックス作成メトリックを有効にする

PopulateIndexMetrics プロパティを true に設定すると、クエリのインデックス作成メトリックを有効にすることができます。 指定しない場合、PopulateIndexMetrics の既定値は false です。 クエリのパフォーマンスのトラブルシューティングにのみ、インデックス メトリックを有効にすることをお勧めします。 クエリとインデックス作成ポリシーが同じであれば、インデックス メトリックが変化することはほとんどありません。 代わりに、診断ログを使用してクエリ RU の料金と待機時間を監視することで、コストの高いクエリを特定することをお勧めします。

.NET SDK

    string sqlQueryText = "SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2";

    QueryDefinition query = new QueryDefinition(sqlQueryText);

    FeedIterator<Item> resultSetIterator = container.GetItemQueryIterator<Item>(
                query, requestOptions: new QueryRequestOptions
        {
            PopulateIndexMetrics = true
        });

    FeedResponse<Item> response = null;

    while (resultSetIterator.HasMoreResults)
        {
          response = await resultSetIterator.ReadNextAsync();
          Console.WriteLine(response.IndexMetrics);
        }

Java SDK Sync

    SqlQuerySpec querySpec = new SqlQuerySpec("SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2");
    CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
    options.setIndexMetricsEnabled(true);

    CosmosPagedIterable<JsonNode> items = container.queryItems(querySpec, options, JsonNode.class);

    // Print
    items.iterableByPage().forEach(itemResponse -> {
        logger.info("diagnostics: {}", itemResponse.getCosmosDiagnostics());
        for (JsonNode item : itemResponse.getResults()) {
            logger.info("Item: {}", item.toString());
        }
    });  

Java SDK Async

    SqlQuerySpec querySpec = new SqlQuerySpec("SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2");
    CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
    options.setIndexMetricsEnabled(true);

    CosmosPagedFlux<JsonNode> items = container.queryItems(querySpec, options, JsonNode.class);
    
    // Print
    items.byPage(100).flatMap(itemsResponse -> {
        logger.info("diagnostics: {}",itemsResponse.getCosmosDiagnostics());
        for (JsonNode item : itemsResponse.getResults()) {
            logger.info("Item: {}", item.toString());
        }
        executeCountQueryPrintSingleResultNumber.incrementAndGet();
        return Flux.just(itemsResponse);
    }).blockLast();   

JavaScript SDK

const querySpec = {
    query: "SELECT TOP 10 c.id FROM c WHERE c.Item = 'value1234' AND c.Price > 2",
  };
const { resources: resultsIndexMetrics, indexMetrics } = await container.items
    .query(querySpec, { populateIndexMetrics: true })
    .fetchAll();
console.log("IndexMetrics: ", indexMetrics);

Python SDK

populate_index_metrics キーワードをクエリ項目で渡し、"x-ms-cosmos-index-utilization" ヘッダーの値を応答から読み取ることでインデックス メトリクスをキャプチャできます。 このヘッダーは、クエリから項目が返される場合にのみ返されます。

query_items = container.query_items(query="Select * from c",
    enable_cross_partition_query=True,
    populate_index_metrics=True)

print(container.client_connection.last_response_headers['x-ms-cosmos-index-utilization'])

出力例

このクエリ例では、使用されているパス /Item/? と /Price/?、および考えられる複合インデックス (/Item ASC, /Price ASC) を確認します。

Index Utilization Information
  Utilized Single Indexes
    Index Spec: /Item/?
    Index Impact Score: High
    ---
    Index Spec: /Price/?
    Index Impact Score: High
    ---
  Potential Single Indexes
  Utilized Composite Indexes
  Potential Composite Indexes
    Index Spec: /Item ASC, /Price ASC
    Index Impact Score: High
    ---

使用されたインデックス付きパス

使用された単一のインデックスと使用された複合インデックスは、それぞれ、インクルード パスと、クエリで使用された複合インデックスを示しています。 クエリでは、複数のインデックス付きパスと、インクルード パスと複合インデックスの組み合わせを使用できます。 インデックス付きパスが使用されたものとして表示されていない場合、インデックス付きパスを削除しても、クエリのパフォーマンスには影響しません。

使用されたインデックス付きパスの一覧については、クエリでそれらのパスが使用された証拠と考えてください。 新しいインデックス付きのパスによってクエリのパフォーマンスが向上するかどうかわからない場合は、新しいインデックス付きパスを追加し、クエリで使用されているかどうかを確認する必要があります。

考えられるインデックス付きパス

考えられる単一のインデックスと使用された複合インデックスは、それぞれ、インクルード パスと、追加されていれば、クエリで使用された可能性のある複合インデックスを示しています。 考えられるインデックス付きパスがある場合は、それらをインデックス作成ポリシーに追加して、クエリのパフォーマンスが向上するかどうかを確認する必要があります。

考えられるインデックス付きパスの一覧は、クエリで特定のインデックス付きパスが使用されることの明確な証拠ではなく、推奨されるものと考えてください。 考えられるインデックス付きパスは、クエリで使用されるインデックス付きパスの網羅的な一覧ではありません。 また、考えられるインデックス付きパスの中には、クエリのパフォーマンスに影響しないものもあります。 推奨されるインデックス付きパスを追加し、クエリのパフォーマンスが向上することを確認します。

Note

インデックス作成メトリックについてフィードバックをお寄せください。 ご意見をお待ちしています。 ぜひ、Azure Cosmos DB エンジニアリング チーム (cosmosdbindexing@microsoft.com) まで直接ご意見をお寄せください。

インデックスの影響スコア

インデックスの影響スコアとは、クエリ シェイプに基づいて、インデックス付きパスがクエリのパフォーマンスに大きな影響を与える見込みのことです。 言い換えれば、インデックスの影響スコアは、その特定のインデックス付きパスを使用しなければ、クエリ RU の料金が大幅に高くなっていた可能性を示すものです。

インデックスの影響スコアは、高 と 低 の 2 つがあります。 考えられるインデックス付きパスが複数ある場合は、高の影響スコアを持つインデックス付きパスに注目することをお勧めします。

インデックスの影響スコアで使用される基準は、クエリ シェイプだけです。 たとえば、次のクエリでは、インデックス付きパス /name/? に高のインデックスの影響スコアが割り当てられます。

SELECT * 
FROM c
WHERE c.name = "Samer"

実際の影響は、データの性質によって異なります。 /name フィルターに一致する項目が少数の場合、インデックス付きのパスによってクエリ RU の料金が大幅に向上します。 ただし、ほとんどの項目が /name フィルターに一致してしまう場合、インデックス付きのパスではクエリのパフォーマンスが向上しない可能性があります。 いずれの場合も、インデックス付きパス /name/? には高のインデックスの影響スコアが割り当てられます。これは、クエリ シェイプに基づいて、インデックス付きパスがクエリのパフォーマンスを向上させる可能性が高いためです。

追加の例

クエリの例

SELECT c.id 
FROM c 
WHERE c.name = 'Tim' AND c.age > 15 AND c.town = 'Redmond' AND c.timestamp > 2349230183

インデックス メトリック

Index Utilization Information
  Utilized Single Indexes
    Index Spec: /name/?
    Index Impact Score: High
    ---
    Index Spec: /age/?
    Index Impact Score: High
    ---
    Index Spec: /town/?
    Index Impact Score: High
    ---
    Index Spec: /timestamp/?
    Index Impact Score: High
    ---
  Potential Single Indexes
  Utilized Composite Indexes
  Potential Composite Indexes
    Index Spec: /name ASC, /town ASC, /age ASC
    Index Impact Score: High
    ---
    Index Spec: /name ASC, /town ASC, /timestamp ASC
    Index Impact Score: High
    ---

これらのインデックス メトリックは、クエリがインデックス付きパス /name/?、/age/?、/town/?、/timestamp/? を使用したことを示しています。 また、インデックス メトリックは、複合インデックス (/name ASC, /town ASC, /age ASC)、(/name ASC, /town ASC, /timestamp ASC) を追加するとパフォーマンスがさらに向上する可能性が高いことも示しています。

次のステップ

以下の記事で、インデックス作成についての詳細を参照してください。

• インデックス作成の概要
• インデックス作成ポリシーを管理する方法