Gérer les index de l'édition Standard

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

L'édition Standard de 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 pour vous. Lorsque vous utilisez et testez votre application, l'édition Standard de 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, composites et vectoriels.

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.

Si un index vectoriel est requis, le message d'erreur inclut une commande Google Cloud CLI permettant de créer l'index vectoriel manquant. Exécutez la commande pour créer l'index manquant.

Rôles et autorisations

Avant de pouvoir créer un index dans l'édition Standard de Firestore, assurez-vous de disposer de l'un des rôles suivants :

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 Google Cloud Platform

Dans la console Google Cloud Platform, vous pouvez gérer les exceptions d'indexation des champs individuels 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 :

Dans la console Google Cloud , accédez à la page Bases de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Composite.
Cliquez sur Créer un index.
Saisissez un ID de collection. Ajoutez les noms des champs que vous souhaitez indexer et un mode d'indexation pour chaque champ. Cliquez sur Enregistrer l'index.

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

Supprimer un index composite

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

Dans la console Google Cloud , accédez à la page Bases de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Composite.
Dans la liste de vos index composites, cliquez sur le bouton Plus correspondant à l'index que vous souhaitez supprimer. Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer cet index en cliquant sur Supprimer l'index dans l'alerte.

Ajouter une exception d'index de champs individuels

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

Dans la console Google Cloud , accédez à la page Bases de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Champ unique.
Cliquez sur Ajouter une exception.
Saisissez un ID de collection et le chemin d'accès au champ.
Sélectionnez les nouveaux paramètres d'indexation pour ce champ. Activer ou désactiver la mise à jour automatique des paramètres "ascendant", "descendant" et "le tableau contient" des index de champs individuels pour ce champ.
Cliquez sur Enregistrer les exceptions.

Ajouter une exemption au niveau de la collection

Pour définir une exception d'index de champ unique qui s'applique à tous les champs sous un ID de collection :

Cliquez sur Ajouter une exception.
Saisissez un ID de collection pour le groupe de collections et définissez le chemin d'accès au champ sur *.
Sélectionnez les exemptions d'indexation que vous souhaitez appliquer à tous les champs du groupe de collections.
Cliquez sur Enregistrer les exceptions.

Supprimer une exception d'index de champs individuels

Pour supprimer une exception d'index de champs individuels, procédez comme suit :

Dans la console Google Cloud , accédez à la page Bases de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Champ unique.
Dans votre liste d'exceptions d'index de champs individuels, cliquez sur le bouton Plus correspondant à l'exception que vous souhaitez supprimer. Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer cette exception en cliquant sur Supprimer dans l'alerte.

Lorsque vous supprimez une exception de champ individuel, le champ ou le sous-champ spécifié utilise les paramètres d'indexation hérités. Les champs de document rétablissent les paramètres d'indexation 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'indexation automatiques.

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 de l'édition Standard de Firestore, ajoutez l'indicateur --only firestore.

Si vous modifiez les index à l'aide de la console Firebase, assurez-vous de mettre à jour votre fichier d'index local. Consultez la documentation de référence sur la définition de l'index JSON.

Utiliser Terraform

Créer des index dans la base de données

Les bases de données Firestore édition Standard peuvent inclure des index à champ unique et des index composites. Vous pouvez modifier le fichier de configuration Terraform pour créer un index pour votre base de données. Les index à champ unique et composites utilisent des types de ressources Terraform distincts (google_firestore_index et google_firestore_field).

Les index en mode natif Firestore et en mode Datastore sont acceptés.

Index à champ unique

L'exemple de fichier de configuration Terraform suivant crée un index à un seul champ sur 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 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 l'ID du projet. Les ID de projet doivent être uniques.
Remplacez database-id par l'ID de votre base de données.

Index vectoriel

L'exemple de fichier de configuration Terraform suivant crée un index vectoriel sur le champ embedding de la collection chatrooms :

firestore.tf

resource "google_firestore_index" "vector-index" {
  project = "project-id"
  database = "database-id"
  collection = "chatrooms"

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

  fields {
    field_path = "embedding"
    vector_config {
      dimension = 128
      flat {}
    }
  }
}

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 du mode Datastore

Vous pouvez également créer des index en mode Datastore à l'aide de Terraform.

datastore.tf

resource "google_firestore_index" "datastore-mode-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

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

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

  query_scope = "COLLECTION_GROUP"
  api_scope   = "DATASTORE_MODE_API"
}

Migrer depuis google_datastore_index

La ressource google_datastore_index est obsolète et ne sera plus disponible dans terraform-provider-google version 6.0.0 et ultérieure.

Si vous utilisiez auparavant la ressource google_datastore_index, vous pouvez migrer vers google_firestore_index. Pour migrer, procédez comme suit :

