Advanced Keyspace Accessors

Enterprise Edition

Advanced Keyspace Accessors make it possible to access advanced KV functionality using the following built-in operators. They utilize the same bucket bindings defined in the handler as Basic Keyspace Accessors, but expose a richer set of options and operators that can be used to 1) set or retrieve expirations, 2) solve race conditions via CAS and 3) manipulate hot KV items under high contention.

The Basic Keyspace Accessors are much easier to use, having a trivial API, and are also a bit faster than the corresponding Advanced Keyspace Accessors.

The following Advanced Keyspace Accessors are supported:

The Advanced GET operation
The Advanced INSERT operation
The Advanced UPSERT operation
The Advanced REPLACE operation
The Advanced DELETE operation
The Advanced INCREMENT operation
The Advanced DECREMENT operation

These seven (7) Advanced Keyspace Accessors make it possible to utilize and leverage CAS directly and/or set a document expiration (or TTL) in the Data Service (or KV) via Eventing plus perform distributed atomic counter operations.

For example rather than blindly relying on the Basic Keyspace Accessors for an upsert like operation ‘src_col[id_str] = some_doc’ the Advanced Accessors allow you to resolve contention (or possible contention) with JavaScript driven logic in your Eventing Function.

If the document doesn’t exist you can use ‘couchbase.insert(src_col, {"id: id_str}, some_doc)’ and check the return value for success
You can use ‘couchbase.upsert(src_col, {"id: id_str}, some_doc)’ to update a document if it already exists. If the document doesn’t exist, then a new document will be created. Check the return value to see if the operation was successful.
If the document exists you can use ‘couchbase.replace(src_col, {"id: id_str, "cas": current_cas}, some_doc)’ and check the return value for success or a CAS mismatch.

To view complete examples including JavaScript, input mutations, output mutations and/or log messages for each Advanced Bucket Accessor refer to Scriptlets: Advanced Accessor Handlers in the examples section of the documentation.

Functions that Listen to Multiple Collections: may require the meta.keyspace parameter

For Eventing Functions that listen to multiple collections via a wildcard of * for the scope and/or the collection, an additional parameter is required if the binding used by the Advanced Keyspace Accessor also contains a wildcard of * for the scope and/or the collection.

‘couchbase.insert(src_col, {"id: id_str, "keyspace":{"bucket_name": "bkt01","scope_name":"scp01","collection_name":"col01"}}, some_doc)’

The example above adds a keyspace to the meta object to specify win which keyspace the insert is to take place. Note as of 7.1.1 the entry points of OnUpdate() and OnDelete() provide meta.keyspace with every mutation. For a detailed example refer to the multiCollectionEventing example in Scriptlets: Advanced Accessor Handlers

The Advanced GET operation: result = couchbase.get(binding, meta)

This operation allows reading a document along with metadata from the bucket and subsequent operations to utilize CAS or check/modify the expiry_date.

Contrast this to the Basic Bucket Accessor GET operation which merely exposes a JavaScript binding or map, "var adoc = src_col[meta.id]", where the return value is just the document without any metadata.

Below is an example of the Advanced GET operation.

function OnUpdate(doc, meta) {
    log('input doc ', doc);
    log('input meta', meta);
    // could be the same or different
    var new_meta = {"id":"test_adv_get::1"};
    var result = couchbase.get(src_col,new_meta);
    if (result.success) {
        log('success adv. get: result',result);
    } else {
        log('failure adv. get: id',new_meta.id,'result',result);
    }
}

Couchbase Server 7.0.2 In version 7.0.2 an optional third parameter {"cache": true} enables a bucket backed cache to hold the document for at most 1 second. This cache exists on each eventing node and is shared across all Eventing Functions (or threads) on the same node.

The performance is typically 18X-25X faster than reading data directly from the Data Service (or KV). A common use case is to load near static data such as a lookup table from the Data Service where the external data is needed on every document mutation to drive the Eventing Function’s business logic.

This cache has RYOW (read your own write) semantics. This implies that a thread of execution writing and then subsequently reading the same document with {"cache": true} will always retreive the value just written.

function OnUpdate(doc, meta) {
    log('input doc ', doc);
    log('input meta', meta);
    // could be the same or different
    var new_meta = {"id":"test_adv_get::1"};
    var result = couchbase.get(src_col,new_meta,{"cache": true});
    if (result.success) {
        log('success adv. get: result',result);
    } else {
        log('failure adv. get: id',new_meta.id,'result',result);
    }
}

Some example return values:

{
    "doc": {
        "id": 1,
        "type": "test_adv_get"
    },
    "meta": {
        "id": "test_adv_get::1",
        "cas": "1610034762747412480",
        "datatype": "json"
    },
    "success": true
}

{
    "doc": {
        "a": 1,
        "random": 0.09799092443129842
    },
    "meta": {
        "id": "test_adv_insert:1",
        "cas": "1610140272584884224",
        "expiry_date": "2021-01-08T21:12:12.000Z",
        "datatype": "json"
    },
    "success": true
}

{
    "error": {
        "code": 272,
        "name": "LCB_KEY_ENOENT",
        "desc": "The document key does not exist on the server",
        "key_not_found": true
    },
    "success": false
}

binding

The name of the binding that references the target bucket. The binding can have an access level of "read" or "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At a minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the data fetched if successful, or details of the error in case of a failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the object that was fetched. If the specified key is not present in the bucket, the operation fails and key_not_found will be set in the error object.
  - result.meta.id (type: string)
    
    The key of the document that was fetched by this operation.
  - result.meta.cas (type: string)
    
    The CAS value of the document that was fetched by this operation.
  - result.meta.expiry_date (type: Date)
    
    The expiration date of the document. If no expiration is set on the document, this field will be absent.
  - result.meta.datatype (type: string)
    
    An indicator of whther the document is "json" or "binary". Couchbase Server 6.6.2
- result.doc (type: string, number, boolean, null, Object or Array)
  
  If the operation is successful, this field contains the content of the requested document.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  - result.error.key_not_found (type: boolean)
    
    If present and set to true, this indicates that the operation failed because the specified key did not exist in the bucket.
  - result.error.code (type: number)
    
    If present, represents the SDK error code that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced INSERT operation: result = couchbase.insert(binding, meta, doc)

This operation allows creating a fresh document in the bucket. This operation will fail if the document with the specified key already exists. It allows specifying an expiration time (or TTL) to be set on the document.

There is no analogous Basic Bucket Accessor operation to the Advanced INSERT operation (as "src_col[meta.id] = adoc" is more like an upsert).

Below is an example of the Advanced INSERT operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);
    // could be the same or different
    var new_meta = {"id":"test_adv_insert:1"};
    // optional set an expiry 60 seconds in the future
    // new_meta.expiry_date = new Date(Date.now() + 60 * 1000);
    var new_doc = doc;
    new_doc.random = Math.random();
    var result = couchbase.insert(src_col,new_meta,new_doc);
    if (result.success) {
        log('success adv. insert: result',result);
    } else {
        log('failure adv. insert: id',new_meta.id,'result',result);
    }
}

Some example return values:

{
    "meta": {
        "id": "test_adv_insert:1",
        "cas": "1610041053310025728"
    },
    "success": true
}

{
    "error": {
        "code": 272,
        "name": "LCB_KEY_EEXISTS",
        "desc": "The document key already exists in the server.",
        "key_already_exists": true
    },
    "success": false
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. The document key must be specified in this meta object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type. If a document already exists with the specified key, the operation fails and key_already_exists will be set in the error object.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
- meta.expiry_date (type: Date)
  
  This is an optional parameter, and if specified must be of JavaScript Date object type. The document will be marked to expire at the specified time. If no expiry_date is passed, no expiration will be set on the document.
doc (type: any JSON serializable))

This is the document content for the operation. This can be any JavaScript object that can be serialized to JSON (i.e., number, string, boolean, null, object and array).
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the data fetched if successful, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the object that was inserted.
  - result.meta.id (type: string)
    
    The key of the document that was inserted by this operation.
  - result.meta.cas (type: string)
    
    The CAS value of the document that was created by this operation.
  - result.meta.expiry_date (type: Date)
    
    The expiration field of the document, if one was set. If no expiration is set on the document, this field will be absent.
- result.doc (type: string, number, boolean, null, Object or Array)
  
  If the operation is successful, this field contains the content of the requested document.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  - result.error.key_already_exists (type: boolean)
    
    If present and set to true, this indicates that the operation failed because the specified key already existed.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced UPSERT operation: result = couchbase.upsert(binding, meta, doc)

This operation allows updating an existing document in the bucket, or if absent, creating a fresh document with the specified key. The operation does not allow specifying CAS (it will be silently ignored). It also allows specifying an expiration time (or TTL) to be set on the document.

Contrast this to the Basic Bucket Accessor SET operation which merely uses an exposed JavaScript map defined via a bucket binding alias "src_col[meta.id] = adoc". For the basic SET operation there is no return value (no status and no metadata) thus no way to check the CAS value.

Below is an example of the Advanced UPSERT operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);
    // could be the same or different
    var new_meta = {"id":"test_adv_upsert:1"}; // CAS if supplied will be ignored
    // optional set an expiry 60 seconds in the future
    // new_meta.expiry_date = new Date(Date.now() + 60 * 1000);
    var new_doc = doc;
    new_doc.random = Math.random();
    var result = couchbase.upsert(src_col,new_meta,new_doc);
    if (result.success) {
        log('success adv. upsert: result',result);
    } else {
        log('failure adv. upsert: id',new_meta.id,'result',result);
    }
}

An example return value:

{
    "meta": {
        "id": "test_adv_upsert:1",
        "cas": "1610127444908376064"
    },
    "success": true
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
- meta.expiry_date (type: Date)
  
  This is an optional parameter. If specified, it must be of JavaScript Date object type. The document created or updated by this operation will be marked to expire at the specified time. If no expiry_date is passed, and if the document had a prior expiration set, the prior expiration will be cleared.
doc (type: any JSON serializable))

This is the document content for the operation. This can be any JavaScript object that can be serialized to JSON (i.e., number, string, boolean, null, object and array).
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the metadata of the operation, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the object that was inserted or updated.
  - result.meta.id (type: string)
    
    The key of the document that was inserted or updated by this operation.
  - result.meta.cas (type: string)
    
    The CAS value of the document that was inserted or updated by this operation.
  - result.meta.expiry_date (type: Date)
    
    The expiration field of the document, if one was set. If no expiration is set on the document, this field will be absent.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced REPLACE operation: result = couchbase.replace(binding, meta, doc)

This operation replaces an existing document in the bucket. This operation will fail if the document with the specified key does not exist. This operation allows specifying a CAS value that must be matched as a pre-condition before proceeding with the operation. It also allows specifying an expiration time (or TTL) to be set on the document.

There is no analogous Basic Bucket Accessor operation to the Advanced REPLACE operation (as "src_col[meta.id] = adoc" is more like an upsert).

Below is an example of the Advanced REPLACE operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);

    var mode = 3; // 1-> no CA, 2-> mismatch in CA, 3-> good CAS

    // Setup, make sure we have our doc to "replace", ignore any errors
    couchbase.insert(src_col,{"id":"test_adv_replace:10"},{"a:": 1});

    var new_meta;
    if (mode === 1) {
        // If we pass no CAS it will succeed
        new_meta = {"id":"test_adv_replace:10"};
        // optional set an expiry 60 seconds in the future
        // new_meta.expiry_date = new Date(Date.now() + 60 * 1000);
    }
    if (mode === 2) {
        // If we pass a non-matching CAS it will fail, so test this
        new_meta = {"id":"test_adv_replace:10", "cas":"1111111111111111111"};
    }
    if (mode === 3) {
        // If we pass the matching or current CAS it will succeed
        var tmp_r = couchbase.get(src_col,{"id":"test_adv_replace:10"});
        if (tmp_r.success) {
            // Here we use the current CAS just read via couchbase.get(...)
            new_meta = {"id":"test_adv_replace:10", "cas": tmp_r.meta.cas};
        } else {
            log('Cannot replace non-existing key that create it and rerun',"test_adv_replace:10");
            return;
        }
    }
    var new_doc = doc;
    new_doc.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);
    }
}

