Indexe der Standard Edition verwalten

Das Indexierungsverhalten hängt von der Edition der Datenbank ab. Auf dieser Seite wird beschrieben, wie Sie Ihre Indexe für Firestore Standard Edition verwalten. Informationen zur Firestore Enterprise-Version finden Sie unter Firestore Enterprise-Version – Indexübersicht.

Firestore Standard Edition gewährleistet die Abfrageleistung durch verbindliche Verwendung von Indexen für jede Abfrage. Die für grundlegende Abfragen erforderlichen Indexe werden automatisch erstellt. Während Sie Ihre Anwendung verwenden und testen, zeigt die Firestore Standard Edition 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.

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

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.

Rollen und Berechtigungen

Bevor Sie einen Index in Firestore Standard Edition 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 alle folgenden Berechtigungen zum Erstellen von Indexen zu:

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

Google Cloud Platform Console verwenden

Über die Google Cloud Platform Console können Sie Einzelfeldindex-Ausnahmen sowie zusammengesetzte Indexe verwalten.

Zusammengesetzten Index erstellen

So erstellen Sie manuell einen neuen zusammengesetzten Index über die GCP Console:

Rufen Sie in der Google Cloud Console die Seite Datenbanken auf.

Zur Seite „Datenbanken“
Wählen Sie die benötigte Datenbank aus der Liste der Datenbanken aus.
Klicken Sie im Navigationsmenü auf Indizes und dann auf den Tab Zusammengesetzt.
Klicken Sie auf Index erstellen.
Geben Sie eine Sammlungs-ID ein. Fügen Sie die Namen der Felder, die Sie indexieren möchten, sowie einen Indexmodus für jedes Feld hinzu. Klicken Sie auf Index speichern.

Ihr neuer Index wird in der Liste der zusammengesetzten Indexe angezeigt und Firestore Standard Edition beginnt mit dem Erstellen des Index. Wenn der Index angelegt ist, wird neben dem Index ein grünes Häkchen angezeigt.

Zusammengesetzten Index löschen

So löschen Sie einen zusammengesetzten Index:

Rufen Sie in der Google Cloud Console die Seite Datenbanken auf.

Zur Seite „Datenbanken“
Wählen Sie die benötigte Datenbank aus der Liste der Datenbanken aus.
Klicken Sie im Navigationsmenü auf Indizes und dann auf den Tab Zusammengesetzt.
Klicken Sie in der Liste Ihrer zusammengesetzten Indexe auf die Schaltfläche Mehr für den Index, den Sie löschen möchten. Klicken Sie auf Löschen.
Bestätigen Sie, dass dieser Index gelöscht werden soll. Klicken Sie dafür in der Benachrichtigung auf Index löschen.

Einzelfeldindex-Ausnahme hinzufügen

Mit Einzelfeldindex-Ausnahmen können Sie die Einstellungen für die automatische Indexierung für bestimmte Felder in einer Sammlung überschreiben. Sie können Ausnahmen für Einzelfelder über die Konsole hinzufügen:

Rufen Sie in der Google Cloud Console die Seite Datenbanken auf.

Zur Seite „Datenbanken“
Wählen Sie die benötigte Datenbank aus der Liste der Datenbanken aus.
Klicken Sie im Navigationsmenü auf Indizes und dann auf den Tab Einzelfeld.
Klicken Sie auf Ausnahme hinzufügen.
Geben Sie eine Sammlungs-ID und einen Feldpfad ein.
Wählen Sie neue Indexierungseinstellungen für dieses Feld aus. Aktivieren oder deaktivieren Sie für dieses Feld automatisch aktualisierte aufsteigende, absteigende und "array-contains"-Einzelfeldindexe.
Klicken Sie auf Ausnahme speichern.

Ausnahme auf Sammlungsebene hinzufügen

So definieren Sie eine Einzelfeldindex-Ausnahme, die für alle Felder unter einer Sammlungs-ID gilt:

Klicken Sie auf Ausnahme hinzufügen.
Geben Sie eine Sammlungs-ID für die Sammlungsgruppe ein und legen Sie Feldpfad als * fest.
Wählen Sie die Indexierungsausnahmen aus, die für alle Felder in der Sammlungsgruppe gelten sollen.
Klicken Sie auf Ausnahme speichern.

Einzelfeldindex-Ausnahme löschen

So löschen Sie eine Einzelfeldindex-Ausnahme:

Rufen Sie in der Google Cloud Console die Seite Datenbanken auf.

Zur Seite „Datenbanken“
Wählen Sie die benötigte Datenbank aus der Liste der Datenbanken aus.
Klicken Sie im Navigationsmenü auf Indizes und dann auf den Tab Einzelfeld.
Klicken Sie in der Liste der Einzelfeldindex-Ausnahmen auf die Schaltfläche Mehr für die Ausnahme, die Sie löschen möchten. Klicken Sie auf Löschen.
Bestätigen Sie, dass Sie diese Ausnahme löschen möchten. Klicken Sie dafür in der Benachrichtigung auf Löschen.

Wenn Sie eine Einzelfeldausnahme löschen, werden für das angegebene Feld oder Unterfeld die übernommenen Indexierungseinstellungen verwendet. Dokumentfelder werden auf die Einstellungen Ihrer Datenbank für die automatische Indexierung zurückgesetzt. Für Unterfelder in einer Karte werden alle Ausnahmen der übergeordneten Felder übernommen, bevor die Einstellungen für die automatische Indexierung übernommen werden.

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 Firestore Standard Edition-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

Firestore Standard Edition-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).

Sowohl Indizes im nativen Modus als auch im Datastore-Modus von Firestore werden unterstützt.

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.

Indexe im Datastore-Modus

