StructuredQuery

{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}

object (Projection)

要返回的可选字段子集。

这充当从查询返回的文档的 DocumentMask。如果未设置，则假定调用方希望返回所有字段。

object (CollectionSelector)

要查询的集合。

object (Filter)

要应用的过滤条件。

object (Order)

要应用于查询结果的顺序。

Firestore 允许调用方提供完整排序、部分排序或完全不排序。在所有情况下，Firestore 都会通过以下规则保证稳定排序：

• 必须提供 orderBy 才能引用不等性过滤条件使用的所有字段。
• 需要包含在 orderBy 中但尚不存在的所有字段都会按字段名称的字典顺序附加。
• 如果未指定 __name__ 的订单，系统会默认附加该订单。

字段将附加与最后一个指定顺序相同的排序方向，如果未指定排序顺序，则为“ASCENDING”。例如：

• ORDER BY a 会变为 ORDER BY a ASC, __name__ ASC
• ORDER BY a DESC 会变为 ORDER BY a DESC, __name__ DESC
• WHERE a > 1 会变为 WHERE a > 1 ORDER BY a ASC, __name__ ASC
• WHERE __name__ > ... AND a > 1 会变为 WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

object (Cursor)

结果集中开始查询的位置的可能前缀。

结果集的排序基于原始查询的 ORDER BY 子句。

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

此查询的结果按 (b ASC, __name__ ASC) 排序。

游标可以引用位置的完整排序或前缀，但其引用的字段不能超过提供的 ORDER BY 中的字段。

继续上面的示例，附加以下开始游标会产生不同的影响：

• START BEFORE (2, /k/123)：在 a = 1 AND b > 2 AND __name__ > /k/123 前面开始查询。
• START AFTER (10)：紧跟在 a = 1 AND b > 10 之后开始查询。

与需要跳过前 N 个结果的 OFFSET 不同，起始游标允许查询从某个逻辑位置开始。此位置并非必须匹配实际结果，它会从此位置向前扫描以查找下一个文档。

需要：

• 值的数量不能大于 ORDER BY 子句中指定的字段数量。

object (Cursor)

结果集中查询结束位置的潜在前缀。

这与 START_AT 类似，但它控制的是结束位置，而不是起始位置。

需要：

• 值的数量不能大于 ORDER BY 子句中指定的字段数量。

integer

在返回第一个结果之前要跳过的文档数量。

这在 WHERE、START AT 和 END AT 指定的约束条件之后、LIMIT 子句之前适用。

需要：

• 如果指定，该值必须大于或等于零。

integer

要返回的结果数上限。

在所有其他限制条件之后应用。

需要：

• 如果指定，该值必须大于或等于零。

object (FindNearest)

可选。潜在的“最近邻”搜索。

在所有其他过滤条件和排序之后应用。

查找与指定查询向量最接近的向量嵌入。