使用 index.yaml 配置 Datastore 索引

您可以使用 Datastore 模式的 Firestore (Datastore) 来存储在标准环境中运行的应用的数据。Datastore 使用索引来处理应用执行的每个查询。每当实体更改时，这些索引都会更新，因此在应用执行查询时，系统可以快速返回结果。为此，Datastore 需要预先了解应用将执行哪些查询。您可以在 index.yaml 配置文件中指定应用所需的索引。您可以在自行测试应用或编写文件时使用 Datastore 模拟器来自动生成该文件。部署应用时，必须上传 index.yaml 文件。

index.yaml 简介

应用执行的每个 Datastore 查询都需要相应的索引。简单查询（例如对单个属性的查询）的索引是自动创建的。复杂查询的索引必须在名为 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 的列表元素。列表中的每个元素表示一个应用索引。

索引元素可包含以下元素：

kind
查询的实体种类。此元素是必需的。
properties

一个要作为索引列包含在内的属性列表，排序顺序如下：先是等式过滤条件中使用的属性，然后是非等式过滤条件中使用的属性，最后是排序顺序及其方向。

该列表中的每个元素包含以下元素：

name
属性的数据存储区名称。
direction
排序方向：asc 表示升序，desc 表示降序。仅查询的排序顺序中使用的属性需要该元素，且必须与查询使用的方向匹配。默认值为 asc。
ancestor

如果查询具有祖先子句 (Query.setAncestor)，则此元素为 yes。默认值为 no。

创建索引文件

您可以使用文本编辑器并按照上述文件布局手动创建索引文件。更高效的方法是在本地测试应用时自动生成文件。您可以结合使用这两种方法。

当您在本地环境中测试应用时，可以先使用 gcloud 模拟器命令启动模拟 Datastore 的服务，然后再运行应用：

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

使用 --data-dir 标志可指定自动生成的 index.yaml 文件的存储目录。

在测试应用时，每当您生成一个 Datastore 查询，该模拟器都会将生成的索引定义添加到 index.yaml。所有自动生成的索引定义都将出现在文件中以下行的下方：

# AUTOGENERATED

该行上方的所有索引定义都被视为手动控制，开发 Web 服务器不对其进行更新。网络服务器仅会更改该行下方的内容，并且仅在完整的 index.yaml 文件未说明与应用执行的查询对应的索引时才执行此操作。要手动控制自动生成的索引定义，请将其移到该行上方。

模拟器可能会在应用执行查询时更新该行下方的现有定义。如果应用在您测试时生成其将要执行的每个查询，则 index.yaml 中生成的条目将是完整的。您可能需要手动修改该文件以删除生产环境未使用的索引，或者定义测试时未创建的索引。

部署索引配置文件

index.yaml 文件可以位于源代码目录中的任意位置。

要在不更改当前服务版本的情况下部署该文件，请根据您的环境，在包含索引文件的目录中使用以下命令之一：

gcloud

gcloud app deploy index.yaml

Maven

mvn appengine:deployIndex index.yaml

Gradle

gradle appengineDeployIndex index.yaml

IDE

如果您使用 IntelliJ 或 Eclipse，则可以使用部署表单来选择要部署的各个配置文件。

删除未使用的索引

通过索引配置更改或移除索引时，原始索引不会自动从 App Engine 中删除。这样，您便能够在构建新索引期间让应用的旧版本继续运行，或者在发现新版本存在问题时立即还原到旧版本。

如果您确定不再需要旧索引，则可以使用以下命令从 App Engine 中删除这些索引：

gcloud datastore indexes cleanup index.yaml