Firestore im Datastore-Modus nutzt Indexe für jede Abfrage, die von Ihrer Anwendung durchgeführt wird.
Diese Indexe werden aktualisiert, sobald sich eine Entität ändert. So können Ergebnisse schnell zurückgegeben werden, wenn die Anwendung eine Abfrage ausführt. Im Datastore-Modus werden integrierte Indexe automatisch erstellt, vorab werden jedoch Informationen über die für die Anwendung notwendigen zusammengesetzten Indexe benötigt. In einer Konfigurationsdatei legen Sie fest, welche zusammengesetzten Indexe Ihre Anwendung braucht. Der Datastore-Emulator kann die zusammengesetzte Indexkonfiguration für den Datastore-Modus automatisch erzeugen, wenn Sie Ihre Anwendung testen. Das gcloud
-Befehlszeilentool enthält Befehle zum Aktualisieren der Indexe, die für Ihre Produktionsdatenbank im Datastore-Modus verfügbar sind.
Systemanforderungen
Wenn Sie die gcloud CLI verwenden möchten, müssen Sie die Google Cloud CLI installiert haben.
Über index.yaml
Jede Abfrage im Datastore-Modus, die von einer Anwendung durchgeführt wird, erfordert einen entsprechenden Index.
Indexe für einfache Abfragen, zum Beispiel Abfragen zu einzelnen Attributen, werden automatisch erstellt. Zusammengesetzte Indexe für komplexe Abfragen müssen in einer Konfigurationsdatei namens index.yaml
definiert werden. Diese Datei wird zusammen mit der Anwendung hochgeladen, um in einer Datenbank im Datastore-Modus zusammengesetzte Indexe zu erstellen.
Der Datastore-Emulator fügt dieser Datei automatisch Elemente hinzu, wenn die Anwendung versucht, eine Abfrage auszuführen, für die ein zusammengesetzter Index benötigt wird, der keinen geeigneten Eintrag in der Konfigurationsdatei hat. Durch Bearbeiten der Datei können Sie zusammengesetzte Indexe manuell anpassen oder neue Indexe erstellen. Die Datei index.yaml
befindet sich im Ordner <project-directory>/WEB-INF/
. Standardmäßig befindet sich die Datei WEB-INF/appengine-generated/index.yaml
im Datenverzeichnis ~/.config/gcloud/emulators/datastore/
. Weitere Informationen finden Sie unter Projektverzeichnisse des Datastore-Emulators.
Im Folgenden finden Sie ein Beispiel für eine index.yaml
-Datei:
indexes:
- kind: Task
ancestor: no
properties:
- name: done
- name: priority
direction: desc
- kind: Task
properties:
- name: collaborators
direction: asc
- name: created
direction: desc
- kind: TaskList
ancestor: yes
properties:
- name: percent_complete
direction: asc
- name: type
direction: asc
Die Syntax von index.yaml
ist das YAML-Format. Weitere Informationen zu dieser Syntax finden Sie auf der YAML-Website.
Definitionen für zusammengesetzte Indexe
index.yaml
verfügt über ein einziges Listenelement mit dem Namen indexes
. Jedes Element in der Liste stellt einen zusammengesetzten Index für die Anwendung dar.
Ein Indexelement kann folgende Elemente enthalten:
kind
- Die Art der Entität für die Abfrage. Dieses Element ist ein Pflichtelement.
properties
Eine Liste der Attribute, die in der gewünschten Reihenfolge als Spalten des zusammengesetzten Index hinzugefügt werden sollen: zuerst Attribute in Gleichheitsfiltern, dann Attribute in Ungleichheitsfiltern und zum Schluss die Sortierreihenfolge und -richtung.
Jedes Element in dieser Liste weist folgende Elemente auf:
name
- Name des Attributs im Datastore-Modus
direction
- Die Sortierreihenfolge, entweder
asc
für aufsteigend oderdesc
für absteigend. Diese muss nur für Attribute angegeben werden, die in der Sortierfolge der Anfrage verwendet werden, und muss mit der von der Anfrage verwendeten Richtung übereinstimmen. Der Standardwert istasc
.
ancestor
yes
, wenn die Abfrage eine Ancestor-Klausel enthält. Der Standardwert istno
.
Automatische und manuelle zusammengesetzte Indexe
Wenn der Datastore-Emulator der Datei index.yaml
eine erstellte zusammengesetzte Indexdefinition hinzufügt, geschieht dies nach der folgenden Zeile. Falls diese Zeile noch nicht vorhanden ist, wird sie eingefügt:
# AUTOGENERATED
Der Emulator betrachtet alle zusammengesetzten Indexdefinitionen unterhalb dieser Zeile als automatisch erzeugt und kann vorhandene Definitionen unterhalb dieser Zeile aktualisieren, während die Anwendung Abfragen ausführt.
Alle zusammengesetzten Indexdefinitionen oberhalb dieser Zeile werden als manuell betrachtet und vom Emulator nicht aktualisiert. Der Emulator nimmt Änderungen nur unterhalb der Zeile vor, und zwar nur dann, wenn in der Datei index.yaml
kein zusammengesetzter Index für eine von der Anwendung ausgeführte Abfrage beschrieben wird. Verschieben Sie automatische Indexdefinitionen an eine Stelle vor dieser Zeile, um sie manuell zu verwalten.
Zusammengesetzte Indexe aktualisieren
Mit dem Befehl datastore indexes create
können Sie Ihre lokale Datastore-Konfiguration für zusammengesetzte Indexe (die Datei index.yaml
) anzeigen lassen. Wenn in der Konfiguration für zusammengesetzte Indexe ein zusammengesetzter Index definiert ist, der in Ihrer Produktionsdatenbank im Datastore-Modus noch nicht vorhanden ist, wird der neue zusammengesetzte Index von der Datenbank erstellt. Im Entwicklungsworkflow mit der gcloud CLI finden Sie ein Beispiel für die Verwendung von indexes create
.
Zum Erstellen eines zusammengesetzten Index muss die Datenbank den zusammengesetzten Index einrichten und diesen anschließend mit vorhandenen Daten auffüllen. Die Erstellungszeit eines zusammengesetzten Index ist die Summe der Einrichtungs- und Backfill-Zeit:
Die Einrichtung eines zusammengesetzten Index dauert einige Minuten. Die Mindesterstellungszeit für einen zusammengesetzten 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 zusammengesetzten Index gehören. Je mehr Attributwerte im zusammengesetzten Index enthalten sind, desto länger dauert das Backfill des zusammengesetzten Index.
Falls die Anwendung eine Abfrage ausführt, für die ein zusammengesetzter Index erforderlich ist, der noch nicht fertiggestellt wurde, wird eine Ausnahme ausgelöst. Um dies zu verhindern, müssen Sie bei der Bereitstellung einer neuen Version Ihrer Anwendung vorsichtig sein, wenn diese einen zusammengesetzten Index erfordert, der noch nicht vollständig erstellt ist.
Den Status der zusammengesetzten Indexe können Sie in der Google Cloud Console auf der Seite Indexe prüfen.
Nicht verwendete zusammengesetzte Indexe löschen
Wenn Sie einen zusammengesetzten Index aus der Konfiguration zusammengesetzter Indexe ändern oder entfernen, wird der ursprüngliche zusammengesetzte Index nicht automatisch aus der Datenbank im Datastore-Modus gelöscht. Dadurch haben Sie die Möglichkeit, eine ältere Version der Anwendung noch in Betrieb zu lassen, während neue zusammengesetzte Indexe aufgebaut werden. Sie können außerdem wieder zur älteren Version zurück wechseln, wenn mit einer neueren Version ein Problem festgestellt wird.
Wenn Sie sich sicher sind, dass Sie die alten zusammengesetzten Indexe nicht mehr benötigen, können Sie sie mit dem Befehl datastore indexes cleanup
löschen. Mit diesem Befehl werden alle zusammengesetzten Indexe für die Produktionsinstanz im Datastore-Modus gelöscht, die in der lokalen Version von index.yaml
nicht mehr aufgeführt sind. Im Entwicklungsworkflow mit der gcloud CLI finden Sie ein Beispiel für die Verwendung von indexes cleanup
.
Befehlszeilenargumente
Details zu Befehlszeilenargumenten zum Erstellen und Bereinigen von zusammengesetzten Indexen finden Sie unter datastore indexes create
bzw. datastore indexes cleanup
. Details zu Befehlszeilenargumenten für die gcloud CLI finden Sie in der Referenz gcloud CLI-Befehlszeile.
Lange laufende Vorgänge verwalten
Das Erstellen zusammengesetzter Indexe ist ein Vorgang mit langer Ausführungszeit, der sehr lange dauern kann.
Nachdem Sie einen zusammengesetzten Index erstellt haben, weist der Datastore-Modus 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 von Vorgängen mit langer Ausführungszeit den Befehl gcloud datastore 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
gcloud datastore operations list
rest
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- project-id: Ihre Projekt-ID
HTTP-Methode und URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Weitere Informationen zur Antwort finden Sie weiter unten.
Beispiel: Ein kürzlich abgeschlossener zusammengesetzter Index-Build enthält die folgenden Informationen:
{ "operations": [ { "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg", "done": true, "metadata": { "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata", "common": { "endTime": "2020-06-23T16:55:29.923562Z", "operationType": "CREATE_INDEX", "startTime": "2020-06-23T16:55:10Z", "state": "SUCCESSFUL" }, "indexId": "CICAJiUpoMK", "progressEntities": { "workCompleted": "2193027", "workEstimated": "2198182" } }, "response": { "@type": "type.googleapis.com/google.datastore.admin.v1.Index", "ancestor": "NONE", "indexId": "CICAJiUpoMK", "kind": "Task", "projectId": "project-id", "properties": [ { "direction": "ASCENDING", "name": "priority" }, { "direction": "ASCENDING", "name": "done" }, { "direction": "DESCENDING", "name": "created" } ], "state": "READY" } }, ] }
Einzelnen Vorgang beschreiben
Anstelle aller Vorgänge mit langer Ausführungszeit können Sie auch die Details eines einzelnen Vorgangs auflisten:
gcloud
Verwenden Sie den Befehl operations describe
, um den Status eines zusammengesetzten Index-Builds aufzurufen.
gcloud datastore operations describe operation-name
REST
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- project-id: Ihre Projekt-ID
HTTP-Methode und URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
Weitere Informationen zur Antwort finden Sie weiter unten.
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 Entitäten zurückgegeben. workEstimated
gibt die geschätzte Gesamtanzahl der Entitäten an, die ein Vorgang verarbeitet. Die Schätzungen beruhen auf Datenbankstatistiken. workCompleted
gibt die Anzahl der bis jetzt verarbeiteten Entitäten an. Nach Abschluss des Vorgangs gibt workCompleted
die Gesamtzahl der tatsächlich verarbeiteten Entitäten wieder. Dieser kann vom Wert von workEstimated
abweichen.
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 zusammengesetzten Index-Builds:
{ "operations": [ { "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI", "metadata": { "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata", "common": { "operationType": "CREATE_INDEX", "startTime": "2020-06-23T16:52:25.697539Z", "state": "PROCESSING" }, "progressEntities": { "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
.