تعديل البيانات باستخدام عمليات Firestore Pipeline

استخدِم مرحلتَي update(...) وdelete(...) "لغة معالجة البيانات" (DML) لإنشاء مسارات بيانات يمكنها البحث عن المستندات ثم حذف البيانات أو تعديلها.

متطلبات الإصدار

تتطلّب العمليات الموضّحة في هذه الصفحة استخدام إصدار Firestore Enterprise.

قبل البدء

يجب أن تكون على دراية بكيفية طلب البحث من قاعدة بيانات باستخدام عمليات Pipeline.

تعديل المستندات

استخدِم مرحلة update(...) DML لإنشاء مسارات بيانات يمكنها طلب المستندات ثم إضافة البيانات أو تعديلها.

يجب أن تأتي جميع مراحل DML في نهاية مسار العرض. يجب أن تتضمّن المستندات التي تصل إلى هذه المرحلة الحقل __name__ لتحديد المستندات التي سيتم تعديلها. تفشل العملية إذا كان أي من المستندات التي تحاول تعديلها غير موجود.

على سبيل المثال، تعبئ العملية التالية تغييرًا في نموذج البيانات لجميع المستندات في حزمة المجموعات. تضيف عملية المعالجة حقل 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();

حذف المستندات

استخدِم مراحل delete(...) DML لإنشاء مسارات بيانات يمكنها الاستعلام عن المستندات ثم حذف البيانات. لتجنُّب عمليات الحذف المجمّع غير المقصودة، يجب أن تتضمّن المسارات التي تنتهي بـ delete(...) مرحلة where(...) واحدة على الأقل. يجب أن تأتي جميع مراحل DML في نهاية مسار العرض.

على سبيل المثال، تحذف سلسلة المعالجة التالية جميع مستندات 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();

المطابقة

لا تتوافق عمليات سلسلة الإجراءات التي تتضمّن مرحلتَي update(...) وdelete() مع المعاملات. يتم تنفيذ مراحل DML خارج نطاق معاملة مع السلوك التالي:

  • يتم تعديل كل مستند بشكل مستقل. وهذا يعني أنّ العمليات ليست ذرية في جميع المستندات. يتعذّر إتمام العملية عند حدوث أول خطأ، ويمكن تحقيق نجاح جزئي.
  • تتوفّر المراحل التالية:
    • collection(...)
    • collection_group(...)
    • where(...)
    • select(...)
    • add_fields(...)
    • remove_fields(...)
    • let(...)
    • sort(...)
    • limit(...)
    • offset(...)
  • لا تتوفّر المراحل التالية:
    • aggregate(...)
    • distinct(...)
    • unnest(...)
    • find_nearest(...)
    • لا يُسمح بمراحل طلبات البحث المتعددة، مثل union(...) وعمليات الربط وطلبات البحث الفرعية، قبل مرحلة DML.

القيود

يُرجى ملاحظة القيود التالية لمراحل DML:

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