Como configurar índices do Datastore com index.yaml

Use o Firestore no modo Datastore (Datastore) para armazenar dados dos seus aplicativos executados no ambiente padrão. 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 carregado quando você implanta seu aplicativo.

Sobre 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
O tipo da entidade da consulta. Normalmente, esse é o nome da classe Model que define o modelo das entidades. Esse 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 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

yes se a consulta tiver uma cláusula ancestral (Query.ancestor() ou uma cláusula GQL ANCESTOR IS). O padrão é no.

Como criar arquivos de índices

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.

Como implantar o arquivo de configuração do índice

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

gcloud app deploy index.yaml

Como 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