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