Some example return values:

{
    "meta": {
        "id": "test_adv_replace:10",
        "cas": "1610130177286144000"
    },
    "success": true
}

{
    "error": {
        "code": 272,
        "name": "LCB_KEY_EEXISTS",
        "desc": "The document key exists with a CAS value different than specified",
        "cas_mismatch": true
    },
    "success": false
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At a minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type. If the specified key is not present in the bucket, the operation fails and key_not_found will be set in the error object.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
- meta.cas (type: string)
  
  This is an optional parameter that specifies the CAS value to be used as a pre-condition for the operation. If the document’s CAS value does not match the CAS value specified here, the operation will fail, setting the parameter cas_mismatch to true in the error object of the return object.
- meta.expiry_date (type: Date)
  
  This is an optional parameter. If specified, it must be of JavaScript Date object type. The document updated by this operation will be marked to expire at the specified time. If no expiration is provided, and if the document had a prior expiration set, the prior expiration will be cleared.
doc (type: any JSON serializable))

This is the document content for the operation. This can be any JavaScript object that can be serialized to JSON (i.e., number, string, boolean, null, object and array).
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the metadata of the operation, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the object that was replaced.
  - result.meta.id (type: string)
    
    The key of the document that was replaced by this operation.
  - result.meta.cas (type: string)
    
    The CAS value of the document that was replaced by this operation.
  - result.meta.expiry_date (type: Date)
    
    The expiration field of the document, if one was set. If no expiration is set on the document, this field will be absent.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  - result.error.error.cas_mismatch (type: boolean)
    
    If present and set to true, this indicates that the operation failed because a CAS value was specified, and the CAS value on the object did not match the requested value.
  - result.error.key_not_found (type: boolean)
    
    If present and set to true, this indicates that the operation failed because the specified key did not exist in the bucket.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced DELETE operation: result = couchbase.delete(binding, meta)

