Package google.firestore.v1

索引

• 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
rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse) 获取多个文档。 不保证此方法返回的文档会按照请求的顺序返回。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

BatchWrite
rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse) 应用批量写入操作。 BatchWrite 方法不会以原子方式应用写入操作，并可不按顺序应用这些操作。方法不允许每个文档执行多次写入。每次写入都会独立成功或失败。如需了解每次写入的成功状态，请参阅 BatchWriteResponse。 如果您需要以原子方式应用的一组写入，请改用 Commit。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

BeginTransaction
rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) 启动新事务。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

提交
rpc Commit(CommitRequest) returns (CommitResponse) 提交事务，同时选择性地更新文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

CreateDocument
rpc CreateDocument(CreateDocumentRequest) returns (Document) 新建一个文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

DeleteDocument
rpc DeleteDocument(DeleteDocumentRequest) returns (Empty) 删除文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

GetDocument
rpc GetDocument(GetDocumentRequest) returns (Document) 获取单个文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

ListCollectionIds
rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse) 列出文档下的所有集合 ID。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

ListDocuments
rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) 列出文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

聆听
rpc Listen(ListenRequest) returns (ListenResponse) 监听更改。此方法只能通过 gRPC 或 WebChannel（而非 REST）使用。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

PartitionQuery
rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse) 通过返回可用于并行运行查询的分区游标来对查询进行分区。返回的分区游标是拆分点，RunQuery 可以将其用作查询结果的起点/终点。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

回滚
rpc Rollback(RollbackRequest) returns (Empty) 回滚事务。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse) 运行聚合查询。 此 API 允许运行聚合以在服务器端生成一系列 AggregationResult，而不是生成 Firestore.RunQuery 等 Document 结果。 简要示例： -- Return the number of documents in table given a filter. SELECT COUNT(*) FROM ( SELECT * FROM k where a = true ); 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

运行查询
rpc RunQuery(RunQueryRequest) returns (RunQueryResponse) 运行查询。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

UpdateDocument
rpc UpdateDocument(UpdateDocumentRequest) returns (Document) 更新或插入文档。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

Write
rpc Write(WriteRequest) returns (WriteResponse) 按顺序流式执行批量文档更新和删除操作。此方法只能通过 gRPC 或 WebChannel（而非 REST）使用。 授权范围 需要以下 OAuth 范围之一： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

AggregationResult 类中的方法

Firestore 聚合查询返回单个存储分区的结果。

聚合查询中所有结果的 aggregate_fields 键都是相同的，这与文档查询可以为每个结果显示不同的字段不同。

字段
aggregate_fields	map<string, Value> 聚合函数的结果，例如：COUNT(*) AS total_docs。 键是针对输入分配给聚合函数的 alias，此映射的大小等于查询中聚合函数的数量。

ArrayValue

数组值。

字段
values[]	Value 数组中的值。

BatchGetDocumentsRequest

对 Firestore.BatchGetDocuments 的请求。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
documents[]	string 要检索的文档的名称。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。如有任何文档不是给定 database 的子资源，请求将失败。重复的名称会被省略。
mask	DocumentMask 要返回的字段。如果未设置，则返回所有字段。 如果文档的某个字段在此掩码中不存在，则不会在响应中返回该字段。
联合字段 consistency_selector。此事务的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
transaction	bytes 读取事务中的文档。
new_transaction	TransactionOptions 启动新事务并读取文档。默认为只读事务。新的交易 ID 将作为数据流中的第一个响应返回。
read_time	Timestamp 以给定时间原样读取文档。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

BatchGetDocumentsResponse

Firestore.BatchGetDocuments 的流式传输响应。

字段
transaction	bytes 作为此请求的一部分启动的事务。仅在第一个响应中，且仅当请求中设置了 BatchGetDocumentsRequest.new_transaction 时才会设置。
read_time	Timestamp 文档的读取时间。该值可能会单调递增，在这种情况下，结果流中的先前文档保证在其 read_time 与此时间之间没有变化。
联合字段 result。单个结果。如果服务器仅返回事务，此字段可能为空。result 只能是下列其中一项：
found	Document 所请求的文档。
missing	string 所请求的文档名称不存在。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。

BatchWriteRequest

对 Firestore.BatchWrite 的请求。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
writes[]	Write 要应用的写入。 该方法不会以原子方式应用写入，也无法保证排序。每次写入都会独立成功或失败。对于每个请求，您不能向同一文档写入多次。
labels	map<string, string> 与此批量写入关联的标签。

BatchWriteResponse

来自 Firestore.BatchWrite 的响应。

字段
write_results[]	WriteResult 应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。
status[]	Status 应用写入的状态。 第 i 个写入状态对应于请求中的第 i 个写入。

BeginTransactionRequest

对 Firestore.BeginTransaction 的请求。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
options	TransactionOptions 交易的选项。默认为读写事务。

BeginTransactionResponse

Firestore.BeginTransaction 的响应。

字段
transaction	bytes 启动的事务。

位序列

采用字节数组编码的位序列。

bitmap 字节数组中的每个字节存储序列的 8 位。唯一的例外是最后一个字节，它存储的位数可能不超过 8 位。padding 将要忽略的最后一个字节的位数定义为“填充”。这些“内边距”位未指定，必须忽略。

要检索第 1 位（即位 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	bytes 对位序列进行编码的字节。长度可能为零。
padding	int32 bitmap 中要作为“填充”忽略的最后一个字节的位数。如果 bitmap 的长度为零，则此值必须为 0。否则，此值必须介于 0 到 7 之间（包括 0 和 7）。

