使用查詢說明功能分析查詢執行作業

本頁面說明如何在執行查詢時，擷取查詢執行資訊。

使用查詢說明

使用查詢說明功能，瞭解查詢的執行方式。您可以根據這些詳細資料最佳化查詢。

您可以透過 Firebase 控制台或 Firestore 伺服器用戶端程式庫使用查詢說明。

控制台

  1. 在 Firebase 控制台中，依序前往「Databases and Storage」>「Firestore」>「Data」>「查詢編輯器」。

  2. 執行要取得執行資訊的查詢。
  3. 點選「查詢說明」分頁標籤，查看查詢分析輸出內容。
Node.js (管理員)
import { field } from '@google-cloud/firestore/pipelines';
 

const q = db.pipeline()
        .collection('/users')
        .sort(field('status').ascending())
        .limit(100);
let results;
try {
    results = await q.execute({
        explainOptions: { mode: 'analyze', outputFormat: 'text' }
    });
} catch (error) {
    console.log(error);
}
const metrics = results?.explainStats?.text;

console.log(metrics);
Java (管理員)
Pipeline q = db.pipeline()
        .collection("/users")
        .sort(field("status").ascending())
        .limit(100);

PipelineExecuteOptions pipelineOpts = new PipelineExecuteOptions().withExplainOptions(
        new ExplainOptions().withExecutionMode(ExplainOptions.ExecutionMode.ANALYZE)
);
Pipeline.Snapshot result = q.execute(pipelineOpts).get();

String metrics = null;
if (result.getExplainStats() != null) {
    metrics = result.getExplainStats().getText();
    System.out.println(metrics);
}

說明模式

視要偵錯的項目而定，您可以使用 Query Explain，以不同模式執行查詢：

  • analyze：規劃並執行查詢。傳回規劃工具資訊、執行階段執行統計資料和指標，以及查詢產生的一般結果。

  • explain：規劃查詢，但不執行。傳回規劃工具資訊，但不傳回執行階段統計資料、指標或結果。這項功能可用於偵錯查詢行為，不必執行高成本作業。

  • stats：規劃並執行查詢，但不傳回結果。傳回規劃工具資訊、執行階段執行統計資料和指標。

分析

Query Explain 的輸出內容包含兩個主要部分：摘要統計資料和執行樹狀結構。請參考以下查詢範例：

db.pipeline().collection('/users').sort(field("status").ascending()).limit(100)

摘要統計資料

說明輸出內容的頂端會顯示執行作業統計資料摘要。您可以根據這些統計資料，判斷查詢是否延遲時間過長或費用過高。此外，其中也包含記憶體統計資料，可讓您瞭解查詢與記憶體限制的差距。

Execution:
 results returned: 2
 request peak memory usage: 20.25 KiB (20,736 B)
 data bytes read: 148 B
 entity row scanned: 2

Billing:
 read units: 1

執行樹狀圖

執行樹狀結構會將查詢執行作業描述為一系列節點。底部節點 (葉節點) 會從儲存層擷取資料，並向上遍歷樹狀結構，產生查詢回應。

如要進一步瞭解各個執行節點，請參閱執行參考資料。

如要瞭解如何運用這項資訊最佳化查詢，請參閱「最佳化查詢執行」。

以下是執行樹狀結構的範例：

Tree:
• Compute
|  $out_1: map_set($record_1, "__name__", $__name___1, "__key__", unset)
|  is query result: true
|
|  Execution:
|   records returned: 2
|   latency: 5.96 ms (local <1 ms)
|
└── • Compute
    |  $__name___1: map_get($record_1, "__key__")
    |
    |  Execution:
    |   records returned: 2
    |   latency: 5.88 ms (local <1 ms)
    |
    └── • MajorSort
        |  fields: [$v_1 ASC]
        |  output: [$record_1]
        |  limit: 100
        |
        |  Execution:
        |   records returned: 2
        |   latency: 5.86 ms (local <1 ms)
        |   peak memory usage: 20.25 KiB (20,736 B)
        |
        └── • Compute
            |  $v_1: map_get($record_1, "status")
            |
            |  Execution:
            |   records returned: 2
            |   latency: 5.23 ms (local <1 ms)
            |
            └── • TableScan
                   source: /users
                   order: UNDEFINED
                   properties: *
                   row range: (-∞..+∞)
                   output record: $record_1
                   variables: [$record_1]

                   Execution:
                    records returned: 2
                    latency: 4.68 ms
                    records scanned: 2
                    data bytes read: 148 B

後續步驟