Gérer les index dans Cloud Firestore

Cloud Firestore garantit les performances des requêtes en exigeant un index pour chaque requête. 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 génère des messages d'erreur qui vous aident à créer les index supplémentaires dont votre application a besoin. Cette page décrit comment gérer vos index à champ unique et composites .

Créer un index manquant via un message d'erreur

Si vous tentez une requête composée avec une clause range qui ne correspond pas à un index existant, vous recevez une erreur. Le message d'erreur inclut un lien direct pour créer l'index manquant dans la console Firebase.

Suivez le lien généré vers la console Firebase, consultez les informations automatiquement renseignées et cliquez sur Créer .

Rôles et autorisations

Avant de pouvoir créer un index dans Cloud Firestore, assurez-vous que l'un des rôles suivants vous est attribué :

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

Si vous avez défini des rôles personnalisés, attribuez toutes les autorisations suivantes pour créer des index :

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Utiliser la console Firebase

Pour créer manuellement un nouvel index à partir de la console Firebase :

image de l'interface d'indexation Firestore dans la console Firebase

  1. Accédez à la section Cloud Firestore de la console Firebase .
  2. Accédez à l'onglet Index et cliquez sur Ajouter un index .
  3. Entrez le nom de la collection et définissez les champs selon lesquels vous souhaitez trier l'index.
  4. Cliquez sur Créer .

Les champs d'index doivent être conformes aux contraintes sur les chemins de champ .

La création des index peut prendre quelques minutes, en fonction de la taille de la requête. Après les avoir créés, vous pouvez voir vos index et leur statut dans la section Index composites. S'ils sont encore en construction, la console Firebase comprend une barre d'état de construction.

Supprimer les index

Pour supprimer un index :

  1. Accédez à la section Cloud Firestore de la console Firebase .
  2. Cliquez sur l'onglet Index .
  3. Passez la souris sur l'index que vous souhaitez supprimer et sélectionnez Supprimer dans le menu contextuel.
  4. Confirmez que vous souhaitez le supprimer en cliquant sur Supprimer de l'alerte.

Utiliser la CLI Firebase

Vous pouvez également déployer des index avec la Firebase CLI . Pour commencer, exécutez firebase init firestore dans le répertoire de votre projet. Lors de l'installation, la CLI Firebase génère un fichier JSON avec les index par défaut au format correct. Modifiez le fichier pour ajouter plus d'index et déployez-le avec la commande firebase deploy .

Pour déployer uniquement les index et les règles Cloud Firestore, ajoutez l'indicateur --only firestore .

Si vous apportez des modifications aux index à l'aide de la console Firebase, assurez-vous de mettre également à jour votre fichier d'index local. Reportez-vous à la référence sur la définition de l'index JSON .

Utiliser Terraform

Création d'index dans la base de données

La base de données Cloud Firestore peut inclure un index à champ unique ou un index composite. Vous pouvez modifier le fichier de configuration Terraform pour créer un index pour votre base de données.

Index à champ unique

L'exemple de fichier de configuration Terraform suivant crée un index à champ unique sur le champ name dans la collection de chatrooms :

firestore.tf

resource "random_id" "variable"{
  byte_length = 8
}

resource "google_firestore_field" "single-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms_${random_id.variable.hex}"
  field = "name"

  index_config {
    indexes {
        order = "ASCENDING"
        query_scope = "COLLECTION_GROUP"
    }
    indexes {
        array_config = "CONTAINS"
    }
  }

  ttl_config {}
}
  • Remplacez project-id par votre ID de projet. Les ID de projet doivent être uniques.
  • Remplacez database-id par votre ID de base de données.

Index composé

L'exemple de fichier de configuration Terraform suivant crée un index composite pour une combinaison du champ name et du champ description dans la collection chatrooms :

firestore.tf

resource "google_firestore_index" "composite-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

}
  • Remplacez project-id par votre ID de projet. Les ID de projet doivent être uniques.
  • Remplacez database-id par votre ID de base de données.

Temps de création de l'index

Pour créer un index, Cloud Firestore doit configurer l'index, puis remplir l'index avec les données existantes. Le temps de création de l'index est la somme du temps de configuration et du temps de remplissage :

  • La configuration d'un index prend quelques minutes. Le temps minimum de construction d'un index est de quelques minutes, même pour une base de données vide.

  • Le temps de remplissage dépend de la quantité de données existantes appartenant au nouvel index. Plus il y a de valeurs de champ correspondant à la définition de l’index, plus le remplissage de l’index prend du temps.

Les constructions d'index sont des opérations de longue durée .

Après avoir démarré une création d'index, Cloud Firestore attribue à l'opération un nom unique. Les noms d'opérations sont préfixés par projects/[PROJECT_ID]/databases/(default)/operations/ , par exemple :

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Toutefois, vous pouvez omettre le préfixe lorsque vous spécifiez un nom d'opération pour la commande describe .

Liste de toutes les opérations de longue durée

Pour répertorier les opérations de longue durée, utilisez la commande gcloud firestore operations list . Cette commande répertorie les opérations en cours et récemment terminées. Les opérations sont répertoriées quelques jours après leur achèvement :

gcloud firestore operations list

Vérifier l'état de fonctionnement

Au lieu de répertorier toutes les opérations de longue durée, vous pouvez répertorier les détails d'une seule opération :

gcloud firestore operations describe operation-name

Estimation du temps de réalisation

Pendant l'exécution de votre opération, consultez la valeur du champ state pour connaître l'état global de l'opération.

Une demande de statut d'une opération de longue durée renvoie également les métriques workEstimated et workCompleted . Ces métriques sont renvoyées pour le nombre de documents. workEstimated indique le nombre total estimé de documents qu’une opération traitera. workCompleted indique le nombre de documents traités jusqu'à présent. Une fois l'opération terminée, workCompleted reflète le nombre total de documents réellement traités, qui peut être différent de la valeur de workEstimated .

Divisez workCompleted par workEstimated pour une estimation approximative des progrès. L’estimation peut être inexacte car elle dépend d’un retard dans la collecte des statistiques.

Par exemple, voici l'état d'avancement d'une création d'index :

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressDocuments": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

Lorsqu'une opération est effectuée, la description de l'opération contiendra "done": true . Voir la valeur du champ state pour le résultat de l'opération. Si le champ done n'est pas défini dans la réponse, sa valeur est false . Ne dépendez pas de l'existence de la valeur done pour les opérations en cours.

Erreurs de création d’index

Vous pouvez rencontrer des erreurs de création d’index lors de la gestion des index composites et des exemptions d’index à champ unique. Une opération d'indexation peut échouer si Cloud Firestore rencontre un problème avec les données qu'il indexe. Le plus souvent, cela signifie que vous avez atteint une limite d'index . Par exemple, l'opération peut avoir atteint le nombre maximum d'entrées d'index par document.

Si la création de l'index échoue, le message d'erreur s'affiche dans la console. Après avoir vérifié que vous n'atteignez aucune limite d'index , réessayez votre opération d'index.