布鲁姆滤镜

泛光滤镜 (https://zh.wikipedia.org/wiki/Bloom_filter)。

布隆过滤器使用 MD5 对条目进行哈希处理，并将生成的 128 位哈希视为 2 个不同的 64 位哈希值，并使用 2 补码编码将其解释为无符号整数。

然后，系统会使用名为 h1 和 h2 的这两个哈希值通过以下公式计算 hash_count 哈希值（从 i=0 开始）：

h(i) = h1 + (i * h2)

然后，这些结果值将取泛泛滤波器中位元数的模数，以获取要测试的给定条目的泛光滤波器位。

字段
bits	BitSequence 泛光过滤器数据。
hash_count	int32 算法使用的哈希数量。

CommitRequest

对 Firestore.Commit 的请求。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
writes[]	Write 要应用的写入。 始终以原子方式按顺序执行。
transaction	bytes 如果设置了此字段，则会应用此事务中的所有写入，并提交它。

CommitResponse

Firestore.Commit 的响应。

字段
write_results[]	WriteResult 应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。
commit_time	Timestamp 提交发生的时间。使用等于或更大的 read_time 执行的任何读取操作都一定会看到提交的效果。

CreateDocumentRequest

对 Firestore.CreateDocument 的请求。

字段
parent	string 必需。父级资源。例如：projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}
collection_id	string 必需。要列出的集合 ID（相对于 parent）。例如：chatrooms。
document_id	string 由客户指定的要用于此文档的文档 ID。 可选。如果未指定，服务将分配一个 ID。
document	Document 必需。要创建的文档。不得设置 name。
mask	DocumentMask 要返回的字段。如果未设置，则返回所有字段。 如果文档的某个字段在此掩码中不存在，则响应中将不会返回该字段。

Cursor

查询结果集中的一个位置。

字段
values[]	Value 用于表示位置的值（按照查询的 by 子句出现的顺序）。 包含的值可以少于排序依据子句中指定的值。
before	bool 位置在给定值之前或之后（相对于查询定义的排序顺序）。

DeleteDocumentRequest

对 Firestore.DeleteDocument 的请求。

字段
name	string 必需。要删除的文档的资源名称。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。
current_document	Precondition 文档的可选前提条件。如果设置了该属性，但目标文档未满足该属性，则请求将失败。

文档

Firestore 文档。

不得超过 1 MiB - 4 个字节。

字段
name	string 文档的资源名称，例如 projects/{project_id}/databases/{database_id}/documents/{document_path}。
fields	map<string, Value>
create_time	Timestamp 仅限输出。文档的创建时间。 当文档被删除然后重新创建时，此值会单调增加。还可将其与其他文档中的值和查询的 read_time 进行比较。
update_time	Timestamp 仅限输出。上次更改文档的时间。 此值最初设置为 create_time，然后随文档的每次更改单调递增。还可将其与其他文档中的值和查询的 read_time 进行比较。

DocumentChange

Document 已更改。

可能是由多次 writes（包括删除）的结果，这些删除最终为 Document 生成了新值。

如果有多个目标受到影响，则同一逻辑更改可能会返回多条 DocumentChange 消息。

字段
document	Document Document 的新状态。 如果设置了 mask，则仅包含已更新或添加的字段。
target_ids[]	int32 与此文档匹配的目标的一组目标 ID。
removed_target_ids[]	int32 与此文档不再匹配的目标的一组目标 ID。

文档删除

已删除Document。

这可能是多个 writes（包括更新）的结果，其中最后一次更新删除了 Document。

如果有多个目标受到影响，则同一逻辑删除操作可能会返回多条 DocumentDelete 消息。

字段
document	string 已删除的 Document 的资源名称。
removed_target_ids[]	int32 之前与此实体匹配的目标的一组目标 ID。
read_time	Timestamp 观察到删除的读取时间戳。 大于或等于删除的 commit_time。

DocumentMask

文档上的一组字段路径。用于将文档上的获取或更新操作限制为文档的一部分字段。这与标准字段掩码不同，因为其范围始终限定为 Document，并考虑到了 Value 的动态特性。

字段
field_paths[]	string 掩码中的字段路径列表。如需查看字段路径语法参考信息，请参阅 Document.fields。

文档删除

Document 已从目标视图中移除。

当文档不再与定位条件相关且不在视野范围内时发送。如果服务器无法发送文档的新值，则可以发送文档，而不是 DocumentDelete 或 DocumentChange。

如果有多个目标受到影响，则同一逻辑写入或删除操作可能会返回多条 DocumentRemove 消息。

字段
document	string 不在视图范围内的 Document 的资源名称。
removed_target_ids[]	int32 之前与此文档匹配的目标的一组目标 ID。
read_time	Timestamp 观察到移除操作的读取时间戳。 大于或等于更改/删除/移除的 commit_time。

DocumentTransform

文档的转换。

字段
document	string 要转换的文档的名称。
field_transforms[]	FieldTransform 要按顺序应用于文档字段的转换列表。此字段不能为空。

FieldTransform

文档字段的转换。