This operation allows deleting a document in the bucket specified by key. Optionally, a CAS value may be specified which will be matched as a pre-condition to proceed with the operation.

Contrast this to the Basic Bucket Accessor DEL operation which merely uses an exposed a JavaScript binding or map, "delete src_col[meta.id]", where there is no return value (no status and no metadata).

Below is an example of the Advanced DELETE operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);

    var mode = 4; // 1-> no CA, 2-> mismatch in CA, 3-> good CAS, 4-> no such key

    // Setup, make sure we have our doc to "delete", ignore any errors
    couchbase.insert(src_col,{"id":"test_adv_delete:10"},{"a:": 1});

    var new_meta;
    if (mode === 1) {
        // If we pass no CAS it will succeed
        new_meta = {"id":"test_adv_delete:10"};
        // optional set an expiry 60 seconds in the future
        // new_meta.expiry_date = new Date(Date.now() + 60 * 1000);
    }
    if (mode === 2) {
        // If we pass a non-matching CAS it will fail, so test this
        new_meta = {"id":"test_adv_delete:10", "cas":"1111111111111111111"};
    }
    if (mode === 3) {
        // If we pass the matching or current CAS it will succeed
        var tmp_r = couchbase.get(src_col,{"id":"test_adv_delete:10"});
        if (tmp_r.success) {
            // Here we use the current CAS just read via couchbase.get(...)
            new_meta = {"id":"test_adv_delete:10", "cas": tmp_r.meta.cas};
        } else {
            log('Cannot delete non-existing key that create it and rerun',"test_adv_delete:10");
            return;
        }
    }
    if (mode === 4) {
        // Remove so that we have: no such key
        delete src_col["test_adv_delete:10"]
        new_meta = {"id":"test_adv_delete:10"};
    }
    var result = couchbase.delete(src_col,new_meta);
    if (result.success) {
        log('success adv. delete: result',result);
    } else {
        log('failure adv. delete: id',new_meta.id,'result',result);
    }
}

