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

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

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

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

قبل البدء

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

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

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

يجب أن تأتي جميع مراحل لغة معالجة البيانات (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();

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

استخدِم مراحل لغة معالجة البيانات (DML) delete(...) stage لإنشاء مسارات بيانات يمكنها الاستعلام عن المستندات ثم حذف البيانات. لمنع عمليات الحذف المجمّع غير المقصودة، يجب أن تتضمّن المسارات التي تنتهي بـ 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(...)، لن يكون لأي محاولات لاحقة بعد المحاولة الأولى أي تأثير.