Configuração de índice

O Cloud Firestore no modo Datastore usa índices para todas as consultas feitas pelo seu aplicativo. Esses índices são atualizados sempre que uma entidade muda. Dessa forma, os resultados podem ser retornados rapidamente quando o aplicativo realiza uma consulta. O modo Datastore fornece índices integrados automaticamente, mas precisa determinar com antecedência quais índices compostos o aplicativo necessitará. Especifique os índices compostos de que o aplicativo precisa em um arquivo de configuração. O emulador do Cloud Datastore pode gerar automaticamente a configuração de índice do modo Datastore enquanto você testa seu aplicativo. Com a ferramenta de linha de comando gcloud, são fornecidos comandos para atualizar os índices disponíveis na instância de produção do Cloud Datastore.

Requisitos do sistema

Para usar a ferramenta gcloud, você precisa ter instalado o SDK do Google Cloud.

Sobre o arquivo index.yaml

Todas as consultas do modo Datastore realizadas por um aplicativo precisam de um índice correspondente. Os índices de consultas simples, como as referentes a propriedades únicas, são criados automaticamente. Os índices de consultas complexas precisam ser definidos em um arquivo de configuração denominado index.yaml. Esse arquivo é carregado com o aplicativo para criar índices em um banco de dados do modo Datastore.

O emulador do Cloud Datastore adiciona automaticamente itens a esse arquivo quando o aplicativo tenta executar uma consulta que precisa de um índice que não tem uma entrada apropriada no arquivo de configuração. Você pode ajustar os índices ou criar novos manualmente editando o arquivo. O arquivo index.yaml está na pasta <project-directory>/WEB-INF/. Por padrão, o diretório de dados que contém WEB-INF/appengine-generated/index.yaml é ~/.config/gcloud/emulators/datastore/. Para mais detalhes, consulte Diretórios de projeto do emulador do Cloud Datastore.

Este é um exemplo de arquivo 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 é o formato YAML. Para saber mais sobre essa sintaxe, consulte o site do YAML.

Definições de índice

index.yaml tem um único elemento de lista chamado indexes. Cada elemento de lista representa um índice do aplicativo.

Um elemento de índice pode ter os seguintes elementos:

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

Uma lista das propriedades a serem incluídas como colunas do índice, na ordem em que serão classificadas: propriedades usadas em filtros de igualdade primeiro, seguidas de propriedades usadas em filtros de desigualdade, e por fim as ordens de classificação e suas direções.

Cada elemento dessa lista tem os seguintes elementos:

name
O nome da propriedade no modo Datastore.
direction
A direção da classificação, asc para crescente ou desc para decrescente. Isso só é necessário para propriedades usadas nas ordens de classificação da consulta e deve corresponder à direção usada pela consulta. A padrão é asc.
ancestor

yes se a consulta tiver uma cláusula ancestral. A padrão é no.

Índices automáticos e manuais

Se o emulador do Cloud Datastore adicionar uma definição de índice gerada ao arquivo index.yaml, ele fará essa adição abaixo da linha a seguir e inserirá se necessário:

# AUTOGENERATED

O emulador considera todas as definições de índice abaixo dessa linha como automáticas e pode atualizá-las à medida que o aplicativo realiza consultas.

Todas as definições de índice acima dessa linha são consideradas sob controle manual e não são atualizadas pelo emulador. O emulador só efetuará alterações abaixo da linha, e apenas se o arquivo index.yaml completo não descrever um índice que se refira a uma consulta executada pelo aplicativo. Para assumir o controle de uma definição de índice automática, mova-a para cima dessa linha.

Como atualizar índices

O comando datastore indexes create examina a configuração de índice do Datastore local (o arquivo index.yaml) e, se ela definir um índice que ainda não existe no banco de dados do modo Datastore de produção, o banco de dados criará o novo índice. No fluxo de trabalho de desenvolvimento usando a ferramenta gcloud, é possível ver um exemplo de como utilizar indexes create.

Dependendo do volume de dados no banco de dados que pertence ao novo índice, o processo de criação do índice poderá levar algum tempo. Se o aplicativo executar uma consulta que precise de um índice que ainda não esteja totalmente criado, a consulta emitirá uma exceção. Para evitar que isso ocorra, tenha cautela ao implantar uma nova versão do aplicativo que necessite de um novo índice antes que o novo índice esteja finalizado.

Consulte a página Índices no Console do GCP para verificar o status dos índices.

Como excluir índices inutilizados

Quando você altera ou remove um índice da configuração, o índice original não é excluído automaticamente do banco de dados do modo Datastore. Você tem assim a oportunidade de manter uma versão antiga do aplicativo em execução enquanto os novos índices estão sendo criados, ou de reverter para a versão antiga imediatamente se for detectado algum problema na nova versão.

Quando tiver certeza de que os índices antigos não são mais necessários, use o comando datastore indexes cleanup para excluí-los. Esse comando remove todos os índices referentes à instância de produção do modo Datastore que não estejam mencionados na versão local de index.yaml. No fluxo de trabalho de desenvolvimento usando a ferramenta gcloud, é possível ver um exemplo de como utilizar indexes cleanup.

Argumentos de linha de comando

Para ver detalhes sobre argumentos de linha de comando para criar e limpar índices, consulte datastore indexes create e datastore indexes cleanup, respectivamente. Para saber mais sobre os argumentos de linha de comando para gcloud, consulte a referência da ferramenta gcloud.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud Datastore