A newer version of this documentation is available.

View Latest

Frequently Asked Questions

    This section provides answers to commonly asked questions pertaining to the Eventing Service and Functions.


    • Is Eventing an MDS-enabled service?

      Yes. MDS enables workload isolation in a Couchbase cluster. Eventing nodes can be added as more Functions are added, or if the mutation rates are high.

    • What kind of nodes do I run my Eventing Service on?

      Eventing leverages the latest trends in multi-core CPUs; therefore nodes that you select for the Eventing Service should optimally have a higher number of cores than those for indexing.

    • Can the Eventing Service be co-located with other services?

      Yes, the Eventing Service node can be co-located with other MDS-enabled services.

    • Is it supported for both text and binary formats of the documents?

      The value or the document must always be text in the form of a JSON document.

    Change Capture

    • Will all the updates to a document be seen in DCP?

      When a document is updated multiple times in a small time-window, not all updates are seen in DCP. This means that the event handlers see only those deduplicated events that are published in DCP.

    • Can a Function listen to all changes across Couchbase Server?

      A defined Function listens only to changes that are exposed using the DCP for the buckets (Couchbase and Ephemeral) in the data-nodes. Memcached buckets are not supported. The Function cannot listen to changes happening in other Couchbase components, such as FTS, Views, or GSI; nor can it listen to system events.

    • Can we determine what has changed on the document?

      No. But you can implement versioning as part of the application logic. If versioning is important, include it as part of the data architecture.

    • Can I get old and new values of the document inside the Function?

      No. We do not support versioning of documents; therefore, this feature is not available out of the box. However, you can have a parent bucket and its replica version. The replica bucket would retain the version of documents before the current set of changes.

    • Is the ordering of document mutations enforced?

      All changes from a document are always processed in order.


    • Are Functions similar to a Database Trigger?

      In a rough sense, Functions are similar to the Post-Triggers of the database world. But with Functions, the action is already completed at the data-layer, and the event handler gives an interface by which developers can key in the logic of what needs to happen ‘after’ the action is done. What a Function sees is the actual event of the change, and hence it does not directly correlate with Database Triggers.

    • Are Functions similar to a Rules Engine?

      Not exactly. A Rules Engine enforces ordering and other semantics that is not possible out of the box with Functions. However, Functions can be used to implement one - even Rules Engine. The Function in its purest form offers a rule to implemented closer to the data, but cannot trigger another Function directly.

    • Are Functions similar to a Stored Procedure?

      Stored Procedures enforce a request-response model. A stored procedure will not be invoked automatically; it has to be invoked by a calling method. Functions are based on the idea of events. Changes to the data are events. These events trigger Functions, and hence this is not a request-response model in its purest sense.

    • Do I need a separate middleware to consume the Functions? How do I consume changes in my middleware/application?

      Database changes are consumed using the Function defined: there is no other programmatic way of accessing the changes (such as by using an SDK, or some other form of middleware). REST endpoints are exposed, to perform administrative operations

    • Can I import my own JS libraries or Node Modules?

      No. We do not allow import of node modules or external JS libraries.

    • Are Functions supported for both Data Node and Document storage?

      The Eventing Service listens to changes that appear in the DCP. DCP is valid for the Data Service, and Functions operate on documents that are either in key-value or in document (JSON) format.

    • What happens when a Function is debugged?

      We block one of the mutations alone and hand it over to the debugger session. The rest of the mutations continue to be serviced by the event handler.

    • How to perform Functions lifecycle operations from CI/CD?

      To perform Functions lifecycle operations from CI/CD, refer to CLI Eventing section.

    • How to invoke a REST endpoint from inside the Function?

      To invoke a REST Endpoint from inside the Function, refer to Functions REST API section.

    • How does the Functions offering compare with the Couchbase’s Kafka Connector?

      The Functions offering is about server-side processing or compute; it does not require any middleware to be deployed or managed. Couchbase’s Kafka connector is an SDK component that needs an application container or middleware to run.

    Function Handler Code

    • What languages are supported?

      Javascript is the language to be used while creating Functions. Node modules cannot be imported: only simple Javascript can be used.

    • Why can’t I create global variables?

      We restrict the language model in such a way that chances of going wrong are minimized. As Functions are stateless compute entities, global variables do not have a good use-case, and therefore, they are not supported. Though you can define Javascript functions inside a Function (outside the scope of OnUpdate and OnDelete) that can be invoked any number of times from either of the event handlers.

    • What is in the "meta" Function parameter (OnUpdate, OnDelete)? Is this the metadata we currently write in order to figure out what has changed in the document?

      These are the meta fields associated with the document. For more information, refer to the Link section.

    • What is the metadata bucket? Do I need to create a separate bucket?

      To provide better resiliency and restartability semantics across Eventing nodes, some of the metadata that is used by the Eventing service needs to be stored in a standard Couchbase bucket (hereafter referred to as the 'metadata bucket').

      After provisioning the Eventing nodes in your cluster, you’ll need to create the metadata bucket before you can start using the Eventing service. All Eventing functions within a cluster can share the same metadata bucket (this is a best practice but not a requirement), regardless of the number of functions, or their source and destination buckets. (Setting up a metadata bucket is a one-time activity for the cluster should you choose to follow this best practice.)

      Some additional requirements of the metadata bucket are as follows:

      • You should enable vBucket replicas on the metadata bucket to allow for failure recovery.

      • You should reserve the metadata bucket solely for Eventing housekeeping. It shouldn’t be used for any other data storage.

      • As a rule of thumb, the metadata bucket should be about 1/10 of the size of the source bucket. However, if the source bucket is made up of very small documents, the sizing of the metadata bucket would trend towards the size of the source bucket. If the Eventing functions utilize timers, then double this estimate.

    • Can there be more than one Function listening to changes to a bucket?

      Yes. More than one Function can be defined for the same bucket. This lets you process the change according to the business logic that you enforce. But there is no ordering enforced; for example, if bucket 'wine' has three different Functions, which are FunctionA, FunctionB, and FunctionC, you cannot enforce the order in which these Functions are executed. Also, database triggers suffered from scalability and diagnosability issues. Functions offer multiple diagnosability solutions and is highly scalable and performant.

    • Is it possible to get additional state during a Function execution? For example, can you read from the data service in a Function to fetch related data? For example, can we enrich the updated document with data from another document (using a document id)?

      Yes. You can read from any other bucket, and enrich the document.

    Cluster Behavior

    • What happens to the Eventing Service during a failover condition?

      When the Data service experiences a failover condition, mutations may be lost and these lost mutations are not processed by the Eventing service. When the Eventing node experiences a failover condition, few mutations may be processed more than once.

    • Does a rebalance have any effect on the firing of events?

      No. Functions do not lose any mutations during a rebalance operation.

    • I have Functions deployed on my cluster, when can I perform an Eventing rebalance operation?

      The Function lifecycle operations (deploying, undeploying and deleting operations)
      and the Eventing rebalance operation are mutually exclusive. The Eventing rebalance
      operation fails when a Function lifecycle operation is currently in progress. Likewise,
      when the Eventing rebalance operation is in progress, you cannot perform a Function
      lifecycle operation.