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) 很有可能會進一步改善效能。

下一步

在下列文章中深入了解編製索引：

共用方式為