字段
field_path	string 字段的路径。如需了解字段路径语法参考信息，请参阅 Document.fields。
联合字段 transform_type。要应用于字段的转换。transform_type 只能是下列其中一项：
set_to_server_value	ServerValue 将字段设置为给定的服务器值。
increment	Value 将指定值与字段的当前值相加。 此值必须是整数或双精度值。如果该字段不是整数或双精度类型，或者该字段尚不存在，转换会将该字段设置为指定值。如果指定值或当前字段值中有双精度值，则这两个值都将被解读为双精度值。双精度值的计算和表示法遵循 IEEE 754 语义。如果存在正/负整数溢出，则该字段将被解析为最大数量级的正/负整数。
maximum	Value 将字段设置为其当前值和指定值的最大值。 此值必须是整数或双精度值。如果该字段不是整数或双精度类型，或者该字段尚不存在，转换会将该字段设置为指定值。如果在字段和输入值是混合类型（即一个为整数，一个为双精度）时应用最大运算，则该字段将采用较大运算数的类型。如果操作数等效（例如 3 和 3.0），则该字段不会更改。0、0.0 和 -0.0 全部为零。零存储值和零输入值的最大值始终为存储值。任何数值 x 和 NaN 的最大值为 NaN。
minimum	Value 将字段设置为其当前值和指定值的最小值。 此值必须是整数或双精度值。如果该字段不是整数或双精度类型，或者该字段尚不存在，转换会将该字段设置为输入值。如果在字段和输入值是混合类型（即一个为整数，一个为双精度）时应用最小运算，则该字段将采用较小运算数的类型。如果操作数等效（例如 3 和 3.0），则该字段不会更改。0、0.0 和 -0.0 全部为零。零存储值和零输入值的最小值始终为存储值。任何数值 x 和 NaN 的最小值为 NaN。
append_missing_elements	ArrayValue 如果给定元素在当前字段值中不存在，请按顺序附加这些元素。如果该字段不是数组，或者该字段尚不存在，则首先将其设置为空数组。 在检查某个值是否缺失时，系统会将不同类型（例如 3L 和 3.0）的等效数值视为相等。NaN 等于 NaN，且 Null 等于 Null。如果输入包含多个等值值，则仅考虑第一个值。 相应的 transform_result 将为 null 值。
remove_all_from_array	ArrayValue 从该字段的数组中移除所有给定元素。如果该字段不是数组，或者该字段尚不存在，则设置为空数组。 在决定是否应移除某个元素时，系统会将不同类型（例如 3L 和 3.0）的等效数值视为相等。NaN 等于 NaN，且 Null 等于 Null。如果存在重复项，这将移除所有等效值。 相应的 transform_result 将为 null 值。

ServerValue

由服务器计算的值。

枚举
SERVER_VALUE_UNSPECIFIED	未指定。不得使用此值。
REQUEST_TIME	服务器处理请求的时间（精确到毫秒）。如果在事务中的多个字段（相同或不同的文档）上使用，所有字段都将获得相同的服务器时间戳。

ExecutionStats

查询的执行统计信息。

