Indextypen in Cloud Firestore

Indexe sind ein wichtiger Faktor für die Leistung einer Datenbank. Ähnlich wie der Index (bzw. das Register) eines Buchs, in dem die Seitenzahlen zu den Themen im Buch stehen, gibt ein Datenbankindex die Positionen der Elemente in der Datenbank an. Wenn Sie eine Datenbank abfragen, kann die Datenbank einen Index verwenden, um die Speicherorte der angeforderten Elemente schnell zu ermitteln.

Auf dieser Seite werden die beiden Arten von Indexen beschrieben, die von Cloud Firestore verwendet werden: automatische Indexe und manuelle Indexe.

Indexdefinition und -struktur

Ein Index wird für eine Liste von Feldern eines bestimmten Dokuments definiert. Für jedes Feld ist ein entsprechender Indexmodus festgelegt.

Ein Index enthält einen Eintrag für jedes Feld, das in der Indexdefinition angegeben ist. Der Index enthält alle Dokumente, die potenzielle Ergebnisse für Abfragen sind, die auf dem Index basieren. Ein Dokument wird nur dann in den Index aufgenommen, wenn für jedes im Index verwendete Feld ein indexierter Wert festgelegt ist. Wenn sich die Indexdefinition auf ein Feld bezieht, für das im Dokument kein Wert festgelegt ist, wird dieses Dokument nicht im Index angezeigt. In diesem Fall wird das Dokument nie als Ergebnis für eine auf dem Index basierende Anfrage zurückgegeben.

Der Index wird nach Feldwerten sortiert, in der Reihenfolge, die in der Indexdefinition angegeben ist.

Ein Index hinter jeder Abfrage

Wenn für eine Abfrage kein Index vorhanden ist, erfassen die meisten Datenbanken die in ihnen enthaltenen Elemente nach und nach. Das ist ein langsamer Vorgang, der mit zunehmender Datenbankgröße auch immer mehr Zeit benötigt. Cloud Firestore sorgt für eine hohe Abfrageleistung, da für alle Abfragen Indexe verwendet werden. Dadurch hängt die Abfrageleistung von der Größe der Ergebnismenge und nicht von der Anzahl der Elemente in der Datenbank ab.

Weniger Indexverwaltung, mehr Anwendungsentwicklung

Cloud Firestore enthält Funktionen, die den Zeitaufwand für die Indexverwaltung reduzieren. Die für die einfachsten Abfragen erforderlichen Indexe werden automatisch für Sie erstellt. Wenn Sie Ihre App verwenden und testen, können Sie mit Cloud Firestore zusätzliche Indexe erstellen, die für Ihre App erforderlich sind.

Indexarten

Cloud Firestore verwendet zwei Arten von Indexen: automatisch und manuell. Manuelle und automatische Indexe unterscheiden sich in der Art und Weise, wie Sie sie verwalten.

Automatische Indexe

Standardmäßig erstellt Cloud Firestore automatisch Indexe für jedes Feld, das in den Dokumenten einer Sammlung vorhanden ist. Mit diesen Einzelfeldindexen können Sie viele grundlegende Abfragen ausführen. Sie verwalten automatische Indizes, indem Sie die Einstellungen für die automatische Indexierung und Indexausnahmen Ihrer Datenbank konfigurieren.

Standardeinstellungen für automatische Indizes

Cloud Firestore verwendet die folgenden Standardeinstellungen für automatische Indexe:

• Für jedes Feld, das kein Array und keine Map ist, definiert Cloud Firestore zwei Indizes im Sammlungsbereich, einen im aufsteigenden und einen im absteigenden Modus.