Sie können Datastore-Modus-Indizes auch mit Terraform erstellen.

datastore.tf

resource "google_firestore_index" "datastore-mode-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

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

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

  query_scope = "COLLECTION_GROUP"
  api_scope   = "DATASTORE_MODE_API"
}

Von google_datastore_index migrieren

Die google_datastore_index-Ressource ist veraltet und in terraform-provider-google Version 6.0.0 und höher nicht mehr verfügbar.

Wenn Sie zuvor die Ressource google_datastore_index verwendet haben, können Sie zu google_firestore_index migrieren. So führen Sie die Migration durch:

Eine entsprechende google_firestore_index-Ressource erstellen
Importieren Sie Ihren vorhandenen Index im Datastore-Modus in die neue Ressource.
Entfernen Sie Verweise auf die alte google_datastore_index-Ressource.
Entfernen Sie die alte google_datastore_index-Ressource aus dem Terraform-Zustand.
Führen Sie terraform apply aus, um Änderungen zu übernehmen.

Eine detailliertere Anleitung finden Sie unten:

Schreiben Sie einen Ersatz für google_firestore_index basierend auf Ihrer vorhandenen google_datastore_index-Ressource. Die erforderlichen Änderungen finden Sie unten.

Bestimmen Sie den Firestore-Ressourcenpfad Ihres Index:

export INDEX_RESOURCE_PATH=$(echo '"projects/${google_datastore_index.datastore-index-resource-name.project}/databases/(default)/collectionGroups/${google_datastore_index.datastore-index-resource-name.kind}/indexes/${google_datastore_index.datastore-index-resource-name.index_id}"' | terraform console | tr -d '"')

Ersetzen Sie datastore-index-resource-name durch den Terraform-Namen Ihrer vorhandenen Ressource.

Importieren Sie Ihren vorhandenen Datastore-Modus-Index in die oben erstellte google_firestore_index-Ressource:
```
terraform import google_firestore_index.firestore-index-resource-name $INDEX_RESOURCE_PATH
```
Ersetzen Sie firestore-index-resource-name durch den Terraform-Namen Ihrer vorhandenen Ressource.

Weitere Informationen zum Importieren von Firestore-Indexressourcen finden Sie in der Referenzdokumentation zu google_firestore_index.
Löschen Sie die vorhandene google_datastore_index-Ressource aus Ihrer Terraform-Konfigurationsdatei.

Entfernen Sie die vorhandene google_datastore_index-Ressource aus dem Terraform-Zustand:
```
terraform state rm google_datastore_index.datastore-index-resource-name
```
Weitere Informationen zum Entfernen von Ressourcen finden Sie auf der Terraform-Seite Removing Resources.

Führen Sie terraform plan aus. Prüfen Sie die Ausgabe, um zu bestätigen, dass Sie keine Ressourcen erstellen oder löschen.

Prüfen Sie die Ausgabe, um sicherzustellen, dass der Import erfolgreich abgeschlossen wurde. Wenn in der Ausgabe Änderungen an Feldern angezeigt werden, prüfen Sie, ob diese Änderungen beabsichtigt sind. Wenn die Ausgabe eine Zeile wie die folgende enthält:
```
google_firestore_index.firestore-index-resource-name must be replaced
```
Prüfen Sie dann Ihre Terraform-Konfigurationsdatei auf Fehler.

Warnung :Führen Sie „terraform apply“ nicht aus, wenn Indexressourcen ersetzt oder gelöscht werden müssen. Andernfalls kann es passieren, dass Ihr Index verloren geht und Ihre Anwendung nicht mehr verfügbar ist.

Wenn Sie mit der Ausgabe des Terraform-Plans zufrieden sind, führen Sie Folgendes aus:
```
terraform apply
```

Index übersetzen

Wenn Sie eine google_datastore_index-Ressource in die entsprechende google_firestore_index-Ressource übersetzen möchten, kopieren Sie sie und nehmen Sie die folgenden Änderungen vor:

Ersetzen Sie google_datastore_index durch google_firestore_index.
Ersetzen Sie den Argumentnamen kind durch collection, behalten Sie aber den Argumentwert bei.
Ersetzen Sie den Argumentnamen ancestor durch query_scope. Ersetzen Sie den Argumentwert ALL_ANCESTORS durch COLLECTION_RECURSIVE und alle anderen Werte durch COLLECTION_GROUP. Wenn kein ancestor-Argument vorhanden war, fügen Sie ein query_scope-Argument mit dem Wert COLLECTION_GROUP hinzu.
Fügen Sie das Argument api_scope mit dem Wert DATASTORE_MODE_API hinzu.
Ersetzen Sie jede Instanz von properties durch eine entsprechende Instanz von fields. Ersetzen Sie jede Instanz von name durch field_path und jede Instanz von direction durch order.

Sehen Sie sich beispielsweise die folgende google_datastore_index-Ressource an:

datastore.tf

resource "google_datastore_index" "legacy" {
  kind = "foo"

  properties {
    name = "property_a"
    direction = "ASCENDING"
  }

  properties {
    name = "property_b"
    direction = "ASCENDING"
  }
}

Die entsprechende google_firestore_index-Ressource wäre:

resource "google_firestore_index" "new" {
  // note: defaults to the provider project
  project = project

  // note: defaults to the (default) database
  database = "(default)"

  collection = "foo"

  api_scope = "DATASTORE_MODE_API"

  // since there was no "ancestor" property set above, use COLLECTION_GROUP here
  query_scope = "COLLECTION_GROUP"

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

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

Indexerstellungszeit

Zum Erstellen eines Indexes muss Firestore Standard Edition 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.

Nachdem Sie einen Index-Build gestartet haben, weist Firestore Standard Edition 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 Firestore Standard Edition 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.