索引
Firestore
(接口)AggregationResult
(消息)ArrayValue
(消息)BatchGetDocumentsRequest
(消息)BatchGetDocumentsResponse
(消息)BatchWriteRequest
(消息)BatchWriteResponse
(消息)BeginTransactionRequest
(消息)BeginTransactionResponse
(消息)BitSequence
(消息)BloomFilter
(消息)CommitRequest
(消息)CommitResponse
(消息)CreateDocumentRequest
(消息)Cursor
(消息)DeleteDocumentRequest
(消息)Document
(消息)DocumentChange
(消息)DocumentDelete
(消息)DocumentMask
(消息)DocumentRemove
(消息)DocumentTransform
(消息)DocumentTransform.FieldTransform
(消息)DocumentTransform.FieldTransform.ServerValue
(枚举)ExecutionStats
(消息)ExistenceFilter
(消息)ExplainMetrics
(消息)ExplainOptions
(消息)GetDocumentRequest
(消息)ListCollectionIdsRequest
(消息)ListCollectionIdsResponse
(消息)ListDocumentsRequest
(消息)ListDocumentsResponse
(消息)ListenRequest
(消息)ListenResponse
(消息)MapValue
(消息)PartitionQueryRequest
(消息)PartitionQueryResponse
(消息)PlanSummary
(消息)Precondition
(消息)RollbackRequest
(消息)RunAggregationQueryRequest
(消息)RunAggregationQueryResponse
(消息)RunQueryRequest
(消息)RunQueryResponse
(消息)StructuredAggregationQuery
(消息)StructuredAggregationQuery.Aggregation
(消息)StructuredAggregationQuery.Aggregation.Avg
(消息)StructuredAggregationQuery.Aggregation.Count
(消息)StructuredAggregationQuery.Aggregation.Sum
(消息)StructuredQuery
(消息)StructuredQuery.CollectionSelector
(消息)StructuredQuery.CompositeFilter
(消息)StructuredQuery.CompositeFilter.Operator
(枚举)StructuredQuery.Direction
(枚举)StructuredQuery.FieldFilter
(消息)StructuredQuery.FieldFilter.Operator
(枚举)StructuredQuery.FieldReference
(消息)StructuredQuery.Filter
(消息)StructuredQuery.FindNearest
(消息)StructuredQuery.FindNearest.DistanceMeasure
(枚举)StructuredQuery.Order
(消息)StructuredQuery.Projection
(消息)StructuredQuery.UnaryFilter
(消息)StructuredQuery.UnaryFilter.Operator
(枚举)Target
(消息)Target.DocumentsTarget
(消息)Target.QueryTarget
(消息)TargetChange
(消息)TargetChange.TargetChangeType
(枚举)TransactionOptions
(消息)TransactionOptions.ReadOnly
(消息)TransactionOptions.ReadWrite
(消息)UpdateDocumentRequest
(消息)Value
(消息)Write
(消息)WriteRequest
(消息)WriteResponse
(消息)WriteResult
(消息)
Firestore
Cloud Firestore 服务。
Cloud Firestore 是一种 NoSQL 文档数据库,具有速度快、完全托管、无服务器、云原生的特性,可为全球规模的移动、Web 和 IoT 应用简化数据存储、同步和查询。它的客户端库可提供实时同步和离线支持,同时还具备多种安全功能并可与 Firebase 和 Google Cloud Platform 集成,从而帮助您更快地构建真正的无服务器应用。
BatchGetDocuments |
---|
获取多个文档。 此方法返回的文档不一定会按照请求的顺序返回。
|
BatchWrite |
---|
应用批量写入操作。 BatchWrite 方法不会以原子方式应用写入操作,而是会不按顺序应用写入操作。方法不允许每个文档执行多次写入。每次写入都会独立成功或失败。请参阅 如果您需要一组以原子方式应用的写入,请改用
|
BeginTransaction |
---|
启动新事务。
|
提交 |
---|
提交事务,同时选择性地更新文档。
|
CreateDocument |
---|
新建一个文档。
|
DeleteDocument |
---|
删除文档。
|
GetDocument |
---|
获取单个文档。
|
ListCollectionIds |
---|
列出某个文档下的所有集合 ID。
|
ListDocuments |
---|
列出文档。
|
聆听 |
---|
监听更改。此方法只能通过 gRPC 或 WebChannel(而非 REST)使用。
|
PartitionQuery |
---|
通过返回可用于并行运行查询的分区游标来对查询进行分区。返回的分区游标是拆分点,可被 RunQuery 用作查询结果的起点/终点。
|
回滚 |
---|
回滚事务。
|
RunAggregationQuery |
---|
运行聚合查询。 此 API 允许运行聚合以在服务器端生成一系列 简要示例:
|
RunQuery |
---|
运行查询。
|
UpdateDocument |
---|
更新或插入文档。
|
书写 |
---|
按顺序流处理批量文档更新和删除操作。此方法只能通过 gRPC 或 WebChannel(而非 REST)使用。
|
AggregationResult
Firestore 聚合查询中单个存储分区的结果。
与文档查询不同,文档查询可以为每个结果显示不同的字段,聚合查询中所有结果的 aggregate_fields
键都是相同的。
字段 | |
---|---|
aggregate_fields |
聚合函数的结果,例如: 键是分配给输入时聚合函数的 |
ArrayValue
数组值。
字段 | |
---|---|
values[] |
数组中的值。 |
BatchGetDocumentsRequest
对 Firestore.BatchGetDocuments
的请求。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
documents[] |
要检索的文档的名称。格式为: |
mask |
要返回的字段。如果未设置,则返回所有字段。 如果文档的某个字段不在此掩码中,则不会在响应中返回该字段。 |
联合字段 consistency_selector 。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
读取事务中的文档。 |
new_transaction |
启动新事务并读取文档。默认为只读事务。新的交易 ID 将作为数据流中的第一个响应返回。 |
read_time |
按指定时间读取文档。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
BatchGetDocumentsResponse
Firestore.BatchGetDocuments
的流式响应。
字段 | |
---|---|
transaction |
作为此请求的一部分启动的事务。此参数将在第一个响应中设置,并且仅当在请求中设置了 |
read_time |
阅读文档的时间。这可能是单调递增的,在这种情况下,结果流中的先前文档保证在其 read_time 和当前时间之间不会发生变化。 |
联合字段 result 。单个结果。如果服务器仅返回事务,则此字段可以为空。result 只能是下列其中一项: |
|
found |
请求的文档。 |
missing |
您请求但不存在的文档名称。格式为: |
BatchWriteRequest
对 Firestore.BatchWrite
的请求。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
writes[] |
要应用的写入。 该方法不会以原子方式应用写入,也不保证排序。每次写入都会独立成功或失败。针对每个请求,您不能多次向同一文档写入数据。 |
labels |
与此批量写入关联的标签。 |
BatchWriteResponse
来自 Firestore.BatchWrite
的响应。
字段 | |
---|---|
write_results[] |
应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。 |
status[] |
应用写入的状态。 第 i 个写入状态对应于请求中的第 i 个写入。 |
BeginTransactionRequest
对 Firestore.BeginTransaction
的请求。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
options |
交易的选项。默认为读写事务。 |
BeginTransactionResponse
字段 | |
---|---|
transaction |
启动的事务。 |
BitSequence
以字节数组编码的位序列。
bitmap
字节数组中的每个字节存储序列的 8 位。唯一的例外是最后一个字节,它可以存储 8 个或更少的位。padding
定义了要作为“填充”忽略的最后一个字节的位数。这些“填充”位的值未指定,必须忽略。
如需检索第一个位(位 0),请计算:(bitmap[0] & 0x01) != 0
。如需检索第二个位(位 1),请计算:(bitmap[0] & 0x02) != 0
。如需检索第三位(位 2),请计算:(bitmap[0] & 0x04) != 0
。如需检索第四位(位 3),请计算:(bitmap[0] & 0x08) != 0
。如需检索位 n,请计算:(bitmap[n / 8] & (0x01 << (n % 8))) != 0
。
BitSequence
的“大小”(其中包含的位数)按以下公式计算:(bitmap.length * 8) - padding
。
字段 | |
---|---|
bitmap |
对位序列进行编码的字节。长度为零。 |
padding |
|
BloomFilter
泛光滤镜 (https://en.wikipedia.org/wiki/Bloom_filter)。
泛光过滤器使用 MD5 对条目进行哈希处理,并将生成的 128 位哈希视为 2 个不同的 64 位哈希值,并使用 2 的补码编码将其解释为无符号整数。
然后,这两个哈希值(名为 h1
和 h2
)会用于使用公式计算 hash_count
哈希值(从 i=0
开始):
h(i) = h1 + (i * h2)
然后,取这些结果值以泛光滤镜中的位数为模,以获得泛光滤镜的位,以测试给定条目。
字段 | |
---|---|
bits |
泛光过滤数据。 |
hash_count |
算法使用的哈希数量。 |
CommitRequest
对 Firestore.Commit
的请求。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
writes[] |
要应用的写入。 始终以原子方式按顺序执行。 |
transaction |
如果设置,则应用此事务中的所有写入,并提交。 |
CommitResponse
Firestore.Commit
的响应。
字段 | |
---|---|
write_results[] |
应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。 |
commit_time |
提交发生的时间。任何具有等于或大于 |
CreateDocumentRequest
对 Firestore.CreateDocument
的请求。
字段 | |
---|---|
parent |
必需。父级资源。例如: |
collection_id |
必需。要列出的集合 ID(相对于 |
document_id |
客户分配的文档 ID,用于此文档。 可选。如果未指定,服务会分配 ID。 |
document |
必需。要创建的文档。不得设置 |
mask |
要返回的字段。如果未设置,则返回所有字段。 如果文档中某个字段不在此掩码中,则不会在响应中返回该字段。 |
Cursor
在查询结果集中的位置。
字段 | |
---|---|
values[] |
表示位置的值,按照它们在查询的 order by 子句中出现的顺序进行。 包含的值可以少于 order by 子句中指定的值。 |
before |
该位置紧跟在给定值之前或之后(相对于查询定义的排序顺序)。 |
DeleteDocumentRequest
对 Firestore.DeleteDocument
的请求。
字段 | |
---|---|
name |
必需。要删除的文档的资源名称。格式为: |
current_document |
文档的可选前提条件。如果已设置此属性,但目标文档未满足此要求,则请求将失败。 |
文档
Firestore 文档。
不得超过 1 MiB - 4 个字节。
字段 | |
---|---|
name |
文档的资源名称,例如 |
fields |
|
create_time |
仅供输出。文档的创建时间。 在删除文档后又重新创建后,此值会单调递增。还可以与其他文档的值和查询的 |
update_time |
仅供输出。上次更改文档的时间。 此值最初设置为 |
DocumentChange
Document
发生了变化。
这可能是多次 writes
(包括删除)的结果,最终导致了 Document
的新值。
如果有多个目标受到影响,系统可能会针对同一逻辑更改返回多条 DocumentChange
消息。
字段 | |
---|---|
document |
如果设置了 |
target_ids[] |
与此文档匹配的目标的一组目标 ID。 |
removed_target_ids[] |
与此文档不再匹配的目标的一组目标 ID。 |
DocumentDelete
已删除Document
。
可能是多次 writes
(包括更新)导致的,但最后一次更新时删除了 Document
。
如果有多个目标受到影响,则对于同一逻辑删除,可能会返回多条 DocumentDelete
消息。
字段 | |
---|---|
document |
已删除的 |
removed_target_ids[] |
之前与此实体匹配的目标的一组目标 ID。 |
read_time |
观察到删除操作的读取时间戳。 大于或等于删除操作的 |
DocumentMask
文档中的一组字段路径。用于将对文档的获取或更新操作限制为其部分字段。这与标准字段掩码不同,因为它的作用域始终限定为 Document
,并考虑到 Value
的动态特性。
字段 | |
---|---|
field_paths[] |
掩码中的字段路径列表。有关字段路径语法参考,请参阅 |
DocumentRemove
从目标视图中移除了 Document
。
当文档不再与目标相关且不在视图范围内时发送。如果服务器无法发送文档的新值,则可以发送可以代替 DocumentDelete 或 DocumentChange。
如果有多个目标受到影响,则可能会针对同一逻辑写入或删除操作返回多条 DocumentRemove
消息。
字段 | |
---|---|
document |
不在视图范围内的 |
removed_target_ids[] |
之前与此文档匹配的目标的一组目标 ID。 |
read_time |
观察到移除操作的读取时间戳。 大于或等于更改/删除/移除的 |
DocumentTransform
文档的转换。
字段 | |
---|---|
document |
要转换的文档的名称。 |
field_transforms[] |
要按顺序应用于文档中各字段的转换列表。此字段不能留空。 |
FieldTransform
文档字段的转换。
字段 | |
---|---|
field_path |
字段的路径。有关字段路径语法参考文档,请参阅 |
联合字段 transform_type 。要应用于字段的转换。transform_type 只能是下列其中一项: |
|
set_to_server_value |
将该字段设置为指定的服务器值。 |
increment |
将指定值与字段的当前值相加。 它必须是整数或双精度值。如果该字段不是整数或双精度值,或者该字段尚不存在,则转换会将该字段设置为给定值。如果给定值或当前字段值是双精度类型,则这两个值都将被解读为双精度类型。双精度值的双精度算术和表示形式遵循 IEEE 754 语义。如果存在正/负整数溢出,则该字段解析为最大幅度的正/负整数。 |
maximum |
将字段设置为其当前值与指定值的最大值。 它必须是整数或双精度值。如果该字段不是整数或双精度值,或者该字段尚不存在,则转换会将该字段设置为给定值。如果在字段和输入值是混合类型(即一个是整数,一个是双精度类型)的情况下应用最大值运算,则字段将采用较大运算数的类型。如果运算数相等(例如 3 和 3.0),此字段不会更改。0、0.0 和 -0.0 都是零。存储值为零和输入值的最大值始终为存储值。任意数值 x 和 NaN 的最大值为 NaN。 |
minimum |
将字段设置为其当前值和指定值的最小值。 它必须是整数或双精度值。如果字段不是整数或双精度值,或者该字段尚不存在,则转换会将该字段设置为输入值。如果在字段和输入值属于混合类型(即一个是整数,一个是双精度类型)的情况下应用最小运算,则字段将采用较小运算数的类型。如果运算数相等(例如 3 和 3.0),此字段不会更改。0、0.0 和 -0.0 都是零。存储值为零和输入值的最小值始终为存储值。任意数值 x 和 NaN 的最小值为 NaN。 |
append_missing_elements |
如果当前字段值中尚不存在给定元素,请按顺序附加这些元素。如果该字段不是数组,或者该字段尚不存在,则会先将其设置为空数组。 在检查值是否缺失时,将不同类型的等效数字(例如 3L 和 3.0)视为相等。NaN 等于 NaN,Null 等于 Null。如果输入包含多个等值值,系统将只考虑第一个值。 相应的 transform_result 将是 null 值。 |
remove_all_from_array |
从该字段的数组中移除所有给定元素。如果该字段不是数组,或者该字段尚不存在,则将其设置为空数组。 在决定是否移除某个元素时,不同类型(例如 3L 和 3.0)的等效数字会被视为相等。NaN 等于 NaN,Null 等于 Null。如果存在重复项,这将移除所有等效值。 相应的 transform_result 将是 null 值。 |
ServerValue
由服务器计算的值。
枚举 | |
---|---|
SERVER_VALUE_UNSPECIFIED |
未指定。不得使用此值。 |
REQUEST_TIME |
服务器处理请求的时间(精确到毫秒)。如果用于事务中的多个字段(相同或不同的文档),则所有字段都将获得相同的服务器时间戳。 |
ExecutionStats
查询的执行统计信息。
字段 | |
---|---|
results_returned |
返回的结果总数,包括文档、预测、汇总结果、键。 |
execution_duration |
在后端执行查询的总时间。 |
read_operations |
计费读取操作总数。 |
debug_stats |
查询执行时的调试统计信息。请注意,调试统计信息可能会随着 Firestore 的发展而发生变化。It could include: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } } |
ExistenceFilter
与指定目标匹配的所有文档的摘要。
字段 | |
---|---|
target_id |
要应用此过滤条件的目标 ID。 |
count |
与 如果与客户端中匹配的文档数量不同,客户端必须手动确定哪些文档不再与目标匹配。 客户端可以使用 |
unchanged_names |
泛光过滤器(尽管名称)包含匹配 服务器可以自行决定省略此泛光过滤器,例如如果认为客户端不会使用该过滤器,或者计算或传输它的计算或传输成本过高。客户端必须通过回退到此字段存在之前所用的逻辑,妥善处理该字段;也就是说,在没有恢复令牌的情况下重新添加目标,以确定客户端缓存中的哪些文档不同步。 |
ExplainMetrics
说明查询的指标。
字段 | |
---|---|
plan_summary |
查询的规划阶段信息。 |
execution_stats |
执行查询时的汇总统计信息。仅当 |
ExplainOptions
说明查询的选项。
字段 | |
---|---|
analyze |
可选。是否执行此查询。 如果此字段设为 false(默认值),系统将规划查询,仅返回规划阶段的指标。 如果为 true,系统会规划和执行查询,并返回完整的查询结果以及规划和执行阶段指标。 |
GetDocumentRequest
对 Firestore.GetDocument
的请求。
字段 | |
---|---|
name |
必需。要获取的文档的资源名称。格式为: |
mask |
要返回的字段。如果未设置,则返回所有字段。 如果文档中某个字段不在此掩码中,则不会在响应中返回该字段。 |
联合字段 consistency_selector 。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
在事务中读取文档。 |
read_time |
读取指定时间的文档版本。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
ListCollectionIdsRequest
对 Firestore.ListCollectionIds
的请求。
字段 | |
---|---|
parent |
必需。父级文档。格式为: |
page_size |
要返回的结果数上限。 |
page_token |
页面令牌。必须是来自 |
联合字段 consistency_selector 。此请求的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
read_time |
按指定时间读取文档。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
ListCollectionIdsResponse
来自 Firestore.ListCollectionIds
的响应。
字段 | |
---|---|
collection_ids[] |
集合 ID。 |
next_page_token |
可用于继续列出列表的页面令牌。 |
ListDocumentsRequest
对 Firestore.ListDocuments
的请求。
字段 | |
---|---|
parent |
必需。父级资源名称。格式为: 例如: |
collection_id |
可选。要列出的集合 ID(相对于 例如: 这是可选内容;如果未提供,Firestore 将列出提供的 |
page_size |
可选。单个响应中要返回的文档数量上限。 Firestore 返回的值可能少于此值。 |
page_token |
可选。从之前的 提供此令牌以检索后续页面。进行分页时,所有其他参数( |
order_by |
可选。要返回的文档的可选顺序。 例如: 这镜像了 Firestore 查询中使用的 |
mask |
可选。要返回的字段。如果未设置,则返回所有字段。 如果文档的某个字段不在此掩码中,则不会在响应中返回该字段。 |
show_missing |
列表是否应显示缺失的文档。 如果某个文档不存在,但该文档下面嵌套了子文档,则它就会丢失。如果为 true,则返回此类缺失的文档时将附带一个键,但不会设置任何字段、 带有 |
联合字段 consistency_selector 。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
作为已活跃事务的一部分执行读取。 |
read_time |
在提供的时间执行读取操作。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
ListDocumentsResponse
字段 | |
---|---|
documents[] |
找到的文件。 |
next_page_token |
用于检索下一页文档的令牌。 如果省略此字段,则不存在后续页面。 |
ListenRequest
对 Firestore.Listen
的请求
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
labels |
与此目标更改相关联的标签。 |
联合字段 target_change 。支持的目标更改。target_change 只能是下列其中一项: |
|
add_target |
要添加到此数据流的目标。 |
remove_target |
要从此数据流中移除的目标的 ID。 |
ListenResponse
Firestore.Listen
的响应。
字段 | |
---|---|
联合字段 response_type 。支持的响应。response_type 只能是下列其中一项: |
|
target_change |
目标已更改。 |
document_change |
|
document_delete |
已删除 |
document_remove |
已从目标中移除 |
filter |
要应用于之前针对指定目标返回的该组文档集的过滤条件。 当文档可能已从指定目标中移除,但具体文档未知时,系统会返回此值。 |
MapValue
映射值。
字段 | |
---|---|
fields |
地图的字段。 映射键表示字段名称。与正则表达式 |
PartitionQueryRequest
对 Firestore.PartitionQuery
的请求。
字段 | |
---|---|
parent |
必需。父级资源名称。格式为: |
partition_count |
所需的最大分区点数。分区可能会跨多个结果页面返回。该数字必须为正数。返回的实际分区数可能会少一些。 例如,可设置为比要运行的并行查询数量少 1,或者在运行数据流水线作业时,设置为比可用工作器或计算实例的数量少 1。 |
page_token |
上一次调用 PartitionQuery 时返回的 例如,使用 page_token 的两个后续调用可能会返回:
要获得按照提供给 PartitionQuery 的查询结果排序的完整结果集,结果集应该合并:游标 A、游标 B、游标 M、游标 Q、游标 U、游标 W |
page_size |
在此调用中返回的最大分区数,受 例如,如果 |
联合字段 query_type 。要分区的查询。query_type 只能是下列其中一项: |
|
structured_query |
结构化查询。查询必须指定集合的所有后代,并按名称升序排序。不支持其他过滤条件、排序依据、限制、偏移和开始/结束游标。 |
联合字段 consistency_selector 。此请求的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
read_time |
按指定时间读取文档。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
PartitionQueryResponse
字段 | |
---|---|
partitions[] |
分区结果。每个分区都是一个拆分点,RunQuery 可将其用作查询结果的起点或终点。发出 RunQuery 请求时必须使用提供给此 PartitionQuery 请求的查询。分区游标将按照与提供给 PartitionQuery 的查询结果相同的顺序进行排序。 例如,如果 PartitionQuery 请求返回分区游标 A 和 B,则运行以下三个查询将返回原始查询的整个结果集:
空结果可能表示查询的结果太少,无法分区,或者查询尚不支持分区。 |
next_page_token |
一个页面令牌,可用于请求一组额外的结果,最多为 PartitionQuery 请求中的 |
PlanSummary
查询的规划阶段信息。
字段 | |
---|---|
indexes_used[] |
为查询选择的索引。For example: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ] |
前提条件
文档的前提条件,用于基于条件的运算。
字段 | |
---|---|
联合字段 condition_type 。前提条件的类型。condition_type 只能是下列其中一项: |
|
exists |
如果设置为 |
update_time |
设置后,目标文档必须存在,并且是当时最后一次更新。时间戳必须与微秒对齐。 |
RollbackRequest
对 Firestore.Rollback
的请求。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
transaction |
必需。要回滚的事务。 |
RunAggregationQueryRequest
字段 | |
---|---|
parent |
必需。父级资源名称。格式为: |
explain_options |
可选。说明查询的选项。如果设置了此字段,则会返回其他查询统计信息。否则,将仅返回查询结果。 |
联合字段 query_type 。要运行的查询。query_type 只能是下列其中一项: |
|
structured_aggregation_query |
聚合查询。 |
联合字段 consistency_selector 。查询的一致性模式默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
在已活跃的事务中运行汇总。 此处的值是要执行查询的不透明事务 ID。 |
new_transaction |
在查询中启动新事务,默认为只读。 新的交易 ID 将作为数据流中的第一个响应返回。 |
read_time |
执行给定时间戳的查询。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
RunAggregationQueryResponse
字段 | |
---|---|
result |
单个汇总结果。 报告部分进度时不存在。 |
transaction |
作为此请求的一部分启动的事务。 仅在请求请求启动新事务时出现在第一个响应中。 |
read_time |
计算汇总结果的时间。此值始终是单调递增的;在这种情况下,结果流中的上一个 AggregationResult 在其 如果查询未返回任何结果,则不会发送包含 |
explain_metrics |
查询说明指标。此属性仅在提供了 |
RunQueryRequest
对 Firestore.RunQuery
的请求。
字段 | |
---|---|
parent |
必需。父级资源名称。格式为: |
explain_options |
可选。说明查询的选项。如果设置了此字段,则会返回其他查询统计信息。否则,将仅返回查询结果。 |
联合字段 query_type 。要运行的查询。query_type 只能是下列其中一项: |
|
structured_query |
结构化查询。 |
联合字段 consistency_selector 。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
transaction |
在已处于活动状态的事务中运行查询。 此处的值是要执行查询的不透明事务 ID。 |
new_transaction |
启动新事务并读取文档。默认为只读事务。新的交易 ID 将作为数据流中的第一个响应返回。 |
read_time |
按指定时间读取文档。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
RunQueryResponse
Firestore.RunQuery
的响应。
字段 | |
---|---|
transaction |
作为此请求的一部分启动的事务。只能在第一个响应中设置,且只能在请求中设置了 |
document |
查询结果,报告部分进度时未设置。 |
read_time |
阅读文档的时间。这可能是单调递增的;在这种情况下,结果流中的先前文档保证在其 如果查询未返回任何结果,则不会发送包含 |
skipped_results |
因上次响应与当前响应之间的偏移量而被跳过的结果数量。 |
explain_metrics |
查询说明指标。此属性仅在提供了 |
联合字段 continuation_selector 。查询的接续模式。如果存在,则表示当前查询响应流已完成。无论是否有 document ,您都可以进行此项设置,但在设置后,系统将不会返回更多结果。continuation_selector 只能是下列其中一项: |
|
done |
如果存在该元素,则 Firestore 已完成请求,并且不会再返回任何文档。 |
StructuredAggregationQuery
用于对 StructuredQuery
运行聚合的 Firestore 查询。
字段 | |
---|---|
aggregations[] |
可选。要应用于 需要:
|
联合字段 query_type 。要汇总的基本查询。query_type 只能是下列其中一项: |
|
structured_query |
嵌套结构化查询。 |
汇总
定义可生成单个结果的聚合。
字段 | |
---|---|
alias |
可选。用于存储汇总结果的字段的可选名称。 如果未提供,Firestore 将选择遵循
变为:
需要:
|
联合字段 operator 。要执行的汇总类型,必填。operator 只能是下列其中一项: |
|
count |
计数聚合器。 |
sum |
求和聚合器。 |
avg |
一般的集合商家。 |
Avg
所请求字段的值的平均值。
系统只会汇总数值。系统会跳过包括
NULL
在内的所有非数字值。如果聚合值包含
NaN
,则返回NaN
。无穷大数学遵循 IEEE-754 标准。如果汇总值集为空,则返回
NULL
。始终以双精度类型返回结果。
字段 | |
---|---|
field |
要汇总的字段。 |
计数
与查询匹配的文档数。
COUNT(*)
聚合函数会对整个文档执行操作,因此不需要字段引用。
字段 | |
---|---|
up_to |
可选。(可选)对要统计的文档数量上限的限制。 这提供了一种方式来设定要扫描的文档数量上限,从而限制延迟时间和费用。 未指定为无限制。 简要示例:
需要:
|
总和
所请求字段的值的总和。
系统只会汇总数值。系统会跳过包括
NULL
在内的所有非数字值。如果聚合值包含
NaN
,则返回NaN
。无穷大数学遵循 IEEE-754 标准。如果汇总值集为空,则返回 0。
如果所有汇总数据都是整数,并且求和结果不溢出,则返回 64 位整数。否则,返回的结果为双精度型。请注意,即使所有聚合值都是整数,如果结果无法放入 64 位的带符号整数,也会以双精度形式返回。如果发生这种情况,返回的值会失去精度。
发生下溢时,浮点聚合是不确定的。这意味着,如果在不更改基础值的情况下重复运行同一查询,每次的结果可能略有不同。在此类情况下,值应存储为整数而非浮点数。
字段 | |
---|---|
field |
要汇总的字段。 |
StructuredQuery
Firestore 查询。
查询阶段按以下顺序执行:1. 从 2. 其中 3. 选择 4. order_by + start_at + end_at 5. offset 6. limit
字段 | |
---|---|
select |
要返回的可选字段子集。 这充当从查询返回的文档的 |
from[] |
要查询的集合。 |
where |
要应用的过滤条件。 |
order_by[] |
要应用于查询结果的顺序。 Firestore 允许调用方提供完整排序、部分排序或完全不排序。在所有情况下,Firestore 都会通过以下规则保证稳定排序:
字段将附加与最后一个指定顺序相同的排序方向,如果未指定排序顺序,则为“ASCENDING”。例如:
|
start_at |
结果集中开始查询的位置的可能前缀。 结果集的排序基于原始查询的
此查询的结果按 游标可以引用位置的完整排序或前缀,但其引用的字段不能超过提供的 继续上面的示例,附加以下开始游标会产生不同的影响:
与需要跳过前 N 个结果的 需要:
|
end_at |
结果集中查询结束位置的潜在前缀。 这与 需要:
|
offset |
在返回第一个结果之前要跳过的文档数量。 这在 需要:
|
limit |
要返回的结果数上限。 在所有其他限制条件之后应用。 需要:
|
find_nearest |
可选。潜在的“最近邻”搜索。 在所有其他过滤条件和排序之后应用。 查找与指定查询向量最接近的向量嵌入。 |
CollectionSelector
对集合的选择,例如 messages as m1
。
字段 | |
---|---|
collection_id |
集合 ID。设置后,仅选择具有此 ID 的集合。 |
all_descendants |
如果为 false,则仅选择属于所包含 |
CompositeFilter
使用给定运算符合并多个其他过滤条件的过滤条件。
字段 | |
---|---|
op |
合并多个过滤条件的运算符。 |
filters[] |
要组合的过滤条件的列表。 需要:
|
运算符
复合过滤器运算符。
枚举 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。不得使用此值。 |
AND |
文档必须满足所有组合的过滤条件。 |
OR |
文档必须满足至少一个组合过滤条件的要求。 |
方向
排序方向。
枚举 | |
---|---|
DIRECTION_UNSPECIFIED |
未指定。 |
ASCENDING |
升序。 |
DESCENDING |
降序。 |
FieldFilter
针对特定字段的过滤条件。
字段 | |
---|---|
field |
要作为过滤条件的字段。 |
op |
作为过滤条件的运算符。 |
value |
要比较的值。 |
运算符
字段过滤器运算符。
枚举 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。不得使用此值。 |
LESS_THAN |
给定 需要:
|
LESS_THAN_OR_EQUAL |
给定 需要:
|
GREATER_THAN |
给定 需要:
|
GREATER_THAN_OR_EQUAL |
给定 需要:
|
EQUAL |
给定 field 等于给定 value 。 |
NOT_EQUAL |
给定 需要:
|
ARRAY_CONTAINS |
指定 field 是包含指定 value 的数组。 |
IN |
给定 需要:
|
ARRAY_CONTAINS_ANY |
指定 需要:
|
NOT_IN |
需要:
|
FieldReference
对文档中某个字段的引用,例如:stats.operations
。
字段 | |
---|---|
field_path |
对文档中字段的引用。 需要:
|
过滤
过滤器。
字段 | |
---|---|
联合字段 filter_type 。过滤器的类型。filter_type 只能是下列其中一项: |
|
composite_filter |
复合过滤条件。 |
field_filter |
基于文档字段的过滤条件。 |
unary_filter |
仅接受一个参数的过滤条件。 |
FindNearest
最近邻搜索配置。
字段 | |
---|---|
vector_field |
必需。要搜索的索引矢量字段。只能返回维度与 query_vector 匹配的向量的文档。 |
query_vector |
必需。我们要搜索的查询向量。必须是一个维度不超过 2048 个的矢量。 |
distance_measure |
必需。要使用的距离测量。 |
limit |
必需。要返回的最近相邻项的数量。必须是不大于 1000 的正整数。 |
DistanceMeasure
比较向量时要使用的距离度量。
枚举 | |
---|---|
DISTANCE_MEASURE_UNSPECIFIED |
不应设置。 |
EUCLIDEAN |
测量向量之间的 EUCLIDEAN 距离。如需了解详情,请参阅欧几里得 |
COSINE |
根据向量之间的角度比较向量,以便您衡量不基于向量大小的相似度。我们建议将 DOT_PRODUCT 与单位归一化向量一起使用,而不是使用 COSINE 距离,因为后者在数学上是等效的,且性能更佳。如需了解详情,请参阅余弦相似度。 |
DOT_PRODUCT |
与余弦相似,但受向量大小的影响。如需了解详情,请参阅 Dot Product。 |
订单
字段上的订单。
字段 | |
---|---|
field |
要排序的字段。 |
direction |
排序依据。默认为 |
Projection
要返回的文档字段的投影。
字段 | |
---|---|
fields[] |
要返回的字段。 如果为空,则返回所有字段。如需仅返回文档的名称,请使用 |
UnaryFilter
具有单个操作数的过滤条件。
字段 | |
---|---|
op |
要应用的一元运算符。 |
联合字段 operand_type 。过滤器的参数。operand_type 只能是下列其中一项: |
|
field |
要应用运算符的字段。 |
运算符
一元运算符。
枚举 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。不得使用此值。 |
IS_NAN |
给定的 field 等于 NaN 。 |
IS_NULL |
给定的 field 等于 NULL 。 |
IS_NOT_NAN |
给定的 需要:
|
IS_NOT_NULL |
给定的 需要:
|
目标
要监听的一组文档的规范。
字段 | |
---|---|
target_id |
用于标识流上的目标的目标 ID。必须是正数且非零。 如果 请注意,如果客户端发送多个不带 ID 的 如果 |
once |
目标是否为最新且一致的目标,是否应将其移除。 |
expected_count |
上次在恢复令牌或读取时与查询匹配的文档数量。 此值仅在提供了 |
联合字段 target_type 。要监听的目标类型。target_type 只能是下列其中一项: |
|
query |
由查询指定的目标。 |
documents |
由一组文档名称指定的目标。 |
联合字段 如果指定,则仅返回在 |
|
resume_token |
相同目标的先前 不支持使用具有不同目标的恢复令牌,此令牌可能会失败。 |
read_time |
在特定的 客户端此时必须知道匹配文档的状态。 |
DocumentsTarget
由一组文档名称指定的目标。
字段 | |
---|---|
documents[] |
要检索的文档的名称。格式为: |
QueryTarget
由查询指定的目标。
字段 | |
---|---|
parent |
父级资源名称。格式为: |
联合字段 query_type 。要运行的查询。query_type 只能是下列其中一项: |
|
structured_query |
结构化查询。 |
TargetChange
监控的目标已发生更改。
字段 | |
---|---|
target_change_type |
已发生的更改类型。 |
target_ids[] |
已更改的目标的 ID。 如果为空,所做的更改会应用于所有目标。 尚未定义目标 ID 的顺序。 |
cause |
导致此项更改的错误(如果有)。 |
resume_token |
可用于恢复给定 并非每次目标值发生更改时都进行设置。 |
read_time |
给定 每当整个数据流到达新的一致快照时,数据流都会发送包含空 对于给定的流, |
TargetChangeType
所做更改的类型。
枚举 | |
---|---|
NO_CHANGE |
未发生任何更改。仅用于发送更新后的 resume_token 。 |
ADD |
目标已添加。 |
REMOVE |
这些目标已被移除。 |
CURRENT |
这些目标反映了在将目标添加到数据流之前提交的所有更改。 此事件将在 如果需要写后读语义,监听器可以等待此变更。 |
RESET |
目标已重置,并且在后续更改中将返回目标的新初始状态。 初始状态完成后,系统将返回 |
TransactionOptions
用于创建新交易的选项。
字段 | |
---|---|
联合字段 mode 。事务的模式。mode 只能是下列其中一项: |
|
read_only |
事务只能用于读取操作。 |
read_write |
事务可用于读取和写入操作。 |
ReadOnly
只能用于读取文档的事务的选项。
字段 | |
---|---|
联合字段 consistency_selector 。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项: |
|
read_time |
读取指定时间的文档。 此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。 |
ReadWrite
可用于读取和写入文档的事务选项。
Firestore 不允许第三方身份验证请求创建读写事务。
字段 | |
---|---|
retry_transaction |
要重试的可选事务。 |
UpdateDocumentRequest
对 Firestore.UpdateDocument
的请求。
字段 | |
---|---|
document |
必需。已更新的文档。创建文档(如果文档尚不存在)。 |
update_mask |
要更新的字段。掩码中的所有字段路径均不得包含预留名称。 如果文档存在于服务器上,并且包含未在掩码中引用的字段,则这些字段保持不变。在掩码中引用,但在输入文档中不存在的字段会从服务器上的文档中删除。 |
mask |
要返回的字段。如果未设置,则返回所有字段。 如果文档中某个字段不在此掩码中,则不会在响应中返回该字段。 |
current_document |
文档的可选前提条件。如果已设置此属性,但目标文档未满足此要求,则请求将失败。 |
值
可包含任何支持的值类型的消息。
字段 | |
---|---|
联合字段 value_type 。必须设置值。value_type 只能是下列其中一项: |
|
null_value |
null 值。 |
boolean_value |
布尔值。 |
integer_value |
一个整数值。 |
double_value |
双精度值。 |
timestamp_value |
时间戳值。 仅精确到微秒。存储后,任何额外的精度都会向下舍入。 |
string_value |
字符串值。 该字符串以 UTF-8 表示,不得超过 1 MiB - 89 个字节。查询只会考虑 UTF-8 表示法的前 1500 个字节。 |
bytes_value |
字节值。 不得超过 1 MiB - 89 字节。查询只会考虑前 1500 个字节。 |
reference_value |
对文档的引用。例如: |
geo_point_value |
表示地球表面上某个点的地理位置点值。 |
array_value |
数组值。 不能直接包含另一个数组值,但可以包含另一个数组的映射。 |
map_value |
映射值。 |
书写
文档上的写入操作。
字段 | |
---|---|
update_mask |
此写入操作中要更新的字段。 只有在操作为 |
update_transforms[] |
更新后要执行的转换。 只有在操作为 |
current_document |
文档的可选前提条件。 如果已设置此属性,但目标文档未满足此要求,则写入将失败。 |
联合字段 operation 。要执行的操作。operation 只能是下列其中一项: |
|
update |
要写入的文档。 |
delete |
要删除的文档的名称。格式为: |
transform |
对文档应用转换。 |
WriteRequest
对 Firestore.Write
的请求。
第一个请求会创建一个数据流,或者从令牌恢复现有的数据流。
创建新流时,服务器会返回仅包含 ID 和令牌的响应,以便在下一个请求中使用。
恢复数据流时,服务器首先流式传输晚于指定令牌的所有响应,然后发送仅包含最新令牌的响应,以便在下一个请求中使用。
字段 | |
---|---|
database |
必需。数据库名称。格式为: |
stream_id |
要恢复的写入流的 ID。此字段只可在第一条消息中设置。如果留空,系统会创建新的写入流。 |
writes[] |
要应用的写入。 始终以原子方式按顺序执行。在第一次请求时,此字段必须为空。对于最后一个请求,此字段可能为空。对于所有其他请求,此字段不得为空。 |
stream_token |
服务器之前发送的流令牌。 客户端应将此字段设置为其最近收到的 如果未确认的响应过多,服务器可能会关闭数据流。 创建新直播时,请勿设置此字段。如需在特定时间点继续流式传输,请设置此字段和 创建新直播时,请勿设置此字段。 |
labels |
与此写入请求关联的标签。 |
WriteResponse
Firestore.Write
的响应。
字段 | |
---|---|
stream_id |
数据流的 ID。仅在创建新信息流时对第一条消息进行设置。 |
stream_token |
一个词元,表示此响应在数据流中的位置。此时,客户端可以使用它来恢复数据流。 此字段始终为设置状态。 |
write_results[] |
应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。 |
commit_time |
提交发生的时间。任何具有等于或大于 |
WriteResult
应用写入的结果。
字段 | |
---|---|
update_time |
应用写入后文档的上次更新时间。在 如果写入的数据实际上并未更改文档,则为之前的 update_time。 |
transform_results[] |
按相同顺序应用每个 |