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 identifizieren.

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

Indexdefinition und -struktur

Ein Index wird für eine Liste von Feldern eines bestimmten Dokuments definiert, wobei für jedes Feld ein entsprechender Indexmodus gilt.

Ein Index enthält einen Eintrag für jedes Feld, das in der Indexdefinition genannt wird. Der Index enthält alle Dokumente, die potenzielle Ergebnisse für Abfragen auf Grundlage des Index sind. 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 Abfrage zurückgegeben, die auf dem Index basiert.

Der Index wird nach Feldwerten in der in der Indexdefinition angegebenen Reihenfolge sortiert.

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 bietet 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 App-Entwicklung

Cloud Firestore enthält Funktionen, mit denen Sie den Zeitaufwand für die Indexverwaltung reduzieren können. Die für die einfachsten Abfragen erforderlichen Indexe werden automatisch für Sie erstellt. Wenn Sie Ihre Anwendung verwenden und testen, hilft Ihnen Cloud Firestore dabei, zusätzliche Indexe zu identifizieren und zu erstellen, die Ihre Anwendung benötigt.

Indexarten

Cloud Firestore verwendet zwei Arten von Indexen: automatische und manuelle. Manuelle und automatische Indexe unterscheiden sich in der Art und Weise, wie sie verwaltet werden.

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 die 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 Zuordnung ist, definiert Cloud Firestore zwei Sammlungsbereichsindexe, einen im aufsteigenden und einen im absteigenden Modus.

• Für jedes Kartenfeld erstellt Cloud Firestore Folgendes:

  • Ein aufsteigender Index auf Sammlungsebene für jedes Unterfeld, das kein Array und keine Map ist.
  • Ein absteigender Index auf Sammlungsebene für jedes Unterfeld, das kein Array und keine Map ist.
  • Ein aufsteigender Index auf Sammlungsebene für den gesamten Kartenwert
  • Ein absteigender Index für den gesamten Kartenwert auf Sammlungsebene
  • Ein Array-Contains-Index auf Sammlungsebene für jedes Array-Unterfeld.
  • Cloud Firestore indexiert jedes Map-Unterfeld rekursiv.

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

  • Ein aufsteigender Index mit Sammlungsumfang für den gesamten Arraywert
  • Ein absteigender Index im Sammlungsbereich für den gesamten Arraywert
  • Ein Array-contains-Index auf Sammlungsebene.

• Automatische Indexe mit Sammlungsgruppenbereich werden standardmäßig nicht verwaltet.

Ausnahmen für automatische Indizes

Sie können ein Feld von den 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. Informationen zu Fällen, in denen Ausnahmen nützlich sein können, finden Sie in den Best Practices für die Indexierung.

Verwenden Sie den Feldpfadwert *, um Indexausnahmen auf Sammlungsebene für alle Felder in einer Sammlungsgruppe hinzuzufügen. Legen Sie beispielsweise für die Sammlungsgruppe comments 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 Felder zu indexieren, die für Ihre Abfragen erforderlich sind. Durch die Reduzierung der Anzahl der indexierten Felder werden die Speicherkosten gesenkt und die Schreibleistung kann verbessert werden.

Wenn Sie eine Indexausnahme für ein Zuordnungsfeld erstellen, übernehmen die Unterfelder der Zuordnung diese Einstellungen. 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 Indexe finden Sie unter Indexe 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, um Abfragen zu unterstützen, die nicht bereits von automatischen Indexen unterstützt werden.

Standardmäßig erstellt Cloud Firestore automatisch Einzelfeldindexe für jedes Feld in einer Sammlung. Cloud Firestore erstellt aufgrund der großen Anzahl möglicher Feldkombinationen nicht automatisch Indexe für Feldkombinationen. Stattdessen hilft Ihnen Cloud Firestore dabei, die erforderlichen Indexe beim Erstellen Ihrer Anwendung zu identifizieren und zu erstellen.

Wenn Sie eine Abfrage versuchen, 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

Automatische und manuelle Indexe werden unterschiedlich konfiguriert. Bei beiden 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

