Configuración de índices

Firestore en modo 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 aplicación realiza una consulta. El modo Datastore proporciona índices integrados de forma automática, pero necesita saber con anticipación qué índices compuestos requerirá la aplicación. Por eso, debes especificarlos en un archivo de configuración. El emulador de Datastore puede generar la configuración del índice del modo Datastore de forma automática mientras pruebas tu aplicación. La herramienta de línea de comandos de gcloud proporciona comandos a fin de actualizar los índices que están disponibles para tu base de datos de producción en modo Datastore.

Requisitos del sistema

Para usar la herramienta de gcloud, debes tener instalado el SDK de Google Cloud.

Acerca de index.yaml

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

El emulador de Datastore agrega elementos a este archivo de forma automática cuando la aplicación intenta ejecutar una consulta que requiere de un índice para el que no existe una entrada apropiada en el archivo de configuración. Puedes editar el archivo para ajustar los índices o crear nuevos de forma manual. index.yaml se encuentra en la carpeta <project-directory>/WEB-INF/. De forma predeterminada, el directorio de datos que contiene WEB-INF/appengine-generated/index.yaml es ~/.config/gcloud/emulators/datastore/. Consulta los directorios de proyectos del emulador de Datastore para obtener más información.

El siguiente es un ejemplo de un archivo index.yaml:

indexes:

    - kind: Task
      ancestor: no
      properties:
      - name: done
      - name: priority
        direction: desc

    - kind: Task
      properties:
      - name: collaborators
        direction: asc
      - name: created
        direction: desc

    - kind: TaskList
      ancestor: yes
      properties:
      - name: percent_complete
        direction: asc
      - name: type
        direction: asc
    

La sintaxis de index.yaml tiene 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 la lista llamado indexes. Cada elemento de la lista representa un índice de la aplicación.

Un índice puede tener los siguientes elementos:

kind
El tipo de entidad de la consulta. Se requiere este elemento.
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 modo Datastore de la propiedad.
direction
La dirección 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

yes si la consulta tiene una cláusula principal. El valor predeterminado es no.

Índices automáticos y manuales

Cuando el emulador de Datastore agrega una definición de índice generado a index.yaml, lo hace debajo de la línea siguiente y la inserta si es necesario:

# AUTOGENERATED
    

El emulador considera que todas las definiciones de índices debajo de esta línea son automáticas y es posible que las actualice a medida que la aplicación realiza consultas.

Se considera que todas las definiciones de índices ubicadas por encima de esta línea son de control manual, por lo que el emulador no las actualiza. El emulador solo realizará cambios debajo de la línea y solo lo hará si el archivo index.yaml completo no describe un índice que represente una consulta ejecutada por la aplicación. Para tomar control sobre una definición de índice automática, colócala por encima de esta línea.

Actualiza índices

El comando datastore indexes create revisa la configuración del índice de Datastore local (el archivo index.yaml). Si la configuración define un índice que aún no existe en la base de datos de producción en modo Datastore, tu base de datos crea el índice nuevo. Consulta el flujo de trabajo de desarrollo con la herramienta gcloud para ver un ejemplo de cómo usar indexes create.

Según la cantidad de datos que haya en tu base de datos pertenecientes al índice nuevo, el proceso de creación del índice puede llevar un tiempo. Si la aplicación realiza una consulta que requiere un índice que aún no se terminó de crear, la consulta generará una excepción. Para evitar que esto ocurra, debes tener cuidado cuando implementes una versión nueva de tu aplicación que requiera de un índice nuevo antes de que este termine de compilarse.

Puedes verificar el estado de los índices desde la página Índices en Cloud Console.

Borra índices en desuso

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

Cuando tengas la seguridad de que ya no se necesitan los índices antiguos, puedes borrarlos con el comando datastore indexes cleanup. Este comando borra todos los índices para la instancia en modo Datastore de producción que no se mencionan en la versión local de index.yaml. Consulta el flujo de trabajo de desarrollo con la herramienta gcloud para ver un ejemplo de cómo usar indexes cleanup.

Argumentos de la línea de comandos

Si deseas obtener detalles sobre los argumentos de la línea de comandos para crear y limpiar índices, consulta los respectivos artículos datastore indexes create y datastore indexes cleanup. A fin de obtener detalles sobre los argumentos de la línea de comandos para la herramienta de gcloud, consulta la referencia de herramienta de gcloud.