Como configurar índices do Datastore

Quando acessado pelo App Engine, o Cloud Datastore usa índices para cada consulta que o aplicativo faz. 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 Cloud Datastore precisa saber com antecedência quais consultas o aplicativo realizará. Você especifica os índices de que o aplicativo precisa em um arquivo de configuração. O servidor de desenvolvimento pode gerar a configuração do índice do Cloud Datastore automaticamente enquanto você testa o aplicativo.

Como criar índices do Cloud Datastore

Especifique a configuração dos índices do Cloud Datastore em WEB-INF/datastore-indexes.xml, no diretório war/ do aplicativo.

Conforme descrito na página Índices do Datastore, um índice é uma tabela de valores que contém um conjunto de certas propriedades para entidades de um determinado tipo. Cada coluna de valores de propriedades é classificada em ordem crescente ou decrescente. A configuração de um índice especifica o tipo das entidades e os nomes das propriedades e suas ordens de classificação.

Veja a seguir um exemplo do datastore-indexes.xml que especifica dois índices:

<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes
  autoGenerate="true">
    <datastore-index kind="Employee" ancestor="false">
        <property name="lastName" direction="asc" />
        <property name="hireDate" direction="desc" />
    </datastore-index>
    <datastore-index kind="Project" ancestor="false">
        <property name="dueDate" direction="asc" />
        <property name="cost" direction="desc" />
    </datastore-index>
</datastore-indexes>

Como criar índices usando o servidor de desenvolvimento

O processo de determinação manual dos índices necessários para o aplicativo pode ser tedioso e sujeito a erros. Felizmente, o servidor de desenvolvimento pode determinar a configuração de índice para você. Para usar a configuração automática de índices, adicione o atributo autoGenerate="true" ao elemento WEB-INF/datastore-indexes.xml do arquivo <datastore-indexes>. A configuração de índices automáticos também é usada se seu aplicativo não tiver um arquivo datastore-indexes.xml.

Com a configuração automática de índices ativada, o servidor de desenvolvimento mantém um arquivo chamado WEB-INF/appengine-generated/datastore-indexes-auto.xml no diretório war/ do aplicativo. Quando o aplicativo, em execução no servidor de desenvolvimento, tenta uma consulta de armazenamento do Cloud Datastore que não tem um índice correspondente em datastore-indexes.xml ou datastore-indexes-auto.xml, o servidor adiciona a configuração apropriada a datastore-indexes-auto.xml.

Se a configuração automática de índices estiver ativada quando você fizer upload do aplicativo, o AppCfg usará datastore-indexes.xml e datastore-indexes-auto.xml para determinar quais índices precisam ser criados para o aplicativo na produção.

Se autoGenerate="false" estiver em seu datastore-indexes.xml, o servidor de desenvolvimento e o AppCfg ignorarão o conteúdo de datastore-indexes-auto.xml. Se o aplicativo em execução localmente executar uma consulta sem um índice especificado em datastore-indexes.xml, o servidor de desenvolvimento lançará uma exceção, assim como o Cloud Datastore de produção faria.

De vez em quando, é recomendável mover a configuração de índices de datastore-indexes-auto.xml para datastore-indexes.xml. Em seguida, desative a configuração automática do índice e teste o aplicativo no servidor de desenvolvimento. Isso torna mais fácil manter os índices sem a necessidade de gerenciar dois arquivos e garante que seus testes reproduzam os erros causados por índices sem configuração.

Como criar índices manualmente

Você pode adicionar índices ao arquivo datastore-indexes.xml manualmente ou mudar os índices que o servidor de desenvolvimento criou automaticamente no arquivo datastore-indexes-auto.xml em seu arquivo datastore-indexes.xml.

Para informações sobre sintaxe, consulte a referência de datastore-indexes.xml.

Como atualizar índices

Quando você faz upload de um aplicativo com a ação update, a atualização inclui a configuração do índice do aplicativo (os arquivos datastore-indexes.xml e generated/datastore-indexes-auto.xml). Se a configuração definir um índice que ainda não existe, o App Engine criará o novo índice. Dependendo do volume de dados existente no Cloud Datastore que precisa ser mencionado no novo índice, o processo de criação pode demorar um pouco. Se o aplicativo executar uma consulta que exige um índice que ainda está em fase de construção, a consulta emitirá uma exceção.

Para evitar isso, certifique-se de que a versão nova do aplicativo que exige um índice novo não é a versão ativa dele até que a criação dos índices seja concluída. Uma maneira de fazer isso é dar ao aplicativo um novo número de versão em appengine-web.xml sempre que você adicionar ou alterar um índice na configuração. O aplicativo é enviado como uma versão nova e não se torna a versão padrão automaticamente. Quando a criação dos índices for concluída, você poderá alterar a versão padrão no console do GCP.

Outra forma de garantir que os novos índices sejam criados antes que o novo aplicativo fique ativo é enviar a configuração do índice separadamente antes de enviar o aplicativo. Para fazer upload apenas da configuração de índice de um aplicativo, use a ação update_indexes:

./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war

O arquivo datastore-indexes.xml precisa estar no diretório WEB-INF/ do módulo padrão.

No console do GCP, você pode verificar o status dos índices do aplicativo.

Como excluir índices não usados

Quando você altera ou remove um índice da configuração, o índice original não é automaticamente excluído do App Engine. Assim, você pode deixar uma versão antiga do aplicativo em execução enquanto novos índices são criados ou pode reverter para a versão antiga imediatamente se for descoberto um problema com a nova versão.

Se você tiver certeza de que os índices antigos não são mais necessários, exclua-os do App Engine usando a ação vacuum_indexes:

./appengine-java-sdk/bin/appcfg.sh vacuum_indexes myapp/war

Esse comando exclui todos os índices do aplicativo que não são mencionados nas versões locais de datastore-indexes.xml e WEB-INF/appengine-generated/datastore-indexes-auto.xml.

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

Enviar comentários sobre…

Ambiente padrão do App Engine para Java 8