Configurar índices do Datastore com index.yaml

Use o Firestore no modo Datastore (Datastore) para armazenar dados dos seus aplicativos executados no ambiente flexível. O Datastore usa índices para todas as consultas feitas pelo seu aplicativo. Esses índices são atualizados sempre que uma entidade sofre alterações para que os resultados sejam retornados com rapidez quando o aplicativo fizer uma consulta. Para isso, o Datastore precisa saber, com antecedência, quais consultas serão realizadas. Especifique os índices necessários para o aplicativo em um arquivo de configuração index.yaml. O emulador do Datastore pode ser usado para gerar o arquivo automaticamente durante a fase de testes do aplicativo. Se preferir, você mesmo pode gravar o arquivo. O arquivo index.yaml precisa ser enviado quando você implantar o aplicativo.

Amostra index.yaml

Todas as consultas ao Datastore realizadas por um aplicativo precisam de um índice correspondente. Os índices de consultas simples, como os de propriedade única, são criados automaticamente. Já os índices para consultas complexas precisam ser definidos em um arquivo de configuração chamado index.yaml. Esse arquivo é transferido com o aplicativo para criar índices no Datastore.

Veja abaixo um exemplo de arquivo index.yaml:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

A sintaxe de index.yaml é o formato YAML. Para saber mais sobre ela, consulte o site do YAML.

Definições de índice

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

Um elemento de índice pode ter os seguintes elementos:

kind
Obrigatório. O tipo da entidade da consulta.
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 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 precisa corresponder à direção usada pela consulta. O padrão é asc.

ancestor

Criar arquivos de índice

Crie um arquivo de índices manualmente. Para isso, basta usar um editor de texto e seguir o layout do arquivo descrito acima. No entanto, a abordagem mais eficiente é gerar o arquivo automaticamente enquanto você estiver testando localmente o app. É possível combinar os dois métodos.

Ao testar no ambiente local, use o comando do emulador gcloud para iniciar um serviço que emula o Datastore antes de executar o aplicativo:

gcloud beta emulators datastore start --data-dir DATA-DIR

Use a sinalização --data-dir para especificar o diretório em que o arquivo index.yaml gerado automaticamente será exibido.

À medida que você testa seu aplicativo, cada vez que uma consulta do Datastore é realizada, o emulador adiciona uma definição de índice gerada para index.yaml. Todas as definições de índice geradas automaticamente aparecerão no arquivo abaixo da seguinte linha:

# AUTOGENERATED

Todas as definições de índice acima dessa linha são consideradas sob controle manual e não são atualizadas servidor da Web de desenvolvimento. O servidor da Web fará alterações somente abaixo da linha e apenas se o arquivo index.yaml completo não descrever um índice responsável por uma consulta executada pelo aplicativo. Para assumir o controle de uma definição de índice automática, mova-a para acima dessa linha.

O emulador pode atualizar as definições abaixo dessa linha, à medida que o aplicativo faz consultas. Se o aplicativo gerar todas as consultas que serão feitas durante o teste, as entradas geradas em index.yaml serão concluídas. Talvez seja necessário editar o arquivo manualmente para excluir os índices que não são usados na produção ou para definir índices que não foram criados durante os testes.

Implantar o arquivo de configuração de índice

Para implantar o arquivo de configuração index.yaml, execute o seguinte comando:

gcloud app deploy index.yaml

Excluir índices não utilizados

Quando você altera ou remove um índice da configuração do índice, o original não é excluído do App Engine automaticamente. Isso permite que você deixe uma versão mais antiga do aplicativo em execução enquanto novos índices são criados ou reverta para a versão mais antiga imediatamente se um problema for descoberto na nova versão.

Quando tiver certeza de que os índices antigos não são mais necessários, será possível excluí-los do App Engine da seguinte maneira:

gcloud datastore indexes cleanup index.yaml