अपसर्ट

ब्यौरा

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

upsert() स्टेज में, डेस्टिनेशन कलेक्शन, दस्तावेज़ आईडी, और फ़ील्ड में किए जाने वाले वैकल्पिक बदलावों को तय करने के लिए, अलग-अलग आर्ग्युमेंट इस्तेमाल किए जा सकते हैं:

  • upsert(collectionName, documentIdExpression, ...transformations): यह तय किए गए कलेक्शन में दस्तावेज़ों को अपसर्ट करता है. इसके लिए, यह आकलन किए गए एक्सप्रेशन का इस्तेमाल करके दस्तावेज़ का आईडी तय करता है. साथ ही, ज़रूरी होने पर बदलाव लागू करता है.
  • upsert(collectionName, ...transformations): यह तय किए गए कलेक्शन में दस्तावेज़ों को अपसर्ट करता है. इसके लिए, इनपुट दस्तावेज़ में __name__ फ़ील्ड की ज़रूरत होती है, ताकि दस्तावेज़ आईडी तय किया जा सके. साथ ही, यह ज़रूरी नहीं होने पर भी बदलाव लागू करता है.
  • upsert(...transformations): यह दस्तावेज़ों को अपसर्ट करता है. इसके लिए, इनपुट दस्तावेज़ में __name__ फ़ील्ड की ज़रूरत होती है, ताकि डेस्टिनेशन कलेक्शन और दस्तावेज़ आईडी का पता लगाया जा सके. साथ ही, यह ज़रूरी न होने पर भी ट्रांसफ़ॉर्मेशन लागू करता है.

उदाहरण

सक्रिय उपयोगकर्ताओं को माइग्रेट करना

यहां दिए गए उदाहरण में, users कलेक्शन से क्वेरी की गई है, जहां age >= 25 है. साथ ही, processed फ़ील्ड जोड़ा गया है और name फ़ील्ड को दस्तावेज़ आईडी के तौर पर इस्तेमाल करके, new_users में अपसर्ट किया गया है:

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("users") .where(field("age").greaterThanOrEqual(25)) .addFields(constant(true).as("processed")) .upsert({ collection: "new_users", documentId: field("name") }) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("users") .where(field("age").greaterThanOrEqual(25)) .addFields(constant(true).as("processed")) .upsert(new Upsert().withCollection("new_users").withDocumentId(field("name"))); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

व्यवहार

यहां दिए गए सेक्शन में, upsert() स्टेज के लिए, लागू करने के तरीके, जवाब, बदलाव, और पाबंदियों के बारे में बताया गया है.

फ़ील्ड ट्रांसफ़ॉर्मेशन की मदद से, मौजूदा डेटा को अपडेट करना या नया डेटा जोड़ना

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

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("users") .upsert([constant(31).as("age")]) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("users") .upsert(constant(31L).as("age")); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

किसी दूसरे कलेक्शन में, साफ़ तौर पर दिए गए आईडी के साथ अपसर्ट करना

यहां दिए गए उदाहरण में, source_coll से डेटा पढ़ा जाता है और target_coll में दस्तावेज़ों को अपसर्ट किया जाता है. इसके लिए, दस्तावेज़ के आईडी "new_doc_id" का इस्तेमाल किया जाता है और फ़ील्ड ट्रांसफ़ॉर्मेशन लागू किया जाता है:

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("source_coll") .upsert( [constant(31).as("age")], { collection: "target_coll", documentId: constant("new_doc_id") } ) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("source_coll") .upsert(new Upsert(constant(31L).as("age")) .withCollection("target_coll") .withDocumentId(constant("new_doc_id"))); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

मौजूदा दस्तावेज़ आईडी (__name__) का इस्तेमाल करके, किसी अन्य कलेक्शन में अपसर्ट करें

यहां दिए गए उदाहरण में, source_coll से दस्तावेज़ों को पढ़ा जाता है और हर दस्तावेज़ के मौजूदा दस्तावेज़ आईडी (__name__) का इस्तेमाल करके, उन्हें target_coll में अपसर्ट किया जाता है:

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("source_coll") .upsert([constant("updated_val").as("status")], { collection: "target_coll" }) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("source_coll") .upsert(new Upsert(constant("updated_val").as("status")) .withCollection("target_coll")); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

दस्तावेज़ के रेफ़रंस के साथ अपसर्ट करें (__name__)