Some example return values:

{
    "meta": {
        "id": "key::10",
        "cas": "1609374065129816064"
    },
    "success": true
}

{
    "error": {
        "code": 272,
        "name": "LCB_KEY_EEXISTS",
        "desc": "The document key exists with a CAS value different than specified",
        "cas_mismatch": true
    },
    "success": false
}

{
    "error": {
        "code": 272,
        "name": "LCB_KEY_ENOENT",
        "desc": "The document key does not exist on the server",
        "key_not_found": true
    },
    "success": false
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At a minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type. If the specified key is not present in the bucket, the operation fails and key_not_found will be set in the error object.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
- meta.cas (type: string)
  
  This is an optional parameter that specifies the CAS value to be used as a pre-condition for the operation. If the document’s CAS value does not match the CAS value specified here, the operation will fail, setting the parameter cas_mismatch to true in the error object of the return object.
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the metadata of the operation, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the object that was deleted.
  - result.meta.id (type: string)
    
    The key of the document that was deleted by this operation.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  - result.error.error.cas_mismatch (type: boolean)
    
    If present and set to true, this indicates that the operation failed because a CAS value was specified, and the CAS value on the object did not match the requested value.
  - result.error.key_not_found (type: boolean)
    
    If present and set to true, this indicates that the operation failed because the specified key did not exist in the bucket.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced INCREMENT operation: result = couchbase.incrment(binding, meta)

This operation atomically increments the field "count" in the specified document. The document must have the below structure:

{"count": 23} // 23 is the current counter value

The increment operation returns the post-increment value.

If the specified counter document does not exist, one is created with count value as 0 and the structure noted above. And so, the first returned value will be 1.

Due to limitations in KV engine API, this operation cannot currently manipulate full document counters.

There is no analogous Basic Bucket Accessor operation to the Advanced INCREMENT operation.

Below is an example of the Advanced INCREMENT operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);

    // if doc.count doesn't exist it will be created
    var ctr_meta = {"id": "my_atomic_counter:1" };
    var result = couchbase.increment(src_col,ctr_meta);
    if (result.success) {
        log('success adv. increment: result',result);
    } else {
        log('failure adv. increment: id',ctr_meta.id,'result',result);
    }
}

