StructuredQuery

Firestore 查询。

查询阶段按以下顺序执行：1. from 2.，其中 3. 选择 4. orderBy + startAt + endAt 5. offset 6. 限制

JSON 表示法 
{
  "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)
  }
}
字段
select

object (Projection)

要返回的可选字段子集。

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

object (CollectionSelector)

要查询的集合。
where

object (Filter)

要应用的过滤条件。
orderBy[]

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”
startAt

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 子句中指定的字段数量。
endAt

object (Cursor)

结果集中某个位置的可能前缀，用于在结果中结束查询。

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

需要：

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

integer

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

这在 WHERE、START AT 和END AT 但在 LIMIT 子句之前。

需要：

  • 该值必须大于或等于零（如果指定）。
limit

integer

要返回的结果数上限。

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

需要：

  • 该值必须大于或等于零（如果指定）。
findNearest

object (FindNearest)

可选。可能的最近邻搜索。

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

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

投影

要返回的文档字段的投影。

JSON 表示法 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
字段
fields[]

object (FieldReference)

要返回的字段。

如果为空，则返回所有字段。如需仅返回文档名称，请使用 ['__name__']。

CollectionSelector

一个集合，例如 messages as m1。

JSON 表示法 
{
  "collectionId": string,
  "allDescendants": boolean
}
字段
collectionId

string

集合 ID。设置后，仅选择具有此 ID 的集合。
allDescendants

boolean

如果为 false，则仅选择作为所属 RunQueryRequest 中指定的 parent 的直接子项的集合。如果为 true，则选择所有后代集合。

过滤

过滤器。

JSON 表示法 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
字段
联合字段 filter_type。过滤器的类型。filter_type 只能是下列其中一项：
compositeFilter

object (CompositeFilter)

复合过滤条件。
fieldFilter

object (FieldFilter)

针对文档字段的过滤条件。
unaryFilter

object (UnaryFilter)

只接受一个参数的过滤器。

CompositeFilter

使用指定运算符合并多个其他过滤条件的过滤条件。

JSON 表示法 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
字段
op

enum (Operator)

合并多个过滤条件的运算符。
filters[]

object (Filter)

要组合的过滤条件列表。

需要：

  • 至少存在一个过滤条件。

运算符

复合过滤器运算符。

枚举
OPERATOR_UNSPECIFIED 未指定。不得使用此值。
AND 文件必须符合所有合并过滤条件。
OR 文件必须满足至少一个合并过滤条件。

FieldFilter

针对特定字段的过滤条件。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
字段
field

object (FieldReference)

要用作过滤条件的字段。
op

enum (Operator)

要作为过滤依据的运算符。
value

object (Value)

要比较的值。

运算符

字段过滤条件运算符。

枚举
OPERATOR_UNSPECIFIED 未指定。不得使用此值。
LESS_THAN

指定的 field 小于指定的 value。

需要：

  • “field”在orderBy中名列前茅。
LESS_THAN_OR_EQUAL

给定的 field 小于或等于给定的 value。

需要：

  • “field”在orderBy中名列前茅。
GREATER_THAN

指定的field大于指定的value。

需要：

  • “field”在orderBy中名列前茅。
GREATER_THAN_OR_EQUAL

指定的 field 大于或等于指定的 value。

需要：

  • “field”在orderBy中名列前茅。
EQUAL 指定的 field 等于指定的 value。
NOT_EQUAL

指定的 field 不等于指定的 value。

需要：

  • 无其他NOT_EQUAL、NOT_IN、IS_NOT_NULL或IS_NOT_NAN。
  • field 在 orderBy 中排在第一位。
ARRAY_CONTAINS 给定的 field 是包含给定 value 的数组。
IN

给定的 field 等于给定数组中的至少一个值。

需要：

  • value 是非空 ArrayValue，受析取限制的约束。
  • 在同一查询中没有 NOT_IN 过滤条件。
ARRAY_CONTAINS_ANY

给定 field 是包含给定数组内任何值的数组。

需要：

  • value 是非空 ArrayValue，受析取限制的约束。
  • 同一析取运算中没有其他 ARRAY_CONTAINS_ANY 过滤条件。
  • 在同一查询中没有 NOT_IN 过滤条件。
NOT_IN

field 的值不在给定数组中。

需要：

  • 该 value 是包含最多 10 个值的非空 ArrayValue。
  • 无其他OR、IN、ARRAY_CONTAINS_ANY、NOT_IN、NOT_EQUAL、IS_NOT_NULL或IS_NOT_NAN。
  • field 在 orderBy 中排在第一位。

一元过滤器

具有单个操作数的过滤器。

JSON 表示法 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
字段
op

enum (Operator)

要应用的一元运算符。
联合字段 operand_type。过滤器的参数。operand_type 只能是下列其中一项：
field

object (FieldReference)

要应用运算符的字段。

运算符

一元运算符。

枚举
OPERATOR_UNSPECIFIED 未指定。不得使用此值。
IS_NAN 给定的 field 等于 NaN。
IS_NULL 给定的 field 等于 NULL。
IS_NOT_NAN

给定的 field 不等于 NaN。

需要：

  • 无其他NOT_EQUAL、NOT_IN、IS_NOT_NULL或IS_NOT_NAN。
  • field 在 orderBy 中排在第一位。
IS_NOT_NULL

给定的 field 不等于 NULL。

需要：

  • 单个 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。
  • field 在 orderBy 中排在第一位。

顺序

字段上的订单。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
字段
field

object (FieldReference)

排序依据的字段。
direction

enum (Direction)

排序依据的方向。默认值为 ASCENDING。

方向

排序方向。

枚举
DIRECTION_UNSPECIFIED 未指定。
ASCENDING 升序。
DESCENDING 降序。

查找最近的地点

最近邻搜索配置。

JSON 表示法 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
字段
vectorField

object (FieldReference)

必需。要搜索的矢量字段。只能返回维度与 queryVector 匹配的向量的文档。
queryVector

object (Value)

必需。我们正在执行搜索的查询矢量。必须是不超过 2048 个维度的矢量。
distanceMeasure

enum (DistanceMeasure)

必需。必须指定要使用的距离测量值。
limit

integer

必需。要返回的最近相邻项的数量。必须是不大于 1000 的正整数。

距离测量

比较矢量时要使用的距离度量。

枚举
DISTANCE_MEASURE_UNSPECIFIED 不应设置。
EUCLIDEAN 测量向量之间的 EUCLIDEAN 距离。如需了解详情，请参阅欧几里得语
COSINE 根据向量之间的角度比较向量，这样您可以衡量并非基于向量量级的相似度。我们建议使用 DOT_PRODUCT 和单位归一化向量而不是 COSINE 距离，后者在数学上等效，性能更好。如需了解详情，请参阅余弦相似度。
DOT_PRODUCT 与余弦类似，但受矢量大小影响。如需了解详情，请参阅 Dot Product。