index.yaml reference

Python 2.7/3.7 |Java 8/11 |PHP |Go 1.9/1.11/1.12 |Node.js

Note: This reference uses a YAML formatted configuration file, used by tooling based on Cloud SDK, such as the gcloud command line, or Cloud SDK-based Maven, Gradle, Eclipse, or IntelliJ plugins. If you are using tooling for the App Engine SDK for Java, such as appcfg, then use the XML format.

App Engine predefines a simple index on each property of an entity. An App Engine application can define further custom indexes in an index configuration file named index.yaml. The development server can generate the index configuration needed by your application when it performs these queries while you are testing your app. You can tune indexes manually by editing the index.yaml file before uploading the application. See Configuring Datastore Indexes for information about how to deploy and manage index configurations.

Example

The following is an example of an index.yaml file:

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

# This pound sign is the syntax for a comment.

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

Syntax

The syntax of index.yaml is the YAML format. The index.yaml file has a single list element called indexes. Each element in the list represents an index for the application.

The index items can have the following elements:

Element	Description
kind	Required. The kind of the entity for the query. Typically, this is the name of the Model class that defines the model for the entities.
properties	A list of properties to include as columns of the index, in the order to be sorted: properties used in equality filters first, followed by the property used in inequality filters, then the sort orders and their directions. Each element in this list has the following elements: name The datastore name of the property. direction The direction to sort, either asc for ascending or desc for descending. This is only required for properties used in sort orders of the query, and must match the direction used by the query. The default is asc.
ancestor	yes if the query has an ancestor clause (either Query.ancestor() or a GQL ANCESTOR IS clause). The default is no.

Automatic and manual indexes

When the development web server adds a generated index definition to index.yaml, it does so below the following line, inserting it if necessary:

# AUTOGENERATED

The development web server considers all index definitions below this line to be automatic, and it may update existing definitions below this line as the application makes queries.

All index definitions above this line are considered to be under manual control, and are not updated by the development web server. The web server will only make changes below the line, and will only do so if the complete index.yaml file does not describe an index that accounts for a query executed by the application. To take control of an automatic index definition, move it above this line.

Deploying the index configuration file

To deploy the index configuration file, run the following command:

gcloud

gcloud app deploy index.yaml

appcfg

If you install the original App Engine SDK, you can run:

appcfg.py update_indexes [YOUR_APP_DIR]

Deleting unused indexes

When you change or remove an index from the index configuration, the original index is not deleted from App Engine automatically. This gives you the opportunity to leave an older version of the app running while new indexes are being built, or to revert to the older version immediately if a problem is discovered with a newer version.

When you are sure that old indexes are no longer needed, you can delete them from App Engine as follows:

gcloud datastore cleanup-indexes index.yaml