Konfiguration eines zusammengesetzten Index

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 Datenspeicher-Emulator kann die Konfiguration eines zusammengesetzten Index im Datastore-Modus automatisch generieren, während Sie Ihre . Das gcloud-Befehlszeilentool enthält Befehle zum Aktualisieren der Indexe, die für Ihre Produktionsdatenbank im Datastore-Modus verfügbar sind.

Systemanforderungen

Damit Sie die gcloud CLI verwenden können, 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 Konfiguration definiert werden Datei mit dem Namen index.yaml. Diese Datei wird mit der Anwendung hochgeladen, um in einer Datenbank im Datastore-Modus.

Der Datastore-Emulator fügt dieser Datei automatisch Elemente hinzu, wenn der Anwendung versucht, eine Abfrage auszuführen, für die ein zusammengesetzter Index ohne in der Konfigurationsdatei. Sie können zusammengesetzte Indexe anpassen oder können Sie manuell neue erstellen, indem Sie die Datei bearbeiten. 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 des zusammengesetzten Index

index.yaml verfügt über ein einziges Listenelement mit dem Namen indexes. Jedes Element im list steht für einen zusammengesetzten Index für die Anwendung.

Ein Indexelement kann folgende Elemente enthalten:

kind
Die Art der Entität für die Abfrage. Dieses Element ist ein Pflichtelement.
properties

Eine Liste von Eigenschaften, die als Spalten des zusammengesetzten Index aufgenommen werden sollen, in der Reihenfolge, sortiert: zuerst die in Gleichheitsfiltern verwendeten Eigenschaften, gefolgt vom verwendeten Attribut in Ungleichheitsfiltern, dann die Sortierreihenfolgen und ihre Richtungen.

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. 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 ist asc.
ancestor

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

Automatische und manuelle zusammengesetzte Indexe

Wenn der Datastore-Emulator index.yaml, wird sie unter der folgenden Zeile eingefügt:

# AUTOGENERATED

Der Emulator betrachtet alle zusammengesetzten Indexdefinitionen unterhalb dieser Zeile als automatisch erstellt und vorhandene Definitionen unterhalb dieser Zeile der Anwendung Abfragen durchführt.

Alle zusammengesetzten Indexdefinitionen oberhalb dieser Zeile werden als manuell kontrollierte Definitionen angesehen. und werden nicht vom Emulator aktualisiert. Der Emulator zeigt nur Änderungen unterhalb der Linie vornehmen, und zwar nur dann, wenn die index.yaml enthält keinen zusammengesetzten Index für eine vom . Verschieben Sie die Definition eines automatischen zusammengesetzten Index nach oben, um sie selbst zu verwalten diese Zeile ein.

Zusammengesetzte Indexe aktualisieren

Der Befehl datastore indexes create prüft den lokalen zusammengesetzten Datastore-Index. (Datei index.yaml) und ob die Konfiguration eines zusammengesetzten Index eine zusammengesetzten Index, der noch nicht in Ihrer Produktionsdatenbank im Datastore-Modus vorhanden ist, Ihrer Datenbank erstellt den neuen zusammengesetzten Index. Siehe Entwicklungs-Workflow mit der gcloud CLI finden Sie ein Beispiel für die Verwendung von indexes create.

Um einen zusammengesetzten Index zu erstellen, muss die Datenbank den zusammengesetzten Index einrichten und dann den zusammengesetzten Index mit vorhandenen Daten aufzufüllen. Die Zeit für die Erstellung des zusammengesetzten Index ist die Summe der Einrichtung Zeit und Backfill-Zeit:

  • Das Einrichten eines zusammengesetzten Index dauert einige Minuten. Minimale Erstellung Zeit für einen zusammengesetzten Index bei einigen Minuten liegt, auch wenn die Datenbank leer ist.

  • Die Backfill-Zeit hängt davon ab, wie viele Daten in den neuen zusammengesetzten Index gehören. Die mehr Eigenschaftswerte, die in den zusammengesetzten Index gehören, Backfill für den zusammengesetzten Index ausführen.

Wenn die Anwendung eine Abfrage ausführt, für die ein zusammengesetzter Index erforderlich ist, der noch nicht abgeschlossen ist erstellt wurde, löst die Abfrage eine Ausnahme aus. Um dies zu verhindern, müssen Sie bei der Bereitstellung einer neuen Version Ihrer Anwendung, für die ein zusammengesetzten Index erstellen, bevor der neue zusammengesetzte Index fertig erstellt ist.

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

Nicht verwendete zusammengesetzte Indexe löschen

Wenn Sie einen zusammengesetzten Index in der Konfiguration eines zusammengesetzten Index ändern oder entfernen, wird er nicht automatisch aus der Datenbank im Datastore-Modus gelöscht. So haben Sie die Möglichkeit, Möglichkeit, eine ältere Version der Anwendung weiter auszuführen, während neue zusammengesetzte Indexe oder die ältere Version sofort wiederherzustellen, falls ein Problem mit einer neueren Version gefunden wurde.

Wenn Sie sicher sind, dass Sie alte zusammengesetzte Indexe nicht mehr benötigen, können Sie sie löschen Verwenden Sie dazu den Befehl datastore indexes cleanup. Dieser Befehl Löscht alle zusammengesetzten Indexe für die Produktionsinstanz im Datastore-Modus, die nicht erwähnt werden in der lokalen Version von index.yaml. Weitere Informationen finden Sie unter Entwicklungsworkflow mit der gcloud CLI. Dort finden Sie ein Beispiel dafür, wie Sie Verwenden Sie indexes cleanup.

Befehlszeilenargumente

Details zu Befehlszeilenargumenten zum Erstellen und Bereinigen von zusammengesetzten Indexen finden Sie unter datastore indexes create und datastore indexes cleanup, . Weitere Informationen zu Befehlszeilenargumenten für die gcloud CLI finden Sie unter Referenz zur gcloud CLI

Lange laufende Vorgänge verwalten

Die Erstellung von zusammengesetzten Indexen ist lang andauernde Vorgänge und kann viel Zeit in Anspruch nehmen.

Nachdem Sie die Erstellung eines zusammengesetzten Index gestartet haben, weist der Datastore-Modus dem Vorgang einen eindeutigen Namen geben. 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.

Ein kürzlich abgeschlossener Build eines zusammengesetzten Index zeigt beispielsweise die folgenden Informationen an:

{
  "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 aufzurufen. eines zusammengesetzten Index erstellen.

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.

Hier ist beispielsweise der Fortschrittsstatus der Erstellung eines zusammengesetzten Index:

{
  "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.