使用查詢說明功能瞭解查詢效能

您可以透過「查詢說明」功能，將 Firestore 原生模式查詢提交至後端，並取得後端查詢執行的詳細效能統計資料。這項作業的功能與許多關聯式資料庫系統中的 EXPLAIN [ANALYZE] 作業類似。

您可以使用 Firestore 伺服器用戶端程式庫傳送查詢說明要求。

查詢說明結果可協助您瞭解查詢的執行方式，找出效率不彰之處，以及可能導致伺服器端瓶頸的位置。

查詢說明：

  • 提供查詢規劃階段的深入分析，方便您調整查詢索引並提升效率。
  • 使用分析選項，有助於瞭解每項查詢的費用和效能，並快速疊代不同的查詢模式，以最佳化查詢的使用情形。

瞭解查詢說明選項：預設和分析

您可以使用「預設」或「分析」選項執行查詢說明作業。

使用預設選項時，查詢說明會規劃查詢，但略過執行階段。系統會傳回規劃師階段資訊。您可以藉此確認查詢是否具備必要索引，並瞭解使用的索引。舉例來說，這有助於驗證特定查詢是否使用複合式索引，而不必與許多不同的索引交集。

使用分析選項時，查詢說明功能會規劃及執行查詢。這會傳回先前提及的所有規劃工具資訊，以及查詢執行階段的統計資料。這包括查詢的帳單資訊，以及查詢執行的系統層級洞察資料。您可以使用這項工具測試各種查詢和索引設定，進而最佳化費用和延遲時間。

查詢說明的費用是多少？

使用預設選項執行查詢說明時，系統不會執行任何索引或讀取作業。無論查詢複雜度為何，系統都會收取一次讀取作業的費用。

使用「查詢說明」的分析選項時，系統會執行索引和讀取作業，因此您需要照常支付查詢費用。分析活動不會產生額外費用，只會照常收取查詢執行費用。

使用預設選項執行查詢說明

您可以使用用戶端程式庫提交預設選項要求。

請注意，系統會使用 IAM 驗證要求，並採用與一般查詢作業相同的權限。系統會忽略其他驗證技術，例如 Firebase Authentication。詳情請參閱伺服器用戶端程式庫的 IAM 指南。

Java (管理員)

Query q = db.collection("col").whereGreaterThan("a", 1);
ExplainOptions options = ExplainOptions.builder().build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();
ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();
節點 (管理員)

const q = db.collection('col').where('country', '=', 'USA');
const options = { analyze : 'false' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;

回應的確切格式取決於執行環境。 傳回的結果可以轉換為 JSON。例如：

{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, __name__ ASC)"},
        {"query_scope": "Collection", "properties": "(country ASC, __name__ ASC)"},
    ]
}

詳情請參閱「查詢說明報表參考資料」。

使用查詢說明和分析選項

您可以使用用戶端程式庫提交分析選項要求。

請注意，系統會使用 IAM 驗證要求，並採用與一般查詢作業相同的權限。系統會忽略其他驗證技術，例如 Firebase Authentication。詳情請參閱伺服器用戶端程式庫的 IAM 指南。

Java (管理員)

Query q = db.collection("col").whereGreaterThan("a", 1);

ExplainOptions options = ExplainOptions.builder().setAnalyze(true).build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();

ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();
List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
ExecutionStats stats = metrics.getExecutionStats();
節點 (管理員)

const q = db.collection('col').where('country', '=', 'USA');

const options = { analyze : 'true' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;
const indexesUsed = plan.indexesUsed;
const stats = metrics.executionStats;

以下範例顯示除了 planInfo 之外，還傳回的 stats 物件。 回應的確切格式取決於執行環境。範例回應為 JSON 格式。

{
    "resultsReturned": "5",
    "executionDuration": "0.100718s",
    "readOperations": "5",
    "debugStats": {
               "index_entries_scanned": "95000",
               "documents_scanned": "5"
               "billing_details": {
                     "documents_billable": "5",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }

}

詳情請參閱「查詢說明報表參考資料」。

解讀結果並進行調整

以下列情境為例，我們依類型和製作國家/地區查詢電影。

為說明這個情況，請假設有這個 SQL 查詢的對等項目。

SELECT *
FROM /movies
WHERE category = 'Romantic' AND country = 'USA';

如果使用分析選項，傳回的指標會顯示查詢在兩個單一欄位索引 ((category ASC, __name__ ASC) 和 (country ASC, __name__ ASC)) 上執行。掃描 16500 個索引項目，但只傳回 1200 份文件。

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, __name__ ASC)"},
        {"query_scope": "Collection", "properties": "(country ASC, __name__ ASC)"},
    ]
}

// Output query status
{
    "resultsReturned": "1200",
    "executionDuration": "0.118882s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "16500",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

如要盡量提升查詢執行效能，可以建立完全涵蓋的複合索引 (category ASC, country ASC, __name__ ASC)。

再次使用分析選項執行查詢，可以看到系統為這項查詢選取了新建立的索引，而且查詢的執行速度更快、效率更高。

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, country ASC,  __name__ ASC)"}
    ]
}

// Output query stats
{
    "resultsReturned": "1200",
    "executionDuration": "0.026139s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "1200",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}