Présentation de l'index de l'édition Enterprise

Le comportement d'indexation dépend de l'édition de la base de données. Cette page décrit l'indexation pour l'édition Enterprise de Firestore. Pour l'édition Standard de Firestore, consultez Présentation des index de l'édition Standard de Firestore.

Cette section décrit l'indexation pour l'édition Enterprise de Firestore. L'édition Enterprise de Firestore ne crée aucun index par défaut. Pour réduire les coûts et améliorer les performances de la base de données, créez des index pour vos requêtes les plus courantes.

Les index ont un impact important sur les performances d'une base de données. Si un index existe pour une requête, la base de données peut renvoyer efficacement les résultats en réduisant la quantité de données à analyser et en réduisant le travail nécessaire pour trier les résultats. Toutefois, les entrées d'index augmentent les coûts de stockage et la quantité de travail effectuée lors d'une opération d'écriture sur des champs indexés.

Définition et structure des index

Un index se compose des éléments suivants :

  • un ID de collection ;
  • Liste des champs de la collection donnée
  • un mode d'index (croissant, décroissant ou array-contains) pour chaque champ.

Un index peut également activer les options sparse ou unique.

Ordre des index

L'ordre et le sens de tri de chaque champ définissent l'index de manière unique. Par exemple, les deux index suivants sont distincts et ne sont pas interchangeables :

Collection Champs
cities pays (ordre croissant), population (ordre décroissant)
cities population (décroissant), pays (croissant),

Lorsque vous créez un index pour prendre en charge une requête, incluez les champs dans le même ordre que dans votre requête.

Densité de l'index

Par défaut, les entrées d'index stockent les données de tous les documents d'une collection. C'est ce qu'on appelle un index non clairsemé. Une entrée d'index sera ajoutée pour un document, que celui-ci contienne ou non l'un des champs spécifiés dans l'index. Les champs inexistants sont traités comme ayant une valeur NULL lors de la génération des entrées d'index. Pour modifier ce comportement, vous pouvez définir l'index comme index creux.

Index creux

Un index à faible densité n'indexe que les documents de la collection contenant une valeur (y compris nulle) pour au moins l'un des champs indexés. Un index creux réduit les coûts de stockage et peut améliorer les performances.

Index array-contains

Pour optimiser les performances des requêtes lorsque vous interrogez un champ de tableau à l'aide de array-contains ou array-contains-any, vous pouvez indexer le champ en mode array-contains. Un index ne peut comporter qu'un seul champ en mode array-contains.

En indexant un champ de tableau en mode array-contains, le moteur de requête peut localiser rapidement les documents contenant des valeurs de tableau spécifiques. Sans index, les requêtes vérifient les valeurs du tableau en effectuant une analyse complète de la collection, ce qui augmente la latence des requêtes et les coûts de lecture à mesure que la taille de la collection augmente.

Pour indexer un champ de tableau, il doit répondre à l'exigence suivante :

  • Exigence concernant les tableaux non vides : une entrée d'index n'est créée que si le champ de tableau existe dans le document et n'est pas vide. Les documents dont les champs de tableau sont manquants, non définis ou vides ne sont pas indexés.

Relation entre la densité et les index array-contains

Pour les index qui incluent un champ array-contains, les règles de densité d'index ne s'appliquent qu'aux champs indexés ordonnés. Si l'exigence de tableau non vide est remplie, les règles de densité s'appliquent aux champs indexés ordonnés restants dans l'index :

  • Index non épars (DENSE) : une entrée d'index est générée pour le document. Tous les champs indexés ordonnés manquants dans l'index sont stockés sous la forme null dans l'entrée d'index.
  • Index à faible densité (SPARSE) : une entrée d'index n'est générée que si au moins l'un des champs indexés ordonnés existe dans le document.

Exemple : Génération d'entrées d'index

Prenons l'index users (tags[*], status ASC) :

Document Index NON-SPARSE Index SPARSE
{
  tags: ["news"],
  status: "active"
}		 Indexé :
• (tags : "news", état : "active")		 Indexé :
• (tags : "news", état : "active")
{
  tags: ["news", "sports"],
  status: "active"
}		 Indexé :
• (tags : "news", état : "active")
• (tags : "sports", état : "active")		 Indexé :
• (tags : "news", état : "active")
• (tags : "sports", état : "active")
{
  tags: ["news", "news"],
  status: "active"
}		 Indexé :
• (tags : "news", état : "active") (dédupliqué)		 Indexé :
• (tags : "news", état : "active") (dédupliqué)
{
  tags: [null],
  status: "active"
}		 Indexé :
• (tags : null, état : "active")		 Indexé :
• (tags : null, état : "active")
{
  tags: ["news"]
}		 Indexé :
• (tags : "news", état : null)		 Non indexé (champ status manquant)
{
  tags: "news",
  status: "active"
}		 Non indexé (le champ n'est pas un tableau) Non indexé (le champ n'est pas un tableau)
{
  tags: null,
  status: "active"
}		 Non indexé (le champ n'est pas un tableau) Non indexé (le champ n'est pas un tableau)
{
  status: "active"
}		 Non indexé (champ tags manquant) Non indexé (champ tags manquant)
{
  tags: [],
  status: "active"
}		 Non indexé (tableau vide) Non indexé (tableau vide)

