Types d'index dans Cloud Firestore

Les index sont un facteur important de performances pour une base de données. Tout comme le sommaire d'un livre qui indique la correspondance des sujets avec des numéros de page, l'index d'une base de données associe les éléments qu'elle contient à leur emplacement. Lorsque vous interrogez une base de données, celle-ci peut utiliser un index pour identifier rapidement l'emplacement des éléments que vous avez demandés.

Cette page décrit les deux types d'index utilisés par Cloud Firestore : les index automatiques et les index manuels.

Définition et structure des index

Un index est défini sur une liste de champs d'un document donné, avec un mode d'index correspondant pour chaque champ.

Un index contient une entrée pour chaque champ nommé dans la définition de l'index. L'index inclut tous les documents qui sont les résultats potentiels des requêtes basées sur l'index. Un document n'est inclus dans l'index que s'il possède une valeur indexée définie pour chaque champ utilisé dans l'index. Si la définition de l'index fait référence à un champ pour lequel le document n'a pas de valeur définie, ce document n'apparaîtra pas dans l'index. Dans ce cas, le document ne sera jamais renvoyé comme résultat d'une requête basée sur l'index.

L'index est trié par valeurs de champ, dans l'ordre spécifié dans la définition de l'index.

Un index derrière chaque requête

Si aucun index n'est disponible pour une requête, la plupart des bases de données parcourent un à un les éléments qu'elles contiennent. Ce processus devient de plus en plus lent à mesure que la base de données s'agrandit. Cloud Firestore permet d'obtenir des performances de requête élevées en utilisant des index pour toutes les requêtes. Ainsi, les performances des requêtes dépendent de la taille de l'ensemble de résultats et non du nombre d'éléments disponibles 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 basiques sont créés automatiquement. Lorsque vous utilisez et testez votre application, Cloud Firestore vous aide à identifier et à créer les index supplémentaires dont votre application a besoin.

Types d'index

Cloud Firestore utilise deux types d'index : automatique et manuel. Les index manuels et automatiques diffèrent par la façon dont vous les gérez.

Index automatiques

Par défaut, Cloud Firestore crée automatiquement des index pour chaque champ présent dans les documents d'une collection. Ces index à champ unique vous permettent d'effectuer de nombreuses requêtes de base. Vous gérez les index automatiques en configurant les paramètres d'indexation automatique et les exceptions d'index de votre base de données.

Paramètres par défaut de l'index automatique

Cloud Firestore utilise les paramètres par défaut suivants pour les index automatiques :

• Pour chaque champ qui n'est pas un tableau ni un mappage, Cloud Firestore définit deux index de champ d'application de la collection, l'un en mode croissant et l'autre en mode décroissant.

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

  • Un index croissant au niveau de la collection pour chaque sous-champ qui n'est ni un tableau, ni un mappage.
  • Un index décroissant au niveau de la collection pour chaque sous-champ qui n'est ni un tableau, ni un mappage.
  • Un index croissant au niveau de la collection pour l'ensemble de la valeur de la carte
  • Un index décroissant au niveau de la collection pour l'ensemble de la valeur de la carte
  • Un index array-contains au niveau de la 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 les éléments suivants :

  • Un index croissant au niveau de la collection pour l'ensemble de la valeur du tableau
  • Un index décroissant au niveau de la collection pour l'ensemble de la valeur du tableau
  • Un index array-contains au niveau de la collection.

• Les index automatiques avec un champ d'application de groupe de collections ne sont pas gérés par défaut.

Exceptions d'index automatiques

Vous pouvez exclure un champ de vos paramètres d'indexation automatique en créant une exception d'indexation. Les exceptions d'indexation vous permettent de remplacer les paramètres d'index automatiques de votre base de données. Une exception permet d'activer un index qui serait normalement désactivé par vos paramètres d'indexation automatiques. À l'inverse, vous pouvez désactiver un index qui serait normalement activé par l'indexation automatique. Pour les cas où les exemptions peuvent être utiles, consultez les bonnes pratiques d'indexation.

