Cloud Firestore 會要求每個查詢都必須有索引,以確保查詢效能。系統會為您自動建立大多數基本查詢所需的索引。您使用及測試應用程式時,Cloud Firestore 會產生錯誤訊息,協助您建立應用程式需要的其他索引。本頁面說明如何管理單一欄位和複合式索引。
透過錯誤訊息建立遺漏的索引
如果您嘗試建立範圍子句無法對應至現有索引的複合式查詢,則會收到錯誤訊息。錯誤訊息會提供直接連結,方便您在 Firebase 控制台中建立缺少的索引。
點選產生的連結前往 Firebase 控制台,查看系統自動填入的資訊,然後按一下「建立」。
角色和權限
在 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 控制台的 Cloud Firestore 部分。
- 前往「索引」分頁,然後按一下「新增索引」。
- 輸入集合名稱,並設定要依據哪些欄位排序索引。
- 按一下「建立」。
索引欄位必須符合欄位路徑限制。
索引可能需要幾分鐘才能建立完成,實際時間取決於查詢的大小。建立索引後,您可以在「複合索引」專區中查看索引和其狀態。如果仍在建構,Firebase 控制台會顯示建構狀態列。
移除索引
如要刪除索引,請按照下列步驟操作:
- 前往 Firebase 控制台的 Cloud Firestore 部分。
- 按一下「索引」分頁標籤。
- 將游標懸停在要刪除的索引上,然後從內容選單中選取「刪除」。
- 按一下快訊中的「刪除」,確認要刪除。
使用 Firebase CLI
您也可以使用 Firebase CLI 部署索引。如要開始使用,請在專案目錄中執行 firebase init firestore
。在設定期間,Firebase CLI 會產生具有正確格式預設索引的 JSON 檔案。您可以編輯該檔案,新增更多索引,並使用 firebase deploy
指令部署檔案。
如果只要部署 Cloud Firestore 索引和規則,請新增 --only firestore
標記。
如果您使用 Firebase 主控台編輯索引,請務必一併更新本機索引檔案。請參閱 JSON 索引定義參考資料。
使用 Terraform
在資料庫中建立索引
Cloud Firestore 資料庫可同時包含單一欄位和複合式索引。您可以編輯 Terraform 設定檔,為資料庫建立索引。單一欄位和複合式索引會使用不同的 Terraform 資源類型。
單一欄位索引
以下範例 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。
索引建構時間
如要建構索引,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 為索引資料發生問題,索引作業可能會失敗。在大多數的情況下,這表示您達到了索引限制。例如,該作業可能已達到每個文件的索引項目數量上限。
如果索引建立失敗,控制台中會顯示錯誤訊息。確認未達到任何索引限制後,請重試索引作業。