更新

update(...) 阶段会更新现有文档。

示例

例如，以下操作会将数据模型更改回填到合集组中的所有文档。流水线会将 preferences.color 字段添加到 users 合集组中缺少该字段的所有文档。

Node.js
const snapshot = await db.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant(null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Constant, Field, Not

snapshot = (
    client.pipeline()
    .collection_group("users")
    .where(Not(Field.of("preferences.color").exists()))
    .add_fields(Constant.of(None).as_("preferences.color"))
    .remove_fields("color")
    .update()
    .execute()
)
Java
Pipeline.Snapshot snapshot = firestore.pipeline()
   .collectionGroup("users")
   .where(not(exists(field("preferences.color"))))
   .addFields(constant((String) null).as("preferences.color"))
   .removeFields("color")
   .update()
   .execute().get();
Go
snapshot := client.Pipeline().
	CollectionGroup("users").
	Where(firestore.Not(firestore.FieldExists(firestore.FieldOf("preferences.color")))).
	AddFields(firestore.Selectables(
		firestore.ConstantOfNull().As("preferences.color"),
	)).
	RemoveFields(firestore.Fields("color")).
	Update().
	Execute(ctx)

行为

所有数据操纵语言 (DML) 阶段都必须位于流水线的末尾。

进入此阶段的文档必须包含 __name__ 字段，以标识要更新的文档。如果任何文档不存在，操作将失败。 大多数输入阶段（例如 collection(...), collection_group(...), database(...) 和 documents(...)）默认包含 __name__ 字段。

您可以选择性地提供 transformations，以便在写入文档之前应用。这些转换的作用与在最终输出阶段之前添加 add_fields(...)完全相同，并且 表达式在先前文档的上下文中运行。

响应包含修改的文档数量的摘要。 例如，以下响应确认流水线修改了三个文档：

{documents_modified: 3L}

限制

  • DML 阶段不支持 Cloud Firestore Security Rules。尝试通过 Cloud Firestore Security Rules 执行 DML 操作 会被拒绝。

  • 在此功能的预览期间，您无法在事务中运行 DML 阶段。如需详细了解一致性行为，请参阅 一致性。

  • 如果 DML 阶段之前的阶段生成了多个具有相同 __name__ 的文档，则每个实例都会被处理。对于 update(...)，这意味着同一目标文档可能会被多次修改。对于 delete(...)，第一次尝试后的后续尝试将是空操作。