字段
results_returned	int64 返回的结果总数，包括文档、投影、聚合结果、键。
execution_duration	Duration 在后端执行查询的总时间。
read_operations	int64 计费读取操作总数。
debug_stats	Struct 调试执行查询后的统计信息。请注意，调试统计信息会随着 Firestore 的发展而发生变化。这可能包括：{ "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details": { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0"} }

ExistenceFilter

符合指定目标的所有文档的摘要。

字段
target_id	int32 此过滤条件适用的目标 ID。
count	int32 与 target_id 匹配的文档总数。 如果与客户端中匹配的文档数量不同，客户端必须手动确定哪些文档不再与目标匹配。 客户端可以使用 unchanged_names 泛光过滤器通过测试所有文档名称来辅助确定该过滤器；如果文档名称不在过滤器中，则意味着该文档不再与目标匹配。
unchanged_names	BloomFilter 一个布鲁姆过滤器（尽管名称如此），它包含匹配 target_id 的所有文档的资源名称的 UTF-8 字节编码，格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。 服务器可以自行决定忽略此泛光过滤器，例如当认为客户端不会使用它，或者如果计算或传输的计算开销过高，就可以忽略此过滤器。客户端必须通过回退到此字段存在之前使用的逻辑来妥善处理此字段不存在的情况；也就是说，在不使用恢复令牌的情况下重新添加目标，以找出客户端缓存中的哪些文档不同步。

说明指标

说明查询的指标。

字段
plan_summary	PlanSummary 查询的规划阶段信息。
execution_stats	ExecutionStats 执行查询后的汇总统计信息。仅当 ExplainOptions.analyze 设为 true 时才显示。

ExplainOptions

解释查询的选项。

字段
analyze	bool 可选。是否执行此查询。 如果为 false（默认值），系统将对查询进行规划，仅返回规划阶段的指标。 如果为 true，系统将规划和执行查询，并返回完整的查询结果以及规划和执行阶段指标。

GetDocumentRequest

对 Firestore.GetDocument 的请求。

字段
name	string 必需。要获取的文档的资源名称。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。
mask	DocumentMask 要返回的字段。如果未设置，则返回所有字段。 如果文档的某个字段在此掩码中不存在，则响应中将不会返回该字段。
联合字段 consistency_selector。此事务的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
transaction	bytes 在事务中读取文档。
read_time	Timestamp 读取指定时间的文档版本。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

ListCollectionIdsRequest

对 Firestore.ListCollectionIds 的请求。

字段
parent	string 必需。父级文档。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。例如 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
page_size	int32 要返回的结果数上限。
page_token	string 页面令牌。必须是 ListCollectionIdsResponse 中的值。
联合字段 consistency_selector。此请求的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
read_time	Timestamp 以给定时间原样读取文档。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

列表集合 ID 响应

来自 Firestore.ListCollectionIds 的响应。

字段
collection_ids[]	string 集合 ID。
next_page_token	string 可用于继续列出列表的页面令牌。

ListDocumentsRequest

对 Firestore.ListDocuments 的请求。

字段
parent	string 必需。父级资源名称。格式为 projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/{document_path}。 例如：projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
collection_id	string 可选。要列出的集合 ID（相对于 parent）。 例如：chatrooms 或 messages。 此字段是可选的；如果未提供，Firestore 将列出所提供的 parent 下所有集合中的文档。
page_size	int32 可选。单个响应中可返回的最大文档数。 Firestore 返回的值可能会少于此值。
page_token	string 可选。从上一个 ListDocuments 响应收到的页面令牌。 提供此令牌以检索后续页面。进行分页时，所有其他参数（page_size 除外）必须与生成页面令牌的请求中设置的值一致。
order_by	string 可选。要返回的文档的可选顺序。 例如：priority desc, __name__ desc。 这反映了 Firestore 查询中使用的 ORDER BY，但使用的是字符串表示形式。如果缺少此参数，文档将按照 __name__ ASC 排序。
mask	DocumentMask 可选。要返回的字段。如果未设置，则返回所有字段。 如果文档的某个字段在此掩码中不存在，则不会在响应中返回该字段。
show_missing	bool 列表是否应显示缺失文件。 如果某个文档不存在，但其下嵌套了子文档，则该文档就缺失。如果为 true，此类缺失的文档将返回键，但不会设置字段、create_time 或 update_time。 带有 show_missing 的请求不能指定 where 或 order_by。
联合字段 consistency_selector。此事务的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
transaction	bytes 将读取作为已处于活动状态的事务的一部分执行。
read_time	Timestamp 在提供的时间执行读取操作。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

ListDocumentsResponse

Firestore.ListDocuments 的响应。

字段
documents[]	Document 已找到文档。
next_page_token	string 用于检索下一页文档的令牌。 如果省略此字段，则不存在后续页面。

ListenRequest

对 Firestore.Listen 的请求

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
labels	map<string, string> 与此目标更改相关联的标签。
联合字段 target_change。支持的目标更改。target_change 只能是下列其中一项：
add_target	Target 要添加到此数据流的目标。
remove_target	int32 要从此数据流中移除的目标的 ID。

监听响应

Firestore.Listen 的响应。

字段
联合字段 response_type。支持的响应。response_type 只能是下列其中一项：
target_change	TargetChange 目标已更改。
document_change	DocumentChange Document 已更改。
document_delete	DocumentDelete 已删除Document。
document_remove	DocumentRemove Document已从目标中移除（因为它不再与该定位条件相关）。
filter	ExistenceFilter 要应用于之前为指定目标返回的一组文档的过滤条件。 当文档可能已从指定目标中移除，但确切文档未知时，系统会返回此错误代码。

映射值

映射值。

字段
fields	map<string, Value> 地图的字段。 映射键表示字段名称。与正则表达式 __.*__ 匹配的字段名称已被保留。禁止使用预留的字段名称，某些已记录的上下文除外。以 UTF-8 表示的映射键不得超过 1,500 个字节，且不得为空。

PartitionQueryRequest

对 Firestore.PartitionQuery 的请求。

字段
parent	string 必需。父级资源名称。格式为 projects/{project_id}/databases/{database_id}/documents。文档资源名称不受支持；只能指定数据库资源名称。
partition_count	int64 所需的分区点数量上限。分区可能会跨多页结果返回。该数字必须为正数。返回的实际分区数可能会少一些。 例如，此值可以设置为比要运行的并行查询数量少一个，或者在运行数据流水线作业时，设置为比可用的工作器或计算实例数量少一个。
page_token	string 之前调用 PartitionQuery 返回的 next_page_token 值，该值可用于获取一组额外的结果。结果集之间没有排序保证。因此，使用多组结果需要合并不同的结果集。 例如，使用 page_token 的两次后续调用可能会返回： 光标 B、光标 M、光标 Q 光标 A、光标 U、光标 W 要获得按照提供给 PartitionQuery 的查询结果进行排序的完整结果集，应合并结果集：游标 A、游标 B、游标 M、游标 Q、游标 U、游标 W
page_size	int32 此调用中要返回的最大分区数，受 partition_count 约束。 例如，如果 partition_count = 10 且 page_size = 8，则首次调用 PartitionQuery 时最多返回 8 个分区；如果存在更多结果，则返回 next_page_token。第二次调用 PartitionQuery 将返回最多 2 个分区，完成 partition_count 中指定的总共 10 个分区。
联合字段 query_type。要分区的查询。query_type 只能是下列其中一项：
structured_query	StructuredQuery 结构化查询。查询必须指定包含所有后代的集合，并按名称升序排序。不支持其他过滤条件、排序依据、限值、偏移量和开始/结束游标。
联合字段 consistency_selector。此请求的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
read_time	Timestamp 以给定时间原样读取文档。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

PartitionQueryResponse

Firestore.PartitionQuery 的响应。

字段
partitions[]	Cursor 分区结果。每个分区都是一个拆分点，RunQuery 可以使用它作为查询结果的起点或终点。发出 RunQuery 请求时，必须使用提供给此 PartitionQuery 请求的相同查询。分区游标将按照与提供给 PartitionQuery 的查询结果相同的排序进行排序。 例如，如果 PartitionQuery 请求返回分区游标 A 和 B，则运行以下三个查询将返回原始查询的整个结果集： 查询，end_at A 查询，在 A 开始，在 B 结束 查询，start_at B 空结果可能表示该查询包含的结果太少，无法进行分区，或者该查询尚不支持分区。
next_page_token	string 可用于请求一组额外结果的页面令牌，最多可使用 PartitionQuery 请求中 partition_count 指定的数量。如果留空，则表示没有更多结果。

计划摘要

查询的规划阶段信息。

字段
indexes_used[]	Struct 为查询选择的索引。例如：[ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

前提条件

文档的前提条件，用于条件操作。

字段
联合字段 condition_type。前提条件的类型。condition_type 只能是下列其中一项：
exists	bool 如果设置为 true，目标文档必须存在。设置为 false 时，目标文档不得存在。
update_time	Timestamp 设置后，目标文档必须存在，并且在该时间的上次更新时间。时间戳必须与微秒对齐。

RollbackRequest

对 Firestore.Rollback 的请求。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。
transaction	bytes 必需。要回滚的事务。

RunAggregationQueryRequest

对 Firestore.RunAggregationQuery 的请求。

字段
parent	string 必需。父级资源名称。格式为 projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/{document_path}。例如：projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
explain_options	ExplainOptions 可选。解释查询的选项。如果设置，将返回其他查询统计信息。否则，系统只会返回查询结果。
联合字段 query_type。要运行的查询。query_type 只能是下列其中一项：
structured_aggregation_query	StructuredAggregationQuery 聚合查询。
联合字段 consistency_selector。查询的一致性模式默认为强一致性。consistency_selector 只能是下列其中一项：
transaction	bytes 在已处于活跃状态的事务中运行聚合。 此处的值是用于执行查询的不透明事务 ID。
new_transaction	TransactionOptions 作为查询的一部分启动一个新事务，默认为只读。 新的交易 ID 将作为数据流中的第一个响应返回。
read_time	Timestamp 在给定的时间戳执行查询。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

RunAggregationQueryResponse

Firestore.RunAggregationQuery 的响应。

字段
result	AggregationResult 单个汇总结果。 报告部分进度时不会显示。
transaction	bytes 作为此请求的一部分启动的事务。 仅当请求请求启动新事务时，才出现在第一个响应中。
read_time	Timestamp 计算汇总结果的时间。该值始终是单调递增的；在这种情况下，结果流中的前一个 AggregationResult 保证在其 read_time 和此版本之间不发生变化。 如果查询未返回任何结果，系统将发送包含 read_time 但不返回 result 的响应，这表示查询的运行时间。
explain_metrics	ExplainMetrics 查询说明指标。仅当提供了 RunAggregationQueryRequest.explain_options 时，此字段才会显示，并且它仅随数据流中的最后一个响应发送一次。

RunQueryRequest

对 Firestore.RunQuery 的请求。

字段
parent	string 必需。父级资源名称。格式为 projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/{document_path}。例如：projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
explain_options	ExplainOptions 可选。解释查询的选项。如果设置，将返回其他查询统计信息。否则，系统只会返回查询结果。
联合字段 query_type。要运行的查询。query_type 只能是下列其中一项：
structured_query	StructuredQuery 结构化查询。
联合字段 consistency_selector。此事务的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
transaction	bytes 在已处于活跃状态的事务中运行查询。 此处的值是用于执行查询的不透明事务 ID。
new_transaction	TransactionOptions 启动新事务并读取文档。默认为只读事务。新的交易 ID 将作为数据流中的第一个响应返回。
read_time	Timestamp 以给定时间原样读取文档。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

RunQueryResponse

Firestore.RunQuery 的响应。

字段
transaction	bytes 作为此请求的一部分启动的事务。只能在第一个响应中设置，并且只能在请求中设置了 RunQueryRequest.new_transaction 时设置。如果已设置，则不会在此响应中设置任何其他字段。
document	Document 查询结果，报告部分进度时未设置。
read_time	Timestamp 文档的读取时间。这可能会单调递增；在这种情况下，结果流中的先前文档保证在其 read_time 与当前文档之间不会发生变化。 如果查询未返回任何结果，系统将发送包含 read_time 但不返回 document 的响应，这表示查询的运行时间。
skipped_results	int32 因上一个响应与当前响应之间的偏移量而跳过的结果数。
explain_metrics	ExplainMetrics 查询说明指标。仅当提供了 RunQueryRequest.explain_options 时，此字段才会显示，并且它仅随数据流中的最后一个响应发送一次。
联合字段 continuation_selector。查询的延续模式。如果存在，则表示当前查询响应流已完成。无论是否存在 document，都可以设置此字段，但设置后，系统便不会返回更多结果。continuation_selector 只能是下列其中一项：
done	bool 如果存在，则 Firestore 已完成请求，并且不会返回更多文档。

StructuredAggregationQuery

Firestore 查询，用于对 StructuredQuery 运行聚合。

字段
aggregations[]	Aggregation 可选。要对 structured_query 的结果应用的一系列聚合。 需要： 每个查询最少包含五项汇总，最多五项。
联合字段 query_type。要汇总的基本查询。query_type 只能是下列其中一项：
structured_query	StructuredQuery 嵌套的结构化查询。

聚合

定义可生成单个结果的聚合。

字段
alias	string 可选。用于存储聚合结果的字段的可选名称。 如果未提供，Firestore 将选择一个遵循 field_<incremental_id++> 格式的默认名称。例如： AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2), COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) OVER ( ... ); 会变为： AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2) AS field_1, COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) AS field_2 OVER ( ... ); 需要： 在所有汇总别名中必须是唯一的。 符合 document field name 限制。
联合字段 operator。要执行的汇总类型，必填。operator 只能是下列其中一项：
count	Count 计数聚合器。
sum	Sum 总和聚合器。
avg	Avg 平均集合商家。

