Gérer les index

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 créés automatiquement. 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 requis par l'application. Cette page explique comment gérer vos index à champ unique et composites.

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

Si vous tentez d'exécuter une requête composée avec une clause de plage qui n'est pas mappée à un index existant, vous recevez un message d'erreur. Le message d'erreur inclut un lien direct permettant de créer l'index manquant dans la console Firebase.

Suivez le lien généré pour accéder à la console Firebase, consultez les informations renseignées automatiquement, puis cliquez sur Créer.

Utiliser la console Google Cloud Platform

La console Google Cloud Platform vous permet de gérer les exceptions d'indexation à champ unique et les index composites.

Créer un index composite

Pour créer manuellement un index composite à partir de la console GCP, procédez comme suit:

  1. Accédez à la section Index composites.

    Accéder à la section "Index composites"

  2. Cliquez sur Créer un index.

  3. Saisissez un ID de collection. Ajoutez les noms des champs que vous souhaitez indexer, ainsi qu'un mode d'index pour chaque champ. Cliquez sur Enregistrer l'index.

Votre nouvel index apparaît dans la liste des index composites et Firestore commence à le créer. Une fois l'index créé, une coche verte s'affiche à côté de l'index.

Supprimer un index composite

Pour supprimer un index composite, procédez comme suit:

  1. Accédez à la section Index composites.

    Accéder à la section "Index composites"

  2. Dans la liste de vos index composites, cliquez sur le bouton Plus correspondant à l'index que vous souhaitez supprimer. Cliquez sur Delete (Supprimer).

  3. Confirmez que vous souhaitez supprimer cet index en cliquant sur Supprimer l'index dans l'alerte.

Ajouter une exception d'index à champ unique

Les exceptions d'index à champ unique vous permettent de remplacer les paramètres d'index automatiques pour des champs spécifiques d'une collection. Vous pouvez ajouter des exceptions de champ unique à partir de la console:

  1. Accédez à la section Index à champ unique.

    Accéder à la section Index des champs uniques

  2. Cliquez sur Ajouter une exception.

  3. Renseignez les champs Collection ID (ID de collection) et Field path (Chemin d'accès du champ).

  4. Sélectionnez de nouveaux paramètres d'indexation pour ce champ. Activez ou désactivez les index croissants, décroissants et de tableau unique mis à jour automatiquement pour ce champ.

  5. Cliquez sur Enregistrer l'exception.

Supprimer une exception d'index à champ unique

Pour supprimer une exception d'index à champ unique, procédez comme suit:

  1. Dans la visionneuse Firestore, accédez à la section Index à champ unique.

    Accéder à la section Index des champs uniques

  2. Dans la liste des exceptions d'index à champ unique, cliquez sur le bouton Plus correspondant à l'exception que vous souhaitez supprimer. Cliquez sur Delete (Supprimer).

  3. Confirmez que vous souhaitez supprimer cette exception en cliquant sur Supprimer dans l'alerte.

Lorsque vous supprimez une exception à champ unique, le champ ou sous-champ spécifié utilise des paramètres d'indexation hérités. Les champs de document rétablissent les paramètres d'index automatiques de votre base de données. Les sous-champs d'une carte héritent des exceptions sur les champs parents avant d'hériter des paramètres d'index automatiques.

Utiliser la CLI Firebase

Vous pouvez également déployer des index à l'aide de la CLI Firebase. Pour commencer, exécutez firebase init firestore dans le répertoire de votre projet. Lors de la configuration, la CLI Firebase génère un fichier JSON avec les index par défaut au format approprié. Modifiez le fichier pour ajouter d'autres index et déployez-le à l'aide de la commande firebase deploy. Si vous souhaitez uniquement déployer des index, ajoutez l'option --only firestore:indexes. Si vous modifiez les index à l'aide de la console Firebase, veillez également à mettre à jour votre fichier d'index local. Consultez la documentation de référence sur la définition de l'index JSON.

Date de création de l'index

Pour créer un index, Firestore doit le configurer, puis remplir l'index avec des données existantes. Le temps de compilation de l'index correspond à la somme du temps de configuration et du temps de remplissage:

  • La configuration d'un index prend quelques minutes. La durée minimale de compilation 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 dans le nouvel index. Plus le nombre de valeurs de champ correspondant à la définition d'index est élevé, plus il faut de temps pour remplir l'index.

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

Une fois que vous avez démarré une compilation d'index, Firestore attribue un nom unique à l'opération. Les noms des opérations comportent le préfixe 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.

Répertorier toutes les opérations de longue durée

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

gcloud firestore operations list

Vérifier l'état de l'opération

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

Estimer le délai d'exécution

Lors de l'exécution de l'opération, consultez la valeur du champ state pour obtenir l'état général de l'opération.

Une requête permettant d'obtenir l'état 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 affiche 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 indique le nombre total de documents réellement traités, qui peut être différent de la valeur de workEstimated.

Divisez workCompleted par workEstimated pour obtenir une estimation approximative de la progression. L'estimation peut être inexacte, car elle dépend de la collecte de statistiques retardée.

Voici par exemple l'état de progression d'une compilation 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 terminée, la description de l'opération contient "done": true. Consultez la valeur du champ state pour obtenir 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 vous basez pas sur l'existence de la valeur done pour les opérations en cours.

Erreurs liées à la création d'index

Vous pouvez rencontrer des erreurs de création d'index lors de la gestion d'index composites et d'exceptions d'index à champ unique. Une opération d'indexation peut échouer si 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 maximal 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'avez atteint aucune limite d'index, réessayez de lancer votre opération d'index.