Configuration de l'index composite

Cloud Firestore en mode Datastore utilise des index pour chaque requête envoyée par votre application. Ces index sont mis à jour chaque fois qu'une entité est modifiée, de sorte que les résultats soient renvoyés rapidement lorsque l'application effectue une requête. Le mode Datastore fournit automatiquement des index intégrés, mais doit connaître à l'avance les index composites qui seront nécessaires à l'application. Vous devez spécifiez les index composites requis par l'application dans un fichier de configuration. L'émulateur Datastore peut générer automatiquement la configuration de l'index composite en mode Datastore lorsque vous testez votre application. L'outil de ligne de commande gcloud fournit des commandes permettant de mettre à jour les index disponibles pour votre base de données de production en mode Datastore.

Configuration requise

Pour utiliser gcloud CLI, vous devez avoir installé Google Cloud CLI.

À propos de index.yaml

Chaque requête en mode Datastore effectuée par une application nécessite un index correspondant. Les index liés à des requêtes simples, telles que des requêtes portant sur une seule propriété, sont créés automatiquement. Les index composites pour les requêtes complexes doivent être définis dans un fichier de configuration nommé index.yaml. Ce fichier est importé en même temps que l'application pour vous permettre de créer des index composites dans une base de données en mode Datastore.

L'émulateur Datastore ajoute automatiquement des éléments à ce fichier lorsque l'application tente d'exécuter une requête qui nécessite un index composite ne disposant pas d'une entrée appropriée dans le fichier de configuration. Vous pouvez modifier ou créer des index composites manuellement en modifiant le fichier. Le fichier index.yaml se trouve dans le dossier <project-directory>/WEB-INF/. Par défaut, le répertoire de données contenant WEB-INF/appengine-generated/index.yaml est ~/.config/gcloud/emulators/datastore/. Consultez les répertoires de projets de l'émulateur Datastore pour plus de détails.

Voici un exemple de fichier index.yaml :

indexes:

- kind: Task
  ancestor: no
  properties:
  - name: done
  - name: priority
    direction: desc

- kind: Task
  properties:
  - name: collaborators
    direction: asc
  - name: created
    direction: desc

- kind: TaskList
  ancestor: yes
  properties:
  - name: percent_complete
    direction: asc
  - name: type
    direction: asc

La syntaxe du fichier index.yaml utilise le format YAML. Pour en savoir plus sur cette syntaxe, consultez le site Web YAML.

Définitions d'index composites

Le fichier index.yaml comporte un élément de liste unique appelé indexes. Chaque élément de la liste représente un indice composite pour l'application.

Un élément d'index peut se composer des éléments suivants :

kind
Genre de l'entité pour la requête. Il s'agit d'un élément obligatoire.
properties

Liste de propriétés à inclure sous forme de colonnes de l'index composite, classée par ordre de tri: les propriétés utilisées dans les filtres d'égalité en premier, puis la propriété utilisée dans les filtres d'inégalité, et enfin les ordres de tri et leurs sens.

Chaque élément de la liste comporte les éléments suivants :

name
Nom du mode Datastore de la propriété.
direction
Sens du tri, à savoir asc pour un ordre croissant ou desc pour un ordre décroissant. Cet élément est requis uniquement pour les propriétés utilisées dans l'ordre de tri de la requête. Il doit correspondre à l'ordre utilisé par la requête. La valeur par défaut est asc.
ancestor

yes si la requête comporte une clause ascendante. La valeur par défaut est no.

Index composites automatiques et manuels

Lorsque l'émulateur Datastore ajoute une définition d'index composite générée à index.yaml, il effectue cette opération en dessous de la ligne suivante, en l'insérant si nécessaire:

# AUTOGENERATED

L'émulateur considère toutes les définitions d'index composite sous cette ligne comme automatiques. Il peut mettre à jour les définitions existantes sous cette ligne lorsque l'application effectue des requêtes.