Utilisez la valeur de chemin d'accès au champ * pour ajouter des exemptions d'index au niveau de la collection sur tous les champs d'un groupe de collections. Par exemple, pour le groupe de collections comments, définissez le chemin d'accès au champ sur * pour qu'il corresponde à tous les champs du groupe de collections comments et désactivez l'indexation de tous les champs du groupe de collections. Vous pouvez ensuite ajouter des exceptions pour n'indexer que les champs requis pour vos requêtes. La réduction du nombre de champs indexés réduit les coûts de stockage et peut améliorer les performances d'écriture.

Si vous créez une exception d'index pour un champ de carte, les sous-champs de la carte héritent de ces paramètres. Vous pouvez toutefois définir des exceptions d'index pour des sous-champs spécifiques. Si vous supprimez une exception pour un sous-champ, le sous-champ hérite des paramètres d'exception de son parent, s'ils existent. Si aucune exception n'existe pour le parent, le sous-champ hérite des paramètres de base de données.

Pour créer et gérer des exceptions d'index automatiques, consultez Gérer les index.

Index manuels

Un index manuel stocke une correspondance triée entre tous les documents d'une collection, en fonction d'une liste numérotée de champs à indexer.

Cloud Firestore utilise des index manuels pour prendre en charge les requêtes qui ne sont pas déjà prises en charge par les index automatiques.

Par défaut, Cloud Firestore crée automatiquement des index à un seul champ pour chaque champ présent dans une collection. Cloud Firestore ne crée pas automatiquement d'index pour les combinaisons de champs en raison du grand nombre de combinaisons de champs possibles. À la place, Cloud Firestore vous aide à identifier et créer les index requis lorsque vous créez votre application.

Chaque fois que vous tentez d'exécuter une requête qui n'est pas compatible avec un index existant, Cloud Firestore renvoie un message d'erreur contenant un lien que vous pouvez suivre pour créer l'index manquant.

Vous pouvez également définir et gérer des index manuellement à l'aide de la console ou de la CLI Firebase. Pour en savoir plus sur la création et la gestion des index manuels, consultez Gérer les index.

Modes d'index et champs d'application des requêtes

Vous configurez les index automatiques et manuels différemment, mais les deux nécessitent que vous configuriez des modes d'indexation et des champs d'application de requête pour vos index.

Modes d'index

Lorsque vous définissez un index, vous sélectionnez un mode d'index pour chaque champ indexé. Le mode d'index de chaque champ accepte des clauses de requête spécifiques à ce champ. Vous pouvez choisir parmi les modes d'index suivants :

Champs d'application des requêtes

Chaque index s'applique à une collection ou à un groupe de collections. C'est ce qu'on appelle le champ d'application des requêtes d'index :

Champ d'application de la collection

Cloud Firestore crée par défaut des index dont le champ d'application est défini sur une collection. Ces index acceptent les requêtes qui renvoient les résultats d'une seule collection.

Champ d'application du groupe de collections

Un groupe de collections inclut toutes les collections possédant le même identifiant. Pour obtenir des résultats filtrés ou triés d'un groupe de collections lorsque vous exécutez une requête de groupe de collections, vous devez créer un index correspondant qui s'applique au groupe de collections.

Ordre par défaut et champ __name__

En plus de trier les documents selon les modes d'indexation 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 de l'ensemble de résultats ayant les mêmes valeurs de champ sont triés par chemin d'accès au document.

Par défaut, le champ __name__ est trié dans la même direction que le dernier champ trié dans la définition de l'index. Exemple :

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

Propriétés d'index

Un index permettant d'exécuter la requête le plus efficacement possible est défini par les propriétés suivantes :

