Configuration d'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 la gcloud CLI, vous devez avoir installé la 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é avec l'application pour 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 nécessitant un index composite ne comportant pas d'entrée appropriée dans le fichier de configuration. Vous pouvez ajuster 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 de l'index composite

Le fichier index.yaml comporte un élément de liste unique appelé indexes. Chaque élément de la liste représente un index composite de 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ées par ordre de tri: les propriétés utilisées dans les filtres d'égalité en premier, suivies de la propriété utilisée dans les filtres d'inégalité, puis 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 au fichier index.yaml, il effectue cette opération sous 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. L'émulateur n'apportera des modifications qu'aux éléments situés sous la ligne, à condition que le fichier index.yaml complet ne décrive pas un index composite qui rend compte d'une requête exécutée par l'application. Pour prendre le contrôle d'une définition d'index composite automatique, dé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 elle définit un index composite qui n'existe pas encore dans votre base de données de production en mode Datastore, elle le crée. 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 le configurer, puis remplir l'index composite avec les données existantes. La durée de création de l'index composite correspond à la somme du temps de configuration et du temps de remplissage:

  • La configuration d'un index composite prend quelques minutes. Le temps minimal de création d'un index composite 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 qui appartiennent au nouvel index composite. Plus il y a de valeurs de propriété appartenant à l'index composite, plus il faut de temps pour remplir l'index composite.

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 génère une exception. Pour éviter cela, vous devez veiller à déployer une nouvelle version de votre application nécessitant un index composite avant que la création de l'index composite ne soit 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 index composite de la configuration d'index composite, l'index composite d'origine n'est pas automatiquement supprimé de votre base de données en mode Datastore. Cela vous donne la possibilité de laisser une ancienne version de l'application s'exécuter pendant la création des nouveaux 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 en savoir plus 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 la gcloud CLI, consultez la documentation de référence sur la gcloud CLI.

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

Les compilations d'index composites sont des opérations de longue durée dont l'exécution peut prendre beaucoup de temps.

Une fois que vous avez démarré 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, 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 de la création d'un index composite.

gcloud datastore operations describe operation-name

rest

Avant d'utiliser les données de requête, 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.