यहां दिए गए उदाहरण में, डेस्टिनेशन कलेक्शन और दस्तावेज़ आईडी की जानकारी देने के लिए, __name__ फ़ील्ड को असाइन किए गए दस्तावेज़ के रेफ़रंस का इस्तेमाल किया गया है:

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .literals([ { __name__: db.doc("users/bob"), name: "bob", age: 30 }, { __name__: db.doc("users/alice"), name: "alice", age: 25 } ]) .upsert() ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("__name__", db.document("users/bob"), "name", "bob", "age", 30), Map.of("__name__", db.document("users/alice"), "name", "alice", "age", 25)) .upsert(new Upsert()); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

अपने-आप जनरेट होने वाले दस्तावेज़ आईडी के साथ अपसर्ट करना

यहां दिए गए उदाहरण में, अपने-आप जनरेट हुए दस्तावेज़ आईडी और फ़ील्ड ट्रांसफ़ॉर्मेशन के साथ, users कलेक्शन में लिटरल वैल्यू को अपसर्ट किया गया है:

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .literals([ { foo: "bar" }, { foo: "baz" } ]) .upsert([constant("active").as("status")], { collection: "users" }) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("foo", "bar"), Map.of("foo", "baz")) .upsert(new Upsert(constant("active").as("status")) .withCollection("users")); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

सब-कलेक्शन में अपसर्ट करें

upsert() स्टेज का इस्तेमाल करके, पूरे पाथ का इस्तेमाल करके सीधे सब-कलेक्शन में दस्तावेज़ों को शामिल किया जा सकता है या उन्हें अपडेट किया जा सकता है.

