Package google.firestore.v1beta1

索引

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

如需了解详情,请参阅身份验证概览

RunQuery

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

如需了解详情,请参阅身份验证概览

书写

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

按指定时间读取文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 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

启动的事务。

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

bytes

对位序列进行编码的字节。长度为零。

padding

int32

bitmap 中要作为“填充”忽略的最后一个字节的位数。如果 bitmap 的长度为零,则此值必须为 0。否则,此值必须介于 0 和 7 之间(含 0 和 7)。

BloomFilter

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

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

然后,这两个哈希值(名为 h1h2)会用于使用公式计算 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}/documentsprojects/{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

表示位置的值,按照它们在查询的 order by 子句中出现的顺序进行。

包含的值可以少于 order 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。

DocumentDelete

已删除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

DocumentRemove

从目标视图中移除了 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 的发展而发生变化。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

int32

要应用此过滤条件的目标 ID。

count

int32

target_id 匹配的文档总数。

如果与客户端中匹配的文档数量不同,客户端必须手动确定哪些文档不再与目标匹配。

客户端可以使用 unchanged_names 的“繁花”过滤器来帮助确定这一点,方法是对照该过滤器测试所有文档名称;如果文档名称不在过滤器中,则表示该文档不再与目标匹配。

unchanged_names

BloomFilter

泛光过滤器(尽管名称)包含匹配 target_id 的所有文档的资源名称的 UTF-8 字节编码,格式为 projects/{project_id}/databases/{database_id}/documents/{document_path}

服务器可以自行决定省略此泛光过滤器,例如如果认为客户端不会使用该过滤器,或者计算或传输它的计算或传输成本过高。客户端必须通过回退到此字段存在之前所用的逻辑,妥善处理该字段;也就是说,在没有恢复令牌的情况下重新添加目标,以确定客户端缓存中的哪些文档不同步。

ExplainMetrics

说明查询的指标。

字段
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

读取指定时间的文档版本。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 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

按指定时间读取文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。

ListCollectionIdsResponse

来自 Firestore.ListCollectionIds 的响应。

字段
collection_ids[]

string

集合 ID。

next_page_token

string

可用于继续列出列表的页面令牌。

ListDocumentsRequest

Firestore.ListDocuments 的请求。

字段
parent

string

必需。父级资源名称。格式为:projects/{project_id}/databases/{database_id}/documentsprojects/{project_id}/databases/{database_id}/documents/{document_path}

例如:projects/my-project/databases/my-database/documentsprojects/my-project/databases/my-database/documents/chatrooms/my-chatroom

collection_id

string

可选。要列出的集合 ID(相对于 parent)。

例如:chatroomsmessages

这是可选内容;如果未提供,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_timeupdate_time

带有 show_missing 的请求不能指定 whereorder_by

联合字段 consistency_selector。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项:
transaction

bytes

作为已活跃事务的一部分执行读取。

read_time

Timestamp

在提供的时间执行读取操作。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 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。

ListenResponse

Firestore.Listen 的响应。

字段
联合字段 response_type。支持的响应。response_type 只能是下列其中一项:
target_change

TargetChange

目标已更改。

document_change

DocumentChange

Document 发生了变化。

document_delete

DocumentDelete

已删除Document

document_remove

DocumentRemove

已从目标中移除 Document(因为它不再与该目标相关)。

filter

ExistenceFilter

要应用于之前针对指定目标返回的该组文档集的过滤条件。

当文档可能已从指定目标中移除,但具体文档未知时,系统会返回此值。

MapValue

映射值。

字段
fields

map<string, Value>

地图的字段。

映射键表示字段名称。与正则表达式 __.*__ 匹配的字段名称已预留。禁止使用保留字段名称,某些规定的上下文除外。映射键(以 UTF-8 格式表示)不得超过 1,500 个字节,并且不能为空。

PartitionQueryRequest

Firestore.PartitionQuery 的请求。

字段
parent

string

必需。父级资源名称。格式为:projects/{project_id}/databases/{database_id}/documents。不支持文档资源名称;只能指定数据库资源名称。

partition_count

int64

所需的最大分区点数。分区可能会跨多个结果页面返回。该数字必须为正数。返回的实际分区数可能会少一些。

例如,可设置为比要运行的并行查询数量少 1,或者在运行数据流水线作业时,设置为比可用工作器或计算实例的数量少 1。

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

按指定时间读取文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。

PartitionQueryResponse

Firestore.PartitionQuery 的响应。

字段
partitions[]

Cursor

分区结果。每个分区都是一个拆分点,RunQuery 可将其用作查询结果的起点或终点。发出 RunQuery 请求时必须使用提供给此 PartitionQuery 请求的查询。分区游标将按照与提供给 PartitionQuery 的查询结果相同的顺序进行排序。

例如,如果 PartitionQuery 请求返回分区游标 A 和 B,则运行以下三个查询将返回原始查询的整个结果集:

  • 查询,A 结尾
  • query、start_at A、end_at B
  • 查询,start_at B

空结果可能表示查询的结果太少,无法分区,或者查询尚不支持分区。

next_page_token

string

一个页面令牌,可用于请求一组额外的结果,最多为 PartitionQuery 请求中的 partition_count 指定的数字。如果为空,则表示没有更多结果。

PlanSummary

查询的规划阶段信息。

字段
indexes_used[]

Struct

为查询选择的索引。For example: [ {"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}/documentsprojects/{project_id}/databases/{database_id}/documents/{document_path}。例如:projects/my-project/databases/my-database/documentsprojects/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

执行给定时间戳的查询。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。

RunAggregationQueryResponse

Firestore.RunAggregationQuery 的响应。

字段
result

AggregationResult

单个汇总结果。

报告部分进度时不存在。

transaction

bytes

作为此请求的一部分启动的事务。

仅在请求请求启动新事务时出现在第一个响应中。

read_time

Timestamp

计算汇总结果的时间。此值始终是单调递增的;在这种情况下,结果流中的上一个 AggregationResult 在其 read_time 和当前 AggregationResult 之间不会发生变化。

如果查询未返回任何结果,则不会发送包含 read_time 但不包含 result 的响应,这表示查询的运行时间。

explain_metrics

ExplainMetrics

查询说明指标。此属性仅在提供了 RunAggregationQueryRequest.explain_options 时才存在,并且仅与数据流中的最后一次响应一起发送一次。

RunQueryRequest

Firestore.RunQuery 的请求。

字段
parent

string

必需。父级资源名称。格式为:projects/{project_id}/databases/{database_id}/documentsprojects/{project_id}/databases/{database_id}/documents/{document_path}。例如:projects/my-project/databases/my-database/documentsprojects/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

按指定时间读取文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 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

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

字段
aggregations[]

Aggregation

可选。要应用于 structured_query 结果的一系列汇总。

需要:

  • 每个查询至少有 1 个汇总,最多 5 个。
联合字段 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 (
  ...
);

需要:

联合字段 operator。要执行的汇总类型,必填。operator 只能是下列其中一项:
count

Count

计数聚合器。

sum

Sum

求和聚合器。

avg

Avg

一般的集合商家。

Avg

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

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

  • 如果聚合值包含 NaN,则返回 NaN。无穷大数学遵循 IEEE-754 标准。

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

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

字段
field

FieldReference

要汇总的字段。

计数

与查询匹配的文档数。

COUNT(*) 聚合函数会对整个文档执行操作,因此不需要字段引用。

字段
up_to

Int64Value

可选。(可选)对要统计的文档数量上限的限制。

这提供了一种方式来设定要扫描的文档数量上限,从而限制延迟时间和费用。

未指定为无限制。

简要示例:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

需要:

  • 如果存在,则必须大于零。

总和

所请求字段的值的总和。

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

  • 如果聚合值包含 NaN,则返回 NaN。无穷大数学遵循 IEEE-754 标准。

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

  • 如果所有汇总数据都是整数,并且求和结果不溢出,则返回 64 位整数。否则,返回的结果为双精度型。请注意,即使所有聚合值都是整数,如果结果无法放入 64 位的带符号整数,也会以双精度形式返回。如果发生这种情况,返回的值会失去精度。

  • 发生下溢时,浮点聚合是不确定的。这意味着,如果在不更改基础值的情况下重复运行同一查询,每次的结果可能略有不同。在此类情况下,值应存储为整数而非浮点数。

字段
field

FieldReference

要汇总的字段。

StructuredQuery

Firestore 查询。

字段
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

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

这在 WHERESTART ATEND AT 指定的约束条件之后、LIMIT 子句之前适用。

需要:

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

Int32Value

要返回的结果数上限。

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

需要:

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

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

需要:

  • fieldorder_by 中排在最前面。
LESS_THAN_OR_EQUAL

给定 field 小于或等于给定 value

需要:

  • fieldorder_by 中排在最前面。
GREATER_THAN

给定 field 大于给定 value

需要:

  • fieldorder_by 中排在最前面。
GREATER_THAN_OR_EQUAL

给定 field 大于或等于给定 value

需要:

  • fieldorder_by 中排在最前面。
EQUAL 给定 field 等于给定 value
NOT_EQUAL

给定 field 不等于给定 value

需要:

  • 没有其他的 NOT_EQUALNOT_INIS_NOT_NULLIS_NOT_NAN
  • fieldorder_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
  • 没有其他的 ORINARRAY_CONTAINS_ANYNOT_INNOT_EQUALIS_NOT_NULLIS_NOT_NAN
  • fieldorder_by 中排在首位。

FieldReference

对文档中某个字段的引用,例如:stats.operations

字段
field_path

string

对文档中字段的引用。

需要:

  • 必须是以英文句点分隔 (.) 的段字符串,其中每个段均符合 document field name 限制。

过滤

过滤器。

字段
联合字段 filter_type。过滤器的类型。filter_type 只能是下列其中一项:
composite_filter

CompositeFilter

复合过滤条件。

field_filter

FieldFilter

基于文档字段的过滤条件。

unary_filter

UnaryFilter

仅接受一个参数的过滤条件。

订单

字段上的订单。

字段
field

FieldReference

要排序的字段。

direction

Direction

排序依据。默认为 ASCENDING

Projection

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

字段
fields[]

FieldReference

要返回的字段。

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

UnaryFilter

具有单个操作数的过滤条件。

字段
op

Operator

要应用的一元运算符。

联合字段 operand_type。过滤器的参数。operand_type 只能是下列其中一项:
field

FieldReference

要应用运算符的字段。

运算符

一元运算符。

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

给定的 field 不等于 NaN

需要:

  • 没有其他的 NOT_EQUALNOT_INIS_NOT_NULLIS_NOT_NAN
  • fieldorder_by 中排在首位。
IS_NOT_NULL

给定的 field 不等于 NULL

需要:

  • 单个 NOT_EQUALNOT_INIS_NOT_NULLIS_NOT_NAN
  • fieldorder_by 中排在首位。

目标

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

字段
target_id

int32

用于标识流上的目标的目标 ID。必须是正数且非零。

如果 target_id 为 0(或未指定),服务器将为此目标分配一个 ID,并在 TargetChange::ADD 事件中返回该 ID。添加具有 target_id=0 的目标后,所有后续目标也必须具有 target_id=0。如果在添加具有 target_id=0 的目标后向服务器发送值为 target_id != 0AddTarget 请求,服务器会立即发送包含 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_tokenread_time 之后更新的匹配文档。否则,系统会在任何后续更改之前返回所有匹配的文档。resume_type 只能是下列其中一项:

resume_token

bytes

相同目标的先前 TargetChange 中的恢复令牌。

不支持使用具有不同目标的恢复令牌,此令牌可能会失败。

read_time

Timestamp

在特定的 read_time 之后开始监听。

客户端此时必须知道匹配文档的状态。

DocumentsTarget

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

字段
documents[]

string

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

QueryTarget

由查询指定的目标。

字段
parent

string

父级资源名称。格式为:projects/{project_id}/databases/{database_id}/documentsprojects/{project_id}/databases/{database_id}/documents/{document_path}。例如:projects/my-project/databases/my-database/documentsprojects/my-project/databases/my-database/documents/chatrooms/my-chatroom

联合字段 query_type。要运行的查询。query_type 只能是下列其中一项:
structured_query

StructuredQuery

结构化查询。

TargetChange

监控的目标已发生更改。

字段
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_id 并非一致的快照时,会被省略)。

每当整个数据流到达新的一致快照时,数据流都会发送包含空 target_idsread_time。ADD、CURRENT 和 RESET 消息一定会(最终)生成一致的新快照(而 NO_CHANGE 和 REMOVE 消息不会)。

对于给定的流,read_time 必定会单调递增。

TargetChangeType

所做更改的类型。

枚举
NO_CHANGE 未发生任何更改。仅用于发送更新后的 resume_token
ADD 目标已添加。
REMOVE 这些目标已被移除。
CURRENT

这些目标反映了在将目标添加到数据流之前提交的所有更改。

此事件将在 read_time 大于或等于目标添加时间后发送。

如果需要写后读语义,监听器可以等待此变更。

RESET

目标已重置,并且在后续更改中将返回目标的新初始状态。

初始状态完成后,系统将返回 CURRENT,即使之前将目标指定为 CURRENT 也是如此。

TransactionOptions

用于创建新交易的选项。

字段
联合字段 mode。事务的模式。mode 只能是下列其中一项:
read_only

ReadOnly

事务只能用于读取操作。

read_write

ReadWrite

事务可用于读取和写入操作。

ReadOnly

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

字段
联合字段 consistency_selector。此事务的一致性模式。如果未设置,则默认为强一致性。consistency_selector 只能是下列其中一项:
read_time

Timestamp

读取指定时间的文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。

ReadWrite

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

Firestore 不允许第三方身份验证请求创建读写事务。

字段
retry_transaction

bytes

要重试的可选事务。

UpdateDocumentRequest

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 字节。查询只会考虑前 1500 个字节。

reference_value

string

对文档的引用。例如:projects/{project_id}/databases/{database_id}/documents/{document_path}

geo_point_value

LatLng

表示地球表面上某个点的地理位置点值。

array_value

ArrayValue

数组值。

不能直接包含另一个数组值,但可以包含另一个数组的映射。

map_value

MapValue

映射值。

书写

文档上的写入操作。

字段
update_mask

DocumentMask

此写入操作中要更新的字段。

只有在操作为 update 时才能设置此字段。如果没有为 update 设置掩码,而文档存在,则所有现有数据都将被覆盖。如果设置了掩码,且服务器上的文档包含未遮盖的字段,则这些字段保持不变。在掩码中引用,但在输入文档中不存在的字段会从服务器上的文档中删除。此掩码中的字段路径不得包含预留的字段名称。

update_transforms[]

FieldTransform

更新后要执行的转换。

只有在操作为 update 时才能设置此字段。如果存在,此写入相当于以原子方式依序对同一文档执行 updatetransform

current_document

Precondition

文档的可选前提条件。

如果已设置此属性,但目标文档未满足此要求,则写入将失败。

联合字段 operation。要执行的操作。operation 只能是下列其中一项:
update

Document

要写入的文档。

delete

string

要删除的文档的名称。格式为:projects/{project_id}/databases/{database_id}/documents/{document_path}

transform

DocumentTransform

对文档应用转换。

WriteRequest

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>

与此写入请求关联的标签。

WriteResponse

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 的结果。