Indexkonfiguration

Firestore im Datastore-Modus nutzt Indexe für jede Abfrage, die von Ihrer Anwendung durchgeführt wird. Diese Indexe werden aktualisiert, wenn 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 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

Die Verwendung des gcloud-Tools erfordert das Google Cloud SDK.

Ü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. Indexe für komplexe Abfragen müssen in einer Konfigurationsdatei namens index.yaml definiert werden. Diese Datei wird zusammen mit der Anwendung hochgeladen, sodass in einer Datenbank im Datastore-Modus Indexe erstellt werden können.

Der Datastore-Emulator fügt dieser Datei automatisch Elemente hinzu, wenn die Anwendung versucht, eine Abfrage auszuführen, für die ein Index erforderlich ist, der keinen entsprechenden Eintrag in der Konfigurationsdatei enthält. Durch Bearbeiten der Datei können Sie Indexe manuell anpassen oder neue Indexe erstellen. Die Datei index.yaml befindet sich im <project-directory>/WEB-INF/-Ordner. 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.

Indexdefinitionen

index.yaml verfügt über ein einziges Listenelement mit dem Namen indexes. Jedes Element in der Liste stellt einen 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 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 oder desc für absteigend. Die Richtung muss nur für Attribute angegeben werden, die in der Sortierreihenfolge der Abfrage verwendet werden, und muss mit der von der Abfrage verwendeten Richtung übereinstimmen. Der Standardwert ist asc.
ancestor

yes, wenn die Abfrage eine Ancestor-Klausel enthält. Der Standardwert ist no.

Automatische und manuelle Indexe

Wenn der Datastore-Emulator der Datei index.yaml eine erstellte 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 Indexdefinitionen unterhalb dieser Zeile als automatisch erzeugt und kann vorhandene Definitionen unterhalb dieser Zeile aktualisieren, während die Anwendung Abfragen ausführt.

Alle 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 Index für eine von der Anwendung ausgeführte Abfrage beschrieben wird. Für eine manuelle Verwaltung verschieben Sie automatische Indexdefinitionen an eine Position vor dieser Zeile.

Indexe aktualisieren

Mit dem Befehl datastore indexes create können Sie Ihre lokale Datastore-Indexkonfiguration (die Datei index.yaml) anzeigen lassen. Wenn in der Indexkonfiguration ein Index definiert ist, der in Ihrer Produktionsdatenbank im Datastore-Modus noch nicht vorhanden ist, wird der neue Index von der Datenbank erstellt. Im Entwicklungsworkflow mit dem gcloud-Tool finden Sie ein Beispiel für die Verwendung von indexes create.

Je nachdem, wie viele Daten für den neuen Index bereits in der Datenbank enthalten sind, kann die Indexerstellung etwas Zeit in Anspruch nehmen. Wenn die Anwendung eine Abfrage ausführt und dafür einen Index benötigt, der noch nicht fertiggestellt wurde, löst die Abfrage eine Ausnahme aus. Um dies zu verhindern, müssen Sie bei der Bereitstellung einer neuen Version Ihrer Anwendung vorsichtig sein, wenn diese einen neuen Index erfordert, der noch nicht vollständig erstellt ist.

Den Status der Indexe können Sie in der Cloud Console auf der Seite Indexe prüfen.

Nicht verwendete Indexe löschen

Wenn Sie einen Index aus der Indexkonfiguration ändern oder entfernen, wird der ursprüngliche Index nicht automatisch aus der Datenbank im Datastore-Modus gelöscht. Dadurch können Sie eine ältere Version der Anwendung weiter verwenden, während neue Indexe erstellt werden. Sie können außerdem wieder zur älteren Version zurückwechseln, wenn mit einer neueren Version ein Problem festgestellt wird.

Wenn Sie sich sicher sind, dass Sie die alten Indexe nicht mehr benötigen, können Sie sie mit dem Befehl datastore indexes cleanup löschen. Mit diesem Befehl werden alle 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 dem gcloud-Tool finden Sie ein Beispiel für die Verwendung von indexes cleanup.

Befehlszeilenargumente

Details zu Befehlszeilenargumenten zum Erstellen und Bereinigen von Indexen finden Sie unter datastore indexes create bzw. datastore indexes cleanup. Details zu Befehlszeilenargumenten für das gcloud-Tool finden Sie in der Referenz zum gcloud-Tool.