平均

所请求字段的值的平均值。

• 系统只会汇总数值。系统会跳过包括 NULL 在内的所有非数字值。

• 如果汇总值包含 NaN，则返回 NaN。无穷大数学遵循 IEEE-754 标准。

• 如果汇总值集为空，则返回 NULL。

• 始终以双精度类型返回结果。

字段
field	FieldReference 要汇总的字段。

计数

与查询匹配的文档数。

COUNT(*) 聚合函数可对整个文档执行运算，因此它不需要字段引用。

字段
up_to	Int64Value 可选。对要计数的文档数量上限的可选限制。 此方法可用于设置要扫描的文档数量的上限，以限制延迟时间和费用。 Unspecified 会被视为无限制。 简要示例： AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k ); 需要： 如果存在，必须大于零。

总和

所请求字段的值的总和。

• 系统只会汇总数值。系统会跳过包括 NULL 在内的所有非数字值。

• 如果汇总值包含 NaN，则返回 NaN。无穷大数学遵循 IEEE-754 标准。

• 如果汇总值集为空，则返回 0。

• 如果所有汇总数字均为整数，且求和结果没有溢出，则返回 64 位整数。否则，结果将作为双精度值返回。请注意，即使所有汇总值都是整数，如果无法放入 64 位带符号的整数，也会以双精度类型的值返回结果。如果发生这种情况，返回的值将失去精度。

