Como configurar índices do armazenamento de dados

O armazenamento de dados acessado pelo Google App Engine usa índices para cada consulta feita 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 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 de índice do armazenamento de dados automaticamente à medida que você testa seu aplicativo.

Como criar índices do armazenamento de dados

Você especifica a configuração de índice do armazenamento de dados em WEB-INF/datastore-indexes.xml, no diretório war/ de seu 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 de 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 seu arquivo <datastore-indexes>. A configuração automática de índices também é usada caso seu aplicativo não tenha um arquivo datastore-indexes.xml.

Com a configuração automática de índice ativada, o servidor de desenvolvimento mantém um arquivo chamado WEB-INF/appengine-generated/datastore-indexes-auto.xml no diretório war/ de seu aplicativo. Quando seu aplicativo, em execução no servidor de desenvolvimento, tenta realizar uma consulta do armazenamento de dados para a qual não existe um índice correspondente em datastore-indexes.xml nem em datastore-indexes-auto.xml, o servidor adiciona a configuração adequada ao datastore-indexes-auto.xml.

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

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

É recomendável eventualmente passar a configuração de índice do datastore-indexes-auto.xmlpara o datastore-indexes.xml, desativar a configuração automática de índices e testar 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 seu arquivo datastore-indexes.xml manualmente ou pode deslocar índices que o servidor de desenvolvimento criou automaticamente no arquivo datastore-indexes-auto.xml para seu arquivo datastore-indexes.xml.

Consulte a referência de datastore-indexes.xml para informações de sintaxe.

Como atualizar índices

Ao enviar um aplicativo usando a ação update, a atualização inclui a configuração de í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 de quantos dados já estão no Datastore que precisam ser mencionados no novo índice, o processo de criação do índice 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 número novo de versão em appengine-web.xml sempre que 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 os índices terminarem de criar, você poderá alterar a versão padrão no Console do Cloud.

Outra maneira de garantir que novos índices sejam criados antes da ativação do novo aplicativo é fazer upload da configuração do índice separadamente antes de fazer o upload do 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 Cloud, você pode verificar o status dos índices do aplicativo.

Excluir índices inutilizados

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.

Quando 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.