index.yaml リファレンス

Datastore モードの Firestore（Datastore）を使用すると、スタンダード環境で稼働しているアプリケーション用のデータを保存できます。Datastore では、アプリケーションからのすべてのクエリにインデックスが使用されます。インデックスはエンティティが変更されるたびに更新されるので、アプリからのクエリに対してすばやく結果を返すことができます。これを実現するには、アプリケーションからどのようなクエリが実行されるかを、Datastore 側であらかじめ把握しておく必要があります。アプリケーションで必要になるインデックスを index.yaml 構成ファイルで指定しておきます。このファイルは、Datastore エミュレータを使用して、アプリをテストする際に自動生成できます。また、自分で記述することもできます。index.yaml ファイルは、アプリをデプロイする際にアップロードする必要があります。

index.yaml の概要

アプリケーションが実行するすべての Datastore クエリには、対応するインデックスが必要です。単純なクエリ用のインデックス（1 つのプロパティに関するクエリなど）は自動的に作成されます。複雑なクエリ用のインデックスは、index.yaml という構成ファイルで定義する必要があります。このファイルはアプリケーションとともにアップロードされ、Datastore にインデックスを作成します。

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

index.yaml の構文は YAML 形式です。この構文の詳細については、YAML のウェブサイトをご覧ください。

インデックスの定義

index.yaml には、indexes という名前のリスト要素が 1 つだけあります。このリストに含まれる各要素は、アプリケーションのインデックスを表します。

インデックス要素には、次のような要素があります。

kind
クエリに対応するエンティティの種類です。通常、これは、エンティティのモデルを定義するモデルクラスの名前です。この要素は必須です。
properties

インデックスの列として組み込むプロパティのリストです。まず、等式フィルタで使用するプロパティ、次に不等式フィルタで使用するプロパティの順に整理してから、並べ替え順序とその方向を指定します。

このリスト内の各要素には、次の要素を指定します。

name
プロパティのデータストア名です。
direction
並べ替えの方向です。昇順の場合は asc を指定し、降順の場合は desc を指定します。この値は、クエリの並べ替え順序で使用するプロパティについてのみ必要です。また、クエリで使用する方向と同じである必要があります。デフォルトは asc です。
ancestor

クエリに祖先句（Query.ancestor() または GQL ANCESTOR IS）がある場合は yes です。デフォルトは no です。

インデックス ファイルを作成する

上述のファイル レイアウトに従って、テキスト エディタを使用してインデックス ファイルを手動で作成できます。また、アプリケーションをローカルでテストする際に自動で生成すれば、インデックス ファイルをより効率的に作成できます。この 2 つの方法は組み合わせることができます。

ローカル環境でテストする際に gcloud エミュレータ コマンドを使用して、アプリの実行前に Datastore をエミュレートするサービスを開始できます。

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

--data-dir フラグを使用して、index.yaml ファイルが自動生成されるディレクトリを指定します。

アプリのテストの際に、Datastore クエリを生成するたびに、生成されたインデックス定義がエミュレータによって index.yaml に追加されます。自動生成されたインデックス定義は、すべてファイル内の次の行の下に記述されます。

# AUTOGENERATED

この行の上のインデックス定義は、すべて手動で管理されているものとみなされ、開発用ウェブサーバーによって更新されることはありません。アプリケーションによって実行されるクエリに対応するインデックスが、index.yaml ファイルのどこにも記載されていない場合に限り、ウェブサーバーはこの行の下にのみを変更を加えます。自動インデックス定義を手動で管理するには、定義をこの行の上に移動します。

アプリケーションがクエリを実行すると、エミュレータがこの行の下の既存の定義を更新する場合があります。テスト中に実行されるすべてのクエリがアプリケーションで生成されると、index.yaml 内のエントリが完成します。本番環境で使用されないインデックスの削除や、テストでは作成されなかったインデックスの定義のために、ファイルの手動編集が必要になることがあります。

インデックス構成ファイルのデプロイ

index.yaml 構成ファイルをデプロイするには、次のコマンドを実行します。

gcloud app deploy index.yaml

使用されていないインデックスの削除

インデックス構成でインデックスを変更または削除しても、元のインデックスは App Engine から自動的に削除されません。これにより、新しいインデックスを作成しながらアプリの古いバージョンを実行したり、新しいバージョンで問題が発見されたらすぐに古いバージョンを復元したりできます。

古いインデックスが不要になったことが確実である場合には、次のコマンドによって App Engine から削除できます。

gcloud datastore indexes cleanup index.yaml