Configura índices de Datastore

Datastore usa índices para cada consulta que realiza tu aplicación cuando se accede mediante App Engine. Estos índices se actualizan siempre que se modifica una entidad, de modo que se puedan mostrar resultados con rapidez cuando la app realiza una consulta. Para ello, Datastore necesita saber de antemano qué consultas realizará la aplicación. Debes especificar los índices que la app necesita en un archivo de configuración. El servidor de desarrollo puede generar la configuración de índice de Datastore de forma automática mientras pruebas la app.

Crea índices de Datastore

Especifica la configuración de los índices de Datastore en WEB-INF/datastore-indexes.xml, en el directorio war/ de tu app.

Como se explica en la página Índices de Datastore, un índice es una tabla de valores de un conjunto de propiedades determinadas para entidades de un tipo específico. Cada columna de valores de propiedades está ordenada de forma ascendente o descendente. La configuración de un índice determina el grupo de similares de las entidades, los nombres de las propiedades y su orden de clasificación.

A continuación, se muestra un ejemplo de datastore-indexes.xml que especifica dos índices:

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

Crea índices mediante el servidor de desarrollo

Determinar los índices que requieren las consultas de tu aplicación de forma manual puede ser una tarea tediosa y propensa a cometer errores. Afortunadamente, el servidor de desarrollo puede determinar la configuración de índices por ti. Para usar la configuración automática de índices, agrega el atributo autoGenerate="true" al elemento <datastore-indexes> del archivo WEB-INF/datastore-indexes.xml. La configuración automática de índices también se usa si la app no tiene un archivo datastore-indexes.xml.

Con la configuración automática de índices habilitada, el servidor de desarrollo conserva un archivo llamado WEB-INF/appengine-generated/datastore-indexes-auto.xml en el directorio war/ de la app. Cuando la app, que se ejecuta en el servidor de desarrollo, intenta realizar una consulta de Datastore para la que no existe un índice correspondiente en datastore-indexes.xml o datastore-indexes-auto.xml, el servidor agrega la configuración adecuada a datastore-indexes-auto.xml.

Si se habilita la configuración automática de índices cuando subes la aplicación, AppCfg usa datastore-indexes.xml y datastore-indexes-auto.xml a fin de determinar qué índices deben compilarse para tu app en producción.

Si autoGenerate="false" está en el datastore-indexes.xml, el servidor de desarrollo y AppCfg ignoran el contenido de datastore-indexes-auto.xml. Si la app que se ejecuta de forma local realiza una consulta cuyo índice no se especifica en datastore-indexes.xml, el servidor de desarrollo arroja una excepción, al igual que lo haría el Datastore de producción.

Es conveniente mover de manera ocasional la configuración de índices de datastore-indexes-auto.xml a datastore-indexes.xml, luego inhabilitar la configuración automática de índices y probar la app en el servidor de desarrollo. Esto facilita el mantenimiento de los índices sin la necesidad de administrar dos archivos, y te asegura de que la prueba reproducirá errores causados por la ausencia de la configuración de índices.

Crea índices de forma manual

Puedes agregar índices a tu archivo datastore-indexes.xml de forma manual o cambiar los índices que el servidor de desarrollo creó de manera automática en el archivo datastore-indexes-auto.xml a tu archivo datastore-indexes.xml.

Consulta la referencia de datastore-indexes.xml para obtener información sobre la sintaxis.

Actualiza índices

Cuando subes una aplicación mediante la acción update, la actualización incluye la configuración de índices de la app (los archivos datastore-indexes.xml y generated/datastore-indexes-auto.xml). Si la configuración del índice define un índice que no existe aún, App Engine creará el nuevo índice. Según la cantidad de datos que ya se encuentren en Datastore y que deban mencionarse en el índice nuevo, el proceso de creación del índice puede tardar un poco. Si la aplicación realiza una consulta que requiere de un índice que aún no se terminó de crear, la consulta devolverá una excepción.

Para evitar que esto ocurra, debes asegurarte de que la nueva versión de la aplicación que requiere de un índice no sea la versión publicada, hasta que los índices terminen de compilarse. Una forma de hacerlo es darle a la app un número de versión nuevo en appengine-web.xml cada vez que agregues o cambies un índice en la configuración. La aplicación se subirá como una nueva versión y no se vuelve la versión predeterminada de forma automática. Cuando tus índices hayan terminado de compilarse, podrás cambiar la versión predeterminada en Cloud Console.

Otra forma de garantizar que se creen índices nuevos antes de que la app nueva se publique es subir la configuración de índices por separado antes de subir la app. Para subir solo la configuración de índices de una app, usa la acción update_indexes:

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

El archivo datastore-indexes.xml debe estar en el directorio WEB-INF/ del módulo predeterminado.

En Cloud Console, puedes verificar el estado de los índices de la app.

Borra índices en desuso

Cuando cambias o quitas un índice de la configuración de índices, el índice original no se borra de App Engine de forma automática. Esto te permite mantener en ejecución una versión anterior de la app mientras que se crean los índices nuevos, o volver de inmediato a la versión anterior si surge un problema con una versión nueva.

Cuando estés seguro de que los índices anteriores ya no son necesarios, puedes borrarlos de App Engine con la acción vacuum_indexes:

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

Este comando borra todos los índices de la app que no se mencionan en las versiones locales de datastore-indexes.xml y WEB-INF/appengine-generated/datastore-indexes-auto.xml.