使用 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
查询的实体种类。通常,该元素是定义实体模型的 Model 类的名称。此元素是必需的。
properties

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

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

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

如果查询具有祖先子句(Query.ancestor() 或 GQL ANCESTOR IS子句),则此元素为 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 app deploy index.yaml

删除未使用的索引

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

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

gcloud datastore indexes cleanup index.yaml