حذف

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();

يجب التأكّد من أنّ مرحلة where(...) قبل delete() النهائية تحدّ من المستندات بشكل صحيح لتعديل المستندات المتوقّعة فقط. من أفضل الممارسات تشغيل الاستعلام بدون مرحلة delete() النهائية أولاً للتحقّق من إزالة المستندات المقصودة فقط.

المرحلة النهائية

يجب أن تأتي مرحلة delete() في نهاية مسار، ولا يمكن تقديم أي مراحل أخرى.

حذف الكل

بشكلٍ تلقائي، ستزيل مرحلة delete() جميع المستندات التي تشير إليها المرحلة السابقة. إذا أردت تحديد حجم عبء العمل، أو إذا كنت تعرف أنّ شروط الفلتر تطابق مستندًا واحدًا بالضبط، يمكن إضافة limit(1) قبل delete() النهائية لتحديد العمل الإجمالي.

التعديلات على مجموعات متعدّدة

ستُجري مرحلة delete() النهائية تعديلات على أي مستند يشير إليه __name__ (بافتراض توفير جميع عمليات المصادقة اللازمة). ويشمل ذلك حذف المستندات من مجموعات أو مجموعات مجموعات مختلفة متعدّدة كجزء من الطلب نفسه.

الحقل __name__ مطلوب

تتطلّب مرحلة delete() أن توفّر المرحلة السابقة حقل __name__ يحتوي على مرجع مستند لإزالته. سيؤدي عدم إجراء ذلك إلى حدوث خطأ في وقت التشغيل، وعند تشغيله خارج عملية، يمكن أن يؤدي إلى نجاح جزئي.

تتضمّن معظم مراحل الإدخال، مثل collection(...) و collection_group(...) و database(...) و documents(...)، الحقل __name__ تلقائيًا، لذا لا يكون ذلك ذا صلة إلا عند استخدام عرض (مثل select(...)) أو إجراء عملية تحويل على المستندات (مثل aggregate(...)).

يتضمّن الردّ ملخصًا لعدد المستندات المعدّلة. على سبيل المثال، يؤكّد الردّ التالي أنّ المسار عدّل ثلاثة مستندات:

{documents_modified: 3L}

القيود

  • لا تتوافق مراحل لغة معالجة البيانات (DML) مع Cloud Firestore Security Rules. ويتم رفض محاولات إجراء عمليات لغة معالجة البيانات (DML) من خلال Cloud Firestore Security Rules

  • أثناء معاينة هذه الميزة، لا يمكنك تشغيل مراحل لغة معالجة البيانات (DML) في عملية. لمزيد من المعلومات حول سلوك الاتساق، يُرجى الاطّلاع على مقالة الاتساق.

  • إذا كانت المرحلة التي تسبق مرحلة لغة معالجة البيانات (DML) تُنتج مستندات متعدّدة لها __name__ نفسه، تتم معالجة كل مثيل. بالنسبة إلى update(...)، يعني ذلك أنّه قد يتم تعديل المستند المستهدَف نفسه عدة مرات. بالنسبة إلى delete(...)، لن تكون المحاولات اللاحقة بعد المحاولة الأولى عمليات غير ضرورية.