• Champs utilisés dans les filtres d'égalité
• Champs utilisés dans les ordres de tri
• Champs utilisés dans les filtres de plage et d'inégalité (qui ne sont pas déjà inclus dans les ordres de tri)
• Champs utilisés dans les agrégations (qui ne sont pas déjà inclus dans les ordres de tri, et les filtres de plage et d'inégalité)

Cloud Firestore calcule les résultats des requêtes comme suit :

1. Identifie l'index correspondant à la collection, aux propriétés de filtre, aux opérateurs de filtre et aux ordres de tri de la requête.
2. Identifie la position d'index à partir de laquelle l'analyse commence. La position de départ est précédée des filtres d'égalité de la requête et se termine par les filtres de plage et d'inégalité sur le premier champ orderBy.
3. Commence à analyser l'index, en renvoyant chaque document qui satisfait à tous les filtres, jusqu'à ce que le processus d'analyse effectue l'une des opérations suivantes :
   • Rencontre un document qui ne répond pas aux conditions de filtre et confirme qu'aucun document ultérieur ne répondra jamais entièrement aux conditions de filtre.
   • Atteint la fin de l'index.
   • Collecte le nombre maximal de résultats demandés par la requête.

Exemple d'indexation

En créant automatiquement des index à champ unique, Cloud Firestore permet à votre application de prendre rapidement en charge les requêtes de base de données les plus simples. Les index à champ unique vous permettent d'effectuer des requêtes simples basées sur les 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.

Examinez les exemples suivants qui illustrent les index à champ unique du point de vue de leur création. L'extrait de code suivant permet de créer des documents city dans une collection cities et de définir les champs name, state, country, capital, population et regions 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 que les paramètres d'indexation automatique par défaut sont utilisés, Cloud Firestore met à jour un index à champ unique croissant par champ, un index à champ unique décroissant par champ et un index à champ unique array-contains pour le champ de tableau. Chaque ligne du tableau suivant représente une entrée dans un index à champ unique :

Requêtes acceptées par les index à champ unique

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

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 in et des requêtes d'égalité composées (==) :

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 composite qui utilise une comparaison de plage (<, <=, > ou >=) ou si vous devez trier par un autre champ, vous devez créer un index manuel 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 compatibles avec les index manuels

Créez des index manuels pour prendre en charge les requêtes composées qui ne sont pas déjà prises en charge par les index automatiques à champ unique. Par exemple, vous auriez besoin d'un index manuel 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 suivant. Étant donné que la requête utilise une clause d'é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 en fonction du champ qu'elles concernent.

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

Pour éviter une perte de performances causée par la fusion d'index, nous vous recommandons de créer un index 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 acceptées par les index de groupes de collections

Pour illustrer un index avec un champ d'application de groupe de collections, ajoutez une sous-collection landmarks à certains documents 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" });

Cet index à champ unique dont le champ d'application est défini sur une collection vous permet d'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"])

Par exemple, si vous souhaitez interroger les monuments de toutes les villes, vous devez exécuter cette requête sur le groupe de collections constitué de toutes les collections landmarks. Vous devez également activer un index à champ unique landmarks avec un champ d'application de groupe de collections :

Lorsque cet index est activé, vous pouvez interroger le groupe de collections 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 ordonnés, vous devez activer un index correspondant avec un champ d'application défini sur un groupe de collections. Toutefois, les requêtes de groupe de collections qui ne filtrent pas ou ne trient pas les résultats ne nécessitent pas de définitions d'index supplémentaires.

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 sont comptabilisées 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 automatiques

• city_name ASC
• city_name DESC
• quartiers ASC
• neighborhoods DESC
• températures ASC
• temperatures DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains

Index manuels

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

Entrées d'index

Cette configuration d'indexation génère les entrées d'index suivantes pour le document :

Index et tarifs

Les coûts de stockage de votre application prennent en compte les index. Pour en savoir plus sur le calcul de la taille de stockage des index, consultez Taille des entrées d'index.

Utiliser la fusion d'index

Bien que Cloud Firestore utilise un index pour chaque requête, il n'en nécessite pas nécessairement un par requête. Pour les requêtes comportant 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 nécessaires pour des requêtes d'égalité plus volumineuses.

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

• collections_bookmark restaurants

  • class burgerthyme

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

Cette application utilise des requêtes comme celle-ci. L'application utilise des combinaisons de clauses d'égalité pour category, city et editors_pick, tout en triant toujours par ordre croissant de 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")

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

Une meilleure solution consiste à 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 accepte également 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 plus d'informations sur les quotas et les limites, consultez la section Quotas et limites.

Bonnes pratiques d'indexation

Pour la plupart des applications, vous pouvez compter sur l'indexation automatique et sur les liens affichés dans les messages d'erreur pour gérer vos index. Toutefois, vous pouvez ajouter des exemptions d'indexation automatique dans les cas suivants :

Si vous utilisez des requêtes avec des opérateurs de plage et d'inégalité sur plusieurs champs, consultez les considérations d'indexation à prendre en compte pour optimiser les performances et le coût des requêtes Cloud Firestore.

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