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 Cloud 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 système 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 Cloud Datastore ajoute automatiquement des éléments à ce fichier lorsque l'application tente d'exécuter une requête nécessitant un index qui ne possède pas l'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 Cloud 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 utilisée dans index.yaml est au format YAML. Pour en savoir plus sur cette syntaxe, consultez le site Web YAML.

Définitions des index

index.yaml possède un seul élément de liste nommé 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
L'ordre du tri, soit asc pour l'ordre croissant ou desc pour l'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 (ordre croissant).
ancestor

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

Index automatiques et index manuels

Lorsque l'émulateur Cloud Datastore ajoute une définition d'index 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 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. L'émulateur n'apportera des modifications qu'aux éléments situés sous la ligne et uniquement si le fichier complet index.yaml ne décrit pas un index qui rend compte d'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 encore 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 avec l'outil gcloud pour un exemple d'utilisation de indexes create.

En fonction de la quantité de données déjà présente dans votre base de données appartenant au nouvel index, le processus de création de l'index peut prendre un certain 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éclenchera une exception. Pour éviter cela, soyez prudent lorsque vous déployez une nouvelle version de votre application nécessitant un nouvel index dont la création n'est pas terminée.

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

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 n'étant pas mentionnés dans la version locale de index.yaml. Référez-vous au processus de développement avec l'outil gcloud pour 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, consultez respectivement datastore indexes create et datastore indexes cleanup. Pour en savoir plus sur les arguments de ligne de commande de l'outil gcloud, consultez la documentation de référence de l'outil gcloud.

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Cloud Datastore