Referenz zu index.yaml

Sie können Firestore im Datastore-Modus (Datastore) verwenden, um Daten für Ihre Anwendungen zu speichern, die in der Standardumgebung ausgeführt werden. Datastore nutzt Indexe für jede Anfrage, die von Ihrer Anwendung ausgeführt wird. Diese Indexe werden bei jeder Änderung von Entitäten aktualisiert. Damit wird sichergestellt, dass die Ergebnisse schnell zurückgeliefert werden, wenn die Anwendung eine Abfrage startet. Dazu muss für Datastore im Voraus angegeben werden, welche Abfragen die Anwendung ausführt. In einer index.yaml-Konfigurationsdatei legen Sie fest, welche Indexe Ihre Anwendung benötigt. Sie können mit dem Datastore-Emulator die Datei beim Testen Ihrer Anwendung automatisch erstellen lassen oder die Datei selbst schreiben. Die Datei index.yaml muss hochgeladen werden, wenn Sie Ihre Anwendung bereitstellen.

Über index.yaml

Jede Datastore-Abfrage, die von einer Anwendung gesendet wird, erfordert einen entsprechenden Index. Indexe für einfache Abfragen, zum Beispiel Abfragen zu einem einzelnen Attribut, werden automatisch erstellt. Indexe für komplexe Anfragen müssen in einer Konfigurationsdatei namens index.yaml definiert werden. Diese Datei wird mit der Anwendung hochgeladen, um Indexe in Datastore zu erstellen.

Im Folgenden finden Sie ein Beispiel für eine index.yaml-Datei:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    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. In der Regel ist dies der Name der Klasse "Modell", die das Modell für die Entitäten definiert. 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
Datenspeichername des Attributs.
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 hat (entweder Query.ancestor() oder eine GQL-ANCESTOR IS-Klausel). Der Standardwert ist no.

Indexdateien erstellen

Sie können eine Indexdatei manuell mit einem Texteditor erstellen und dem oben beschriebenen Dateiaufbau folgen. Ein effizienterer Ansatz besteht darin, die Datei beim lokalen Testen der Anwendung automatisch zu erzeugen. Sie können beide Methoden miteinander kombinieren.

Beim Testen in Ihrer lokalen Umgebung können Sie mithilfe des Emulatorbefehls von gcloud einen Dienst starten, der Datastore emuliert, bevor Sie Ihre Anwendung ausführen:

gcloud beta emulators datastore start --data-dir DATA-DIR

Mit dem Flag --data-dir geben Sie das Verzeichnis an, in dem die automatisch generierte Datei index.yaml angezeigt wird.

Beim Testen der Anwendung fügt der Emulator der Datei index.yaml bei jeder Datastore-Abfrage eine generierte Indexdefinition hinzu. Alle automatisch generierten Indexdefinitionen werden in der Datei unterhalb der folgenden Zeile angezeigt:

# AUTOGENERATED

Alle Indexdefinitionen oberhalb dieser Zeile werden als manuell verwaltete Definitionen behandelt, die nicht vom Entwicklungs-Webserver aktualisiert werden. Der Webserver nimmt Änderungen nur unterhalb der Zeile vor, und zwar nur dann, wenn in der index.yaml-Datei kein Index für eine von der Anwendung ausgeführte Abfrage beschrieben wird. Verschieben Sie automatische Indexdefinitionen an eine Stelle oberhalb dieser Zeile, um diese manuell zu verwalten.

Der Emulator kann vorhandene Definitionen unterhalb dieser Zeile aktualisieren, wenn die Anwendung Abfragen ausführt. Wenn die Anwendung jede Abfrage generiert, die sie während des Testens ausführt, sind die erstellten Einträge in der index.yaml-Datei vollständig. Möglicherweise müssen Sie die Datei manuell bearbeiten, um Indexe zu löschen, die nicht in der Produktion verwendet werden, oder um Indexe zu definieren, die beim Testen nicht erstellt wurden.

Indexkonfigurationsdatei bereitstellen

Führen Sie den folgenden Befehl aus, um die Konfigurationsdatei index.yaml für die Weiterleitung bereitzustellen:

gcloud app deploy index.yaml

Nicht verwendete Indexe löschen

Wenn Sie einen Index in der Indexkonfiguration ändern oder aus ihr entfernen, wird der ursprüngliche Index nicht automatisch aus App Engine gelöscht. Dadurch haben Sie die Möglichkeit, weiterhin eine ältere Version der Anwendung auszuführen, während neue Indexe aufgebaut werden. Außerdem können Sie die ältere Version sofort wiederherstellen, wenn bei einer neueren Version ein Problem festgestellt wird.

Wenn Sie sich sicher sind, dass alte Indexe nicht mehr benötigt werden, können Sie sie so aus App Engine löschen:

gcloud datastore indexes cleanup index.yaml