刪除

delete() 是資料操作語言 (DML) 階段，可讓查詢根據查詢結果移除文件。這個階段可以附加至查詢結尾，並刪除前一階段 __name__ 欄位參照的所有文件。

範例

舉例來說，下列查詢會刪除所有 users 文件，這些文件的 address.users 設為 USA，且 __create_time__ 小於 10 天：

Node.js
const pipeline = db.pipeline()
  .collectionGroup("users")
  .where(field("address.country").equal("USA"))
  .where(field("__create_time__").timestampAdd("day", 10).lessThan(currentTimestamp()))
  .delete();
await pipeline.execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import CurrentTimestamp, Field

snapshot = (
    client.pipeline()
    .collection_group("users")
    .where(Field.of("address.country").equal("USA"))
    .where(
        Field.of("__create_time__")
        .timestamp_add("day", 10)
        .less_than(CurrentTimestamp())
    )
    .delete()
    .execute()
)
Java
Pipeline.Snapshot deleteResults = firestore.pipeline()
  .collectionGroup("users")
  .where(field("address.country").equal("USA"))
  .where(field("__create_time__").add(constant(10)).lessThan(currentTimestamp()))
  .delete()
  .execute().get();
Go
snapshot := client.Pipeline().
	CollectionGroup("users").
	Where(firestore.FieldOf("address.country").Equal("USA")).
	Where(firestore.FieldOf("__create_time__").Add(firestore.ConstantOf(10)).LessThan(firestore.CurrentTimestamp())).
	Delete().
	Execute(ctx)

行為

回應

delete() 階段一律會發出單一文件 (如 { documents_modified: 28L })，說明刪除的文件數量。

完整刪除收藏內容

如要刪除集合中的所有文件，請在輸入階段附加 delete()，例如：

Node.js

const results = await db.pipeline()
  .collection("/users")
  .delete()
  .execute();

請務必確保最終 delete() 前的 where(...) 階段會適當限制文件，只更新預期文件。建議您先執行不含最後 delete() 階段的查詢，確認只會移除預期文件。

最終階段

delete() 階段必須位於管道結尾，不得提供其他階段。

全部刪除

根據預設，delete() 階段會移除前一階段參照的所有文件。如要限制工作負載的大小，或確定篩選條件只會比對一個文件，可以在最後的 delete() 前新增 limit(1)，限制總工作量。

跨集合異動

最後的 delete() 階段會將突變套用至 __name__ 參照的任何文件 (假設已提供所有必要的驗證)。包括在同一個要求中，從多個不同集合或集合群組刪除文件。

需要__name__

在 delete() 階段，前一階段必須提供包含要移除的文件參照的 __name__ 欄位。否則會導致執行階段錯誤，且在交易外執行時可能會部分成功。

大多數輸入階段 (例如 collection(...)、collection_group(...)、database(...) 和 documents(...)) 預設會包含 __name__ 欄位，因此只有在使用投影 (例如 select(...)) 或對文件執行轉換 (例如 aggregate(...)) 時，才需要考慮這個欄位。

回應會包含修改文件數量的摘要。舉例來說，下列回應確認管道修改了三份文件：

{documents_modified: 3L}

限制

  • DML 階段不支援 Cloud Firestore Security Rules。系統會拒絕透過 Cloud Firestore Security Rules 嘗試執行的 DML 作業。

  • 在預先發布版期間，您無法在交易中執行 DML 階段。如要進一步瞭解一致性行為，請參閱「一致性」。

  • 如果 DML 階段之前的階段產生多個具有相同 __name__ 的文件，系統會處理每個執行個體。對於 update(...)，這表示同一個目標文件可能會多次修改。如果是 delete(...)，第一次嘗試後續的嘗試都會是無運算。