• Für jedes Kartenfeld erstellt Cloud Firestore Folgendes:

  • Ein aufsteigender Index des Sammlungsbereichs für jedes Unterfeld, das kein Array und keine Karte ist.
  • Ein absteigender Index auf Sammlungsebene für jedes Unterfeld, das kein Array und keine Karte ist.
  • Ein aufsteigender Index auf Sammlungsebene für den gesamten Kartenwert
  • Ein absteigender Index auf Sammlungsebene für den gesamten Kartenwert
  • Ein „Array-contains“-Index des Sammlungsbereichs für jedes Array-Unterfeld.
  • Cloud Firestore indexiert rekursiv jedes Unterfeld der Karte.

• Für jedes Arrayfeld in einem Dokument erstellt Cloud Firestore Folgendes:

  • Ein aufsteigender Index für den gesamten Arraywert im Erfassungsbereich
  • Ein absteigender Index für den gesamten Arraywert auf Sammlungsebene
  • Ein „Array-contains“-Index auf Sammlungsebene.

• Automatische Indexe mit dem Umfang der Sammlungsgruppe werden standardmäßig nicht verwaltet.

Ausnahmen für automatische Indizes

Sie können ein Feld von Ihren Einstellungen für die automatische Indexierung ausnehmen, indem Sie eine Indexierungsausnahme erstellen. Eine Indexausnahme überschreibt die datenbankweiten Einstellungen für die automatische Indexierung. Eine Ausnahme kann einen Index aktivieren oder deaktivieren, der durch die Einstellungen für die automatische Indexierung ansonsten deaktiviert bzw. aktiviert werden würde. Best Practices für die Indexierung

Verwenden Sie den Feldpfadwert *, um Indexausnahmen auf Sammlungsebene für alle Felder in einer Sammlungsgruppe hinzuzufügen. Für die Sammlungsgruppe comments legen Sie beispielsweise den Feldpfad auf * fest, um alle Felder in der Sammlungsgruppe comments abzugleichen und die Indexierung aller Felder in der Sammlungsgruppe zu deaktivieren. Anschließend können Sie Ausnahmen hinzufügen, um nur die für Ihre Abfragen erforderlichen Felder zu indexieren. Wenn Sie die Anzahl der indexierten Felder verringern, sinken die Speicherkosten und die Schreibvorgänge können schneller ausgeführt werden.

Wenn Sie eine Indexausnahme für ein Zuordnungsfeld erstellen, werden diese Einstellungen von den Unterfeldern der Zuordnung übernommen. Sie können jedoch Indexausnahmen für bestimmte Unterfelder definieren. Wenn Sie eine Ausnahme für ein Unterfeld löschen, übernimmt das Unterfeld die Ausnahme-Einstellungen des übergeordneten Felds, sofern vorhanden, und ansonsten die datenbankweiten Einstellungen.

Informationen zum Erstellen und Verwalten von Ausnahmen für automatische Indizes finden Sie unter Indizes verwalten.

Manuelle Indexe

Ein manueller Index speichert eine sortierte Zuordnung aller Dokumente in einer Sammlung anhand einer sortierten Liste von Feldern, die indexiert werden sollen.

Cloud Firestore verwendet manuelle Indexe für Abfragen, die noch nicht von automatischen Indexen unterstützt werden.

Standardmäßig werden in Cloud Firestore automatisch Einzelfeldindizes für jedes Feld in einer Sammlung erstellt. In Cloud Firestore werden nicht automatisch Indexe für Kombinationen von Feldern erstellt, da es eine große Anzahl möglicher Feldkombinationen gibt. Stattdessen hilft Ihnen Cloud Firestore, erforderliche Indexe zu identifizieren und zu erstellen, während Sie Ihre App entwickeln.

Wenn Sie eine Abfrage ausführen, die von einem vorhandenen Index nicht unterstützt wird, gibt Cloud Firestore eine Fehlermeldung mit einem Link zurück, über den Sie den fehlenden Index erstellen können.

Sie können Indexe auch manuell über die Console oder die Firebase CLI definieren und verwalten. Weitere Informationen zum Erstellen und Verwalten manueller Indexe finden Sie unter Indexe verwalten.