Toutes les définitions d'index composite au-dessus de cette ligne sont considérées comme étant sous contrôle manuel et ne sont pas mises à jour par l'émulateur. Celui-ci ne modifiera que les éléments situés sous la ligne, à condition que le fichier index.yaml complet ne décrive pas un indice composite représentant une requête exécutée par l'application. Pour contrôler une définition d'index composite automatique, placez-la au-dessus de cette ligne.

Mettre à jour des index composites

La commande datastore indexes create examine la configuration de votre index composite Datastore local (le fichier index.yaml). Si la configuration définit un index composite qui n'existe pas encore dans votre base de données de production en mode Datastore, il sera créé par votre base de données. Consultez le workflow de développement à l'aide de gcloud CLI pour obtenir un exemple d'utilisation de indexes create.

Pour créer un index composite, la base de données doit configurer l'index composite, puis remplir l'index composite avec les données existantes. La durée de création de l'index composite correspond à la somme des temps de configuration et de remplissage:

  • La configuration d'un indice composite prend quelques minutes. La durée minimale de création d'un indice composite 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 indice composite. Plus le nombre de valeurs de propriétés appartenant à l'index composite est important, plus le remplissage de l'index composite prend du temps.

Si l'application exécute une requête nécessitant un index composite dont la création n'est pas encore terminée, la requête déclenche une exception. Pour éviter cela, soyez prudent lorsque vous déployez une nouvelle version de votre application nécessitant un indice composite dont la création n'est pas terminée.

Vous pouvez vérifier l'état des index composites à partir de la page Index de la console Google Cloud.

Supprimer des index composites inutilisés

Lorsque vous modifiez ou supprimez un indice composite dans la configuration d'indice composite, l'indice composite d'origine n'est pas automatiquement supprimé de votre base de données en mode Datastore. Cela vous donne la possibilité d'utiliser une ancienne version de l'application pendant la création des index composites ou de revenir immédiatement à l'ancienne version si un problème est détecté dans une version plus récente.

Lorsque vous êtes certain de ne plus avoir besoin des anciens index composites, vous pouvez les supprimer à l'aide de la commande datastore indexes cleanup. Cette commande supprime tous les index composites de l'instance de production en mode Datastore qui ne sont pas mentionnés dans la version locale de index.yaml. Consultez le workflow de développement à l'aide de gcloud CLI pour obtenir un exemple d'utilisation de indexes cleanup.

Arguments de ligne de commande

Pour plus d'informations sur les arguments de ligne de commande permettant de créer et de nettoyer des index composites, consultez respectivement les pages datastore indexes create et datastore indexes cleanup. Pour en savoir plus sur les arguments de ligne de commande de gcloud CLI, consultez la documentation de gcloud CLI gcloud.

Gérer les opérations de longue durée

Les compilations d'index composites sont des opérations de longue durée qui peuvent prendre beaucoup de temps.

Lorsque vous lancez la création d'un index composite, le mode Datastore attribue un nom unique à l'opération. 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, utilisez la commande gcloud datastore 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

gcloud datastore operations list

rest

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • project-id : ID de votre projet.

Méthode HTTP et URL :

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Pour envoyer votre requête, développez l'une des options suivantes :

Consultez les informations concernant la réponse ci-dessous.

Par exemple, une compilation d'index composite récemment terminée affiche les informations suivantes:

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

Décrire une seule 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

Utilisez la commande operations describe pour afficher l'état d'une compilation d'index composite.

gcloud datastore operations describe operation-name

rest

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • project-id : ID de votre projet.

Méthode HTTP et URL :

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Pour envoyer votre requête, développez l'une des options suivantes :

Consultez les informations concernant la réponse ci-dessous.

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 d'entités. workEstimated indique le nombre total estimé d'entités qu'une opération va traiter, en fonction des statistiques de la base de données. workCompleted indique le nombre d'entités traitées jusqu'à présent. Une fois l'opération terminée, workCompleted reflète le nombre total d'entités réellement traitées, 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 progression d'une compilation d'index composite:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressEntities": {
          "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.