• 发生下溢时，浮点汇总是不确定的。这意味着，重复运行同一查询而不更改基础值，每次可能会产生略有不同的结果。在这些情况下，值应该存储为整数而不是浮点数。

字段
field	FieldReference 要汇总的字段。

StructuredQuery

Firestore 查询。

查询阶段按以下顺序执行：1. from 2. where 3. select 4. order_by + start_at + end_at 5. offset 6. limit

字段
select	Projection 要返回的可选字段子集。 这充当从查询返回的文档的 DocumentMask。如果未设置，则假定调用方希望返回所有字段。
from[]	CollectionSelector 要查询的集合。
where	Filter 要应用的过滤条件。
order_by[]	Order 要应用于查询结果的顺序。 Firestore 允许调用方提供完整排序、部分排序或根本不排序。在任何情况下，Firestore 都通过以下规则保证稳定的排序： 引用不等性过滤条件使用的所有字段时需要使用 order_by。 所有需要包含在 order_by 中但尚不存在的字段都会按照字段名称的字典顺序附加。 如果未指定 __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”
start_at	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 子句中指定的字段数量。
end_at	Cursor 结果集中某个位置的可能前缀，用于在结果中结束查询。 这与 START_AT 类似，但前者控制结束位置，而不是起始位置。 需要： 值的数量不能大于 ORDER BY 子句中指定的字段数量。
offset	int32 返回第一个结果之前要跳过的文档数。 这在 WHERE、START AT 和END AT 但在 LIMIT 子句之前。 需要： 该值必须大于或等于零（如果指定）。
limit	Int32Value 要返回的结果数上限。 在所有其他限制条件后应用。 需要： 该值必须大于或等于零（如果指定）。
find_nearest	FindNearest 可选。潜在最近邻搜索。 在所有其他过滤条件和排序后应用。 查找与给定查询向量最接近的向量嵌入。

CollectionSelector

一个集合，例如 messages as m1。

字段
collection_id	string 集合 ID。设置后，仅选择具有此 ID 的集合。
all_descendants	bool 如果为 false，则仅选择作为所属 RunQueryRequest 中指定的 parent 的直接子项的集合。如果为 true，则选择所有后代集合。

CompositeFilter

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

字段
op	Operator 合并多个过滤条件的运算符。
filters[]	Filter 要组合的过滤条件列表。 需要： 至少存在一个过滤条件。

运算符

复合过滤器运算符。

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

方向

排序方向。

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

FieldFilter

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

字段
field	FieldReference 要用作过滤条件的字段。
op	Operator 要作为过滤依据的运算符。
value	Value 要比较的值。

运算符

字段过滤条件运算符。

枚举
OPERATOR_UNSPECIFIED	未指定。不得使用此值。
LESS_THAN	指定的 field 小于指定的 value。 需要： “field”在order_by中名列前茅。
LESS_THAN_OR_EQUAL	给定的 field 小于或等于给定的 value。 需要： “field”在order_by中名列前茅。
GREATER_THAN	指定的field大于指定的value。 需要： “field”在order_by中名列前茅。
GREATER_THAN_OR_EQUAL	指定的 field 大于或等于指定的 value。 需要： “field”在order_by中名列前茅。
EQUAL	指定的 field 等于指定的 value。
NOT_EQUAL	指定的 field 不等于指定的 value。 需要： 无其他NOT_EQUAL、NOT_IN、IS_NOT_NULL或IS_NOT_NAN。 field 在 order_by 中排在第一位。
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 在 order_by 中排在第一位。

FieldReference

对文档中某个字段的引用，例如：stats.operations。

字段
field_path	string 对文档中某个字段的引用。 需要： 必须是以英文句点分隔 (.) 的片段字符串，其中每个片段都符合 document field name 限制。

过滤

过滤器。

