Configuração do índice composto

O Firestore no modo Datastore usa índices para cada consulta que a sua aplicação faz. Estes índices são atualizados sempre que uma entidade é alterada, pelo que os resultados podem ser devolvidos rapidamente quando a aplicação faz uma consulta. O modo Datastore fornece índices incorporados automaticamente, mas precisa de saber antecipadamente que índices compostos a aplicação vai precisar. Especifica os índices compostos de que a sua aplicação precisa num ficheiro de configuração. O emulador do Datastore pode gerar automaticamente a configuração do índice composto do modo Datastore à medida que testa a sua aplicação. A ferramenta de linha de comandos gcloud fornece comandos para atualizar os índices disponíveis para a sua base de dados do modo Datastore de produção.

Requisitos de sistema

Para usar a CLI gcloud, tem de ter instalado a CLI Google Cloud.

Acerca do index.yaml

Cada consulta do modo Datastore feita por uma aplicação precisa de um índice correspondente. Os índices para consultas simples, como consultas sobre uma única propriedade, são criados automaticamente. Os índices compostos para consultas complexas têm de ser definidos num ficheiro de configuração denominado index.yaml. Este ficheiro é carregado com a aplicação para criar índices compostos numa base de dados do modo Datastore.

O emulador do Datastore adiciona automaticamente itens a este ficheiro quando a aplicação tenta executar uma consulta que precisa de um índice composto que não tenha uma entrada adequada no ficheiro de configuração. Pode ajustar os índices compostos ou criar novos manualmente editando o ficheiro. O index.yaml está localizado na pasta <project-directory>/WEB-INF/. Por predefinição, o diretório de dados que contém WEB-INF/appengine-generated/index.yaml é ~/.config/gcloud/emulators/datastore/. Consulte o artigo Diretórios do projeto do emulador do Datastore para ver detalhes adicionais.

Segue-se um exemplo de um ficheiro 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

A sintaxe de index.yaml está no formato YAML. Para mais informações sobre esta sintaxe, consulte o Website do YAML.

Definições do índice composto

index.yaml tem um único elemento de lista denominado indexes. Cada elemento na lista representa um índice composto para a aplicação.

Um elemento de índice pode ter os seguintes elementos:

kind

O tipo de entidade da consulta. Este elemento é obrigatório.

properties

Uma lista de propriedades a incluir como colunas do índice composto, na ordem em que devem ser ordenadas: propriedades usadas primeiro em filtros de igualdade, seguidas da propriedade usada em filtros de desigualdade e, em seguida, as ordens de ordenação e as respetivas direções.

Cada elemento nesta lista tem os seguintes elementos:

name

O nome do modo Datastore da propriedade.

direction

A direção da ordenação, asc para ascendente ou desc para descendente. Isto só é necessário para propriedades usadas em ordens de classificação da consulta e tem de corresponder à direção usada pela consulta. A predefinição é asc.

ancestor

yes se a consulta tiver uma cláusula de antepassado. A predefinição é no.

Índices compostos automáticos e manuais

Quando o emulador do Datastore adiciona uma definição de índice composto gerada a index.yaml, fá-lo abaixo da seguinte linha, inserindo-a, se necessário:

# AUTOGENERATED

O emulador considera todas as definições de índice composto abaixo desta linha como automáticas e pode atualizar as definições existentes abaixo desta linha à medida que a aplicação faz consultas.

Todas as definições de índice composto acima desta linha são consideradas sob controlo manual e não são atualizadas pelo emulador. O emulador só faz alterações abaixo da linha e só o faz se o ficheiro index.yaml completo não descrever um índice composto que tenha em conta uma consulta executada pela aplicação. Para assumir o controlo de uma definição de índice composto automático, mova-a acima desta linha.

Atualizar índices compostos

O comando datastore indexes create analisa a configuração do índice composto do Datastore local (o ficheiro index.yaml) e, se a configuração do índice composto definir um índice composto que ainda não exista na base de dados do modo Datastore de produção, a base de dados cria o novo índice composto. Consulte o fluxo de trabalho de desenvolvimento com a CLI gcloud para ver um exemplo de como usar indexes create.