Node.js
```js const results = await db.pipeline() .literals([ { title: "post1" }, { title: "post2" } ]) .upsert([], { collection: "users/u1/posts" }) .execute(); ```
Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("title", "post1"), Map.of("title", "post2")) .upsert(new Upsert().withCollection("users/u1/posts")); pipeline.execute(); ```

ऐडवांस क्वेरी (खोजें और सबसे नज़दीकी जगह ढूंढें) से अपसर्ट करें

upsert() स्टेज का इस्तेमाल, search या findNearest जैसे ऐडवांस क्वेरी ऑपरेशन के साथ किया जा सकता है. इससे, मैच होने वाले दस्तावेज़ों को आउटपुट कलेक्शन में लिखा जा सकता है या उन्हें उनकी जगह पर अपडेट किया जा सकता है.

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("products") .search({ query: "shoes" }) .upsert([constant(true).as("is_shoes")]) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("products") .search(searchOptionsBuilder().query(documentMatches("shoes"))) .upsert(new Upsert(constant(true).as("is_shoes"))); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

एग्रीगेशन सबक्वेरी से अपसर्ट करना

upsert() स्टेज का इस्तेमाल, एग्रीगेशन सबक्वेरी और स्केलर फ़ंक्शन के साथ किया जा सकता है. इससे डाइनैमिक तौर पर कंप्यूट की गई वैल्यू के आधार पर दस्तावेज़ों को अपडेट किया जा सकता है. जैसे, यह पता लगाना कि किसी उपयोगकर्ता का स्कोर सबसे ज़्यादा है या नहीं. इस पैटर्न को उपयोगकर्ता के लेन-देन के दौरान ही लागू किया जाना चाहिए.

Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("users") .where( field("score").equal( scalar( db.pipeline() .collection("scores") .aggregate({ accumulators: [max(field("points")).as("max_points")] }) .select(field("max_points")) ) ) ) .upsert([constant(true).as("is_top_scorer")]) ); }); ```
Java
```java Pipeline pipeline = db.pipeline() .collection("users") .where( eq( field("score"), scalar( db.pipeline() .collection("scores") .aggregate(max(field("points")).as("max_points")) .select(field("max_points"))))) .upsert(new Upsert(constant(true).as("is_top_scorer"))); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

जवाब

upsert() स्टेज हमेशा एक ही दस्तावेज़ दिखाता है, जैसे कि { documents_modified: 3 }. इसमें बताया जाता है कि कितने दस्तावेज़ डाले गए या अपडेट किए गए.

फ़ाइनल स्टेज

upsert() स्टेज, पाइपलाइन के आखिर में होनी चाहिए. इसके बाद, कोई और स्टेज नहीं जोड़ी जा सकती.

लेन-देन करना ज़रूरी है

upsert() स्टेज के लिए, लेन-देन करना ज़रूरी है. इसे रीड-राइट लेन-देन के दौरान या नया लेन-देन शुरू करते समय, atomic (Node.js) या auto_commit विकल्प को 'सही है' पर सेट करके चलाया जाना चाहिए.

जवाब

जवाब में, उन दस्तावेज़ों की संख्या की खास जानकारी शामिल होती है जिनमें बदलाव किया गया है. उदाहरण के लिए, यहां दिए गए जवाब से पुष्टि होती है कि पाइपलाइन ने तीन दस्तावेज़ों में बदलाव किया है:

{documents_modified: 3L}

सीमाएं

  • डीएमएल स्टेज को अब लेन-देन के दौरान चलाया जा सकता है. ज़्यादातर मामलों में, insert() और upsert() स्टेज को एक ही ट्रांज़ैक्शन में चलाना ज़रूरी होता है.

  • किसी नए लेन-देन में डीएमएल स्टेज वाली पाइपलाइन को लागू करते समय, atomic विकल्प का इस्तेमाल किया जा सकता है. इससे लेन-देन के दौरान पाइपलाइन अपने-आप चलती है और पाइपलाइन के पूरा होने पर लेन-देन पूरा हो जाता है.

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

  • लेन-देन के बाहर चलने पर:

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

  • अगर डीएमएल स्टेज से पहले की स्टेज में, एक ही __name__ वाले कई दस्तावेज़ जनरेट होते हैं या डेस्टिनेशन दस्तावेज़ का एक ही आईडी मिलता है, तो हर म्यूटेशन को क्रम से प्रोसेस किया जाता है:

    • upsert(...) और update(...) के लिए: एक ही दस्तावेज़ को टारगेट करने वाले कई म्यूटेशन, "लास्ट वन विंस" सिमैंटिक का पालन करते हैं. इसमें, प्रोसेस किया गया आखिरी म्यूटेशन, दस्तावेज़ की आखिरी स्थिति तय करता है.
    • delete(...) के लिए: पहली बार में दस्तावेज़ मिट जाता है. इसके बाद, उसी दस्तावेज़ को मिटाने के लिए की गई कार्रवाइयों का कोई असर नहीं होता.
    • insert(...) के लिए: पहली कोशिश में दस्तावेज़ बन जाता है. इसके बाद, उसी दस्तावेज़ आईडी को टारगेट करने की कोशिशें, ALREADY_EXISTS गड़बड़ी के साथ फ़ेल हो जाती हैं.

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

डीएमएल ऑपरेशन को रीड-राइट ट्रांज़ैक्शन के तौर पर चलाया जा सकता है. इसके लिए, पाइपलाइन एक्ज़ीक्यूशन कॉल को साफ़ तौर पर ट्रांज़ैक्शन की जानकारी देनी होगी या atomic विकल्प का इस्तेमाल करना होगा.

Firestore ट्रांज़ैक्शन में, डेटा लिखने से पहले उसे पढ़ना ज़रूरी है. डीएमएल पाइपलाइन, डेटा को सेव करने का काम करती है. इसलिए, एक ही लेन-देन में डीएमएल पाइपलाइन चलाने के बाद, डेटा को पढ़ने की प्रोसेस (जैसे, दस्तावेज़ खोजना या क्वेरी पढ़ना) नहीं की जा सकती. उदाहरण के लिए, किसी एक लेन-देन में डीएमएल पाइपलाइन को कई बार कॉल नहीं किया जा सकता. डीएमएल पाइपलाइन के लागू होने के बाद, डेटा को पढ़ने की कोशिश करने पर, FAILED_PRECONDITION गड़बड़ी का मैसेज दिखता है: Cannot have reads after the first write in a Firestore transaction.

एक्सप्लिसिट ट्रांज़ैक्शन का इस्तेमाल करना

Node.js
```js // Execute a pipeline with DML stage within an explicit transaction const pipeline = db.pipeline() .collection("users") .where(field("active").equal(false)) .addFields(constant("inactive").as("status")) .update(); await db.runTransaction(async (transaction) => { return transaction.execute(pipeline); }); ```
Java
```java // Execute a pipeline with DML stage within an explicit transaction Pipeline pipeline = db.pipeline() .collection("users") .where(field("active").equal(false)) .addFields(constant("inactive").as("status")) .update(); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```

atomic विकल्प का इस्तेमाल करना

Node.js
```js // Execute a pipeline const results = await db.pipeline() .collection("users") .where(field("active").equal(false)) .addFields(constant("inactive").as("status")) .update() .execute({ atomic: true }); ```
Java
```java // Execute a pipeline passing atomic option to execute() Pipeline pipeline = db.pipeline() .collection("users") .where(field("active").equal(false)) .addFields(constant("inactive").as("status")) .update(); pipeline.execute(new PipelineExecuteOptions().withAtomic(true)); ```