Types d'index dans Cloud Firestore

Les index sont un facteur important dans les performances d'une base de données. Tout comme l'index d'un livre qui mappe les sujets d'un livre aux numéros de page, un index de base de données mappe les éléments d'une base de données à leurs emplacements dans la base de données. Lorsque vous envoyez une requête à une base de données, la base de données peut utiliser un index pour rechercher rapidement les emplacements des éléments que vous avez demandés.

Cette page décrit les deux types d'index utilisés par Cloud Firestore, les index à champ unique et les index composites .

Un index derrière chaque requête

Si aucun index n'existe pour une requête, la plupart des bases de données parcourent leur contenu élément par élément, un processus lent qui ralentit encore plus à mesure que la base de données grandit. Cloud Firestore garantit des performances de requête élevées en utilisant des index pour toutes les requêtes. Par conséquent, les performances des requêtes dépendent de la taille du jeu de résultats et non du nombre d'éléments dans la base de données.

Moins de gestion d'index, plus de développement d'applications

Cloud Firestore inclut des fonctionnalités qui réduisent le temps que vous devez consacrer à la gestion des index. Les index requis pour les requêtes les plus élémentaires sont automatiquement créés pour vous. Lorsque vous utilisez et testez votre application, Cloud Firestore vous aide à identifier et à créer des index supplémentaires dont votre application a besoin.

Types d'index

Cloud Firestore utilise deux types d'index : à champ unique et composite . Outre le nombre de champs indexés, les index à champ unique et composites diffèrent dans la façon dont vous les gérez.

Index à champ unique

Un index à champ unique stocke un mappage trié de tous les documents d'une collection contenant un champ spécifique. Chaque entrée dans un index à champ unique enregistre la valeur d'un document pour un champ spécifique et l'emplacement du document dans la base de données. Cloud Firestore utilise ces index pour effectuer de nombreuses requêtes de base. Vous gérez les index à champ unique en configurant les paramètres d'indexation automatique et les exemptions d'index de votre base de données.

Indexation automatique

Par défaut, Cloud Firestore gère automatiquement des index à champ unique pour chaque champ d'un document et chaque sous-champ d'une carte. Cloud Firestore utilise les paramètres par défaut suivants pour les index à champ unique :

• Pour chaque champ non-tableau et non-map, Cloud Firestore définit deux index de champ unique à portée de collection , un en mode croissant et un en mode décroissant.

• Pour chaque champ de carte, Cloud Firestore crée les éléments suivants :

  • Un index ascendant de portée de collection pour chaque sous-champ non-tableau et non-carte.
  • Un index décroissant de portée de collection pour chaque sous-champ non-tableau, non-carte.
  • Un index de contenu de tableau de portée collection pour chaque sous-champ de tableau.
  • Cloud Firestore indexe de manière récursive chaque sous-champ de carte.

• Pour chaque champ de tableau d'un document, Cloud Firestore crée et gère un index de contenu de tableau de portée collection.

• Les index à champ unique avec une portée de groupe de collections ne sont pas gérés par défaut.

Exemptions d'index à champ unique

Vous pouvez exempter un champ de vos paramètres d'indexation automatique en créant une exemption d'index de champ unique. Une exemption d'indexation remplace les paramètres d'indexation automatique à l'échelle de la base de données. Une exemption peut activer un index à champ unique que vos paramètres d'indexation automatique désactiveraient autrement ou désactiver un index à champ unique que l'indexation automatique activerait autrement. Pour les cas où les exemptions peuvent être utiles, consultez les bonnes pratiques d'indexation .

Si vous créez une exemption d'index de champ unique pour un champ de carte, les sous-champs de la carte héritent de ces paramètres. Vous pouvez toutefois définir des exemptions d'index de champ unique pour des sous-champs spécifiques. Si vous supprimez une exemption pour un sous-champ, le sous-champ héritera des paramètres d'exemption de son parent, s'ils existent, ou des paramètres à l'échelle de la base de données s'il n'existe aucune exemption parent.

Pour créer et gérer des exemptions d'index à champ unique, consultez Gestion des index dans Cloud Firestore .

Indices composites

Un index composite stocke un mappage trié de tous les documents d'une collection, basé sur une liste ordonnée de champs à indexer.

Cloud Firestore utilise des index composites pour prendre en charge les requêtes qui ne sont pas encore prises en charge par les index à champ unique.

