Configuración de índices compuestos

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 compuesto 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 gcloud CLI, debes tener instalada Google Cloud CLI.

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 compuestos para 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 compuestos 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 compuesto para el que no existe una entrada apropiada en el archivo de configuración. Puedes editar el archivo para ajustar los índices compuestos 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 usa el formato YAML. Para obtener más información sobre esta sintaxis, consulta el sitio web de YAML.

Definiciones de índices compuestos

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

Un índice puede tener los siguientes elementos:

kind
El tipo de entidad de la consulta. Este elemento es obligatorio.
properties

Una lista de las propiedades que se deben incluir como columnas del índice compuesto, 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 direcciones.

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 necesario para las propiedades que se usan en los órdenes de clasificación de la solicitud y debe coincidir con la dirección que usa la consulta. El valor predeterminado es asc.
ancestor

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

Índices compuestos automáticos y manuales

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

# AUTOGENERATED

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

Se considera que todas las definiciones de índices compuestos 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 compuesto que represente una consulta ejecutada por la aplicación. Para tomar control sobre una definición de índice compuesto automática, colócala por encima de esta línea.

Actualiza índices compuestos

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

Para crear un índice compuesto, la base de datos debe configurar el índice compuesto y, luego, reabastecerlo con los datos existentes. El tiempo de creación del índice compuesto es la suma del tiempo de configuración y el tiempo de reabastecimiento:

  • La configuración de un índice compuesto tarda unos minutos. El tiempo de creación mínimo de un índice compuesto es de unos minutos, incluso para una base de datos vacía.

  • El tiempo de reabastecimiento depende de la cantidad de datos existentes en el nuevo índice compuesto. Cuantos más valores de propiedad pertenezcan al índice compuesto, más tiempo tardará el reabastecimiento del índice compuesto.

Si la aplicación realiza una consulta que requiere un índice compuesto 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 compuesto antes de que este termine de crearse.

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

Cómo borrar índices compuestos sin usar

Cuando cambias o quitas un índice compuesto de la configuración de índices compuestos, el índice compuesto 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 compuestos 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 compuestos anteriores, puedes borrarlos con el comando datastore indexes cleanup. Este comando borra todos los índices compuestos 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 CLI de 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 compuestos, consulta los respectivos artículos datastore indexes create y datastore indexes cleanup. Para obtener más información sobre los argumentos de la línea de comandos de gcloud CLI, consulta gcloud CLI gcloud.

Administrar operaciones de larga duración

Las compilaciones de índices compuestos son operaciones de larga duración y pueden tardar bastante tiempo en completarse.

Después de iniciar una compilación de índice compuesto, el modo Datastore le asigna a la operación un nombre único. Los nombres de las operaciones incluyen el prefijo projects/[PROJECT_ID]/databases/(default)/operations/. Por ejemplo:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Sin embargo, puedes omitir el prefijo cuando especifiques el nombre de una operación para el comando describe.

Enumera todas las operaciones de larga duración

Para enumerar las operaciones de larga duración, usa el comando gcloud datastore operations list. Este comando enumera las operaciones en curso y las que se completaron recientemente. Las operaciones se enumeran durante algunos días luego de completarse:

gcloud

gcloud datastore operations list

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: El ID de tu proyecto

Método HTTP y URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Para enviar tu solicitud, expande una de estas opciones:

A continuación, verás información sobre la respuesta.

Por ejemplo, una compilación de índice compuesto completada recientemente muestra la siguiente información:

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

Describe una sola operación

En lugar de enumerar todas las operaciones de larga duración, puedes enumerar los detalles de una sola operación:

gcloud

Usa el comando operations describe para mostrar el estado de una compilación de índice compuesto.

gcloud datastore operations describe operation-name

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: El ID de tu proyecto

Método HTTP y URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Para enviar tu solicitud, expande una de estas opciones:

A continuación, verás información sobre la respuesta.

Estima la hora de finalización

A medida que se ejecuta tu operación, mira el valor del campo state para conocer el estado general.

Una solicitud del estado de una operación de larga duración también muestra las métricas workEstimated y workCompleted. Estas métricas se muestran para la cantidad de entidades. workEstimated muestra la cantidad total estimada de entidades que procesará una operación, según las estadísticas de base de datos. workCompleted muestra la cantidad de entidades procesadas hasta el momento. Una vez que se completa la operación, workCompleted refleja la cantidad total de documentos que se procesaron, que podría ser diferente del valor de workEstimated.

Divide workCompleted entre workEstimated para obtener una estimación aproximada del progreso. Es posible que la estimación sea inexacta, ya que depende de la demora en la recopilación de estadísticas.

Por ejemplo, este es el estado de progreso de una compilación de índice compuesto:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressEntities": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

Cuando se realiza una operación, su descripción contendrá "done": true. Consulta el valor del campo state para ver el resultado de la operación. Si el campo done no está establecido en la respuesta, su valor es false. No dependas de la existencia del valor done para las operaciones en curso.