Exemple de requête

Web
// Query for users where 'tags' contains 'news' and 'status' is 'active'
const query = db.collection("users")
  .where("tags", "array-contains", "news")
  .where("status", "==", "active");

// Documents returned by the query:
// [
//   {
//     "id": "alice",
//     "tags": ["news", "tech"],
//     "status": "active"
//   }
// ]

Index uniques

Définissez l'option d'index unique pour appliquer des valeurs uniques pour les champs indexés. Pour les index sur plusieurs champs, chaque combinaison de valeurs doit être unique dans l'index. La base de données rejette toute opération de mise à jour et d'insertion qui tente de créer des entrées d'index avec des valeurs en double. Si les données des champs indexés contiennent des valeurs en double et que vous tentez de créer un index unique, la compilation de l'index échoue et un message d'erreur s'affiche dans les détails de l'opération.

Champs absents dans un index unique

Si vous insérez un document avec des champs manquants pour l'index unique, l'index définit des valeurs null pour les champs manquants. L'entrée d'index obtenue doit être unique, sinon l'opération échoue.

Par exemple, avec cet index :

Collection Champs indexés Champ d'application de la requête
cities Nom (ordre croissant) Collection

Si vous ajoutez le document {"abbreviation": "LA"} à la collection, l'index unique crée une entrée avec name défini sur null. Si vous essayez ensuite d'ajouter le document {"abbreviation": "NYC"}, l'opération échoue, car l'entrée obtenue pour l'index unique est la même.

Le même comportement s'applique aux index uniques comportant plusieurs champs. Lors de la création ou de la mise à jour d'un document, les champs indexés manquants sont définis sur null et l'entrée d'index résultante doit être unique dans l'index.

Index uniques sur les valeurs de tableau

Un index array-contains unique interdit les documents dont les éléments de tableau se chevauchent.

Ce type d'index n'impose pas qu'un tableau comporte des valeurs uniques dans un même document.

Par exemple, avec un index unique sur un champ nommé tags :

Le document suivant, doc1, peut être inséré :

{
  "tags": [ "news", "tech", "news", "music" ]
}

L'index autorise les valeurs en double ("news") dans le même tableau d'un même document.

Si vous essayez d'insérer un deuxième document, doc2, avec un élément en double, l'opération échoue :

{
  "tags": [ "sports", "music" ]
}

L'opération échoue, car "music" est déjà présent dans le tableau de doc1 et mappé dans l'index.

Si vous devez vous assurer que les éléments d'un même tableau dans un seul document sont uniques, gérez cela dans la logique de votre application.

Tableaux vides, champs manquants et valeurs nulles

Normalement, les champs manquants dans un index unique sont traités comme null et doivent être uniques dans tous les documents (voir Champs absents dans un index unique). Toutefois, pour les index uniques sur les champs de tableau :

  • Tableaux vides, champs manquants et valeurs nulles autonomes : si le champ de tableau est vide, manquant ou contient une valeur null autonome (pas dans un tableau), aucune clé d'index n'est générée pour le document. Par conséquent, plusieurs documents peuvent comporter des champs vides ou des valeurs null autonomes sans déclencher d'erreurs de clé en double.
  • Éléments nuls dans un tableau : si le tableau contient une valeur null en tant qu'élément (par exemple, ["news", null]), l'élément null est indexé. Tout document ultérieur contenant un élément null dans son champ de tableau indexé échouera et générera une erreur de clé en double.

Résoudre les erreurs de création d'index

Vous pouvez rencontrer des erreurs de création d'index lorsque vous gérez vos index. Une opération d'indexation peut échouer si la base de données rencontre un problème avec les données. Les opérations d'indexation peuvent échouer pour les raisons suivantes :

  • Vous avez atteint une limite d'index. Par exemple, l'opération a peut-être atteint le nombre maximal d'entrées d'index par document. Si la création de l'index échoue, un message d'erreur s'affiche. Si vous n'avez pas atteint de limite d'index, réessayez l'opération d'index.
  • Vous définissez l'option d'index unique et les données des champs indexés créent des entrées d'index en double. Pour continuer, supprimez les combinaisons de valeurs en double des données.