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 schnell die Positionen der angeforderten Elemente zu ermitteln.

Auf dieser Seite werden die beiden Indextypen beschrieben, die von Cloud Firestore verwendet werden: Einzelfeldindexe und zusammengesetzte Indexe.

Indexdefinition und -struktur

Ein Index wird auf eine Liste von Feldern eines bestimmten Dokuments angewendet. Für jedes Feld gilt dabei ein bestimmter Indexmodus.

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 Indexes sind. Ein Dokument wird nur 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 das Dokument nicht im Index aufgeführt. In diesem Fall wird das Dokument nie als Ergebnis für eine Abfrage zurückgegeben, die auf dem Index basiert.

Der zusammengesetzte 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 garantiert eine hohe Abfrageleistung durch die Verwendung von Indexen für alle Abfragen. 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 bietet Funktionen, mit denen sich der Zeitaufwand für die Indexverwaltung reduzieren lässt. Die für grundlegende 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 erstellen, die von der Anwendung benötigt werden.

Indexarten

Cloud Firestore verwendet zwei Arten von Indexen: Einzelfeldindexe und zusammengesetzte Indexe. Neben der Anzahl der indexierten Felder unterscheiden sich Einzelfeldindexe und zusammengesetzte Indexe hinsichtlich der Art und Weise der Verwaltung.

Einzelfeldindexe

Bei einem Einzelfeldindex wird eine sortierte Zuordnung aller Dokumente, die ein bestimmtes Feld enthalten, in einer Sammlung gespeichert. Jeder Eintrag in einem Einzelfeldindex erfasst den Wert eines Dokuments für ein bestimmtes Feld sowie die Position des Dokuments in der Datenbank. Cloud Firestore verwendet diese Indexe für viele grundlegende Abfragen. Zum Verwalten von Einzelfeldindexen müssen Sie die Einstellungen der Datenbank für die automatische Indexierung sowie die Indexausnahmen konfigurieren.

Automatische Indexierung

Standardmäßig verwaltet Cloud Firestore automatisch Einzelfeldindexe für jedes Feld in einem Dokument und jedes Unterfeld in einer Map. Cloud Firestore verwendet die folgenden Standardeinstellungen für Einzelfeldindexe:

• Für jedes Feld, das kein Array- und kein Kartenfeld ist, definiert Cloud Firestore zwei Einzelfeldindexe für den Sammlungsbereich – einen im aufsteigenden und einen im absteigenden Modus.

• Für jedes Kartenfeld erstellt Cloud Firestore Folgendes:

  • Einen aufsteigenden Index auf Sammlungsebene für jedes Unterfeld, das kein Array- und kein Map-Feld ist.
  • Ein absteigender Index auf Sammlungsebene für jedes Unterfeld, das kein Array- und kein Map-Feld ist.
  • Für jedes Unterfeld des Arrays wird ein „array-contains“-Index auf Sammlungsebene erstellt.
  • Cloud Firestore indexiert jedes Kartenunterfeld rekursiv.

• Für jedes Arrayfeld in einem Dokument erstellt und verwaltet Cloud Firestore einen „array-contains“-Index des Sammlungsbereichs.

• Einzelfeldindexe mit Sammlungsgruppenbereich werden nicht standardmäßig bereitgestellt.

Einzelfeldindex-Ausnahmen

Sie können ein Feld durch Erstellen einer Einzelfeldindex-Ausnahme von der automatischen Indexierung ausschließen. Eine Indexausnahme überschreibt die datenbankweiten Einstellungen für die automatische Indexierung. Eine Ausnahme kann einen Einzelfeldindex aktivieren, der durch die Einstellungen für die automatische Indexierung ansonsten deaktiviert werden würde, oder einen Einzelfeldindex deaktivieren, der durch die Einstellungen für die automatische Indexierung ansonsten aktiviert werden würde. Beispiele für Fälle, in denen Ausnahmen nützlich sein können, finden Sie in den Best Practices zur Indexierung.

Verwenden Sie den Pfadwert des Felds *, 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 deaktivieren Sie die Indexierung aller Felder in der Sammlungsgruppe. Sie können dann Ausnahmen hinzufügen, um nur die Felder zu indexieren, die für Ihre Abfragen erforderlich sind. Wenn Sie die Anzahl der indexierten Felder reduzieren, sinken die Speicherkosten und die Schreibleistung kann verbessert werden.

Wenn Sie eine Einzelfeldindex-Ausnahme für ein Map-Feld erstellen, werden diese Einstellungen für die Unterfelder der Karte übernommen. Sie können jedoch Einzelfeldindex-Ausnahmen 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 Einzelfeldindex-Ausnahmen finden Sie unter Indexe verwalten.

Zusammengesetzte Indexe

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

Cloud Firestore verwendet zusammengesetzte Indexe für Abfragen, die noch nicht von Einzelfeldindexen unterstützt werden.

Cloud Firestore erstellt aufgrund der großen Anzahl möglicher Feldkombinationen nicht automatisch zusammengesetzte Indexe wie bei Einzelfeldindexen. Stattdessen hilft Ihnen Cloud Firestore, erforderliche zusammengesetzte Indexe zu ermitteln und zu erstellen, während Sie Ihre Anwendung entwickeln.

Wenn Sie eine Abfrage ausführen, die nicht von einem Index 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 zusammengesetzte Indexe auch manuell definieren oder verwalten, indem Sie die Console oder Firebase CLI verwenden. Weitere Informationen zum Erstellen und Verwalten von zusammengesetzten Indexen finden Sie unter Indexe verwalten.

