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 elementos siguientes:

kind
El tipo de entidad de la consulta. 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 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 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 puede 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.

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

  • La configuración de un índice tarda unos minutos. El tiempo de creación mínimo de un índice 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 índice nuevo. Cuantos más valores de propiedad pertenezcan al índice, más tiempo tardará el reabastecimiento del índice.

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 antes de que el índice nuevo termine de crearse.

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 que 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.

Administrar operaciones de larga duración

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

Después de iniciar una compilación de índice, 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 siguientes, realiza los siguientes reemplazos:

  • project-id: Es 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 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.

gcloud datastore operations describe operation-name

rest

Antes de usar cualquiera de los datos de solicitud siguientes, realiza los siguientes reemplazos:

  • project-id: Es 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:

{
  "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.