Configurar índices do armazenamento de dados com index.yaml

Pode usar o Firestore no modo Datastore (Datastore) para armazenar dados para as suas aplicações executadas no ambiente padrão. O Datastore usa índices para cada consulta que a sua aplicação faz. Estes índices são atualizados sempre que uma entidade muda, pelo que os resultados podem ser devolvidos rapidamente quando a app faz uma consulta. Para tal, o Datastore tem de saber antecipadamente que consultas a aplicação vai fazer. Especifica os índices de que a sua app precisa num index.yamlficheiro de configuração. Pode usar o emulador do Datastore para gerar o ficheiro automaticamente à medida que testa a sua app ou escrever o ficheiro manualmente. O ficheiro index.yaml tem de ser carregado quando implementar a sua app.

Acerca de index.yaml

Todas as consultas do Datastore feitas por uma aplicação precisam de um índice correspondente. Os índices para consultas simples, como consultas sobre uma única propriedade, são criados automaticamente. Os índices 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 no Datastore.

Segue-se um exemplo de um ficheiro 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 está no formato YAML. Para mais informações sobre esta sintaxe, consulte o Website do YAML.

Definições de índices

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

Um elemento de índice pode ter os seguintes elementos:

kind
O tipo de entidade da consulta. Este deve ser o argumento kind fornecido a datastore.NewKey quando a entidade é criada. Este elemento é obrigatório.
properties

Uma lista de propriedades a incluir como colunas do índice, 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 arquivo de dados 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 ordenaçã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 predecessora (Query.Ancestor). A predefinição é no.

A criar ficheiros de índice

Pode criar um ficheiro de índice manualmente, usando um editor de texto e seguindo o esquema de ficheiro descrito acima. Uma abordagem mais eficiente consiste em gerar automaticamente o ficheiro à medida que testa a sua app localmente. Pode combinar os dois métodos.

Quando estiver a testar no seu ambiente local, pode usar o comando gcloud emulator para iniciar um serviço que emula o Datastore antes de executar a sua app:

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

Use a flag --data-dir para especificar o diretório onde o ficheiro index.yaml gerado automaticamente vai aparecer.

À medida que testa a sua app, sempre que gera uma consulta do Datastore, o emulador adiciona uma definição de índice gerada a index.yaml. Todas as definições de índice geradas automaticamente aparecem no ficheiro abaixo da seguinte linha:

# AUTOGENERATED

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

O emulador pode atualizar as definições existentes abaixo desta linha à medida que a aplicação faz consultas. Se a app gerar todas as consultas que vai fazer enquanto a testa, as entradas geradas em index.yaml vão estar completas. Pode ter de editar o ficheiro manualmente para eliminar índices que não são usados na produção ou para definir índices que não foram criados durante os testes.

Implementar o ficheiro de configuração do índice

Para implementar o ficheiro de configuração index.yaml, execute o seguinte comando:

gcloud app deploy index.yaml

Eliminar índices não usados

Quando altera ou remove um índice da configuração do índice, o índice original não é eliminado automaticamente do App Engine. Isto dá-lhe a oportunidade de deixar uma versão mais antiga da app em execução enquanto são criados novos índices 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 antigos, pode eliminá-los do App Engine da seguinte forma:

gcloud datastore indexes cleanup index.yaml