You can use Cloud
for storing data for your applications that run in the flexible
environment. 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. You can use the datastore emulator to generate the file
automatically as you test your app, or write the file yourself. The
index.yaml file must be uploaded when you deploy your app.
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
index.yaml. This file is uploaded with the application to create
indexes in the datastore.
The following is an example of an
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.
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:
- 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.
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:
- The datastore name of the property.
- The direction to sort, either
ascfor ascending or
descfor 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
yesif the query has an ancestor clause (either Query.ancestor() or a GQL ANCESTOR IS clause). The default is
Creating index files
You can create an index file manually, using a text editor and following the file layout described above. A more efficient approach is to automatically generate the file as you test your app locally. You can combine the two methods.
When you are testing in your local environment, you can use the gcloud emulator command to start a service that emulates Cloud Datastore before you run your app:
gcloud beta emulators datastore start --data-dir DATA-DIR
--data-dir flag to specify the directory where the auto-generated
index.yaml file will appear.
As you test your app, each time you generate a Datastore query, the emulator
adds a generated index definition to
index.yaml. All the automatically
generated indexes will appear in the file below the following line:
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.
The emulator may update existing definitions below this line as the application
makes queries. If the app generates every query it will make while you test it,
then the generated entries in
index.yaml will be complete. You might need to
edit the file manually to delete indexes that are not used in production, or to
define indexes that were not created while testing.
Deploying the index file
Before you deploy your application, you should use the gcloud command to deploy
gcloud app deploy index.yaml