Cloud Firestore 中的索引类型

索引是决定数据库性能的一个重要因素。就像书的索引可以将书中的主题映射到页码一样，数据库中的索引可以将数据库中的数据项映射到数据库中的位置。当您向数据库发送查询请求时，数据库可以使用索引来快速查找所请求数据项的位置。

本页面介绍了 Cloud Firestore 使用的两种索引类型：单字段索引和复合索引。

每个查询的背后都有索引在发挥作用

如果查询没有索引，大部分数据库将需要一项一项地查找需要的内容，这个过程非常缓慢，并且随着数据库内容的增加，查询速度会越来越慢。 为了确保提供高查询性能，Cloud Firestore 会为所有查询使用索引。这样一来，查询的性能将取决于结果集的大小，而不是数据库中的条目数量。

减少索引管理，专注应用开发

Cloud Firestore 的功能可减少管理索引所需的时间，它会自动为您创建最基本的查询所需的索引。在您使用并测试应用的过程中，Cloud Firestore 会帮助您识别并创建您的应用所需的其他索引。

索引类型

Cloud Firestore 使用了两种索引类型：单字段索引和复合索引。除了编入索引的字段数量不同之外，单字段索引和复合索引的管理方式也不同。

单字段索引

单字段索引会为一个集合中包含某个特定字段的所有文档存储一个映射，并按顺序对其排序。单字段索引中的每个条目会记录文档中一个特定字段的值，以及该文档在数据库中的位置。Cloud Firestore 使用这些索引来执行许多基本的查询。您可以通过配置数据库的自动索引设置和索引例外项来管理单字段索引。

自动编入索引

默认情况下，Cloud Firestore 会自动为文档中的每个字段和映射 (map) 中的每个子字段维护单字段索引。Cloud Firestore 对单字段索引使用以下默认设置：

• 对于每个既非数组也非映射的字段，Cloud Firestore 会定义两个集合范围的单字段索引，一个采用升序模式，另一个采用降序模式。

• 对于每个映射字段，Cloud Firestore 会为映射中的每个既非数组也非映射的子字段创建一个集合范围的升序索引和一个降序索引。

• 对于文档中的每个数组字段，Cloud Firestore 会创建并维护一个集合范围的 array-contains 索引。

• 默认情况下，系统不维护集合组范围的单字段索引。

单字段索引例外项

您可以通过创建单字段索引例外项来从自动索引设置中排除字段。 索引例外项会覆盖适用于整个数据库的自动索引设置。例外项可让您启用自动索引设置停用的单字段索引，或停用自动索引启用的单字段索引。如需了解例外项的适用场景，请参阅索引最佳实践。

如果为映射字段创建单字段索引例外项，映射的子字段会继承这些设置。不过，您也可以为特定子字段定义单字段索引例外项。如果删除子字段的例外项，子字段将继承其父级的例外项设置（如果有），如果没有父级例外项，则继承数据库范围的设置。

如需了解如何创建和管理单字段索引例外项，请参阅在 Cloud Firestore 中管理索引。

复合索引

复合索引根据要建立索引的字段的有序列表为一个集合中的所有文档存储一个映射，并按顺序对其排序。

Cloud Firestore 使用复合索引来支持单字段索引不支持的查询。

Cloud Firestore 不会像自动创建单字段索引那样自动创建复合索引，因为可能的字段组合数太多。但是，Cloud Firestore 可以帮助您在构建应用时识别并创建必需的复合索引。

如果您没有创建必需的索引就尝试执行上述查询，Cloud Firestore 会返回一条包含链接的错误消息，按照链接中的说明操作即可创建缺少的索引。每次当您尝试运行没有索引支持的查询时，就会出现这种情况。您还可以使用控制台或 Firebase CLI 手动定义和管理复合索引。如需详细了解如何创建和管理复合索引，请参阅管理索引。

索引模式和查询范围

虽然单字段索引和复合索引的配置方式不同，但都需要为其配置索引模式和查询范围。

索引模式

定义索引时，需要为每个编入索引的字段选择索引模式。每个字段的索引模式都支持针对该字段的特定查询子句。您可以选择以下某种索引模式：

查询范围

每个索引的范围都限定为一个集合或集合组。这称为索引的查询范围：

集合范围

Cloud Firestore 创建的索引默认具有集合范围。 这些索引支持从单个集合返回结果的查询。

集合组范围

集合组包括具有相同集合 ID 的所有集合。如需运行从集合组返回已过滤或已排序结果的集合组查询，必须创建具有集合组范围的相应索引。

默认排序方式和 __name__ 字段

除了按每个字段的指定索引模式（升序或降序）对文档进行排序之外，索引还会按每个文档的 __name__ 字段进行最终排序。__name__ 字段的值设置为完整的文档路径。这意味着结果集中具有相同字段值的文档将按文档路径排序。