Écrivez une ressource google_firestore_index équivalente.
Importez votre index en mode Datastore existant dans la nouvelle ressource.
Supprimez les références à l'ancienne ressource google_datastore_index.
Supprimez l'ancienne ressource google_datastore_index de l'état Terraform.
Exécutez terraform apply pour appliquer les modifications.

Voici des instructions plus détaillées :

Écris un google_firestore_index de remplacement en fonction de votre ressource google_datastore_index existante. Consultez la section ci-dessous pour connaître les modifications requises.

Déterminez le chemin d'accès à la ressource Firestore de votre index :

export INDEX_RESOURCE_PATH=$(echo '"projects/${google_datastore_index.datastore-index-resource-name.project}/databases/(default)/collectionGroups/${google_datastore_index.datastore-index-resource-name.kind}/indexes/${google_datastore_index.datastore-index-resource-name.index_id}"' | terraform console | tr -d '"')

Remplacez datastore-index-resource-name par le nom Terraform de votre ressource existante.

Importez votre index en mode Datastore existant dans la ressource google_firestore_index que vous avez créée ci-dessus :
```
terraform import google_firestore_index.firestore-index-resource-name $INDEX_RESOURCE_PATH
```
Remplacez firestore-index-resource-name par le nom Terraform de votre ressource existante.

Pour en savoir plus sur l'importation de ressources d'index Firestore, consultez la documentation de référence google_firestore_index.
Supprimez la ressource google_datastore_index existante de votre fichier de configuration Terraform.

Supprimez la ressource google_datastore_index existante de l'état Terraform :
```
terraform state rm google_datastore_index.datastore-index-resource-name
```
Pour en savoir plus sur la suppression de ressources, consultez la page Terraform sur la suppression de ressources.

Exécutez terraform plan. Vérifiez le résultat pour confirmer que vous ne créez ni ne détruisez aucune ressource.

Inspectez le résultat pour vous assurer que l'importation a réussi. Si le résultat indique que des champs ont été modifiés, assurez-vous que ces modifications sont intentionnelles. Si le résultat inclut une ligne semblable à celle-ci :
```
google_firestore_index.firestore-index-resource-name must be replaced
```
Ensuite, inspectez votre fichier de configuration Terraform pour voir si vous avez commis des erreurs.

Avertissement : N'exécutez pas "terraform apply" si vous voyez des ressources d'index nécessitant un remplacement ou des ressources d'index en cours de suppression. Cela peut entraîner la perte de votre index et, éventuellement, un temps d'arrêt pour votre application.

Une fois que vous êtes satisfait de la sortie du plan Terraform, exécutez la commande suivante :
```
terraform apply
```

Traduire votre index

Pour traduire une ressource google_datastore_index en ressource google_firestore_index équivalente, copiez-la et apportez les modifications suivantes :

Remplacez google_datastore_index par google_firestore_index.
Remplacez le nom de l'argument kind par collection, mais conservez la même valeur d'argument.
Remplacez le nom de l'argument ancestor par query_scope. Remplacez la valeur de l'argument ALL_ANCESTORS par COLLECTION_RECURSIVE et toute autre valeur par COLLECTION_GROUP. S'il n'y a pas d'argument ancestor, ajoutez un argument query_scope avec la valeur COLLECTION_GROUP.
Ajoutez l'argument api_scope avec la valeur DATASTORE_MODE_API.
Pour chaque instance de properties, remplacez-la par une instance correspondante de fields. Remplacez chaque instance de name par field_path et chaque instance de direction par order.

Par exemple, prenons cette ressource google_datastore_index :

datastore.tf

resource "google_datastore_index" "legacy" {
  kind = "foo"

  properties {
    name = "property_a"
    direction = "ASCENDING"
  }

  properties {
    name = "property_b"
    direction = "ASCENDING"
  }
}

La ressource google_firestore_index équivalente serait :

resource "google_firestore_index" "new" {
  // note: defaults to the provider project
  project = project

  // note: defaults to the (default) database
  database = "(default)"

  collection = "foo"

  api_scope = "DATASTORE_MODE_API"

  // since there was no "ancestor" property set above, use COLLECTION_GROUP here
  query_scope = "COLLECTION_GROUP"

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

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

Temps de création d'un index

Pour créer un index, l'édition standard de Firestore doit configurer l'index, puis le remplir avec les 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 que vous avez lancé la création d'un index, l'édition Standard de Firestore attribue à l'opération un nom unique. Les noms des opérations 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 l'édition Standard de Firestore rencontre un problème avec les données qu'il est en train d'indexer. 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'atteignez aucune limite d'index, essayez à nouveau.