Configura índices de Datastore con index.yaml

Puedes usar Firestore en modo Datastore (Datastore) para almacenar datos de las aplicaciones que se ejecutan en el entorno estándar. Datastore usa índices para cada consulta que realiza tu aplicación. 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 necesita la app en un archivo de configuración index.yaml. Puedes usar el emulador de Datastore para generar el archivo de forma automática mientras pruebas la app o escribes el archivo. El archivo index.yaml debe subirse cuando se implementa la app.

Acerca de index.yaml

Cada consulta de Datastore que realiza una aplicación necesita un índice correspondiente. Los índices para las consultas simples, como las de una sola propiedad, se crean de manera automática. Los índices para las consultas complejas se deben definir en el archivo de configuración denominado index.yaml. Este archivo se sube con la aplicación para crear índices en Datastore.

El siguiente es 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 usa el formato YAML. Visita el sitio web de YAML para obtener más información sobre esta sintaxis.

Definiciones de índices

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

Un índice puede tener los elementos siguientes:

kind
La categoría de entidad de la consulta. Por lo general, este es el nombre de la clase Model que define el modelo para las entidades. Este elemento es obligatorio.
properties

Una lista de las propiedades que deben incluirse como columnas del índice, en el orden de clasificación deseado: primero, las propiedades de los filtros de igualdad; luego, las propiedades de los filtros de desigualdad; y por último, los órdenes de clasificación y sus sentidos.

Cada elemento de la lista se compone de los siguientes:

name
El nombre del almacén de datos de la propiedad.
direction
El sentido de la clasificación, que puede ser asc (ascendente) o desc (descendente). Esto solo es obligatorio en las propiedades que se utilizan en los órdenes de clasificación de la consulta y debe coincidir con el sentido que utiliza la consulta. El valor predeterminado es asc.
ancestor

Es yes si la consulta tiene una cláusula principal (Query.ancestor() o una cláusula GQL ANCESTOR IS). El valor predeterminado es no.

Crea archivos de índice

Puedes crear un archivo de índice de forma manual mediante un editor de texto con el diseño de archivo descrito con anterioridad. Un enfoque más eficiente es la generación automática del archivo mientras pruebas la app a nivel local. Puedes combinar los dos métodos.

Cuando realices pruebas en tu entorno local, podrás usar el comando del emulador de gcloud para iniciar un servicio que emule Datastore antes de ejecutar la app:

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.yaml generado de forma automática.

Cada vez que pruebas la app y generas una consulta de Datastore, el emulador agrega una definición de índice a index.yaml. Todas las definiciones de índice que se generaron de forma automática aparecerán en el archivo debajo de la siguiente línea:

# AUTOGENERATED

Se considera que todas las definiciones de índices ubicadas por encima de esta línea son de control manual, por lo que el servidor web de desarrollador no las actualiza. El servidor web solo modificará lo que esté por debajo de la línea y lo hará solo si el archivo index.yaml completo no describe un índice que corresponda a una consulta que ejecutó la aplicación. Para tomar control sobre una definición de índice automática, colócala por encima de esta línea.

El emulador puede actualizar las definiciones existentes que estén por debajo de esta línea mientras la aplicación realiza consultas. Si la app genera cada consulta que realizará mientras realizas pruebas con ella, las entradas generadas en index.yaml se completarán. Es posible que necesites editar el archivo de forma manual para borrar los índices que no se utilizan en la producción o definir los índices que no se crearon mientras se realizaban las pruebas.

Implementa el archivo de configuración de índices

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

gcloud app deploy index.yaml

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 manera automática. Esto te permite conservar una versión anterior de la aplicación para que se ejecute mientras los índices nuevos se compilan, o volver de inmediato a la versión anterior si se descubre un problema en la versión nueva.

Cuando sepas que ya no volverás a necesitar los índices anteriores, puedes borrarlos de App Engine de la manera siguiente:

gcloud datastore indexes cleanup index.yaml