Indexmodi und Abfragebereiche

Sie konfigurieren Einzelfeldindexe und zusammengesetzte Indexe unterschiedlich, aber beide erfordern das Konfigurieren von Indexmodi und Abfragebereichen.

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.

Standardreihenfolge und das Feld __name__

Dokumente werden nicht nur nach den für jedes Feld angegebenen Indexmodi (aufsteigend oder absteigend) sortiert, sondern auch nach dem Feld __name__ jedes Dokuments. Der Wert des Felds __name__ ist auf den vollständigen Dokumentpfad festgelegt. Das bedeutet, dass Dokumente in der Ergebnismenge mit denselben Feldwerten nach dem Dokumentpfad sortiert werden.

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

Wenn Sie Ergebnisse nach einer anderen __name__-Sortierrichtung als der Standardsortierrichtung sortieren möchten, müssen Sie diesen Index erstellen.

Unterkünfte indexieren

Ein Index, der die effizienteste Ausführung der Abfrage ermöglicht, wird durch die folgenden Eigenschaften definiert:

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

Cloud Firestore berechnet die Ergebnisse für Abfragen so:

1. Identifizierung des zugehörigen Indexes für die Sammlung, die Filterattribute, die Filteroperatoren und die Sortierreihenfolgen einer Abfrage
2. Gibt die Indexposition an, ab der der Scan beginnt. Die Startposition beginnt mit den Gleichheitsfiltern der Abfrage und endet mit den Bereichs- und Ungleichheitsfiltern für das erste orderBy-Feld.
3. Der Index wird gescannt und alle Dokumente zurückgegeben, die alle Filter erfüllen, bis einer der folgenden Schritte ausgeführt wird:
   • Es wird ein Dokument gefunden, das nicht den Filterbedingungen entspricht, und bestätigt wird, dass auch nachfolgende Dokumente die Filterbedingungen nie vollständig erfüllen werden.
   • das Indexende erreicht ist.
   • Die maximale Anzahl von Ergebnissen, die von der Abfrage angefordert wurden, wird erfasst.

Indexierungsbeispiel

Durch das automatische Erstellen von Einzelfeldindexen bietet Cloud Firestore eine schnelle Unterstützung grundlegender Datenbankabfragen für Ihre Anwendung. Mithilfe von Einzelfeldindexen können Sie einfache Abfragen ausführen, die auf Feldwerten sowie auf den Vergleichsoperatoren <, <=, ==, >=, > und in beruhen. 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 tags 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 die Standardeinstellungen für die automatische Indexierung gelten, aktualisiert Cloud Firestore einen aufsteigenden Einzelfeldindex pro Nicht-Arrayfeld, einen absteigenden Einzelfeldindex pro Nicht-Arrayfeld 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 ein kumulierende Abfrage ausführen müssen, die einen Bereichsvergleich (<, <=, > oder >=) verwendet, oder wenn Sie nach einem anderen Feld sortieren müssen, ist es erforderlich, für diese Abfrage einen zusammengesetzten Index zu 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 zusammengesetzten Indexen unterstützte Abfragen

Cloud Firestore verwendet zusammengesetzte Indexe für zusammengesetzte Abfragen, die noch nicht von Einzelfeldindexen unterstützt werden. Einen zusammengesetzten Index benötigen Sie beispielsweise für die folgenden Abfragen:

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 unten stehende zusammengesetzte 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.

Um dieselben Abfragen mit absteigender Sortierreihenfolge auszuführen, benötigen Sie für population einen zusätzlichen zusammengesetzten Index in absteigender Reihenfolge:

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 die Indexzusammenführung zu vermeiden, empfehlen wir, einen zusammengesetzten 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 Sammlungsgruppenbereich zu verstehen, fügen Sie einigen der city-Dokumente eine landmarks-Untersammlung 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 auf der Sammlungsgruppe aus, die aus allen landmarks-Sammlungen besteht. Außerdem müssen Sie einen landmarks-Einzelfeldindex mit Sammlungsgruppenbereich 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 geordnete Ergebnisse zurückgibt, müssen Sie einen entsprechenden Einzelfeldindex oder zusammengesetzten Index mit Sammlungsgruppenbereich aktivieren. Sammlungsgruppenabfragen, die keine Ergebnisse filtern oder ordnen, erfordern jedoch keine zusätzlichen Indexdefinitionen.

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

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

Indexeinträge

Die Anzahl der Indexeinträge für ein Dokument wird durch die konfigurierten Indexe Ihres Projekts und die Struktur eines Dokuments bestimmt. 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"]

Einzelfeldindexe

• city_name ASC
• city_name DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• „neighborhoods“ Array-contains (ASC und DESC)

Zusammengesetzte Indexe

• city_name ASC, neighborhoods ARRAY
• stadt_name DESC, vierteln 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

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 zusammengesetzten Indexe zu erstellen, die für größere Gleichheitsabfragen benötigt werden.

Sie können die Indexierungskosten reduzieren, wenn Sie prüfen, welche Situationen sich für die Indexzusammenführung eignen. Beispiel in einer restaurants-Sammlung für eine Restaurantbewertungs-App:

• 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 folgende. Die App verwendet Kombinationen aus Gleichheitsklauseln für category, city und editors_pick und sortiert dabei 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 einzelne Felder hinzufügen:

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

Weitere Informationen zum Beheben von Indexierungsproblemen (Indexverzweigung, INVALID_ARGUMENT-Fehler) finden Sie auf der Fehlerbehebungsseite.