An example return value, assume you create this KEY "my_atomic_counter:1" DOC {"count": 23} if the Eventing function above is deployed the count will be immediately incremented :

{
    "doc": {
        "count": 24
    },
    "meta": {
        "id": "key::1",
        "cas": "1609374571840471040"
    },
    "success": true
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the metadata of the operation, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the counter that was incremented (or created and incremented).
  - result.meta.id (type: string)
    
    The key of the document that was incremented (or created and incremented) by this operation.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  
  Note: if you will be handling large counts (more than 15 digits), please refer to JSON Number Precision.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.

The Advanced DECREMENT operation: result = couchbase.decrement(binding, meta)

This operation atomically decrements the field "count" in the specified document. The document must have the below structure:

{"count": 23} // 23 is the current counter value

The decrement operation returns the post-decrement value.

If the specified counter document does not exist, one is created with count value as 0 and the structure noted above. And so, the first returned value will be -1.

Due to limitations in KV engine API, this operation cannot currently manipulate full document counters.

There is no analogous Basic Bucket Accessor operation to the Advanced DECREMENT operation.

Below is an example of the Advanced DECREMENT operation.

function OnUpdate(doc, meta) {
    log('input meta', meta);
    log('input doc ', doc);

    // if doc.count doesn't exist it will be created
    var ctr_meta = {"id": "my_atomic_counter:1" };
    var result = couchbase.decrement(src_col,ctr_meta);
    if (result.success) {
        log('success adv. decrement: result',result);
    } else {
        log('failure adv. decrement: id',ctr_meta.id,'result',result);
    }
}

An example return value, assume you create this KEY "my_atomic_counter:1" DOC {"count": 23} if the Eventing function above is deployed the count will be immediately decremented :

{
    "doc": {
        "count": 22
    },
    "meta": {
        "id": "key::1",
        "cas": "1609374770297176064"
    },
    "success": true
}

binding

The name of the binding that references the target bucket. The binding must have access level of "read/write".
meta (type: Object)

The positional parameter (denoted by meta in the prototype above) represents the metadata of the operation. At minimum, the document key must be specified in this object.
- meta.id (type: string)
  
  The key of the document to be used for the operation. This is a mandatory parameter and must be of JavaScript string type.
- meta.keyspace (type: Object)
  
  The keyspace of the document to be used for the operation with the JavaScript format:
  "keyspace":{"bucket_name":_string_,"scope_name":_string_,"collection_name":_string_}
  This parameter is only required if you are using a binding with a wildcard for the scope and/or the collection.
result – the return value (type: Object)

The return object indicates success/failure of the operation, and the metadata of the operation, or the error details if failure.
- result.success (type: boolean)
  
  This field indicates if the operation was successful or not. It is always present in the return object.
- result.meta (type: Object)
  
  This field is present only if the operation succeeded. It contains metadata about the counter that was decremented (or created and decremented).
  - result.meta.id (type: string)
    
    The key of the document that was decremented (or created and decremented) by this operation.
- result.error (type: Object)
  
  This field is populated only if the operation failed. The content of the error varies based on the type of error encountered, and commonly occurring fields are documented below.
  
  Note: if you will be handling large counts (more than 15 digits), please refer to JSON Number Precision.
  - result.error.code (type: number)
    
    If present, the code of the SDK error that triggered this operation to fail. This is typically an internal numeric code.
  - result.error.name (type: string)
    
    If present, the key is a token indicating the error that SDK encountered that caused this operation to fail.
  - result.error.desc (type: string)
    
    If present, a human readable description of the error that occurred. The description is for diagnostics and logging purposes only and may change over time. No programmatic logic should be tied to specific contents from this field.
exceptions

This API indicates errors via the error object in the return value. Exceptions are thrown only during system failure conditions.