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éé 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 requis par votre application. Cette page explique comment gérer les index de champs individuels et les index composites.
Créer un index manquant via un message d'erreur
Si vous tentez d'effectuer 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 comprend un lien direct qui permet de créer l'index manquant dans la console Firebase.
Cliquez sur 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.ownerroles/datastore.indexAdminroles/editorroles/owner
Si vous avez défini des rôles personnalisés, attribuez toutes les autorisations suivantes pour créer des index :
datastore.indexes.createdatastore.indexes.deletedatastore.indexes.getdatastore.indexes.listdatastore.indexes.update
Utiliser la console Firebase
Pour créer manuellement un index à partir de la console Firebase:
- Accédez à la section Cloud Firestore de la console Firebase.
- Accédez à l'onglet Index, puis cliquez sur Ajouter un index.
- Saisissez le nom de la collection et définissez les champs selon lesquels vous souhaitez classer l'index.
- Cliquez sur Créer.
Les champs d'index doivent respecter les contraintes sur les chemins d'accès des champs.
La création des index peut prendre quelques minutes, en fonction de la taille de la requête. Une fois les index créés, vous pouvez consulter vos index et leur état dans la section Index composites. Si la création est toujours en cours, la console Firebase inclut une barre d’état d’un bâtiment.
Supprimer des index
Pour supprimer un index :
- Accédez à la section Cloud Firestore de la console Firebase.
- Cliquez sur l'onglet Index.
- Pointez sur l'index que vous souhaitez supprimer et sélectionnez Supprimer dans le menu contextuel.
- Confirmez que vous souhaitez la supprimer en cliquant sur Supprimer dans l'alerte.
Utiliser la CLI 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 approprié. Modifiez le fichier pour ajouter d'autres index et déployez-le avec la commande firebase deploy.
Pour déployer uniquement les index et les règles Cloud Firestore, ajoutez le
--only firestore.
Si vous modifiez les index à l'aide de la console Firebase, veillez également à mettre à jour votre fichier d'index local. Consultez la référence de définition d'index JSON.
Utiliser Terraform
Créer des index dans la base de données
Les bases de données Cloud Firestore peuvent inclure à la fois des index à champ unique et des index composites. Vous pouvez modifier le fichier de configuration Terraform afin de créer un index pour votre base de données. Les index à champ unique et composites utilisent des types de ressources Terraform distincts.
Index à champ unique
L'exemple de fichier de configuration Terraform suivant crée un index à champ unique pour le champ name de la collection 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 l'ID du projet. Les ID de projet doivent être uniques.
- Remplacez database-id par l'ID de votre base de données.
Index composite
L'exemple de fichier de configuration Terraform suivant crée un index composite pour une combinaison des champs name et description de 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 l'ID du projet. Les ID de projet doivent être uniques.
- Remplacez database-id par l'ID de votre base de données.
Temps de création d'un index
Pour créer un index, Cloud Firestore doit le configurer, puis remplir l'index avec des données existantes. La durée de création de l'index correspond à la somme des temps de configuration et de remplissage :
La configuration d'un index prend quelques minutes. La durée minimale de création d'un index est de quelques minutes, même pour une base de données vide.
Le délai de remplissage dépend de la quantité de données existantes qui appartiennent au nouvel index. Plus les valeurs de champs correspondant à la définition de l'index sont nombreuses, plus le remplissage de l'index prend du temps.
Les créations d'index sont des opérations de longue durée.
Une fois la compilation d'index lancée, Cloud Firestore attribue
à l'opération un nom unique. Les noms d'opération sont précédés du préfixe 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, exécutez la commande gcloud firestore operations list. Cette commande répertorie les opérations en cours et récemment terminées. Une fois terminées, les opérations restent accessibles pendant quelques jours :
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
Estimation du délai d'exécution
Lorsque l'opération s'exécute, consultez la valeur du champ state pour connaître son état global.
Une requête permettant d'obtenir l'état d'une opération de longue durée renvoie 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 va traiter. 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 obtenir une estimation approximative de la progression. L'estimation peut être inexacte, car elle dépend de la collecte de statistiques retardée.
Par exemple, voici l'état de la 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 afficher 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 de création d'index
Vous risquez de rencontrer des erreurs lorsque vous gérez des index composites et des exceptions d'index de champs individuels. Une opération d'indexation peut échouer si Cloud Firestore rencontre un problème avec les données qu'il est en train d'indexer. La plupart cela signifie que vous atteignez 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, essayez à nouveau.