字段
联合字段 filter_type。过滤器的类型。filter_type 只能是下列其中一项：
composite_filter	CompositeFilter 复合过滤条件。
field_filter	FieldFilter 针对文档字段的过滤条件。
unary_filter	UnaryFilter 只接受一个参数的过滤器。

查找最近的地点

最近邻搜索配置。

字段
vector_field	FieldReference 必需。要搜索的矢量字段。只能返回维度与 query_vector 匹配的向量的文档。
query_vector	Value 必需。我们正在执行搜索的查询矢量。必须是不超过 2048 个维度的矢量。
distance_measure	DistanceMeasure 必需。要使用的距离计量单位，必填。
limit	Int32Value 必需。要返回的最近相邻项的数量。必须是不大于 1000 的正整数。

距离测量

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

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

顺序

字段上的订单。

字段
field	FieldReference 排序依据的字段。
direction	Direction 排序依据的方向。默认值为 ASCENDING。

投影

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

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

一元过滤器

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

字段
op	Operator 要应用的一元运算符。
联合字段 operand_type。过滤器的参数。operand_type 只能是下列其中一项：
field	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 在 order_by 中排在第一位。
IS_NOT_NULL	给定的 field 不等于 NULL。 需要： 单个 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。 field 在 order_by 中排在第一位。

定位

要监听的一组文档的规范。

字段
target_id	int32 用于标识数据流中的目标的目标 ID。必须是非零的正数。 如果 target_id 为 0（或未指定），服务器将为此目标分配 ID，并在 TargetChange::ADD 事件中返回该 ID。添加具有 target_id=0 的目标后，所有后续目标也必须具有 target_id=0。如果在添加具有 target_id=0 的目标后向服务器发送带有 target_id != 0 的 AddTarget 请求，服务器将立即发送包含 TargetChange::Remove 事件的响应。 请注意，如果客户端发送多个不带 ID 的 AddTarget 请求，则 TargetChage.target_ids 中返回的 ID 顺序是未定义的。因此，客户端应提供目标 ID，而不是依靠服务器分配目标 ID。 如果 target_id 为非零值，则此数据流中不得存在具有相同 ID 的有效目标。
once	bool 目标在保持最新状态且一致后是否应将其移除。
expected_count	Int32Value 继续令牌或读取时最后一次与查询匹配的文档数。 只有在提供 resume_type 时，此值才相关。该值存在且大于零表示客户端希望 ExistenceFilter.unchanged_names 包含在响应中。
联合字段 target_type。要监听的目标类型。target_type 只能是下列其中一项：
query	QueryTarget 由查询指定的目标。
documents	DocumentsTarget 由一组文档名称指定的目标。
联合字段 resume_type。何时开始收听。 如果指定，则系统将仅返回在 resume_token 或 read_time 之后更新的匹配文档。否则，将先返回所有匹配的文档，然后再进行任何后续更改。resume_type 只能是下列其中一项：
resume_token	bytes 来自同一目标的先前 TargetChange 的恢复令牌。 系统不支持将恢复令牌用于其他目标，因此可能会失败。
read_time	Timestamp 在特定 read_time 之后开始监听。 客户端必须知道目前匹配文档的状态。

文档目标

由一组文档名称指定的目标。

字段
documents[]	string 要检索的文档的名称。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。如有任何文档不是给定 database 的子资源，请求将失败。重复的名称会被省略。

查询目标

由查询指定的目标。

字段
parent	string 父级资源名称。格式为 projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/{document_path}。例如：projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
联合字段 query_type。要运行的查询。query_type 只能是下列其中一项：
structured_query	StructuredQuery 结构化查询。

目标值更改

正在监控的目标已更改。

字段
target_change_type	TargetChangeType 已发生的更改的类型。
target_ids[]	int32 已更改的目标的目标 ID。 如果为空，更改会应用于所有目标。 未定义定位条件 ID 的顺序。
cause	Status 导致此项更改的错误（如果适用）。
resume_token	bytes 可用于为指定 target_ids 恢复数据流的令牌，如果 target_ids 为空，则可用于恢复所有目标的数据流。 并非每次更改目标值时都设置。
read_time	Timestamp 给定 target_ids 的一致 read_time（当 target_ids 不在一致的快照中时，应省略）。 每当整个数据流到达新的一致快照时，该数据流都必须发送 target_ids 为空的 read_time。ADD、CURRENT 和 RESET 消息保证（最终）生成新的一致快照（而 NO_CHANGE 和 REMOVE 消息则不能）。 对于给定的流，read_time 必定是单调递增的。

目标更改类型

所做更改的类型。

枚举
NO_CHANGE	未发生任何更改。仅用于发送更新后的 resume_token。
ADD	已添加目标。
REMOVE	这些目标已删除。
CURRENT	这些目标反映了在将目标添加到数据流之前提交的所有更改。 此请求将在 read_time 之后发送，或随 read_time 大于或等于添加目标的时间一起发送。 如果需要“写入后读”语义，监听器可以等待此更改。
RESET	目标已重置，系统将在后续更改中返回目标的新初始状态。 初始状态完成后，即使之前指示目标为 CURRENT，系统也会返回 CURRENT。

TransactionOptions

用于创建新交易的选项。

字段
联合字段 mode。交易的模式。mode 只能是下列其中一项：
read_only	ReadOnly 事务只能用于读取操作。
read_write	ReadWrite 事务可用于读写操作。

只读

仅用于读取文档的事务的选项。

