O armazenamento de dados do Google App Engine utiliza índices para cada consulta feita pelo aplicativo. Esses índices são atualizados sempre que uma entidade é alterada, de modo que os resultados possam ser retornados rapidamente quando o aplicativo realizar uma consulta. Para isso, o armazenamento de dados precisa saber com antecedência quais consultas o aplicativo fará. Os índices de que o aplicativo precisa são especificados por você em um arquivo de configuração. O servidor de desenvolvimento pode gerar automaticamente a configuração do índice do armazenamento de dados à medida que você testa o seu aplicativo.
A configuração dos índices de armazenamento de dados é especificada em um arquivo denominado datastore-indexes.xml, no diretório WEB-INF/ do WAR do seu aplicativo. Esse é um arquivo XML cujo elemento raiz é <datastore-indexes>. Ele contém nenhum ou mais de um elemento <datastore-index>, um para cada índice que o Google App Engine deve manter.
Como descrito em Consultas e índices, um índice é uma tabela de valores para um conjunto de determinadas propriedades de um determinado tipo de entidade. Cada coluna de valores da propriedade é classificada em ordem crescente ou decrescente. A configuração de um índice especifica o tipo das entidades e o nome das propriedades e das ordens de classificação.
O exemplo abaixo especifica dois índices:
|
<?xml version="1.0" encoding="utf-8"?>
<datastore-indexes
xmlns="http://appengine.google.com/ns/datastore-indexes/1.0"
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" />
</datastore-index>
</datastore-indexes>
O elemento <datastore-indexes> possui um atributo autoGenerate que controla se o arquivo deveria ser considerado juntamente com a configuração do índice gerada automaticamente. Consulte Como usar a configuração automática de índice abaixo.
Cada elemento <datastore-index> representa um índice. O atributo kind especifica o tipo da entidade para o índice. O atributo ancestor será true se o índice suportar uma consulta que filtra entidades pelo pai do grupo da entidade; caso contrário será false.
Os elementos <property> em um <datastore-index> representam as propriedades da entidade para o índice. O atributo name é o nome da propriedade e o atributo direction é a ordem de classificação, asc para crescente ou desc para decrescente. A ordem dos elementos da propriedade especifica a ordem no índice: as linhas são classificadas pela primeira propriedade, depois pela segunda e assim por diante.
Determinar manualmente os índices necessários para as consultas do seu aplicativo pode ser entediante e causar erros. Felizmente, o servidor de desenvolvimento pode determinar isso para você. Para usar a configuração automática do índice, adicione o atributo autoGenerate="true" ao elemento <datastore-indexes> do seu arquivo datastore-indexes.xml. A configuração automática do índice também é utilizada caso o seu aplicativo não tenha um arquivo datastore-indexes.xml.
Com a configuração automática do índice ativada, o servidor de desenvolvimento mantém um arquivo chamado datastore-indexes-auto.xml no diretório WEB-INF/appengine-generated/ do WAR do seu aplicativo. Quando o seu aplicativo sendo executado no servidor de desenvolvimento tenta fazer uma consulta no armazenamento de dados para a qual não há índice correspondente no datastore-indexes.xml ou no datastore-indexes-auto.xml, o servidor adiciona a configuração adequada ao datastore-indexes-auto.xml.
Se a configuração automática do índice estiver ativada durante o envio do seu aplicativo, o AppCfg usará o datastore-indexes.xml e o datastore-indexes-auto.xml para determinar quais índices precisam ser construídos para o seu aplicativo no Google App Engine.
Se autoGenerate="false" no seu datastore-indexes.xml, o servidor de desenvolvimento e o AppCfg ignoram o conteúdo de datastore-indexes-auto.xml Se o aplicativo sendo executado no servidor de desenvolvimento executar uma consulta cujo índice não esteja especificado em datastore-indexes.xml, o servidor de desenvolvimento gerará uma exceção, assim como o Google App Engine faria.
É uma boa ideia mover ocasionalmente a configuração do índice de datastore-indexes-auto.xml para datastore-indexes.xml, desativar a configuração automática do índice em seguida e testar o aplicativo no servidor de desenvolvimento. Isso facilita a manutenção dos índices sem ter que gerenciar dois arquivos e garante que os seus testes reproduzirão os erros causados pela falta de configuração do índice.