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 des 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 de plage 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, passez en revue les informations renseignées automatiquement, puis 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 a été 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 :
- Accédez à la section Cloud Firestore de la console Firebase .
- Accédez à l'onglet Index et cliquez sur Ajouter un index .
- Entrez le nom de la collection et définissez les champs selon lesquels vous souhaitez trier l'index.
- Cliquez sur Créer .
La création des index peut prendre quelques minutes, selon la taille de la requête. Après les avoir créés, vous pouvez voir vos index et leur état dans la section Index composites. S'ils sont toujours en construction, la console Firebase inclut une barre d'état de construction.
Supprimer les index
Pour supprimer un index :
- Accédez à la section Cloud Firestore de la console Firebase .
- Cliquez sur l'onglet Index .
- Survolez l'index que vous souhaitez supprimer et sélectionnez Supprimer dans le menu contextuel.
- Confirmez que vous souhaitez le supprimer en cliquant sur Supprimer de l'alerte.
Utiliser l'interface de ligne de commande Firebase
Vous pouvez également déployer des index avec 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 correct. Modifiez le fichier pour ajouter d'autres index et déployez-le avec la commande firebase deploy
. Si vous souhaitez uniquement déployer des index, ajoutez l'indicateur --only firestore:indexes
. 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 de définition d'index JSON .
Temps de construction de l'index
Pour créer un index, Cloud Firestore doit configurer l'index, puis remplir l'index avec des données existantes. Le temps de construction de l'index est la somme du temps de configuration et du temps de remplissage :
La création d'un index prend quelques minutes. Le temps de construction minimum pour 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 .
Une fois que vous avez démarré une création d'index, Cloud Firestore attribue à l'opération un nom unique. Les noms d'opération sont précédés de projects/[PROJECT_ID]/databases/(default)/operations/
, par exemple :
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Cependant, 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 operations 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 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
Au fur et à mesure que votre opération s'exécute, consultez la valeur du champ state
pour connaître l'état général 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
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
reflète le nombre total de documents réellement traités, qui peut être différent de la valeur de workEstimated
.
Diviser workCompleted
par workEstimated
pour une estimation approximative de l'avancement. L'estimation peut être inexacte car elle dépend de la collecte tardive des statistiques.
Par exemple, voici l'état d'avancement d'une génération 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 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épend 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 atteignez 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'atteignez aucune limite d'index , réessayez votre opération d'index.