Configura índices de Datastore

Cloud Datastore utiliza í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 aplicación realiza una consulta. Para esto, Cloud Datastore debe saber con antelación qué consultas hará 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 Cloud Datastore de forma automática mientras pruebas tu app.

Cómo crear índices de Cloud Datastore

Puedes especificar la configuración de los índices de Cloud 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.

El siguiente es 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>

Cómo crear í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> de tu archivo WEB-INF/datastore-indexes.xml. La configuración automática de índices también se usa si tu app no cuenta con un archivo datastore-indexes.xml.

Con la configuración automática de índices habilitada, el servidor de desarrollo mantiene un archivo llamado WEB-INF/appengine-generated/datastore-indexes-auto.xml en el directorio war/ de tu app. Cuando tu aplicación, que se ejecuta en el servidor de desarrollo, hace una consulta de Cloud Datastore para la cual no existe un índice correspondiente en datastore-indexes.xml ni en datastore-indexes-auto.xml, el servidor agregará la configuración apropiada a datastore-indexes-auto.xml.

Si la configuración automática de índices está habilitada, cuando subas la aplicación, AppCfg usará datastore-indexes.xml y datastore-indexes-auto.xml a fines de determinar qué índices deben compilarse para tu aplicación en producción.

Si autoGenerate="false" está en tu datastore-indexes.xml, el servidor de desarrollo y AppCfg ignorarán el contenido de datastore-indexes-auto.xml. Si la aplicación que se ejecuta de forma local realiza una consulta cuyo índice no está especificado en datastore-indexes.xml, el servidor de desarrollo creará una excepción, como lo haría Cloud Datastore de producción.

Es una buena idea mover de forma ocasional la configuración de los índices de datastore-indexes-auto.xml a datastore-indexes.xml, luego inhabilitar la configuración automática de índices y probar tu 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.

Cómo crear índices de forma manual

Puedes agregar índices a tu archivo datastore-indexes.xml de forma manual o puedes modificar índices que el servidor de desarrollo haya creado automáticamente en el archivo datastore-indexes-auto.xml dentro de tu archivo datastore-indexes.xml.

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

Cómo actualizar índices

Cuando subes una aplicación a través de la acción update, la actualización incluye la configuración del índice de la aplicación (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. El proceso de crear un nuevo índice puede prolongarse según la cantidad de datos que se encuentren en Cloud Datastore que necesiten mencionarse en el nuevo índice. 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 hacer esto es dándole a la aplicación un nuevo número de versión en appengine-web.xml cada vez que cambies o agregues 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 terminen de compilarse, podrás cambiar la versión predeterminada en GCP Console.

Otra forma de asegurarse de que los nuevos índices se compilen antes de que la nueva aplicación se publique es subir la configuración del índice por separado antes de subir la aplicación. Si solo deseas subir la configuración del índice para una aplicación, usa la acción update_indexes:

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

El archivo datastore-indexes.xml debería encontrarse en el módulo predeterminado del directorio WEB-INF/.

En GCP Console, puedes verificar el estado de los índices de la aplicación.

Cómo borrar í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.

Una vez que estés seguro de que los índices anteriores no se necesitan, puedes borrarlos desde App Engine a través de 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.