Firestore पाइपलाइन ऑपरेशन की मदद से डेटा में बदलाव करना

डेटा पाइपलाइन बनाने के लिए, update(...) और delete(...) डेटा में बदलाव करने वाली कंप्यूटर प्रोग्राम की भाषा (डीएमएल) के चरणों का इस्तेमाल करें. इससे दस्तावेज़ों के लिए क्वेरी की जा सकती है. इसके बाद, डेटा को मिटाया जा सकता है या उसमें बदलाव किया जा सकता है.

वर्शन के लिए ज़रूरी शर्तें

इस पेज पर बताई गई कार्रवाइयों के लिए, Firestore Enterprise वर्शन ज़रूरी है.

शुरू करने से पहले

आपको पाइपलाइन ऑपरेशन की मदद से डेटाबेस को क्वेरी करने का तरीका पता होना चाहिए.

दस्तावेज़ अपडेट करना

डेटा पाइपलाइन बनाने के लिए, update(...) डीएमएल स्टेज का इस्तेमाल करें. इससे दस्तावेज़ों के लिए क्वेरी की जा सकती है. इसके बाद, डेटा जोड़ा जा सकता है या उसमें बदलाव किया जा सकता है.

डीएमएल के सभी स्टेज, पाइपलाइन के आखिर में होने चाहिए. इस स्टेज में आने वाले दस्तावेज़ों में __name__ फ़ील्ड शामिल होना चाहिए, ताकि यह पहचाना जा सके कि किन दस्तावेज़ों को अपडेट करना है. अगर अपडेट किए जाने वाले दस्तावेज़ों में से कोई भी दस्तावेज़ मौजूद नहीं है, तो कार्रवाई पूरी नहीं होगी.

उदाहरण के लिए, यहां दिया गया ऑपरेशन, कलेक्शन ग्रुप के सभी दस्तावेज़ों में डेटा मॉडल में हुए बदलाव को बैकफ़िल करता है. पाइपलाइन, users कलेक्शन ग्रुप के उन सभी दस्तावेज़ों में preferences.color फ़ील्ड जोड़ती है जिनमें यह फ़ील्ड मौजूद नहीं है.

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();
जाएं
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)

दस्तावेज़ मिटाना

डेटा पाइपलाइन बनाने के लिए, delete(...) डीएमएल स्टेज का इस्तेमाल करें. इससे दस्तावेज़ों के लिए क्वेरी की जा सकती है और फिर डेटा मिटाया जा सकता है. गलती से एक साथ कई आइटम मिटाने से बचने के लिए, delete(...) पर खत्म होने वाली पाइपलाइन में कम से कम एक where(...) स्टेज शामिल होना चाहिए. डीएमएल के सभी स्टेज, पाइपलाइन के आखिर में होने चाहिए.

उदाहरण के लिए, यहां दी गई पाइपलाइन उन सभी 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();
जाएं
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)

एक्ज़ीक्यूशन मोड और एक जैसी जानकारी

डीएमएल स्टेज को किसी साफ़ तौर पर बताए गए लेन-देन के अंदर या लेन-देन के बाहर चलाया जा सकता है:

लेन-देन से जुड़ा एक्ज़ीक्यूशन

ट्रांज़ैक्शनल डीएमएल, सभी दस्तावेज़ों में एक जैसी और पूरी जानकारी उपलब्ध कराता है. साथ ही, यह पाइपलाइन क्वेरी के सभी चरणों के साथ काम करता है. इस वजह से, यह उन वर्कलोड के लिए सबसे सही है जिनमें डेटा की एक जैसी क्वालिटी की गारंटी ज़रूरी होती है. इनमें, अधूरे अपडेट स्वीकार नहीं किए जाते. इसके अलावा, यह उन वर्कलोड के लिए भी सही है जो क्वेरी के मुश्किल चरणों पर निर्भर करते हैं. हालांकि, इसके लिए ज़रूरी है कि बदलाव, ट्रांज़ैक्शन के साइज़ की सीमाओं के अंदर हों.

किसी एक्सप्लिसिट ट्रांज़ैक्शन (runTransaction / transaction.execute(pipeline) या atomic: true विकल्प का इस्तेमाल करके) में डीएमएल पाइपलाइन चलाने पर, यह व्यवहार होता है:

  • सभी म्यूटेशन या तो एक साथ लागू होते हैं या फिर गड़बड़ी होने पर पूरी तरह से वापस ले लिए जाते हैं.
  • डीएमएल स्टेज से पहले, पाइपलाइन क्वेरी के सभी स्टेज इस्तेमाल किए जा सकते हैं. इनमें where, add_fields, union, find_nearest, और aggregate सब-क्वेरी शामिल हैं.
  • किसी लेन-देन में, डेटा लिखने से जुड़े सभी ऑपरेशन से पहले, डेटा पढ़ने से जुड़े सभी ऑपरेशन पूरे होने चाहिए. डीएमएल पाइपलाइन, डेटा को लिखने का काम करती है. इसलिए, एक ही लेन-देन में डीएमएल पाइपलाइन को चलाने के बाद, डेटा को पढ़ने का काम नहीं किया जा सकता. उदाहरण के लिए, एक ही लेन-देन में डीएमएल पाइपलाइन को कई बार कॉल नहीं किया जा सकता. साथ ही, डीएमएल पाइपलाइन को लागू करने के बाद दस्तावेज़ों को नहीं पढ़ा जा सकता. डीएमएल पाइपलाइन के चलने के बाद, डेटा को पढ़ने की कोशिश करने पर, FAILED_PRECONDITION गड़बड़ी के साथ काम नहीं हो पाता: Cannot have reads after the first write in a Firestore transaction.
  • यह कार्रवाई, Firestore Enterprise वर्शन के लेन-देन की सीमाओं के तहत की जाती है.