Indexmodi und Abfragebereiche

Sie konfigurieren automatische und manuelle Indexe unterschiedlich. Für beide müssen Sie jedoch Indexmodi und Abfragebereiche für Ihre Indexe konfigurieren.

Indexmodi

Wenn Sie einen Index definieren, wählen Sie für jedes indexierte Feld einen Indexmodus aus. Der Indexmodus jedes Felds unterstützt bestimmte Abfrageklauseln für das Feld. Sie können aus den folgenden Indexmodi auswählen:

Abfrageumfänge

Jeder Index ist entweder einer Sammlung oder einer Sammlungsgruppe zugeordnet. Dies wird als Abfragebereich des Index bezeichnet.

Umfang der Sammlung

Mit

Cloud Firestore werden standardmäßig Indexe mit Sammlungsbereich erstellt. Diese Indexe unterstützen Abfragen, die Ergebnisse aus einer einzelnen Sammlung zurückgeben.

Umfang der Sammlungsgruppe

Eine Sammlungsgruppe enthält alle Sammlungen mit derselben Sammlungs-ID. Um eine Sammlungsgruppenabfrage auszuführen, die gefilterte oder geordnete Ergebnisse aus einer Sammlungsgruppe zurückgibt, müssen Sie einen entsprechenden Index mit Sammlungsgruppenbereich erstellen.

Standardsortierung und das Feld __name__

Zusätzlich zum Sortieren von Dokumenten nach den für jedes Feld angegebenen Indexmodi (aufsteigend oder absteigend) wird bei Indexen eine endgültige Sortierung nach dem Feld __name__ jedes Dokuments angewendet. Der Wert des Felds __name__ wird auf den vollständigen Dokumentpfad festgelegt. Das bedeutet, dass Dokumente in der Ergebnismenge mit denselben Feldwerten nach Dokumentpfad sortiert werden.

Standardmäßig wird das Feld __name__ in derselben Richtung wie das zuletzt sortierte Feld in der Indexdefinition sortiert. Beispiel:

Wenn Sie Ergebnisse nach der nicht standardmäßigen __name__-Richtung sortieren möchten, müssen Sie diesen Index erstellen.

Indexattribute

Ein Index, der die effizienteste Verarbeitung der Abfrage ermöglicht, ist durch die folgenden Attribute definiert:

• In Gleichheitsfiltern verwendete Felder
• Felder, die in Sortierreihenfolgen verwendet werden
• Felder, die in Bereichs- und Ungleichheitsfiltern verwendet werden und noch nicht in Sortierfolgen enthalten sind
• Felder, die in Aggregationen verwendet werden und noch nicht in Sortierreihenfolgen sowie Bereichs- und Ungleichheitsfiltern enthalten sind

Cloud Firestore berechnet die Ergebnisse für Abfragen so:

1. Gibt den Index an, der der Sammlung, den Filterattributen, den Filteroperatoren und den Sortierreihenfolgen der Abfrage entspricht.
2. Gibt die Indexposition an, ab der gescannt wird. Die Startposition wird mit den Gleichheitsfiltern der Abfrage präfixiert und endet mit den Bereichs- und Ungleichheitsfiltern für das erste orderBy-Feld.
3. Startet das Scannen des Index und gibt jedes Dokument zurück, das alle Filter erfüllt, bis der Scanvorgang eine der folgenden Aktionen ausführt:
   • Es wird ein Dokument gefunden, das die Filterbedingungen nicht erfüllt, und es wird bestätigt, dass kein nachfolgendes Dokument die Filterbedingungen jemals vollständig erfüllen wird.
   • Das Ende des Index wird erreicht.
   • Es werden die maximale Anzahl von Ergebnissen erfasst, die in der Abfrage angefordert wurden.

Indexierungsbeispiel

