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 6.0 BETA 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.

  • The document being observed and its Extended Attributes.

Buckets

There are two distinct buckets: source bucket and metadata bucket.

Source Bucket

Couchbase Functions use a bucket to track data mutations. This bucket is termed as the source bucket. The source bucket can be either Couchbase or Ephemeral bucket type. However, memcached bucket types are not supported.

When you are creating a function, you need to specify a source bucket. The handler code polls this bucket to track data mutations.

You can use a common source bucket to listen to multiple Functions running different code.

When a source bucket is deleted, all deployed functions associated with this source
bucket, are undeployed.

After processing the handler code, documents can be stored in a different bucket. For understanding purposes, this bucket can be termed as a destination bucket.

At times, the handler code can trigger data mutations. To avoid cyclic generation of data changes, refer to Bucket Allocation Considerations.

Metadata Bucket

Metadata bucket stores artifacts such as timers, DCP streams, worker allocations along with internal checkpoint information.

When you are creating a Function, ensure that a separate bucket is destined as a
metadata bucket. You can use a common metadata bucket across multiple Functions.

At any point, refrain from deleting the metadata bucket. Also, ensure that the Function handler code does not perform a write operation on the metadata bucket.

If a metadata bucket gets accidentally deleted, then all deployed functions are
undeployed and associated indexes get dropped.

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

A binding allows separating of environment specific variables from the handler code.

You can add bindings as a name-value pair, where name is the actual name of the bucket in the cluster, and value is the alias that you can use to refer to the bucket from your
handler code.

Bindings are mandatory when your handler code performs any bucket related operations.

Bindings ensure easy porting of source code across different environments. You can export-import Functions from test-to-test, test-to-production, or production-to-production environments, without making code changes.

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 data mutations available 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.