管理 Cloud Firestore 中的索引

Cloud Firestore 規定每個查詢都必須有索引，確保查詢效能。系統會自動建立最基本查詢所需的索引。使用及測試應用程式時，Cloud Firestore 會產生錯誤訊息，協助您建立應用程式所需的其他索引。本頁說明如何管理自動、手動和向量索引。

透過錯誤訊息建立缺少的索引

如果您嘗試使用範圍子句進行複合查詢，但該子句未對應至現有索引，系統會傳回錯誤。錯誤訊息會提供直接連結，方便您在 Firebase 控制台中建立缺少的索引。

按照產生的連結前往 Firebase 控制台，查看自動填入的資訊，然後按一下「建立」。

如果需要向量索引，錯誤訊息會包含 Google Cloud CLI 指令，用於建立缺少的向量索引。執行指令，建立缺少的索引。

角色和權限

如要在 Cloud Firestore 中建立索引，請務必先獲派下列任一角色：

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

如果您已定義自訂角色，請指派下列所有權限來建立索引：

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

使用 Firebase 控制台

如要透過 Firebase 控制台手動建立新索引，請按照下列步驟操作：

Firebase 控制台中的 Firestore 索引介面圖片

  1. 在 Firebase 控制台中，依序前往「資料庫和儲存空間」>「Firestore」。
  2. 在「索引」分頁中，按一下「新增索引」。
  3. 輸入集合名稱，並設定要用來排序索引的欄位。
  4. 點選「建立」。

索引欄位必須符合欄位路徑限制。

視查詢大小而定，建立索引可能需要幾分鐘的時間。 建立索引後，您可以在「複合索引」部分查看索引和狀態。如果仍在建構中，Firebase 控制台會顯示建構狀態列。

移除索引

如要刪除索引，請按照下列步驟操作：

  1. 在 Firebase 控制台中，依序前往「資料庫和儲存空間」>「Firestore」。
  2. 在「索引」分頁中，將游標懸停在要刪除的索引上，然後從內容選單選取「刪除」。
  3. 按一下快訊中的「刪除」，確認要刪除。

使用 Firebase CLI

您也可以使用 Firebase CLI 部署索引。 如要開始使用，請在專案目錄中執行 firebase init firestore。 設定期間，Firebase CLI 會產生 JSON 檔案，其中包含格式正確的預設索引。編輯檔案以新增更多索引，然後使用 firebase deploy 指令部署檔案。

如要只部署 Cloud Firestore 索引和規則，請新增 --only firestore 旗標。

如果您使用 Firebase 控制台編輯索引，請務必同時更新本機索引檔案。請參閱 JSON 索引定義參考資料。

使用 Terraform

在資料庫中建立索引

Cloud Firestore 資料庫可包含單一欄位 (自動) 和複合式 (手動) 索引。您可以編輯 Terraform 設定檔，為資料庫建立索引。自動和手動索引使用不同的 Terraform 資源類型 (google_firestore_index 和 google_firestore_field)。

單一欄位 (自動) 索引

以下範例 Terraform 設定檔會在 chatrooms 集合的 name 欄位上建立單一欄位索引：

firestore.tf

resource "random_id" "variable"{
  byte_length = 8
}

resource "google_firestore_field" "single-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms_${random_id.variable.hex}"
  field = "name"

  index_config {
    indexes {
        order = "ASCENDING"
        query_scope = "COLLECTION_GROUP"
    }
    indexes {
        array_config = "CONTAINS"
    }
  }

  ttl_config {}
}
  • 將 project-id 替換為專案 ID。專案 ID 不得重複。
  • 將 database-id 替換為資料庫 ID。

複合式 (手動) 索引

下列 Terraform 設定檔範例會為 chatrooms 集合中的 name 欄位和 description 欄位組合建立複合索引：

firestore.tf

resource "google_firestore_index" "composite-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

}
  • 將 project-id 替換為專案 ID。專案 ID 不得重複。
  • 將 database-id 替換為資料庫 ID。

向量索引

以下 Terraform 設定檔範例會在 chatrooms 集合的 embedding 欄位中建立向量索引：

firestore.tf

resource "google_firestore_index" "vector-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms"

  fields {
    field_path = "__name__"
    order = "ASCENDING"
  }

  fields {
    field_path = "embedding"
    vector_config {
      dimension = 128
      flat {}
    }
  }
}
  • 將 project-id 替換為專案 ID。專案 ID 不得重複。
  • 將 database-id 替換為資料庫 ID。

索引建構時間

如要建構索引，Cloud Firestore 必須設定索引，然後使用現有資料回填索引。索引建構時間是設定時間和回填時間的總和：

  • 設定索引需要幾分鐘的時間。即使是空白資料庫，建立索引也至少需要幾分鐘。

  • 回填時間取決於新索引中現有資料的數量。與索引定義相符的欄位值越多，回填索引所需的時間就越長。

建立索引是長時間執行的作業。

啟動索引建構作業後，Cloud Firestore 會為作業指派不重複的名稱。作業名稱的前置字串為 projects/[PROJECT_ID]/databases/(default)/operations/，例如：

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

不過，為 describe 指令指定作業名稱時，可以省略前置字串。

列出所有長時間執行的作業

如要列出長時間執行的作業，請使用 gcloud firestore operations list 指令。這個指令會列出進行中和最近完成的作業。 匯出完成後其項目會保留幾天以供存取：

gcloud firestore operations list

檢查作業狀態

您可以列出單一作業的詳細資料，而不必列出所有長時間執行的作業：

gcloud firestore operations describe operation-name

估算完成時間

作業執行時，可查看 state 欄位值，以瞭解作業的整體狀態。

用於取得長時間執行的作業狀態的要求，也會傳回 workEstimated 和 workCompleted 指標。這些指標會針對文件數量傳回。workEstimated 顯示作業預計處理的文件總數。workCompleted 會顯示目前處理的文件數量。作業完成後，workCompleted 會反映出實際處理的文件總數，可能與 workEstimated 的值不同。

將 workCompleted 除以 workEstimated 可得出進度的粗估值。此估計可能不準確，因為此取決於延遲的統計數據收集。

例如，以下是索引建構作業的進度狀態：

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressDocuments": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

作業完成時，作業說明中會包含 "done": true。查看 state 欄位值可得知作業結果。如果未在回應中設定 done 欄位，則其值為 false。若是進行中的作業，則不用考慮是否有 done 值。

建立索引時發生錯誤

管理手動索引和自動索引豁免項目時，可能會發生索引建構錯誤。如果 Cloud Firestore 在建立索引時遇到資料問題，索引作業可能會失敗。最常見的原因是達到索引上限。舉例來說，作業可能已達到每個文件的索引項目數量上限。

如果索引建立失敗，控制台中會顯示錯誤訊息。確認未達到任何索引限制後，請重試索引作業。