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

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

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

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

قبل البدء

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

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

استخدِم مرحلة لغة معالجة البيانات (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();
test.firestore.js

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()
)
firestore_pipelines.py

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();
PipelineSnippets.java

متابعة

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)
pipeline_snippets_dml.go

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

استخدِم مرحلة 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();
test.firestore.js

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()
)
firestore_pipelines.py

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();
PipelineSnippets.java

متابعة

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)
pipeline_snippets_dml.go

أوضاع التنفيذ والاتساق

يمكن تنفيذ مراحل لغة معالجة البيانات (DML) إما داخل معاملة صريحة أو خارج معاملة:

تنفيذ المعاملات

توفّر لغة DML الخاصة بالمعاملات اتساقًا ذريًا وشاملاً في جميع المستندات، وتتيح استخدام المجموعة الكاملة من مراحل طلبات البيانات في المسار. وهذا يجعلها مثالية لأعباء العمل التي تتطلب ضمانات صارمة للاتساق، حيث تكون التحديثات الجزئية غير مقبولة، أو التي تعتمد على مراحل طلبات بحث معقدة، بشرط أن تتناسب التعديلات مع حدود حجم المعاملة.

عند تشغيل مسار DML داخل معاملة صريحة (باستخدام runTransaction / transaction.execute(pipeline) أو الخيار atomic: true)، يتم تنفيذ الإجراءات التالية:

• يتم تنفيذ جميع التغييرات معًا أو التراجع عنها بالكامل في حال تعذّر تنفيذها.
• تتوفّر جميع مراحل طلبات البحث في المسار قبل مرحلة DML (بما في ذلك طلبات البحث الفرعية where وadd_fields وunion وfind_nearest وaggregate).
• في أي معاملة، يجب تنفيذ جميع عمليات القراءة قبل أي عمليات كتابة. بما أنّ مسار DML ينفّذ عمليات كتابة، لا يمكنك تنفيذ عمليات قراءة بعد تشغيل مسار DML في المعاملة نفسها. على سبيل المثال، لا يمكنك استدعاء مسار DML عدة مرات في معاملة واحدة، ولا يمكنك قراءة المستندات بعد تنفيذ مسار DML. تؤدي محاولة تنفيذ عملية قراءة بعد تشغيل مسار DML إلى حدوث خطأ FAILED_PRECONDITION: Cannot have reads after the first write in a Firestore transaction.
• تخضع العملية لحدود المعاملات في إصدار Firestore Enterprise.

التنفيذ غير المرتبط بمعاملات

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

عند تشغيل مراحل DML خارج معاملة صريحة:

• التحديثات المستقلة والنجاح الجزئي: يتم تحديث كل مستند بشكل مستقل عن الآخر، ولا تكون العمليات موحّدة في جميع المستندات. يتوقف المسار عند الخطأ الأول، وتظل المستندات المعدَّلة سابقًا مكتوبة في قاعدة البيانات، ما يسمح بحدوث نجاح جزئي.
• دعم المسرح:
  • لا تتوفّر المراحل المتقدّمة والمتعدّدة الطلبات (مثل aggregate(...) وdistinct(...) وunnest(...) وfind_nearest(...) وunion(...) وعمليات الربط والطلبات الفرعية) قبل لغة معالجة البيانات (DML) خارج المعاملة. استخدم معاملة إذا كان المسار يتطلب هذه المراحل.
• حدّ البحث في قواعد الأمان البالغ 20: يتم تنفيذ كل دفعة من المستندات في معاملتها الخاصة وإعادة تقييم قواعد الأمان. إذا كانت قواعد الأمان تستخدم عمليات البحث get() أو exists()، تنفّذ كل دفعة عملية بحث، وتصل إلى الحد الأقصى لكل طلب وهو 20 عملية بحث بعد كتابة حوالي 200 مستند وتتعذّر باستخدام PERMISSION_DENIED. استخدِم المطالبات المخصّصة بدلاً من عمليات البحث في get() أو exists() لتجنُّب هذا الحدّ.

القيود

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

• يجب أن تكون مراحل DML هي المرحلة الأخيرة في تعريف المسار قبل استدعاء .execute().
• عند تشغيلها خارج معاملة، يتم تعديل كل مستند بشكل مستقل عن الآخر، ما يسمح بتحقيق نجاح جزئي.
• تخضع عمليات لغة معالجة البيانات (DML) غير المستندة إلى المعاملات لقواعد الأمان التي تتضمّن عمليات بحث get() أو exists()، ويبلغ الحد الأقصى لها حوالي 200 مستند بسبب الحد الأقصى لعمليات البحث البالغ 20 عملية.
• تخضع عمليات لغة معالجة البيانات (DML) المستندة إلى المعاملات لحدود المعاملات في إصدار Firestore Enterprise. بما أنّ معاملات Firestore لا تسمح بعمليات القراءة بعد عملية الكتابة الأولى، لا يمكنك استدعاء مسار DML عدة مرات ضمن معاملة واحدة، ولا يمكنك قراءة المستندات بعد تنفيذ مسار DML. تؤدي محاولة تنفيذ عملية قراءة بعد تعذُّر عملية كتابة بلغة DML إلى ظهور الخطأ FAILED_PRECONDITION: Cannot have reads after the first write in a Firestore transaction.
• إذا كانت المرحلة التي تسبق مرحلة DML تنتج مستندات متعددة باستخدام نفس __name__ أو يتم تقييمها إلى نفس معرّف المستند الوجهة، تتم معالجة كل طفرة بشكل تسلسلي:
  • بالنسبة إلى upsert(...) وupdate(...): في حال إجراء عدة تغييرات على المستند نفسه، يتم تطبيق "آخر تغيير"، أي أنّ آخر تغيير تتم معالجته يحدّد الحالة النهائية للمستند.
  • بالنسبة إلى delete(...): تؤدي المحاولة الأولى إلى حذف المستند، وتكون المحاولات اللاحقة للمستند نفسه غير فعّالة.
  • بالنسبة إلى insert(...): تؤدي المحاولة الأولى إلى إنشاء المستند، وتفشل المحاولات اللاحقة التي تستهدف رقم تعريف المستند نفسه مع ظهور الخطأ ALREADY_EXISTS.