A newer version of this documentation is available.

View Latest

Function: Advanced REPLACE Operation

    Couchbase Server Enterprise Edition 7.6 reaches End of Life on March 31, 2027. Please upgrade to 8.0.x by following Upgrade, or contact Couchbase Support.

    Perform the Advanced REPLACE operation where Eventing interacts with the Data Service.

    The advancedReplaceOp function:

    • Performs the Advanced REPLACE operation

    • Requires Eventing Storage (or a metadata collection) and a source collection

    • Requires a binding of type bucket alias

    • Operates on any mutation where doc.type === "control_adv_replace"

    • Always tries to insert the test document and ignores insert errors

    • Has 3 modes of operation: no_cas, bad_cas, and good_cas

    For more information about the Advanced Self-Recursion Parameter, see Advanced REPLACE Operation.

    • advancedReplaceOp

    • Input data

    • Output data

    • Output log

    // Configure the settings for the advancedReplaceOp function as follows:
    //
    // Version 7.1+
    //   "Function Scope"
    //     *.* (or try bulk.data if non-privileged)
    // Version 7.0+
    //   "Listen to Location"
    //     bulk.data.source
    //   "Eventing Storage"
    //     rr100.eventing.metadata
    //   Binding(s)
    //    1. "binding type", "alias name...", "bucket.scope.collection", "Access"
    //       "bucket alias", "src_col",       "bulk.data.source",        "read and write"
    //
    // Version 6.6.1
    //   "Source Bucket"
    //     source
    //   "MetaData Bucket"
    //     metadata
    //   Binding(s)
    //    1. "binding type", "alias name...", "bucket",     "Access"
    //       "bucket alias", "src_col",       "source",     "read and write"
    
    function OnUpdate(doc, meta) {
        if (!meta.id.startsWith("control_adv_replace")) return;
    
        log('input meta', meta);
        log('input doc ', doc);
    
        // Setup, make sure there is a doc to "replace", ignore any errors
        couchbase.insert(src_col,{"id":"test_adv_replace:" + doc.ins_id},{"a:": 1});
    
        var new_meta;
        if (doc.mode && doc.mode === "no_cas") {
            // No CAS is passed - it always succeeds
            new_meta = {"id":"test_adv_replace:" + doc.ins_id};
            // (Optional) Set an expiry 60 seconds in the future
            // new_meta.expiry_date = new Date(Date.now() + 60 * 1000);
        }
        if (doc.mode && doc.mode === "bad_cas") {
            // Pass a non-matching CAS - it always fails
            new_meta = {"id":"test_adv_replace:" + doc.ins_id, "cas":"1111111111111111111"};
        }
        if (doc.mode && doc.mode === "good_cas") {
            // Pass the matching or current CAS - it succeeds
            var tmp_r = couchbase.get(src_col,{"id":"test_adv_replace:" + doc.ins_id});
            if (tmp_r.success) {
                // Use the current CAS to read via couchbase.get(...)
                new_meta = {"id":"test_adv_replace:" + doc.ins_id, "cas": tmp_r.meta.cas};
            } else {
                log('Cannot replace due to no such key',"test_adv_replace:" + doc.ins_id);
                return;
            }
        }
        var new_doc = {id: doc.ins_id, type: "test_adv_replace", random: Math.random()};
        var result = couchbase.replace(src_col,new_meta,new_doc);
        if (result.success) {
            log('success adv. replace: result',result);
        } else {
            log('failure adv. replace: id',new_meta.id,'result',result);
        }
    }
    Mutation #1
    
    INPUT: KEY control_adv_replace::1
    
    {
      "id": 1,
      "type": "control_adv_replace",
      "ins_id": 10,
      "mode": "no_cas"
    }
    
    Mutation #2
    
    INPUT: KEY control_adv_replace::2
    
    {
      "id": 2,
      "type": "control_adv_replace",
      "ins_id": 10,
      "mode": "bad_cas"
    }
    
    Mutation #3
    
    INPUT: KEY control_adv_replace::3
    
    {
      "id": 3,
      "type": "control_adv_replace",
      "ins_id": 10,
      "mode": "good_cas"
    }

    Replace 3 documents. The first and last replacements are successful; the second replacement fails because of a CAS mismatch.

    KEY: test_adv_replace:10
    
    {
      "id": 10,
      "type": "test_adv_replace",
      "random": 0.40223830137164085
    }
    Logs from Mutation #1
    
    2021-01-08T10:58:39.846-08:00 [INFO] "input meta"
    {
        "cas": "1610131902064820224",
        "id": "control_adv_replace::1",
        "expiration": 0,
        "flags": 33554438,
        "vb": 417,
        "seq": 4
    }
    2021-01-08T10:58:39.846-08:00 [INFO] "input doc "
    {
        "id": 1,
        "type": "control_adv_replace",
        "ins_id": 10,
        "mode": "no_cas"
    }
    2021-01-08T10:58:39.847-08:00 [INFO] "success adv. replace: result"
    {
        "meta": {
            "id": "test_adv_replace:10",
            "cas": "1610132319847055360"
        },
        "success": true
    }
    
    Logs from Mutation #2
    
    2021-01-08T10:59:04.151-08:00 [INFO] "input meta"
    {
        "cas": "1610132344113397760",
        "id": "control_adv_replace::2",
        "expiration": 0,
        "flags": 33554438,
        "vb": 168,
        "seq": 3
    }
    2021-01-08T10:59:04.151-08:00 [INFO] "input doc "
    {
        "id": 2,
        "type": "control_adv_replace",
        "ins_id": 10,
        "mode": "bad_cas"
    }
    2021-01-08T10:59:04.154-08:00 [INFO] "failure adv. replace: id" "test_adv_replace:10" "result"
    {
        "error": {
            "code": 272,
            "name": "LCB_KEY_EEXISTS",
            "desc": "The document key exists with a CAS value different than specified",
            "cas_mismatch": true
        },
        "success": false
    }
    
    Logs from Mutation #3
    
    2021-01-08T10:59:35.692-08:00 [INFO] "input meta"
    {
        "cas": "1610132375634706432",
        "id": "control_adv_replace::3",
        "expiration": 0,
        "flags": 33554438,
        "vb": 943,
        "seq": 3
    }
    2021-01-08T10:59:35.692-08:00 [INFO] "input doc "
    {
        "id": 3,
        "type": "control_adv_replace",
        "ins_id": 10,
        "mode": "good_cas"
    }
    2021-01-08T10:59:35.696-08:00 [INFO] "success adv. replace: result"
    {
        "meta": {
            "id": "test_adv_replace:10",
            "cas": "1610132375695589376"
        },
        "success": true
    }