लेन-देन से जुड़ी कार्रवाई न करना

नॉन-ट्रांज़ैक्शनल डीएमएल को बड़ी संख्या में दस्तावेज़ों में एक साथ बदलाव करने के लिए डिज़ाइन किया गया है. इसमें ट्रांज़ैक्शन के साइज़ की सीमाओं का सामना नहीं करना पड़ता. यह पूरे ऑपरेशन के बजाय दस्तावेज़ के लेवल पर लॉक करता है. इससे, बड़े पैमाने पर दस्तावेज़ों को अपडेट करते समय, एक साथ होने वाले अन्य ऑपरेशन जारी रहते हैं.

जब डीएमएल स्टेज, किसी साफ़ तौर पर किए गए लेन-देन के बाहर चलते हैं, तो:

  • अलग-अलग अपडेट और कुछ हद तक सफलता: हर दस्तावेज़ को अलग-अलग अपडेट किया जाता है. साथ ही, सभी दस्तावेज़ों पर कार्रवाइयां एक साथ नहीं की जाती हैं. पहली गड़बड़ी होने पर पाइपलाइन रुक जाती है. साथ ही, पहले से बदले गए दस्तावेज़, डेटाबेस में सेव रहते हैं. इससे कुछ हद तक सफलता मिलती है.
  • स्टेज की सुविधा:
    • ट्रांज़ैक्शन के बाहर, डीएमएल से पहले ऐडवांस और मल्टी-क्वेरी स्टेज (जैसे, aggregate(...), distinct(...), unnest(...), find_nearest(...), union(...), जॉइन, और सबक्वेरी) का इस्तेमाल नहीं किया जा सकता. अगर आपकी पाइपलाइन को इन चरणों की ज़रूरत है, तो लेन-देन का इस्तेमाल करें.
  • सुरक्षा नियमों के लिए 20 लुकअप की सीमा: दस्तावेज़ों का हर बैच अपने लेन-देन में लागू होता है और सुरक्षा नियमों का फिर से आकलन करता है. अगर आपके सुरक्षा नियम get() या exists() लुकअप का इस्तेमाल करते हैं, तो हर बैच एक लुकअप को लागू करता है. इससे, करीब 200 दस्तावेज़ लिखने के बाद, हर अनुरोध के लिए 20 लुकअप की सीमा पूरी हो जाती है और PERMISSION_DENIED के साथ काम नहीं करता. इस सीमा से बचने के लिए, get() या exists() लुकअप के बजाय कस्टम दावे का इस्तेमाल करें.

सीमाएं

डीएमएल स्टेज के लिए, इन सीमाओं का ध्यान रखें:

  • .execute() को कॉल करने से पहले, डीएमएल स्टेज को पाइपलाइन की परिभाषा में आखिरी स्टेज होना चाहिए.
  • लेन-देन के बाहर चलाए जाने पर, हर दस्तावेज़ को एक-दूसरे से अलग अपडेट किया जाता है. इससे, कुछ दस्तावेज़ों को अपडेट किया जा सकता है.
  • बिना लेन-देन वाले डीएमएल ऑपरेशन, सुरक्षा के नियमों के तहत आते हैं. इनमें get() या exists() लुकअप की संख्या करीब 200 दस्तावेज़ों तक सीमित होती है. ऐसा इसलिए होता है, क्योंकि लुकअप की सीमा 20 होती है.
  • लेन-देन से जुड़े डीएमएल ऑपरेशन, Firestore Enterprise वर्शन के लेन-देन की सीमाओं के दायरे में आते हैं. Firestore ट्रांज़ैक्शन में, पहली बार डेटा लिखने के बाद उसे पढ़ने की अनुमति नहीं होती. इसलिए, एक ही ट्रांज़ैक्शन में डीएमएल पाइपलाइन को कई बार कॉल नहीं किया जा सकता. इसके अलावा, डीएमएल पाइपलाइन को लागू करने के बाद, दस्तावेज़ों को पढ़ा नहीं जा सकता. डीएमएल राइट के बाद, रीड को एक्ज़ीक्यूट करने की कोशिश करने पर, FAILED_PRECONDITION गड़बड़ी के साथ काम नहीं करता: Cannot have reads after the first write in a Firestore transaction.
  • अगर डीएमएल स्टेज से पहले की स्टेज में, एक ही __name__ वाले कई दस्तावेज़ जनरेट होते हैं या डेस्टिनेशन दस्तावेज़ का एक ही आईडी जनरेट होता है, तो हर बदलाव को क्रम से प्रोसेस किया जाता है:
    • upsert(...) और update(...) के लिए: एक ही दस्तावेज़ को टारगेट करने वाले कई म्यूटेशन, "लास्ट वन विंस" सिमैंटिक का पालन करते हैं. इसमें, प्रोसेस किया गया आखिरी म्यूटेशन, दस्तावेज़ की आखिरी स्थिति तय करता है.
    • delete(...) के लिए: पहली बार में दस्तावेज़ मिट जाता है. इसके बाद, उसी दस्तावेज़ को मिटाने के लिए की गई कार्रवाइयों का कोई असर नहीं होता.
    • insert(...) के लिए: पहली कोशिश में दस्तावेज़ बन जाता है. इसके बाद, उसी दस्तावेज़ आईडी को टारगेट करने की कोशिशें, ALREADY_EXISTS गड़बड़ी के साथ फ़ेल हो जाती हैं.