Azure Cosmos DB 中的 Indexing metrics

適用於: ✅ 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'])

要在 Go SDK 中啟用索引指標，請在 PopulateIndexMetrics 中設定true為。 QueryItemsResponse 中的索引指標資料已被base64編碼，必須先解碼才能使用。

啟用索引指標會產生額外負擔，因此應僅在除錯緩慢查詢時使用，且不建議在生產環境中使用。

	pager := container.NewQueryItemsPager("SELECT c.id FROM c WHERE CONTAINS(LOWER(c.description), @word)", azcosmos.NewPartitionKey(), &azcosmos.QueryOptions{
		PopulateIndexMetrics: true,
		QueryParameters: []azcosmos.QueryParameter{
			{
				Name:  "@word",
				Value: "happy",
			},
		},
	})

	if pager.More() {
		page, _ := pager.NextPage(context.Background())
		
    // process results

		decoded, _ := base64.StdEncoding.DecodeString(*page.IndexMetrics)
		log.Println("Index metrics", string(decoded))
	}

解碼後，索引指標以 JSON 格式提供。例如：

{
    "UtilizedSingleIndexes": [
        {
            "FilterExpression": "",
            "IndexSpec": "/description/?",
            "FilterPreciseSet": true,
            "IndexPreciseSet": true,
            "IndexImpactScore": "High"
        }
    ],
    "PotentialSingleIndexes": [],
    "UtilizedCompositeIndexes": [],
    "PotentialCompositeIndexes": []
}

範例輸出

在這個範例查詢中，我們觀察到所使用的路徑 /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)的可能性很高，有助於進一步提升效能。

後續步驟

更多關於索引的資訊，請參閱以下文章：

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-19