Cloud Firestore stellt die Abfrageleistung sicher, indem für jede Abfrage. Die für die einfachsten Abfragen erforderlichen Indexe werden automatisch erstellt haben. Während Sie Ihre Anwendung verwenden und testen, zeigt Cloud Firestore Fehlermeldungen an, mit deren Hilfe Sie zusätzliche Indexe erstellen können, die für Ihre Anwendung erforderlich sind. Auf dieser Seite wird beschrieben, wie Sie Ihr Einzelfeldindexe und zusammengesetzte Indexe.
Fehlenden Index über eine Fehlermeldung erstellen
Wenn Sie versuchen, eine kumulierende Abfrage mit einer Bereichsklausel auszuführen, die keinem vorhandenen Index zugeordnet ist, erhalten Sie einen Fehler. Die Fehlermeldung enthält einen direkten Link zum Erstellen des fehlenden Index in der Firebase Console.
Folgen Sie dem erstellten Link zur Firebase Console, prüfen Sie die automatisch ausgefüllten Informationen und klicken Sie auf Erstellen.
Rollen und Berechtigungen
Bevor Sie einen Index in Cloud Firestore erstellen können, muss Ihnen eine der folgenden Rollen zugewiesen sein:
roles/datastore.owner
roles/datastore.indexAdmin
roles/editor
roles/owner
Wenn Sie benutzerdefinierte Rollen definiert haben, weisen Sie zum Erstellen von Indexen alle folgenden Berechtigungen zu:
datastore.indexes.create
datastore.indexes.delete
datastore.indexes.get
datastore.indexes.list
datastore.indexes.update
Firebase Console verwenden
So erstellen Sie manuell einen neuen Index über die Firebase Console:
- Gehen Sie in der Firebase Console zum Abschnitt Cloud Firestore.
- Rufen Sie den Tab Indexe auf und klicken Sie auf Index hinzufügen.
- Geben Sie den Namen der Sammlung ein und legen Sie die Felder fest, nach denen der Index sortiert werden soll.
- Klicken Sie auf Erstellen.
Indexfelder müssen den Einschränkungen für Feldpfade entsprechen.
Das Erstellen der Indexe kann je nach Größe der Abfrage einige Minuten dauern. Nachdem Sie sie erstellt haben, können Sie Ihre Indexe und ihren Status in der Abschnitt „Zusammengesetzte Indexe“. Wenn sie sich noch im Aufbau befinden, enthält die Firebase Console Statusleiste eines Gebäudes.
Indexe entfernen
So löschen Sie einen Index:
- Gehen Sie in der Firebase Console zum Abschnitt Cloud Firestore.
- Klicken Sie auf den Tab Indexe.
- Bewegen Sie den Mauszeiger auf den Index, den Sie löschen möchten, und wählen Sie im Kontextmenü Löschen aus.
- Bestätigen Sie, dass Sie sie löschen möchten, indem Sie in der Benachrichtigung auf Löschen klicken.
Firebase CLI verwenden
Sie können Indexe auch mit Firebase CLI bereitstellen.
Führen Sie zuerst firebase init firestore
in Ihrem Projektverzeichnis aus.
Während der Einrichtung erstellt Firebase CLI eine JSON-Datei mit den Standardindexen im richtigen Format. Bearbeiten Sie die Datei, um weitere Indexe hinzuzufügen, und stellen Sie sie mit dem Befehl firebase deploy
bereit.
Wenn Sie nur Cloud Firestore-Indexe und -Regeln bereitstellen möchten, fügen Sie den
--only firestore
-Flag.
Wenn Sie über die Firebase Console Änderungen an den Indexen vornehmen, Aktualisieren Sie auch Ihre lokale Indexdatei. Weitere Informationen finden Sie unter die Referenz zur JSON-Indexdefinition
Terraform verwenden
Indexe in der Datenbank erstellen
Cloud Firestore-Datenbanken können sowohl Einzelfeldindexe als auch zusammengesetzte Indexe enthalten. Sie können die Terraform-Konfigurationsdatei bearbeiten, um einen Index für Ihre Datenbank zu erstellen. Einzelfeld- und zusammengesetzte Indexe verwenden unterschiedliche Terraform-Ressourcentypen.
Einzelfeldindex
In der folgenden Beispiel-Terraform-Konfigurationsdatei wird ein Index mit einem einzelnen Feld für das Feld name
in der Sammlung chatrooms
erstellt:
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 {} }
- Ersetzen Sie project-id durch Ihre Projekt-ID. Projekt-IDs müssen eindeutig sein.
- Ersetzen Sie database-id durch Ihre Datenbank-ID.
Zusammengesetzter Index
In der folgenden Beispiel-Terraform-Konfigurationsdatei wird ein zusammengesetzter Index für eine Kombination aus dem Feld name
und dem Feld description
in der Sammlung chatrooms
erstellt:
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" } }
- Ersetzen Sie project-id durch Ihre Projekt-ID. Projekt-IDs müssen eindeutig sein.
- Ersetzen Sie database-id durch Ihre Datenbank-ID.
Indexerstellungszeit
Zum Erstellen eines Index muss Cloud Firestore den Index einrichten und dann den Index mit vorhandenen Daten auffüllen. Die Indexerstellungszeit ergibt sich aus der Summe der Einrichtungs- und der Backfill-Zeit:
Die Einrichtung eines Index dauert einige Minuten. Die Mindesterstellungszeit für einen Index beträgt einige Minuten, auch bei einer leeren Datenbank.
Die Dauer des Backfill hängt davon ab, wie viele vorhandene Daten in den neuen Index gehören. Je mehr Feldwerte mit der Indexdefinition übereinstimmen, desto länger dauert es, bis der Index befüllt ist.
Index-Builds sind Vorgänge mit langer Ausführungszeit.
Nach dem Start einer Indexerstellung weist Cloud Firestore
dem Vorgang einen eindeutigen Namen geben. Vorgangsnamen haben das Präfix projects/[PROJECT_ID]/databases/(default)/operations/
, zum Beispiel:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Wenn Sie für den Befehl describe
einen Vorgangsnamen angeben, können Sie das Präfix weglassen.
Lang andauernde Vorgänge auflisten
Verwenden Sie zum Auflisten lang andauernder Vorgänge den Befehl gcloud firestore operations list. Dieser Befehl listet laufende und kürzlich abgeschlossene Vorgänge auf. Die Vorgänge sind nach Abschluss einige Tage lang in der Liste enthalten:
gcloud firestore operations list
Vorgangsstatus prüfen
Anstelle aller Vorgänge mit langer Ausführungszeit können Sie auch die Details eines einzelnen Vorgangs auflisten:
gcloud firestore operations describe operation-name
Fertigstellungszeit schätzen
Während der Ausführung eines Vorgangs wird im Feld state
der Gesamtstatus des Vorgangs angezeigt.
Eine Anfrage für den Status eines Vorgangs mit langer Ausführungszeit gibt auch die Messwerte workEstimated
und workCompleted
zurück. Diese Messwerte werden für die Anzahl der Dokumente zurückgegeben. workEstimated
gibt die geschätzte Gesamtzahl der Dokumente an, die ein Vorgang verarbeitet. workCompleted
gibt die Anzahl der bisher verarbeiteten Dokumente an. Nach Abschluss des Vorgangs gibt workCompleted
die Gesamtzahl der tatsächlich verarbeiteten Dokumente wieder, die sich vom Wert von workEstimated
unterscheiden können.
Teilen Sie workCompleted
durch workEstimated
, um eine grobe Schätzung des Fortschritts zu erhalten. Die Schätzung ist möglicherweise ungenau, da sie von der verzögerten Statistikerfassung abhängt.
Dies ist der Fortschrittsstatus eines Index-Builds:
{ "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" } }, }, ...
Wenn ein Vorgang abgeschlossen ist, enthält die Vorgangsbeschreibung "done":
true
. Der Wert des Feldes state
stellt das Ergebnis des Vorgangs dar. Wenn das Feld done
nicht in der Antwort festgelegt ist, lautet der Wert false
. Verlassen Sie sich bei laufenden Vorgängen nicht auf die Existenz des Werts done
.
Fehler bei der Indexerstellung
Bei der Nutzung von zusammengesetzten Indexen und Einzelfeldindex-Ausnahmen kann es zu Fehlern der Indexerstellung kommen. Ein Indexierungsvorgang kann fehlschlagen, wenn in Cloud Firestore ein Problem mit den zu indexierenden Daten auftritt. In den meisten Fällen bedeutet dies, dass Sie ein Indexlimit erreicht haben. Beispielsweise hat der Vorgang möglicherweise die maximale Anzahl von Indexeinträgen pro Dokument erreicht.
Wenn die Indexerstellung fehlschlägt, wird die entsprechende Fehlermeldung in der Console angezeigt. Nachdem Sie bestätigt haben, dass Sie keine Indexlimits erreicht haben, führen Sie den Indexierungsvorgang nochmal aus.