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 automáticamente mientras pruebas tu y mantener la integridad de su 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 una configuración llamado index.yaml. Este archivo se sube con la aplicación para crear los í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 que no tenga un una entrada adecuada en el archivo de configuración. Puedes ajustar los índices compuestos o crear a los nuevos manualmente editando 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 list 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 propiedades para incluir como columnas del índice compuesto, en el orden en que deben ordenado: las propiedades que se usan primero en los filtros de igualdad y, luego, la propiedad utilizada en filtros de desigualdad, luego 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, que se 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ático y es posible que actualice las definiciones existentes que se encuentran debajo de esta línea a medida que la aplicación realiza consultas.

Se considera que todas las definiciones de índices compuestos que se encuentran por encima de esta línea están bajo control manual. y el emulador no las actualiza. El emulador solo realiza cambios debajo de la línea, y solo lo hará si se completa el index.yaml no describe un índice compuesto que represente una consulta ejecutada por el y mantener la integridad de su aplicación. Para tomar el control de una definición automática de índice compuesto, colócala en la parte superior esta línea.

Actualiza índices compuestos

El comando datastore indexes create examina tu índice compuesto de Datastore local. del índice (el archivo index.yaml) y si la configuración del índice compuesto define una índice compuesto que todavía no existe en tu base de datos de producción en modo Datastore, crea el índice compuesto nuevo. 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. La hora de creación del índice compuesto es la suma de la configuración y el tiempo de reabastecimiento:

• Configurar un índice compuesto tarda unos minutos. La cantidad mínima de tiempo de 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 que pertenecen al nuevo índice compuesto. El cuantos más valores de propiedad pertenezcan al índice compuesto, más tiempo llevará reabastecer el índice compuesto.

Si la aplicación realiza una consulta que requiere un índice compuesto que no ha finalizado compilando aún, la consulta genera una excepción. Para evitar esto, debes ten cuidado con la implementación de una versión nueva de tu aplicación que requiera índice compuesto antes de que termine de crearse el nuevo índice compuesto.

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

Borra índices compuestos sin usar

Cuando cambias o quitas un índice compuesto de su configuración, el El índice compuesto no se borra automáticamente de la base de datos en modo Datastore. Esto te da la de mantener en ejecución una versión anterior de la aplicación mientras se ejecutan los índices compuestos o volver de inmediato a la versión anterior si se produce descubierto con una versión más reciente.

Cuando tengas la certeza de que los índices compuestos anteriores ya no son necesarios, puedes borrarlos con el comando datastore indexes cleanup. Este comando Borra todos los índices compuestos para la instancia de producción en modo Datastore que no se mencionan. en la versión local de index.yaml. Consulta el flujo de trabajo de desarrollo con gcloud CLI para ver un ejemplo de cómo usa 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. Para obtener detalles sobre los argumentos de la línea de comandos para gcloud CLI, consulta la referencia de gcloud CLI.

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 la compilación de un índice compuesto, el modo Datastore asigna a la operación con 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 datastore operations list

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

Por ejemplo, una compilación de índice compuesto recientemente completada 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 datastore operations describe operation-name

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

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.