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

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

使用「查詢說明」

使用查詢說明功能，瞭解查詢的執行方式。 這項資訊可協助您最佳化查詢。

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

控制台

  1. 在 Firebase 控制台中，依序前往「資料庫和儲存空間」>「Firestore」>「資料」>「查詢編輯器」。

  2. 執行要取得執行資訊的查詢。
  3. 按一下「Query Explain」(查詢說明) 分頁標籤，即可查看查詢分析輸出內容。
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);
}

說明模式

視要偵錯的內容而定，您可以在不同模式下執行查詢說明查詢：

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

  • 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

後續步驟