Configuration de l'index

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 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 l'outil gcloud, vous devez avoir installé le SDK Google Cloud.

À 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 liés à des 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 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 ne disposant pas d'une entrée appropriée dans le fichier de configuration. Vous pouvez modifier ou créer des index 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 des index

Le fichier index.yaml comporte un élément de liste unique appelé indexes. Chaque élément de la liste représente un index lié à 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, 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ément 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 automatiques et index manuels

Lorsque l'émulateur Datastore ajoute une définition d'index générée au fichier 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 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 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 index représentant une requête exécutée par l'application. Pour prendre le contrôle d'une définition d'index automatique, déplacez-la au-dessus de cette ligne.

Mettre à jour des index

La commande datastore indexes create examine la configuration de votre index Datastore local (le fichier index.yaml). Si la configuration définit un index qui n'existe pas dans votre base de données de production en mode Datastore, il sera créé par votre base de données. Référez-vous au processus de développement à l'aide de l'outil gcloud pour obtenir un exemple d'utilisation de indexes create.

Pour créer un index, la base de données doit configurer l'index, puis remplir l'index 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 le nombre de valeurs de propriétés appartenant à l'index est important, plus le remplissage de l'index prend du temps.

Si l'application exécute une requête nécessitant un index dont la construction 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 index dont la création n'est pas terminée.

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

Supprimer des index inutilisés

Lorsque vous modifiez ou supprimez un index dans la configuration d'index, l'index d'origine n'est pas automatiquement supprimé de votre base de données en mode Datastore. Ainsi, vous pouvez laisser une ancienne version de l'application en cours d'exécution pendant la création de nouveaux index ou revenir immédiatement à l'ancienne version si un problème survient sur une version plus récente.

Lorsque vous êtes certain de ne plus avoir besoin des anciens index, vous pouvez les supprimer à l'aide de la commande datastore indexes cleanup. Cette commande supprime tous les index de l'instance de production en mode Datastore qui ne sont pas mentionnés dans la version locale de index.yaml. Référez-vous au processus de développement à l'aide de l'outil gcloud 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, consultez respectivement les pages datastore indexes create et datastore indexes cleanup. Pour plus d'informations sur les arguments de ligne de commande de l'outil gcloud, consultez la documentation de référence de l'outil gcloud.

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

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

Lorsque vous lancez une compilation d'index, 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 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

Exécutez la commande operations describe pour afficher l'état d'une compilation d'index.

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 la progression d'une compilation d'index :

{
  "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.