Da Einzelfeldindexe automatisch für Sie erstellt werden, kann Ihre Anwendung mit Cloud Firestore schnell die grundlegendsten Datenbankabfragen unterstützen. Mithilfe von Einzelfeldindexen können Sie einfache Abfragen ausführen, die auf Feldwerten sowie den Vergleichsoperatoren <, <=, ==, >=, > und in basieren. Für Arrayfelder ermöglichen sie die Ausführung von array-contains- und array-contains-any-Abfragen.

Betrachten Sie zur Veranschaulichung die folgenden Beispiele aus der Sicht der Indexerstellung. Mit dem folgenden Snippet werden einige city-Dokumente in einer cities-Sammlung erstellt und für jedes Dokument die Felder name, state, country, capital, population und regions festgelegt:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

Wenn für die automatische Indexierung die Standardeinstellungen gelten, aktualisiert Cloud Firestore einen aufsteigenden Einzelfeldindex pro Feld, einen absteigenden Einzelfeldindex pro Feld sowie einen „Array-contains“-Einzelfeldindex für das Arrayfeld. Jede Zeile in der folgenden Tabelle steht für einen Eintrag in einem Einzelfeldindex:

Von Einzelfeldindexen unterstützte Abfragen

Mit diesen automatisch erstellten Einzelfeldindexen können Sie einfache Abfragen wie die folgenden ausführen:

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

Sie können auch in- und kumulierende Gleichheitsabfragen erstellen {==}:

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

Wenn Sie eine zusammengesetzte Abfrage mit einem Bereichsvergleich (<, <=, > oder >=) ausführen oder nach einem anderen Feld sortieren müssen, müssen Sie einen manuellen Index für diese Abfrage erstellen.

Mit dem array-contains-Index können Sie das Arrayfeld regions abfragen:

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

Von manuellen Indexen unterstützte Abfragen

Erstellen Sie manuelle Indexe, um zusammengesetzte Abfragen zu unterstützen, die noch nicht von automatischen Einzelfeldindexen unterstützt werden. Für die folgenden Abfragen ist beispielsweise ein manueller Index erforderlich:

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

Für diese Abfragen ist der folgende Index erforderlich. Da die Abfrage für das Feld country einen Gleichheitsoperator (== oder in) verwendet, können Sie für dieses Feld den aufsteigenden oder absteigenden Indexmodus verwenden. Standardmäßig wird bei Ungleichheitsklauseln eine aufsteigende Sortierreihenfolge basierend auf dem Feld in der Ungleichheitsklausel angewendet.

Wenn Sie dieselben Abfragen mit einer absteigenden Sortierreihenfolge ausführen möchten, benötigen Sie einen zusätzlichen Index in absteigender Richtung für population:

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

Um Leistungseinbußen durch das Zusammenführen von Indexen zu vermeiden, empfehlen wir, einen Index zu erstellen, um eine array-contains- oder array-contains-any-Abfrage mit zusätzlichen Klauseln zu kombinieren:

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

Von Sammlungsgruppenindexen unterstützte Abfragen

Um einen Index mit dem Bereich „Sammlungsgruppe“ zu demonstrieren, fügen Sie einigen der city-Dokumente eine landmarks-Unterkollektion hinzu:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

Mithilfe des folgenden Einzelfeldindex mit Sammlungsbereich können Sie die landmarks-Sammlung einer einzelnen Stadt basierend auf dem Feld category abfragen:

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

Wenn Sie beispielsweise die Sehenswürdigkeiten in allen Städten abfragen möchten, führen Sie diese Abfrage für die Sammlungsgruppe aus, die aus allen landmarks-Sammlungen besteht. Sie müssen auch einen landmarks-Einzelfeldindex mit Sammlungsgruppenumfang aktivieren:

Wenn dieser Index aktiviert ist, können Sie die landmarks-Sammlungsgruppe abfragen:

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