Cloud Firestore erstellt standardmäßig Indexe mit Sammlungsbereich. 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 zur Sortierung von Dokumenten nach den für jedes Feld angegebenen Indexmodi (aufsteigend oder absteigend) wird bei Indexen eine abschließende 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 die Ergebnisse nach der nicht standardmäßigen __name__-Richtung sortieren möchten, müssen Sie diesen Index erstellen.

Indexattribute

Ein Index, mit dem die Abfrage am effizientesten ausgeführt werden kann, wird durch die folgenden Attribute definiert:

• In Gleichheitsfiltern verwendete Felder
• In Sortierreihenfolgen verwendete Felder
• Felder, die in Bereichs- und Ungleichheitsfiltern verwendet werden (und nicht bereits in Sortierreihenfolgen enthalten sind)
• Felder, die in Aggregationen verwendet werden (und nicht bereits 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 der Scan beginnt. Die Startposition wird mit den Gleichheitsfiltern der Abfrage vorangestellt 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 einen der folgenden Schritte ausführt:
   • Ein Dokument wird gefunden, das die Filterbedingungen nicht erfüllt, und es wird bestätigt, dass nachfolgende Dokumente die Filterbedingungen nie vollständig erfüllen werden.
   • Das Ende des Index wird erreicht.
   • Erfasst die maximale Anzahl von Ergebnissen, die von der Abfrage angefordert wurden.

Indexierungsbeispiel

Durch die automatische Erstellung von Einzelfeldindexen ermöglicht Cloud Firestore Ihrer Anwendung, die grundlegendsten Datenbankabfragen schnell zu unterstützen. Mit Einzelfeldindexen können Sie einfache Abfragen basierend auf Feldwerten und den Vergleichsoperatoren <, <=, ==, >=, > und in ausführen. Bei Array-Feldern können Sie damit array-contains- und array-contains-any-Abfragen ausführen.

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

Bei den standardmäßigen Einstellungen für die automatische Indexierung aktualisiert Cloud Firestore einen aufsteigenden Einzelfeldindex pro Feld, einen absteigenden Einzelfeldindex pro Feld und einen „array-contains“-Einzelfeldindex für das Array-Feld. 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 ausführen müssen, die einen Bereichsvergleich (<, <=, > oder >=) verwendet, oder wenn Sie nach einem anderen Feld sortieren müssen, müssen Sie einen manuellen Index für diese Abfrage erstellen.

Mit dem Index array-contains 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 benötigen Sie beispielsweise einen manuellen Index:

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 angewendet, die auf dem Feld in der Ungleichheitsklausel basiert.

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 Indexzusammenführung 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

Fügen Sie einigen der city-Dokumente eine landmarks-Untersammlung hinzu, um einen Index mit dem Bereich „Sammlungsgruppe“ zu demonstrieren:

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 außerdem einen Einzelfeldindex für landmarks mit dem Bereich „Sammlungsgruppe“ 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 Abfragen von Sammlungsgruppen, 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
• neighborhoods ASC
• neighborhoods DESC
• Temperaturen ASC
• temperatures DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.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 des Indexeintrags.

Indexzusammenführung verwenden

Obwohl Cloud Firestore für jede Abfrage einen Index verwendet, ist nicht unbedingt 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 für größere Gleichheitsabfragen erforderlichen Indexe zu erstellen.

Sie können die Indexierungskosten senken, indem Sie Situationen identifizieren, in denen Sie die Indexzusammenführung verwenden können. Beispiel für eine 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 Anwendung verwendet Abfragen wie die folgende. Die App verwendet Kombinationen von Gleichheitsklauseln für category, city und editors_pick und sortiert immer nach aufsteigendem 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 besteht darin, die Anzahl der Indexe zu reduzieren. Dazu können Sie die Fähigkeit von Cloud Firestore nutzen, 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 kann es jedoch sinnvoll sein, Ausnahmen für die automatische Indexierung hinzuzufügen:

Wenn Sie Abfragen mit Bereichs- und Ungleichheitsoperatoren für mehrere Felder verwenden, beachten Sie die Indexierungshinweise, um die Leistung und Kosten von Cloud Firestore-Abfragen zu optimieren.

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