你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Cosmos DB 中的索引指标

项目
08/15/2024

适用范围： 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 费用和延迟，以识别耗费大量资源的查询。

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

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

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

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

可以通过在查询项中传入 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
    ---

已利用的索引路径

已利用的单一索引和已利用的组合索引分别显示查询使用的包含路径和组合索引。查询可以使用多个索引路径，以及包含路径和组合索引的组合。如果索引路径未列为已利用，则删除索引路径不会影响查询的性能。

将已利用的索引路径的列表视为查询使用了这些路径的证据。如果你不确定新的索引路径是否会提高查询性能，应尝试添加新的索引路径，并检查查询是否使用它们。

可能的索引路径

可能的单一索引和潜在的组合索引分别显示查询可能利用的包含路径和组合索引（如果已添加）。如果你看到可能的索引路径，应考虑将它们添加到索引策略，并观察它们是否会提高查询性能。

将可能的索引路径的列表视为建议，而不是查询将使用特定索引路径的最终证据。可能的索引路径不是查询可以使用的索引路径的详尽列表。此外，某些可能的索引路径可能不会影响查询性能。添加建议的索引路径并确认它们会提高查询性能。

注意

你对指标的索引有何反馈？我们想听一听！欢迎直接与 Azure Cosmos DB 工程团队分享反馈：cosmosdbindexing@microsoft.com

索引影响分数

索引影响分数是基于查询形状的索引路径对查询性能产生重大影响的可能性。换句话说，索引影响分数是在没有该特定索引路径的情况下，查询 RU 费用就会高得多的可能性。

有两个可能的索引影响分数：“高”和“低”。如果有多个可能的索引路径，我们建议重点关注具有“高”影响分数的索引路径。

索引影响分数中使用的唯一条件是查询形状。例如，在以下查询中，会为索引路径 /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) 很有可能会进一步提高性能。

后续步骤

阅读以下文章中有关索引的详细信息：

通过