Wenn Sie eine Sammlungsgruppenabfrage ausführen möchten, die gefilterte oder sortierte Ergebnisse zurückgibt, müssen Sie einen entsprechenden Index mit Sammlungsgruppenbereich aktivieren. Für Sammlungsgruppenabfragen, bei denen die Ergebnisse nicht gefiltert oder sortiert werden, sind jedoch keine zusätzlichen Indexdefinitionen erforderlich.

Sie können beispielsweise die folgende Sammlungsgruppenabfrage ausführen, ohne einen zusätzlichen Index zu aktivieren:

db.collectionGroup("landmarks").get()

Indexeinträge

Die konfigurierten Indexe Ihres Projekts und die Struktur eines Dokuments bestimmen die Anzahl der Indexeinträge für ein Dokument. Indexeinträge werden auf das Limit für die Anzahl der Indexeinträge angerechnet.

Das folgende Beispiel zeigt die Indexeinträge eines Dokuments.

Dokument

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

Automatische Indexe

• city_name ASC
• city_name DESC
• Stadtteile ASC
• neighborhoods DESC
• temperaturen ASC
• temperatures DESC
• temperature.summer ASC
• temperaturen.sommer DESC
• temperature.winter ASC
• temperatures.winter DESC
• Stadtviertel Array-contains

Manuelle Indexe

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

Indexeinträge

Diese Indexierungskonfiguration führt zu den folgenden Indexeinträgen für das Dokument:

Indexe und Preise

Indexe tragen zu den Speicherkosten Ihrer Anwendung bei. Weitere Informationen zur Berechnung der Speichergröße für Indexe finden Sie unter Größe von Indexeinträgen.

Indexzusammenführung verwenden

Auch wenn Cloud Firestore für jede Abfrage einen Index verwendet, ist nicht immer ein Index pro Abfrage erforderlich. Bei Abfragen mit mehreren Gleichheitsklauseln (==) und optional einer orderBy-Klausel kann Cloud Firestore vorhandene Indexe wiederverwenden. Cloud Firestore kann die Indexe für einfache Gleichheitsfilter zusammenführen, um die Indexe zu erstellen, die für größere Gleichheitsabfragen erforderlich sind.

Sie können die Indexierungskosten senken, indem Sie Situationen identifizieren, in denen Sie das Zusammenführen von Indexen verwenden können. Beispiel: restaurants-Sammlung für eine App zur Restaurantbewertung:

• collections_bookmark restaurants

  • class burgerthyme

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

Diese App verwendet Abfragen wie die folgenden. Die App verwendet Kombinationen von Gleichheitsklauseln für category, city und editors_pick und sortiert immer aufsteigend nach star_rating:

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

Sie können für jede Abfrage einen Index erstellen:

Eine bessere Lösung bestünde darin, die Anzahl der Indexe zu reduzieren, indem Sie die Möglichkeit nutzen, in Cloud Firestore Indexe für Gleichheitsklauseln zusammenzuführen:

Dieser Indexsatz ist nicht nur kleiner, sondern unterstützt auch eine zusätzliche Abfrage:

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

Limits für die Indexierung

Die folgenden Limits gelten für Indexe. Weitere Informationen zu Kontingenten und Limits finden Sie unter Kontingente und Limits.

Best Practices zur Indexierung

Bei den meisten Anwendungen sind die automatische Indexierung sowie Fehlermeldungslinks zur Verwaltung der Indexe ausreichend. In den folgenden Fällen können Sie aber Ausnahmen für die automatische Indexierung hinzufügen:

Wenn Sie Abfragen mit Bereichs- und Ungleichheitsoperatoren für mehrere Felder verwenden, sollten Sie die Überlegungen zur Indexierung berücksichtigen, um die Leistung und Kosten von Cloud Firestore-Abfragen zu optimieren.

Weitere Informationen zur Behebung von Indexierungsproblemen (Index-Fanout, INVALID_ARGUMENT-Fehler) finden Sie auf der Seite zur Fehlerbehebung.