使用 Azure Cosmos DB Python SDK 取得 SQL 查詢執行計量並分析查詢效能

適用於：NoSQL

本文說明如何使用查詢執行計量來分析 Azure Cosmos DB 上的 SQL 查詢效能。 它包含累計計量，這些計量會匯總至要求的所有實體分割區、每個實體分割區的計量清單，以及要求費用總計。 微調查詢效能一文詳述這些計量。

啟用查詢計量

若要取得查詢計量，您必須在查詢參數中將 旗標設定 populate_query_metrics 為 True ，如下所示。 您可能有興趣啟用索引計量以及進行偵錯，而且您可以將 旗標設定 populate_query_metrics 為 來 True加以啟用：

Python

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_index_metrics=True,
    populate_query_metrics=True
)

取得查詢執行計量

在 Python SDK 中，您可以從容器用戶端讀取 x-ms-documentdb-query-metrics 標頭值，以取得查詢執行計量。 下列代碼段示範如何讀取查詢執行計量：

Python

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_query_metrics=True
)

items = [item for item in results]
'''
Please note that the last_response_headers are available only after the first iteration of the results as the query execution starts only when result iteration begins
'''
print("Query Metrics: ",container.client_connection.last_response_headers['x-ms-documentdb-query-metrics'])

結果會提供查詢執行相關信息，如下所示：

Python

totalExecutionTimeInMs=0.27;
queryCompileTimeInMs=0.04;
queryLogicalPlanBuildTimeInMs=0.00;
queryPhysicalPlanBuildTimeInMs=0.02;
queryOptimizationTimeInMs=0.00;
VMExecutionTimeInMs=0.02;
indexLookupTimeInMs=0.00;
instructionCount=17;
documentLoadTimeInMs=0.01;
systemFunctionExecuteTimeInMs=0.00;
userFunctionExecuteTimeInMs=0.00;
retrievedDocumentCount=3;
retrievedDocumentSize=1005;
outputDocumentCount=3;
outputDocumentSize=1056;
writeOutputTimeInMs=0.00;
indexUtilizationRatio=1.00

上述結果可讓您深入了解查詢的效率。 您可以查看 totalExecutionTimeInMs，以查看查詢執行所花費的時間長度。 indexUtilizationRatio 可讓您深入了解查詢使用索引的方式。 若要深入瞭解計量，請參閱 查詢執行計量 一文。

取得查詢要求費用

您可以擷取讀取 x-ms-request-charge 值所取用的要求單位總計（RU）。 您不需要明確設定任何參數，即可擷取要求費用值。 下列範例示範如何取得每個查詢接續的要求費用：

Python

items = [item for item in results]
print("Request Units consumed: ",container.client_connection.last_response_headers['x-ms-request-charge'])

取得索引使用率

查看索引使用率可協助您偵錯緩慢的查詢。 良好的索引使用率分數必須接近 1。 無法使用索引的查詢，會在傳回結果集之前，先完整掃描容器中的所有檔。

以下是掃描查詢的範例：

SQL

SELECT VALUE c.description 
FROM   c 
WHERE UPPER(c.description) = "BABYFOOD, DESSERT, FRUIT DESSERT, WITHOUT ASCORBIC ACID, JUNIOR"

此查詢的篩選條件使用未經索引處理的系統函數 UPPER。 針對大型集合執行此查詢時，第一次延續會產生下列查詢計量：

QueryMetrics

Retrieved Document Count                 :          60,951
Retrieved Document Size                  :     399,998,938 bytes
Output Document Count                    :               7
Output Document Size                     :             510 bytes
Index Utilization                        :            0.00 %
Total Query Execution Time               :        4,500.34 milliseconds
Query Preparation Time                   :             0.2 milliseconds
Index Lookup Time                        :            0.01 milliseconds
Document Load Time                       :        4,177.66 milliseconds
Runtime Execution Time                   :           407.9 milliseconds
Document Write Time                      :            0.01 milliseconds

在查詢計量輸出中，請注意下列值：

Retrieved Document Count                 :          60,951
Retrieved Document Size                  :     399,998,938 bytes

此查詢載入 60,951 個文件，總計 399,998,938 個位元組。 載入如此多位元組導致很高的成本或要求單位費用。 執行此查詢也耗時甚久，從花費總時間屬性即可明白：

Total Query Execution Time               :        4,500.34 milliseconds

表示執行查詢花 4.5 秒 (這只是一次延續)。

若要將此範例查詢最佳化，請避免在篩選條件中使用 UPPER。 相反地，在建立或更新文件時，必須以全部大寫字元插入 c.description 值。 於是查詢變成：

SQL

SELECT VALUE c.description 
FROM   c 
WHERE c.description = "BABYFOOD, DESSERT, FRUIT DESSERT, WITHOUT ASCORBIC ACID, JUNIOR"

此查詢現在可以經過索引處理。 或者，您可以使用計算屬性來編製系統函數或複雜計算結果的索引，否則會導致完整掃描。

若要查看潛在的索引建議，並檢查已使用哪些索引，您必須將 參數設定 populate_index_metrics 為 True ，然後您可以從容器用戶端讀取 x-ms-documentdb-index-utilization 標頭值。 下列代碼段示範如何讀取索引使用率計量：

Python

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_index_metrics = True
)
items = [item for item in results]
print("Index Utilization Info: ",container.client_connection.last_response_headers['x-ms-cosmos-index-utilization'])

若要深入了解微調查詢效能，請參閱微調查詢效能一文。

參考資料

• Azure Cosmos DB SQL 規格

下一步

• 調整查詢效能
• 索引編製概觀
• Azure Cosmos DB Python SDK 最佳做法
• Azure Cosmos DB Python SDK 效能秘訣