默认情况下，__name__ 字段的排序方向与索引定义中最后排序的字段的方向相同。例如：

如需按非默认 __name__ 方向对结果排序，您需要创建该索引。

索引示例

Cloud Firestore 会自动为您创建单字段索引，让您的应用可以快速执行最基本的数据库查询。您可以使用单字段索引执行基于字段值和比较运算符（<、<=、==、>=、> 和 in）的简单查询。对于数组字段，您可以使用单字段索引执行 array-contains 和 array-contains-any 查询。

为便于说明，请从索引创建的角度查看以下示例。以下代码段在 cities 集合中创建了一些 city 文档，并为每个文档设置了 name、state、country、capital、population 和 tags 字段：

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

假设使用默认的自动索引设置，Cloud Firestore 会为每个非数组字段更新一个升序单字段索引和一个降序单字段索引，并为数组字段更新一个 array-contains 单字段索引。下表中的每一行代表单字段索引中的一个条目：

单字段索引支持的查询

使用这些自动创建的单字段索引，您可以运行如下所示的简单查询：

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

您还可以创建 in 和复合等式 (==) 查询：

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

如果您需要运行使用了范围比较运算符（<、<=、> 或 >=）的复合查询，或者您需要按照另一个字段进行排序，则必须为该查询创建复合索引。

您可以使用 array-contains 索引查询 regions 数组字段：

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

复合索引支持的查询

Cloud Firestore 使用复合索引来支持单字段索引不支持的复合查询。例如，您需要使用复合索引来支持下列查询：

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

这些查询需要使用下列复合索引。由于查询针对 country 字段使用等式（== 或 in），因此您可以对此字段使用升序或降序索引模式。默认情况下，不等式子句会基于其中的字段使用升序排序。

如需以降序运行相同的查询，您需要针对 population 字段额外创建一个降序的复合索引：

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

如果您要将 array-contains 或 array-contains-any 查询与其他子句组合使用，也需要创建复合索引。

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

集合组索引支持的查询

为了演示查询范围为集合组的索引，假设您将 city 子集合添加到部分 landmarks 文档：

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

使用查询范围为集合的如下单字段索引，您可以根据 category 字段查询单个城市的 landmarks 集合：

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

现在，假设您想要查询所有城市的地标。如需针对包含所有 landmarks 集合的集合组运行此查询，必须启用具有集合组范围的 landmarks 单字段索引：

启用此索引后，您可以查询 landmarks 集合组：

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

若要运行返回已过滤或已排序结果的集合组查询，必须启用范围为集合组的相应单字段索引或复合索引。但是，不过滤或不排序结果的集合组查询不需要任何其他索引定义。

例如，您可以在不启用其他索引的情况下运行以下集合组查询：

db.collectionGroup("landmarks").get()

索引条目

项目的已配置索引和文档的结构决定了文档索引条目的数量。这些索引条目均会计入索引条目数限制。

以下示例展示了文档的索引条目。

文档

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

单字段索引

• city_name ASC
• city_name DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains（ASC 及 DESC）

复合索引

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

索引条目

此索引配置会生成文档的下面 18 个索引条目：

索引和价格

使用索引时，您的应用会产生存储费用。 如需详细了解如何计算索引的存储空间使用量，请参阅索引条目大小。

充分利用索引合并功能

虽然 Cloud Firestore 会为每个查询使用索引，但实际上没有必要为每个查询都创建一个索引。如果查询使用多个等式 (==) 子句和可选的 orderBy 子句，Cloud Firestore 可以重复利用现有的索引。Cloud Firestore 可以将针对简单等式过滤条件创建的索引合并起来，构建运行更大的等式查询所需的复合索引。

通过找出可利用索引合并的情况，您可以降低索引产生的费用。例如，假设一个餐厅评分应用有一个 restaurants 集合：

• collections_bookmark restaurants

  • class burgerthyme

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

现在，假设该应用使用下列查询。请注意，该应用使用的是 category、city 和 editors_pick 等式子句的组合，并始终按 star_rating 进行升序排序：

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

您可以为每个查询创建一个索引：

但更好的方式是，充分利用 Cloud Firestore 合并等式子句索引的功能，来减少索引的数量：

此索引集不仅更小，还可支持其他查询：

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

索引限制

索引存在以下限制。如需了解与配额和限制有关的全部信息，请参阅配额和限制。

索引最佳实践

对于大多数应用，您可以依靠自动索引和错误消息链接来管理索引。但是，在以下情况下，您可能需要添加单字段例外项：

如需详细了解如何解决索引编制问题（索引扇出、INVALID_ARGUMENT 错误），请参阅问题排查页面。