Configurer les index Datastore avec index.yaml

Vous pouvez utiliser Firestore en mode Datastore (Datastore) pour stocker les données de vos applications exécutées dans l'environnement standard. Datastore utilise des index pour chaque requête effectuée par votre application. Ces index sont mis à jour chaque fois qu'une entité est modifiée pour que les résultats soient renvoyés rapidement lorsque l'application génère une requête. Pour ce faire, Datastore doit connaître à l'avance les requêtes que l'application va effectuer. Vous devez spécifier les index dont votre application a besoin dans un fichier de configuration index.yaml. Vous pouvez utiliser l'émulateur Datastore pour générer le fichier automatiquement lorsque vous testez votre application, ou rédiger le fichier vous-même. Le fichier index.yaml doit être importé lorsque vous déployez votre application.

À propos de index.yaml

Chaque requête Datastore effectuée par une application nécessite un index correspondant. Les index liés à des requêtes simples, telles que celles 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 afin de créer les index dans Datastore.

Voici un exemple de fichier index.yaml :

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    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 doit correspondre à l'argument kind donné à datastore.NewKey lors de la création de l'entité. 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éments suivants :

name
Nom du 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 n'est requis que pour les propriétés utilisées dans l'ordre de tri de la requête et il doit correspondre au sens utilisé par la requête. La valeur par défaut est asc.
ancestor

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

Créer des fichiers d'index

Vous pouvez créer un fichier d'index manuellement, à l'aide d'un éditeur de texte et en respectant le format de fichier décrit ci-dessus. Une approche plus efficace consiste à générer automatiquement le fichier lorsque vous testez votre application localement. Vous pouvez combiner les deux méthodes.

Lorsque vous testez dans votre environnement local, vous pouvez utiliser la commande gcloud emulator pour démarrer un service qui émule Datastore avant d'exécuter votre application :

gcloud beta emulators datastore start --data-dir DATA-DIR

Utilisez l'indicateur --data-dir pour spécifier le répertoire dans lequel le fichier index.yaml généré automatiquement va être placé.

Lorsque vous testez votre application, l'émulateur ajoute une définition d'index générée au fichier index.yaml chaque fois que vous émettez une requête Datastore. Toutes les définitions d'index générées automatiquement s'affichent dans le fichier sous la ligne suivante :

# AUTOGENERATED

Toutes les définitions d'index situées au-dessus de cette ligne sont considérées comme étant gérées manuellement et ne sont pas mises à jour par le serveur Web de développement. Il 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 contrôler une définition d'index automatique, placez-la au-dessus de cette ligne.

L'émulateur peut mettre à jour les définitions qui figurent sous cette ligne lorsque l'application effectue des requêtes. Si toutes les requêtes que l'application va effectuer sont émises pendant que vous la testez, les entrées générées dans le fichier index.yaml sont complètes. Vous devrez peut-être modifier le fichier manuellement pour supprimer les index dont vous n'avez pas besoin en production ou pour définir des index non créés lors des tests.

Déployer le fichier de configuration d'index

Pour déployer le fichier de configuration index.yaml, exécutez la commande suivante :

gcloud app deploy index.yaml

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é d'App Engine. Cela vous donne la possibilité d'utiliser une ancienne version de l'application pendant la création des index 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, vous pouvez les supprimer d'App Engine comme suit :

gcloud datastore indexes cleanup index.yaml