Cava is OpenSearch's built-in scripting language for extending search behavior. Upload Cava scripts to the Cava Configurations tab to define custom functions, scorers, and summaries for your cluster.
How it works
A Cava configuration moves through four stages before it takes effect in queries:
| Stage | Action | Result |
|---|---|---|
| 1. Upload | Create directories and upload script files | Draft version created |
| 2. Publish | Click Publish New Version | Versioned, immutable snapshot generated |
| 3. Apply | Select the version and apply it to the cluster | Cluster update initiated |
| 4. Active | Finite-state machine (FSM) process completes | Cava script available for queries |
Note: Published versions are immutable. To update a configuration, modify a published version to create a new draft. The system saves only the latest draft — earlier unsaved drafts are discarded.
Prerequisites
Before you begin, ensure that you have:
An OpenSearch instance with Cluster Configuration access
Cava script files ready to upload
File requirements:
| Constraint | Limit |
|---|---|
| Maximum file size | 20 MB |
| Allowed formats | .cava, .json, .txt, .xml |
Directory name requirements:
| Constraint | Rule |
|---|---|
| Allowed characters | Letters, digits, and underscores (_) |
| Length | 1–100 characters |
Upload and publish a Cava configuration
On your instance details page, choose Configuration Management > Cluster Configuration in the left-side pane.
Click the Cava Configurations tab, find the version to modify, and click Modify in the Actions column.
On the Modify page, create directories or upload your Cava script files.
(Optional) Configure the Cava parameters listed in Cava configuration parameters.
Click Publish New Version.
The system generates a new versioned snapshot. To make further changes, modify the published version to create a new draft.
Cava configuration parameters
Configure these parameters on the Modify page before publishing:
| Parameter | Description |
|---|---|
enable_cava | Enables or disables the Cava feature for this cluster. |
cava_alloc_size_limit | Maximum memory allocated per query. Leave blank to use the default value. |
cava_module_cache_size | Maximum number of source code blocks passed to the cache query. When the limit is exceeded, the least recently used (LRU) algorithm evicts older entries. Leave blank to use the default value. |
cava_compile_thread_num | — |
cava_loop_and_func_limit | — |
cava_max_variable_count | — |
cava_config | — |
Apply a Cava configuration to your cluster
After publishing a version, apply it to your cluster:
Go to the Cluster Management page.
In the Configuration Information section, click Update.
In the Update Cluster Configuration panel, select the published Cava configuration version and confirm.
Track the rollout on the Change History page in the Extended Features module.
After the FSM process completes, the Cava configuration is active and available for queries.
Delete a Cava configuration version
Only versions in the Unused state can be deleted. Versions in the In Use state are protected and cannot be deleted.
To delete an unused version, go to the Cava Configurations tab on the Cluster Configuration page, find the version with the Unused status, and delete it.