Cloud Firestore ne crée pas automatiquement des index composites comme il le fait pour les index à champ unique en raison du grand nombre de combinaisons de champs possibles. Au lieu de cela, Cloud Firestore vous aide à identifier et à créer les index composites requis lorsque vous créez votre application.

Si vous tentez la requête ci-dessus sans créer au préalable l'index requis, Cloud Firestore renvoie un message d'erreur contenant un lien que vous pouvez suivre pour créer l'index manquant. Cela se produit chaque fois que vous tentez une requête non prise en charge par un index. Vous pouvez également définir et gérer manuellement les index composites à l'aide de la console ou de la CLI Firebase . Pour plus d'informations sur la création et la gestion des index composites, voir Gestion des index .

Modes d'indexation et étendues de requête

Vous configurez différemment les index à champ unique et composites, mais les deux nécessitent que vous configuriez des modes d'index et des étendues de requête pour vos index.

Modes d'indexation

Lorsque vous définissez un index, vous sélectionnez un mode d'index pour chaque champ indexé. Le mode index de chaque champ prend en charge des clauses de requête spécifiques sur ce champ. Vous pouvez sélectionner l'un des modes d'indexation suivants :

Étendues des requêtes

Chaque index est limité à une collection ou à un groupe de collections. C'est ce qu'on appelle la portée de la requête de l'index :

Périmètre de collecte

Cloud Firestore crée des index avec une portée de collection par défaut. Ces index prennent en charge les requêtes qui renvoient les résultats d'une seule collection.

Étendue du groupe de collecte

Un groupe de collections comprend toutes les collections avec le même ID de collection. Pour exécuter une requête de groupe de collections qui renvoie des résultats filtrés ou triés à partir d'un groupe de collections, vous devez créer un index correspondant avec l'étendue du groupe de collections.

Ordre par défaut et champ __name__

En plus de trier les documents selon les modes d'index spécifiés pour chaque champ (croissant ou décroissant), les index appliquent un tri final par le champ __name__ de chaque document. La valeur du champ __name__ est définie sur le chemin d'accès complet au document. Cela signifie que les documents du jeu de résultats avec les mêmes valeurs de champ sont triés par chemin de document.

Par défaut, le champ __name__ est trié dans le même sens que le dernier champ trié dans la définition d'index. Par exemple:

Pour trier les résultats par la direction __name__ non par défaut, vous devez créer cet index.

Exemple d'indexation

En créant automatiquement des index à champ unique pour vous, Cloud Firestore permet à votre application de prendre rapidement en charge les requêtes de base de données les plus élémentaires. Les index à champ unique vous permettent d'effectuer des requêtes simples basées sur des valeurs de champ et les comparateurs < , <= , == , >= , > et in . Pour les champs de tableau, ils vous permettent d'effectuer des requêtes array-contains et array-contains-any .

Pour illustrer, examinez les exemples suivants du point de vue de la création d'index. L'extrait de code suivant crée quelques documents city dans une collection cities et définit les champs name , state , country , capital , population et tags pour chaque document :

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

En supposant les paramètres d'indexation automatique par défaut, Cloud Firestore met à jour un index à champ unique ascendant par champ non-tableau, un index à champ unique descendant par champ non-tableau et un index à champ unique contenant un tableau pour le champ tableau. Chaque ligne du tableau suivant représente une entrée dans un index à champ unique :

Requêtes prises en charge par des index à champ unique

À l'aide de ces index à champ unique créés automatiquement, vous pouvez exécuter des requêtes simples telles que les suivantes :

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

Vous pouvez également créer des requêtes d'égalité in et composée ( == ) :

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)

Si vous devez exécuter une requête composée qui utilise une comparaison de plage ( < , <= , > ou >= ) ou si vous devez trier par un champ différent, vous devez créer un index composite pour cette requête.

L'index array-contains vous permet d'interroger le champ de tableau regions :

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"])

Requêtes prises en charge par les index composites

Cloud Firestore utilise des index composites pour prendre en charge les requêtes composées qui ne sont pas encore prises en charge par les index à champ unique. Par exemple, vous auriez besoin d'un index composite pour les requêtes suivantes :

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)

Ces requêtes nécessitent l'index composite ci-dessous. Étant donné que la requête utilise une égalité ( == ou in ) pour le champ country , vous pouvez utiliser un mode d'index croissant ou décroissant pour ce champ. Par défaut, les clauses d'inégalité appliquent un ordre de tri croissant basé sur le champ de la clause d'inégalité.