字段
联合字段 consistency_selector。此事务的一致性模式。如果未设置，则默认为强一致性。consistency_selector 只能是下列其中一项：
read_time	Timestamp 在给定时间读取文档。 该时间戳必须是过去 1 小时内精确到微秒的时间戳，或者如果启用了时间点恢复，也可以是过去 7 天内整分钟的时间戳。

读写

可用于读取和写入文档的事务的选项。

Firestore 不允许第三方身份验证请求创建读写操作。交易。

字段
retry_transaction	bytes 要重试的可选事务。

更新文档请求

对 Firestore.UpdateDocument 的请求。

字段
document	Document 必需。已更新的文档。如果文档不存在，则创建该文档。
update_mask	DocumentMask 要更新的字段。掩码中的所有字段路径均不得包含预留名称。 如果文档存在于服务器上，并且有字段未在掩码中引用，则这些字段将保持不变。系统会将掩码中引用但未显示在输入文档中的字段从服务器上的文档中删除。
mask	DocumentMask 要返回的字段。如果未设置，则返回所有字段。 如果文档的某个字段在此掩码中不存在，则响应中将不会返回该字段。
current_document	Precondition 文档的可选前提条件。如果设置了该属性，但目标文档未满足该属性，则请求将失败。

值

可以包含任何支持的值类型的消息。

字段
联合字段 value_type。必须设置值。value_type 只能是下列其中一项：
null_value	NullValue null 值。
boolean_value	bool 布尔值。
integer_value	int64 整数值。
double_value	double 双精度值。
timestamp_value	Timestamp 时间戳值。 只能精确到微秒。存储时，任何额外的精度都会向下舍入。
string_value	string 字符串值。 以 UTF-8 表示的字符串不得超过 1 MiB - 89 个字节。查询只会考虑 UTF-8 表示法的前 1500 个字节。
bytes_value	bytes 一个字节值。 不得超过 1 MiB - 89 个字节。查询只会考虑前 1,500 个字节。
reference_value	string 对文档的引用。例如：projects/{project_id}/databases/{database_id}/documents/{document_path}。
geo_point_value	LatLng 表示地球表面上某个点的地理点值。
array_value	ArrayValue 数组值。 不能直接包含其他数组值，但可以包含包含另一个数组的映射。
map_value	MapValue 映射值。

Write

在文档上撰写的内容。

字段
update_mask	DocumentMask 本次写入中要更新的字段。 仅当操作为 update 时才能设置此字段。如果没有为 update 设置掩码，并且文档存在，则任何现有数据都将被覆盖。如果已设置掩码，但服务器上的文档具有该掩码未覆盖的字段，则这些字段将保持不变。系统会将掩码中引用但未显示在输入文档中的字段从服务器上的文档中删除。此掩码中的字段路径不得包含预留字段名称。
update_transforms[]	FieldTransform 更新后要执行的转换。 仅当操作为 update 时才能设置此字段。如果存在，则此写入等同于以原子方式按顺序对同一文档执行 update 和 transform。
current_document	Precondition 文档的可选前提条件。 如果设置了该属性，但目标文档未满足该属性，则写入将失败。
联合字段 operation。要执行的操作。operation 只能是下列其中一项：
update	Document 要写入的文档。
delete	string 要删除的文档名称。格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}。
transform	DocumentTransform 对文档应用转换。

写入请求

对 Firestore.Write 的请求。

第一个请求会创建一个数据流，或者从令牌恢复现有的数据流。

创建新数据流时，服务器会返回仅包含 ID 和令牌的响应，以供下一个请求使用。

恢复数据流时，服务器首先流式传输晚于给定令牌的所有响应，然后流式传输仅包含最新令牌的响应，以便在下一个请求中使用。

字段
database	string 必需。数据库名称。格式为 projects/{project_id}/databases/{database_id}。只有在第一条消息中才需要执行此操作。
stream_id	string 要恢复的写入流的 ID。此字段只能在第一条消息中设置。如果留空，系统会创建新的写入流。
writes[]	Write 要应用的写入。 始终以原子方式按顺序执行。首次请求时，此字段必须为空。在最后一个请求中，此字段可能为空。对于所有其他请求，此字段不得为空。
stream_token	bytes 服务器之前发送的流令牌。 客户端应将此字段设置为其最近收到的 WriteResponse 中的令牌。这将确认客户端已收到至此令牌的响应。发送此令牌后，可能不会再使用之前的令牌。 如果有太多未确认的响应，服务器可能会关闭该数据流。 创建新的直播时，请勿设置此字段。如需在特定时间点恢复数据流，请设置此字段和 stream_id 字段。 创建新的直播时，请勿设置此字段。
labels	map<string, string> 与此写入请求关联的标签。

写入响应

Firestore.Write 的响应。

字段
stream_id	string 数据流的 ID。仅在创建新信息流时为第一条消息设置。
stream_token	bytes 表示此响应在流中的位置的令牌。此时，客户端可以使用它来恢复数据流。 此字段始终设置。
write_results[]	WriteResult 应用写入的结果。 第 i 个写入结果对应于请求中的第 i 个写入。
commit_time	Timestamp 提交发生的时间。使用等于或更大的 read_time 执行的任何读取操作都一定会看到写入的效果。

WriteResult

应用写入操作的结果。

字段
update_time	Timestamp 应用写入后文档的上次更新时间。在 delete 之后未设置。 如果写入实际上并未更改文档，则将是之前的 update_time。
transform_results[]	Value 按相同顺序应用每个 DocumentTransform.FieldTransform 的结果。