Configurar índices de Datastore con index.yaml

Puedes usar Firestore en el modo de Datastore (Datastore) para almacenar datos de las aplicaciones que se ejecutan en el entorno estándar. Datastore usa índices para cada consulta que hace tu aplicación. Estos índices se actualizan cada vez que cambia una entidad, por lo que los resultados se pueden devolver rápidamente cuando la aplicación hace una consulta. Para ello, Datastore debe saber de antemano qué consultas hará la aplicación. En un archivo de configuración index.yaml, especifica los índices que necesita tu aplicación. Puedes usar el emulador de Datastore para generar el archivo automáticamente mientras pruebas tu aplicación o escribir el archivo tú mismo. El archivo index.yaml se debe subir al implementar la aplicación.

Acerca de index.yaml

Cada consulta de Datastore que realiza una aplicación necesita un índice correspondiente. Los índices de consultas sencillas, como las consultas sobre una sola propiedad, se crean automáticamente. Los índices de las consultas complejas deben definirse en un archivo de configuración llamado index.yaml. Este archivo se sube con la aplicación para crear índices en Datastore.

A continuación, se muestra un ejemplo de un archivo index.yaml:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

La sintaxis de index.yaml es el formato YAML. Para obtener más información sobre esta sintaxis, consulta el sitio web de YAML.

Definiciones de índices

index.yaml tiene un solo elemento de lista llamado indexes. Cada elemento de la lista representa un índice de la aplicación.

Un elemento de índice puede contener los siguientes elementos:

kind
El tipo de entidad de la consulta. Debe ser el argumento kind que se le da a datastore.NewKey al crear la entidad. Este elemento es obligatorio.
properties

Lista de propiedades que se incluirán como columnas del índice, en el orden en el que se van a ordenar: primero, las propiedades usadas en los filtros de igualdad; después, la propiedad usada en los filtros de desigualdad; y, por último, los criterios de ordenación y sus direcciones.

Cada elemento de esta lista incluye los siguientes elementos:

name
Nombre de la propiedad en el almacén de datos.
direction
Orden en que se muestran los resultados. Puede ser asc (ascendente) o desc (descendente). Este elemento solo es necesario en caso de las propiedades que se utilizan en las órdenes de clasificación de la consulta y debe coincidir con la dirección utilizada por la consulta. El valor predeterminado es asc.
ancestor

yes si la consulta tiene una cláusula de ancestro (Query.Ancestor). El valor predeterminado es no.

Crear archivos de índice

Puede crear un archivo de índice manualmente con un editor de texto y siguiendo el diseño de archivo descrito anteriormente. Una forma más eficiente es generar el archivo automáticamente mientras pruebas la aplicación de forma local. Puedes combinar ambos métodos.

Cuando hagas pruebas en tu entorno local, puedes usar el comando gcloud emulator para iniciar un servicio que emule Datastore antes de ejecutar tu aplicación:

gcloud beta emulators datastore start --data-dir DATA-DIR

Usa la marca --data-dir para especificar el directorio en el que aparecerá el archivo index.yamlgenerado automáticamente.

Mientras pruebas tu aplicación, cada vez que generas una consulta de Datastore, el emulador añade una definición de índice generada a index.yaml. Todas las definiciones de índice generadas automáticamente aparecerán en el archivo debajo de la siguiente línea:

# AUTOGENERATED

Todas las definiciones de índice que se encuentren por encima de esta línea se considerarán bajo control manual y no se actualizarán mediante el servidor web de desarrollo. El servidor web solo hará cambios por debajo de la línea y solo lo hará si el archivo index.yaml completo no describe un índice que tenga en cuenta una consulta ejecutada por la aplicación. Para tomar el control de una definición de índice automático, muévala por encima de esta línea.

El emulador puede actualizar las definiciones que haya debajo de esta línea a medida que la aplicación haga consultas. Si la aplicación genera todas las consultas que hará mientras la pruebas, las entradas generadas en index.yaml estarán completas. Es posible que tengas que editar el archivo manualmente para eliminar los índices que no se usen en producción o para definir los índices que no se hayan creado durante las pruebas.

Desplegar el archivo de configuración del índice

Para desplegar el archivo de configuración index.yaml, ejecuta el siguiente comando:

gcloud app deploy index.yaml

Eliminar los índices que no se usan

Cuando cambias o quitas un índice de la configuración de índices, el índice original no se elimina automáticamente de App Engine. De esta forma, tienes la oportunidad de dejar una versión anterior de la aplicación en ejecución mientras se crean nuevos índices o de volver a la versión anterior inmediatamente si se detecta un problema con una versión más reciente.

Cuando tengas la certeza de que ya no necesitas los índices antiguos, puedes eliminarlos de App Engine de la siguiente manera:

gcloud datastore indexes cleanup index.yaml