Indexe in Cloud Firestore verwalten

Cloud Firestore gewährleistet die Abfrageleistung dadurch, dass für jede Abfrage ein Index erforderlich ist. Die für grundlegende Abfragen erforderlichen Indexe werden automatisch erstellt. 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 Ihre Einzelfeldindexe, zusammengesetzten Indexe und Vektorindexe verwalten.

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.

Hinweis :Sie können Cloud Firestore über die Firebase Console oder die Google Cloud Console verwalten. Diese Links werden jedoch immer in der Firebase Console geöffnet.

Folgen Sie dem erstellten Link zur Firebase Console, prüfen Sie die automatisch ausgefüllten Informationen und klicken Sie auf Erstellen.

Hinweis: Für Nicht-Arrayfelder und Nicht-Kartenfelder müssen Sie eine aufsteigende oder absteigende Sortierung auswählen, auch wenn Sie das Feld nicht zum Sortieren benötigen. Ihre Auswahl hat keinen Einfluss auf das Verhalten von Gleichheiten in der Abfrage.

Wenn ein Vektorindex erforderlich ist, enthält die Fehlermeldung einen Google Cloud CLI-Befehl zum Erstellen des fehlenden Vektorindex. Führen Sie den Befehl aus, um den fehlenden Index zu erstellen.

Hinweis: Derzeit können Vektorindexe nicht in der Firebase Console oder der Google Cloud Console erstellt werden.

Rollen und Berechtigungen

Bevor Sie einen Index in Cloud Firestore erstellen können, muss Ihnen eine der folgenden Rollen zugewiesen sein:

Hinweis :Die folgenden Rollen werden über Identity and Access Management (IAM) verwaltet. Weitere Informationen zu Rollen und den zugehörigen Berechtigungen finden Sie unter Vordefinierte Rollen.

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

Wenn Sie benutzerdefinierte Rollen definiert haben, weisen Sie alle folgenden Berechtigungen zum Erstellen von Indexen 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:

1. Rufen Sie in der Firebase Console den Bereich Cloud Firestore auf.
2. Rufen Sie den Tab Indexe auf und klicken Sie auf Index hinzufügen.
3. Geben Sie den Namen der Sammlung ein und legen Sie die Felder fest, nach denen der Index sortiert werden soll.
4. Klicken Sie auf Erstellen.

Indexfelder müssen den Einschränkungen für Feldpfade entsprechen.

Je nach Größe der Abfrage kann es einige Minuten dauern, bis die Indexe erstellt sind. Nachdem Sie sie erstellt haben, können Sie Ihre Indexe und ihren Status im Bereich „Zusammengesetzte Indexe“ sehen. Wenn die App noch erstellt wird, sehen Sie in der Firebase Console eine Statusleiste.

Indexe entfernen

So löschen Sie einen Index:

1. Rufen Sie in der Firebase Console den Bereich Cloud Firestore auf.
2. Klicken Sie auf den Tab Indexe.
3. Bewegen Sie den Mauszeiger auf den Index, den Sie löschen möchten, und wählen Sie im Kontextmenü Löschen aus.
4. Bestätigen Sie, dass Sie sie löschen möchten. Klicken Sie dafür in der Benachrichtigung auf Löschen.

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 das Flag --only firestore hinzu.

Wenn Sie mithilfe der Firebase Console Änderungen an den Indexen vornehmen, denken Sie daran, auch die lokale Indexdatei zu aktualisieren. Weitere Informationen finden Sie in der Referenz zur JSON-Indexdefinition.

Terraform verwenden

Indexe in der Datenbank erstellen

Cloud Firestore-Datenbanken können sowohl Einzelfeld- als auch zusammengesetzte Indexe enthalten. Sie können die Terraform-Konfigurationsdatei bearbeiten, um einen Index für Ihre Datenbank zu erstellen. Für Einzelfeld- und zusammengesetzte Indexe werden unterschiedliche Terraform-Ressourcentypen verwendet (google_firestore_index und google_firestore_field).

Einzelfeldindex

Mit der folgenden Terraform-Konfigurationsdatei wird ein Einzelfeldindex 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

Mit der folgenden 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.

Vektorindex

Mit der folgenden Terraform-Konfigurationsdatei wird ein Vektorindex für das Feld embedding in der Sammlung chatrooms erstellt:

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 {}
    }
  }
}

• 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 diesen anschließend mit vorhandenen Daten fü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.

Schlüsselbegriff: Cloud Firestore unterstützt mehrere Verwaltungsvorgänge, deren Ausführung lange dauern kann. Diese Vorgänge werden als Vorgänge mit langer Ausführungszeit bezeichnet. Cloud Firestore umfasst Funktionen zum Ausführen und Verwalten von Vorgängen mit langer Ausführungszeit. Unterstützte Vorgängen mit langer Ausführungszeit umfassen Index-Builds und Exportvorgänge.

Nachdem Sie einen Index-Build gestartet haben, weist Cloud Firestore dem Vorgang einen eindeutigen Namen zu. 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 Daten auftritt, die indexiert werden sollen. 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.