更新

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(...)，第一次嘗試後續的嘗試都會是無運算。