Configuración de índice compuesto

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 de í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 instalado 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 las consultas complejas se deben definir en un archivo de configuración llamado 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 automáticamente cuando la aplicación intenta ejecutar una consulta que necesita un índice compuesto sin una entrada apropiada en el archivo de configuración. Para ajustar los índices compuestos o crear nuevos de forma manual, edita el archivo. 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 para la aplicación.

Un índice puede tener los elementos siguientes:

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

Una lista de las propiedades que se incluirán como columnas del índice compuesto, en el orden de clasificación: 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 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, que inserta si es necesario:

# AUTOGENERATED

El emulador considera que todas las definiciones de índices compuestos que se encuentran 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 que están 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 si en el archivo index.yaml completo no se describe un índice compuesto que represente una consulta que haya ejecutado 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 analiza la configuración del índice compuesto de Datastore local (el archivo index.yaml) y, si la configuración del índice compuesto 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 nuevo índice compuesto. Consulta el flujo de trabajo de desarrollo con gcloud CLI 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, reabastecer el índice compuesto con los datos existentes. El tiempo de creación de índices compuestos es la suma del tiempo de configuración y el tiempo de reabastecimiento:

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

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

Si la aplicación realiza una consulta que requiere un índice compuesto que aún no se terminó de compilar, la consulta genera una excepción. Para evitar que esto suceda, debes tener cuidado cuando implementes una versión nueva de tu aplicación que requiera un índice compuesto antes de que el índice compuesto nuevo termine de compilarse.

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

Borra índices compuestos sin usar

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

Cuando estés seguro de que ya no necesitas los índices compuestos antiguos, puedes borrarlos con el comando datastore indexes cleanup. Este comando borra todos los índices compuestos de la instancia de producción en modo Datastore que no se mencionen 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 quieres obtener detalles sobre los argumentos de la línea de comandos para crear y limpiar índices compuestos, consulta datastore indexes create y datastore indexes cleanup, respectivamente. Si deseas obtener detalles sobre los argumentos de la línea de comandos para gcloud CLI, consulta la referencia de 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 un í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

HTTP method and 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 la compilación de un í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

HTTP method and 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 la compilación de un í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.