Para criar um índice composto, a base de dados tem de configurar o índice composto e, em seguida, preencher o índice composto com dados existentes. O tempo de criação do índice composto é a soma do tempo de configuração e do tempo de preenchimento:

• A configuração de um índice composto demora alguns minutos. O tempo mínimo de criação de um índice composto é de alguns minutos, mesmo para uma base de dados vazia.

• O tempo de preenchimento depende da quantidade de dados existentes que pertencem ao novo índice composto. Quanto mais valores de propriedades pertencerem ao índice composto, mais tempo demora a preencher o índice composto.

Se a aplicação executar uma consulta que exija um índice composto que ainda não tenha sido criado, a consulta gera uma exceção. Para evitar esta situação, tem de ter cuidado ao implementar uma nova versão da sua aplicação que exija um índice composto antes de o novo índice composto terminar a criação.

Pode verificar o estado dos índices compostos na página Índices na Google Cloud consola.

Eliminar índices compostos não usados

Quando altera ou remove um índice composto da configuração do índice composto, o índice composto original não é eliminado automaticamente da base de dados do modo Datastore. Isto dá-lhe a oportunidade de deixar uma versão mais antiga da aplicação em execução enquanto os novos índices compostos estão a ser criados ou de reverter imediatamente para a versão mais antiga se for detetado um problema com uma versão mais recente.

Quando tiver a certeza de que já não precisa dos índices compostos antigos, pode eliminá-los com o comando datastore indexes cleanup. Este comando elimina todos os índices compostos da instância do modo Datastore de produção que não são mencionados na versão local de index.yaml. Consulte o fluxo de trabalho de desenvolvimento com a CLI gcloud para ver um exemplo de como usar indexes cleanup.

Argumentos da linha de comandos

Para ver detalhes sobre argumentos de linha de comandos para criar e limpar índices compostos, consulte datastore indexes create e datastore indexes cleanup, respetivamente. Para ver detalhes sobre os argumentos de linha de comandos para a CLI gcloud, consulte a referência da CLI gcloud.

Gerir operações de longa duração

As compilações de índices compostos são operações de longa duração e podem demorar um período considerável a serem concluídas.

Depois de iniciar uma compilação de índice composto, o modo Datastore atribui um nome exclusivo à operação. Os nomes das operações têm o prefixo projects/[PROJECT_ID]/databases/(default)/operations/, por exemplo:

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

No entanto, pode omitir o prefixo quando especificar um nome de operação para o comando describe.

Listar todas as operações de longa duração

Para listar operações de longa duração, use o comando gcloud datastore operations list. Este comando apresenta as operações em curso e concluídas recentemente. As operações são apresentadas durante alguns dias após a conclusão:

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 exemplo, uma compilação de índice composto concluída recentemente mostra as seguintes informações:

{
  "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"
    }
  },
  ]
}

Descrever uma única operação

Em vez de listar todas as operações de longa duração, pode listar os detalhes de uma única operação:

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

Estimar o tempo de conclusão

À medida que a operação é executada, veja o valor do campo state para o estado geral da operação.

Um pedido do estado de uma operação de longa duração também devolve as métricas workEstimated e workCompleted. Estas métricas são devolvidas para o número de entidades. workEstimated mostra o número total estimado de entidades que uma operação vai processar, com base nas estatísticas da base de dados. workCompleted mostra o número de entidades processadas até agora. Após a conclusão da operação, workCompleted reflete o número total de entidades que foram realmente processadas, o que pode ser diferente do valor de workEstimated.

Divida workCompleted por workEstimated para uma estimativa aproximada do progresso. A estimativa pode ser imprecisa porque depende da recolha de estatísticas atrasadas.

Por exemplo, segue-se o estado de progresso de uma compilação de índice composto:

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

Quando uma operação estiver concluída, a descrição da operação contém "done": true. Consulte o valor do campo state para ver o resultado da operação. Se o campo done não estiver definido na resposta, o respetivo valor é false. Não dependa da existência do valor done para operações em curso.