Documentation de référence sur datastore-indexes.xml

App Engine prédéfinit un index simple sur chaque propriété d'une entité. Une application App Engine peut définir d'autres index personnalisés dans un fichier de configuration d'index appelé datastore-indexes.xml. Le serveur de développement peut générer la configuration d'index requise par votre application lorsqu'il exécute ces requêtes pendant que vous testez votre application. Vous pouvez ajuster des index manuellement en modifiant le fichier datastore-indexes.xml avant d'importer l'application. Consultez la page Configurer des index Datastore pour en savoir plus sur le déploiement et la gestion des configurations d'index.

Exemple

Voici un exemple de fichier datastore-indexes.xml :

<?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>

Syntaxe

L'élément <datastore-index> peut contenir les éléments suivants :

Élément Description
<kind> Obligatoire. Genre de l'entité pour la requête.
<properties>

Liste des 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 obligatoire que 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 (Query.setAncestor). La valeur par défaut est no.

Index automatiques et index manuels

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 de 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, la commande appcfg utilise datastore-indexes.xml et datastore-indexes-auto.xml pour déterminer les index à créer pour l'application en 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.

Déployer le fichier de configuration d'index

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

Pour déployer le fichier de configuration d'index Datastore sans modifier la version actuellement diffusée, utilisez la commande suivante :

appcfg.sh update_indexes <application root path>

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 :

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