App Engine からアクセスする Datastore では、アプリケーションからのすべてのクエリにインデックスが使用されます。インデックスはエンティティが変更されるたびに更新されるので、アプリからのクエリに対してすばやく結果を返すことができます。これを実現するには、アプリケーションからどのようなクエリが実行されるかを、Datastore 側であらかじめ把握しておく必要があります。アプリケーションで必要になるインデックスを構成ファイルで指定しておきます。開発用サーバーでは、アプリケーションをテストする際に、Datastore のインデックス構成が自動的に生成されます。
Datastore インデックスの作成
Datastore インデックスの構成は、アプリの war/ ディレクトリにある WEB-INF/datastore-indexes.xml で指定します。
Datastore インデックスのページで説明したように、インデックスとは、特定の種類のエンティティの特定のプロパティ セットの値のテーブルです。プロパティ値の各列は、昇順または降順に並べ替えられます。インデックスの構成では、エンティティの種類、プロパティの名前とそれらの並べ替え順を指定します。
2 つのインデックスを指定する datastore-indexes.xml の例を次に示します。
<?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>
開発用サーバーを使用してインデックスを作成する
アプリケーションのクエリで必要になるインデックスを手作業で設定すると、面倒なだけでなく間違えやすくなります。幸いなことに、開発用サーバーでは、インデックスを自動的に構成できます。自動インデックス構成を使用するには、属性 autoGenerate="true" を WEB-INF/datastore-indexes.xml ファイルの <datastore-indexes> 要素に追加します。自動インデックス構成は、アプリに datastore-indexes.xml ファイルがない場合にも使用します。
自動インデックス構成を有効にすると、開発用サーバーによって、WEB-INF/appengine-generated/datastore-indexes-auto.xml というファイルがアプリの war/ ディレクトリに保持されます。アプリが、開発サーバーで実行されているときに、Datastore クエリを試行し、これに対して対応するインデックスが datastore-indexes.xml と datastore-indexes-auto.xml のいずれにもない場合、サーバーによって、datastore-indexes-auto.xml に適切な構成が追加されます。
アプリケーションのアップロード時に自動インデックス構成が有効になっている場合は、AppCfg は datastore-indexes.xml と datastore-indexes-auto.xml の両方を使用して、本番環境でアプリに作成する必要があるインデックスを決定します。
autoGenerate="false" が datastore-indexes.xml に含まれている場合、開発用サーバーと AppCfg では datastore-indexes-auto.xml のコンテンツを無視します。datastore-indexes.xml にインデックスが指定されていないクエリが、ローカルで実行されているアプリによって実行されると、開発サーバーによって、本番環境の Datastore の場合と同様に、例外がスローされます。
たまに datastore-indexes-auto.xml から datastore-indexes.xml にインデックス構成を移動し、自動インデックス構成を無効にして、開発サーバーでアプリをテストすることをおすすめします。これにより、2 つのファイルを管理しなくてもインデックスを簡単に管理でき、さらにインデックスが構成されていない場合のエラーをテストで確実に再現できます。
インデックスを手動で作成する
datastore-indexes.xml ファイルにインデックスを手動で追加することも、datastore-indexes-auto.xml ファイルで開発用サーバーが自動的に作成したインデックスを、datastore-indexes.xml ファイルに移動することもできます。
構文については、datastore-indexes.xml リファレンスをご覧ください。
インデックスを更新する
update アクションを使用してアプリケーションをアップロードすると、アップデートにはアプリケーションのインデックス構成（datastore-indexes.xml および generated/datastore-indexes-auto.xml ファイル）が含まれます。インデックス構成でまだ存在しないインデックスを定義している場合、App Engine が新しいインデックスを作成します。新しいインデックスに含まれる必要がある Datastore にデータがすでにどの程度存在するかによって、インデックス作成のプロセスには相応の時間がかかります。まだ作成が完了していないインデックスを要求するクエリをアプリが実行すると、例外が発生します。
このエラーを回避するため、インデックスの作成が完了するまで、新しいインデックスを必要とするアプリの新しいバージョンをライブ バージョンにしないでください。これを行う 1 つの方法は、構成でインデックスを追加または変更するたびに、appengine-web.xml でアプリに新しいバージョン番号を設定することです。アプリは新しいバージョンとしてアップロードされますが、自動的にデフォルト バージョンにはなりません。インデックスの作成が完了すると、Cloud Console でデフォルト バージョンを変更できます。
新しいアプリを公開する前に新しいインデックスを作成するもう 1 つの方法は、アプリをアップロードする前にインデックス構成を個別にアップロードすることです。アプリのインデックス構成のみをアップロードするには、update_indexes アクションを使用します。
./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war
datastore-indexes.xml ファイルは、デフォルト モジュールの WEB-INF/ ディレクトリに配置する必要があります。
Cloud Console では、アプリのインデックスのステータスを確認できます。
使用されていないインデックスを削除する
インデックス構成でインデックスを変更または削除する場合は、元のインデックスは App Engine から自動的に削除されません。これにより、新しいインデックスを作成しながらアプリの古いバージョンを実行したり、新しいバージョンで問題が発見されたらすぐに古いバージョンを復元したりできます。
古いインデックスが不要になった場合は、vacuum_indexes アクションを使用して App Engine から削除できます。
./appengine-java-sdk/bin/appcfg.sh vacuum_indexes myapp/war
このコマンドは、datastore-indexes.xml および WEB-INF/appengine-generated/datastore-indexes-auto.xml のローカル バージョンに含まれていないアプリのインデックスをすべて削除します。