Configurer des index Datastore

En cas d'accès à partir d'App Engine, Cloud 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 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. Consignez dans un fichier de configuration les index dont a besoin l'application. Le serveur de développement peut générer automatiquement la configuration d'index Cloud Datastore lorsque vous testez l'application.

Créer des index Datastore

Spécifiez la configuration des index Datastore dans WEB-INF/datastore-indexes.xml dans le répertoire war/ de votre application.

Comme décrit sur la page Index Datastore, un index est une table de valeurs pour un ensemble de propriétés données pour des entités d'un genre spécifique. Chaque colonne des valeurs de propriété est classée par ordre croissant ou décroissant. La configuration d'un index spécifie le genre des entités, le nom des propriétés et l'ordre de tri.

Voici un exemple de datastore-indexes.xml qui spécifie deux index :

<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes
  autoGenerate="true">
    <datastore-index kind="Employee" ancestor="false">
        <property name="lastName" direction="asc" />
        <property name="hireDate" direction="desc" />
    </datastore-index>
    <datastore-index kind="Project" ancestor="false">
        <property name="dueDate" direction="asc" />
        <property name="cost" direction="desc" />
    </datastore-index>
</datastore-indexes>

Créer des index à l'aide du serveur de développement

La procédure manuelle de définition des index requis par les requêtes de votre application peut se révéler difficile et être source d'erreurs. Toutefois, le serveur de développement peut déterminer la configuration des index à votre place. Pour faire appel à la configuration automatique des index, ajoutez l'attribut autoGenerate="true" à l'élément <datastore-indexes> du fichier WEB-INF/datastore-indexes.xml. La configuration automatique des index est également utilisée lorsque votre application ne possède pas de fichier datastore-indexes.xml.

Avec la configuration automatique des index activée, le serveur de développement conserve un fichier nommé WEB-INF/appengine-generated/datastore-indexes-auto.xml dans le répertoire war/ de votre application. Lorsqu'une application s'exécutant sur le serveur de développement tente d'exécuter une requête Datastore pour laquelle aucun index correspondant n'existe dans datastore-indexes.xml ou datastore-indexes-auto.xml, le serveur ajoute la configuration adéquate au fichier datastore-indexes-auto.xml.

Si la configuration automatique des index est activée lorsque vous importez votre application, AppCfg utilise datastore-indexes.xml et datastore-indexes-auto.xml pour déterminer les index à créer pour l'application en cours de production.

Si autoGenerate="false" figure dans votre fichier datastore-indexes.xml, le serveur de développement et AppCfg ignorent le contenu de datastore-indexes-auto.xml. Si l'application qui s'exécute localement envoie une requête dont l'index n'est pas spécifié dans datastore-indexes.xml, le serveur de développement génère une exception, comme le ferait Datastore en production.

Il est parfois judicieux de déplacer la configuration des index du fichier datastore-indexes-auto.xml vers le fichier datastore-indexes.xml, puis de désactiver la configuration automatique des index et de tester votre application au sein du serveur de développement. Cette procédure permet d'assurer plus facilement la maintenance des index sans avoir à gérer deux fichiers distincts, et de garantir que les tests reproduisent les erreurs causées par une configuration d'index manquante.

Créer des index manuellement

Vous pouvez ajouter manuellement des index au fichier datastore-indexes.xml ou basculer les index que le serveur de développement a créés automatiquement dans le fichier datastore-indexes-auto.xml vers le fichier datastore-indexes.xml.

Consultez la documentation de référence de datastore-indexes.xml pour obtenir des informations sur la syntaxe.

Mettre à jour des index

Lorsque vous transférez une application à l'aide de l'action update, la mise à jour s'applique également à la configuration de son index (les fichiers datastore-indexes.xml et generated/datastore-indexes-auto.xml). Si la configuration d'index définit un index qui n'existe pas encore, App Engine le crée. En fonction de la quantité de données déjà présente dans Datastore qui doit être mentionnée dans le nouvel index, le processus de création de l'index peut prendre un certain temps. Si l'application effectue une requête nécessitant un index dont la création n'est pas terminée, la requête génère une exception.

Pour empêcher ceci, vous devez vous assurer que la nouvelle version de l'application nécessitant un nouvel index n'est pas la version active de l'application tant que la création des index n'est pas terminée. Pour cela, vous pouvez attribuer à l'application un nouveau numéro de version dans appengine-web.xml chaque fois que vous ajoutez ou modifiez un index à la configuration. L'application est transférée sous la forme d'une nouvelle version. Elle ne devient pas automatiquement la version par défaut. Une fois la compilation de vos index terminée, vous pouvez modifier la version par défaut dans Cloud Console.

Un autre moyen de s'assurer que les nouveaux index sont créés avant la mise en ligne de la nouvelle application consiste à importer la configuration de l'index séparément avant de la mettre en ligne. Pour importer uniquement la configuration d'index d'une application, utilisez l'action update_indexes :

./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war

Le fichier datastore-indexes.xml doit se trouver dans le répertoire WEB-INF/ du module par défaut.

Dans Cloud Console, vous pouvez vérifier l'état des index de l'application.

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 sûr que les anciens index ne sont plus nécessaires, vous pouvez les supprimer d'App Engine à l'aide de l'action vacuum_indexes :

./appengine-java-sdk/bin/appcfg.sh vacuum_indexes myapp/war

Cette commande supprime tous les index de l'application qui ne sont pas mentionnés dans les versions locales de datastore-indexes.xml et de WEB-INF/appengine-generated/datastore-indexes-auto.xml.