A newer version of this documentation is available.

View Latest

Terminology

While using Functions, the following terminologies are used:

Functions

Functions offers a computing paradigm using which developers can handle data changes. Functions are either OnUpdate or OnDelete. Resources are managed at or above a Function level, and the containing Function scopes the state of all handlers.

Handler

A stateless, short-running code-fragment that reacts to a specified event. One or more handlers together constitute a Function. A handler must execute from start to finish, before a specified timeout-duration. Currently, OnUpdate and OnDelete are the two supported handlers. Couchbase Functions support multiple OnUpdate/OnDelete handlers during the Function definition process.

In the Couchbase Server 5.5 release, the handler code size is limited to 128KB.

Statelessness

The persistent state of a Function is captured by entities listed below, while any state that appears on the execution stack is ephemeral.

  • The metadata bucket (which will eventually be a system collection).

  • The document being observed and its Extended Attributes.

Buckets

Every Function definition needs two distinct buckets: source bucket and metadata bucket.

The Functions use a source bucket to listen to data changes. The Function handler code polls the source bucket for data mutations. Multiple Functions can use the same source bucket.

Metadata bucket stores internal artifacts and checkpoint information. The metadata bucket provides better restartability semantics when the eventing nodes is offline. Ensure that your Function handler code does not write any data to this bucket.

The Functions can in turn trigger data mutations, to avoid a cyclic generation of events, ensure that you carefully consider options when you select the source and destination buckets. When you are using a series of handlers, ensure that:

  • The source bucket can be either Couchbase or Ephemeral bucket. However, memcached buckets are not supported.

  • Metadata bucket is used by the Eventing Service to store some critical checkpoint information. Avoid writing to the metadata bucket or flushing it. It is recommended that a separate bucket be kept destined as a metadata bucket.

  • A read operation from the source bucket is allowed but operations such as delete, set and update are not supported.

  • The destination buckets to which event handlers perform a write operation, do not have other event handlers configured to listen and track data mutations.

Workers

Workers can be defined as an execution unit that is assigned a group of vBuckets. The worker units are used mostly during Function execution.

Bindings

Bindings are constructs that allow the separating of environment-specific variables from the handler source code such as bucket-names, external endpoint URLs, and credentials. Bindings allow Functions to be developed without source-code changes while working on different workflows. Using bindings, you can port source code from different environments such as Test-to-Test, Test-to-Production, or Production-to-Production environments without making code changes.

During Function definition when you are creating a bindings name-value pair, for a source bucket, ensure that only read operation is performed in the Function handler code.

Function Settings

The log levels, script timeout, and workers allocation are additional options available during the Function definition process.

  • Log Levels: Use log levels to determine the granularity of log messages.

  • Script Timeout: Script Timeout provides a timeout option to terminate a non-responsive Function.

  • Workers: Workers allocate the number of worker threads for a specific Function.

    For a defined Function, Couchbase Server limits the maximum number of workers to 10. This upper limit is configured for system optimization purposes. In the Function definition, if the number of workers exceeds a set threshold, then the system automatically generates a warning message. However, this warning message does not prevent deployment of the Function.

Deploy

The deploy operation activates a Function. Multiple Functions can be deployed in a cluster. Couchbase server performs source validations before deploying a Function, and only valid Functions get deployed. The deploy operation transpiles the code and creates the executable v8 artifacts. The source code of a deployed Function cannot be edited. The Function must be in a deployed status to process events. Once you deploy a Function, depending on the Feed Boundary conditions, the Function execution starts processing the data mutations. Deployment of a Function triggers actions such as creating of necessary metadata, initiating worker processes, calculating initial partitions, and creating checkpoints of processed stream data. To edit a deployed Function, you must first un-deploy the Function.

Feed Boundary

Feed Boundary is a time milestone used during a Function configuration. Using the Feed Boundary option, you can either invoke a Function on all the data present in the cluster or choose to invoke a Function during future instances of data mutation, post Function deployment.

Undeploy

An undeploy operation causes the Function to stop processing events. All allocated worker-processes get terminated, and any runtime resources acquired by the Function gets released. Functions in an undeployed state allow editing of the Function handler code. After a successful undeploy operation, system does not retain the previous state. During redeployment, the Eventing service cannot resume from a prior state before undeployment. An undeployed Function retains the memory of its prior deployment, if necessary. Newly created handlers start in an undeployed state.

Delete

When a Function gets deleted, the source code implementing the Function, all processing checkpoints, and other artifacts in the metadata provider are purged. Before deleting, make sure you have undeployed the Function.