English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Python Datastore Index Configuration

The App Engine datastore uses indexes for every query your application makes. These indexes are updated whenever an entity changes, so the results can be returned quickly when the app makes a query. To do this, the datastore needs to know in advance which queries the application will make. You specify which indexes your app needs in a configuration file. The development server can generate the datastore index configuration automatically as you test your app.

- About index.yaml
- Index Definitions
- Automatic and Manual Indexes

## About index.yaml

Every datastore query made by an application needs a corresponding index. Indexes for simple queries, such as queries over a single property, are created automatically. Indexes for complex queries must be defined in a configuration file named `index.yaml`. This file is uploaded with the application to create indexes in the datastore.

The development web server (dev_appserver.py) automatically adds items to this file when the application tries to execute a query that needs an index that does not have an appropriate entry in the configuration file. You can adjust indexes or create new ones manually by editing the file.

Tip: If during testing the app exercises every query it will make using the development web server, then the generated entries in `index.yaml` will be complete. You only need to edit the file manually to delete indexes that are no longer used, or to define indexes not created by the development web server.

For more information about indexes, see Queries and Indexes.

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

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

The syntax of `index.yaml` is the YAML format. For more information about this syntax, see the YAML website for more information.

Tip: The YAML format supports comments. A line that begins with a pound (`#`) character is ignored:
`# This is a comment.`

### Index Definitions

`index.yaml` has a single list element called `indexes`. Each element in the list represents an index for the application.

An index element can have the following elements:

`kind`

  The kind of the entity for the query. Typically, this is the name of the Model class that defines the model for the entities. This element is required.

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