Pour exécuter les mêmes requêtes mais avec un ordre de tri décroissant, vous avez besoin d'un index composite supplémentaire dans le sens décroissant pour 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")

Vous devez également créer un index composite pour combiner une requête array-contains ou array-contains-any avec des clauses supplémentaires.

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)

Requêtes prises en charge par les index de groupe de collections

Pour illustrer un index avec une portée de groupe de collections, imaginez que vous ajoutez une sous-collection landmarks à certains des documents de la city :

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" });

À l'aide de l'index à champ unique suivant avec une portée de collection, vous pouvez interroger la collection landmarks d'une seule ville en fonction du champ category :

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

Maintenant, imaginez que vous souhaitiez interroger les points de repère dans toutes les villes. Pour exécuter cette requête sur le groupe de collections composé de toutes les collections landmarks , vous devez activer un index à champ unique landmarks avec une portée de groupe de collection :

Lorsque cet index est activé, vous pouvez interroger le groupe de collecte landmarks :

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

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

Pour exécuter une requête de groupe de collections qui renvoie des résultats filtrés ou triés, vous devez activer un champ unique ou un index composite correspondant avec une portée de groupe de collections. Toutefois, les requêtes de groupe de collections qui ne filtrent ni ne trient les résultats ne nécessitent aucune définition d'index supplémentaire.

Par exemple, vous pouvez exécuter la requête de groupe de collections suivante sans activer d'index supplémentaire :

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

Entrées d'index

Les index configurés de votre projet et la structure d'un document déterminent le nombre d'entrées d'index pour un document. Les entrées d'index comptent dans la limite du nombre d'entrées d'index .

L'exemple suivant illustre les entrées d'index d'un document.

Document

/cities/SF

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

Index à champ unique

• nom_ville ASC
• nom_ville DESC
• températures.été ASC
• températures.été DESC
• températures.hiver ASC
• températures.hiver DESC
• quartiers Le tableau contient (ASC et DESC)

Indices composites

• city_name ASC, quartiers ARRAY
• city_name DESC, quartiers ARRAY

Entrées d'index

Cette configuration d'indexation entraîne les 18 entrées d'index suivantes pour le document :

Index et tarification

Les index contribuent aux coûts de stockage de votre application. Pour plus d'informations sur le calcul de la taille de stockage des index, consultez Taille d'entrée d'index .

Profiter de la fusion d'index

Bien que Cloud Firestore utilise un index pour chaque requête, il ne nécessite pas nécessairement un index par requête. Pour les requêtes avec plusieurs clauses d'égalité ( == ) et, éventuellement, une clause orderBy , Cloud Firestore peut réutiliser les index existants. Cloud Firestore peut fusionner les index pour des filtres d'égalité simples afin de créer les index composites nécessaires pour les requêtes d'égalité plus importantes.

Vous pouvez réduire les coûts d'indexation en identifiant les situations dans lesquelles vous pouvez tirer parti de la fusion d'index. Par exemple, imaginez une collection restaurants pour une application d'évaluation de restaurants :

• collections_bookmark restaurants

  • class burgerthym

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

Maintenant, imaginez que cette application utilise des requêtes comme celles ci-dessous. Notez que l'application utilise des combinaisons de clauses d'égalité pour category , city et editors_pick tout en triant toujours par star_rating croissant :

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")

Vous pouvez créer un index pour chaque requête :

Comme meilleure solution, vous pouvez réduire le nombre d'index en tirant parti de la capacité de Cloud Firestore à fusionner les index pour les clauses d'égalité :

Non seulement cet ensemble d'index est plus petit, mais il prend également en charge une requête supplémentaire :

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

Limites d'indexation

Les limites suivantes s'appliquent aux index. Pour tous les quotas et limites, consultez Quotas et limites .

Bonnes pratiques d'indexation

Pour la plupart des applications, vous pouvez compter sur l'indexation automatique et les liens de message d'erreur pour gérer vos index. Toutefois, vous souhaiterez peut-être ajouter des exemptions à champ unique dans les cas suivants :

Pour plus d'informations sur la résolution des problèmes d'indexation (sortance d'index, erreurs INVALID_ARGUMENT ), consultez la page de dépannage .