# opensearch-scripting

Part of **OPENSEARCH**

# OpenSearch Scripting Extension Console Guide

## Operations Overview

| Operation | Console Entry Point | Prerequisites | Description |
|----------|---------------------|---------------|-------------|
| Upload and Publish Cava Script | Console > OpenSearch > Cluster Configuration > Cava Configurations | - OpenSearch instance with Cluster Configuration access<br>- Cava script files ready (.cava, .json, .txt, .xml)<br>- File size ≤ 20 MB<br>- Directory names: 1–100 chars, letters/digits/underscores only | Upload Cava scripts, configure parameters, and publish a new immutable version |
| Apply Published Cava Configuration to Cluster | Console > OpenSearch > Cluster Management | - A published Cava configuration version exists | Select and apply a published Cava version to the OpenSearch cluster |
| Delete Unused Cava Version | Console > OpenSearch > Cluster Configuration > Cava Configurations | - Target version has "Unused" status | Remove an unused Cava configuration version from the system |

## Step-by-Step Instructions

### Upload and Publish Cava Script

**Navigation**: Console > OpenSearch > Cluster Configuration > Cava Configurations

**Prerequisites**:
- An OpenSearch instance with Cluster Configuration access
- Cava script files ready to upload (allowed formats: .cava, .json, .txt, .xml)
- Total file size must not exceed 20 MB
- Directory names must contain only letters, digits, and underscores, and be 1–100 characters long

1. Navigate to **Configuration Management** in the left-side pane  
   - Element: **Configuration Management** (menu) — left-side navigation panel

2. Click the **Cava Configurations** tab at the top  
   - Element: **Cava Configurations** (tab) — top navigation bar

3. Locate the draft version you want to modify and click **Modify** in the Actions column  
   - Element: **Modify** (button) — in the Actions column of the versions table  
   - Notes: If no draft exists, create one first via the console UI (not covered here)

4. On the Modify page, upload your Cava script files or create directories in the main content area  
   - Element: file upload area (form_field) — main content section  
   - Notes: Only files with extensions .cava, .json, .txt, or .xml are accepted. Total uploaded size must not exceed 20 MB.

5. (Optional) Configure Cava runtime parameters below the file browser  
   - Element: parameter fields (form_field) — on the Modify page  
   - Notes: These settings control memory, caching, and execution limits. Leave blank to use defaults.

6. Click **Publish New Version** in the top-right corner  
   - Element: **Publish New Version** (button) — top-right corner of the page  
   - Notes: After publishing, the version becomes immutable. Any further changes require creating a new draft.

| Parameter | Type | Required | Options/Values | Description |
|-----------|------|----------|----------------|-------------|
| enable_cava | toggle | No | true, false | Enables or disables the Cava feature for this cluster. |
| cava_alloc_size_limit | text_input | No | — | Maximum memory allocated per query. Leave blank to use the default value. |
| cava_module_cache_size | text_input | No | — | 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 | text_input | No | — | — |
| cava_loop_and_func_limit | text_input | No | — | — |
| cava_max_variable_count | text_input | No | — | — |
| cava_config | text_input | No | — | — |

### Apply Published Cava Configuration to Cluster

**Navigation**: Console > OpenSearch > Cluster Management

**Prerequisites**:
- At least one Cava configuration version has been published

1. In the left-side pane, click **Cluster Management**  
   - Element: **Cluster Management** (link) — left-side navigation panel

2. In the **Configuration Information** section, click **Update**  
   - Element: **Update** (button) — within the Configuration Information section

3. In the **Update Cluster Configuration** panel that appears, select the desired published Cava version  
   - Element: **Update Cluster Configuration** (panel) — center of screen  
   - Notes: Only published versions appear in this list. The selected version will be applied to the cluster.

4. Confirm the update. The system begins the rollout process.  
   - Notes: A finite-state machine (FSM) orchestrates the deployment. Do not interrupt this process.

5. (Optional) Track rollout progress by navigating to the **Extended Features** module and clicking **Change History**  
   - Element: **Change History** (link) — in the Extended Features module  
   - Notes: Wait for the FSM process to reach "Completed" status before the configuration becomes active.

### Delete Unused Cava Version

**Navigation**: Console > OpenSearch > Cluster Configuration > Cava Configurations

**Prerequisites**:
- The target Cava version must have "Unused" status (not currently applied to any cluster)

1. Go to **Configuration Management** > **Cava Configurations** as in the upload flow  
   - Element: **Configuration Management** (menu), then **Cava Configurations** (tab)

2. Find the version with "Unused" status and click **Delete** in the Actions column  
   - Element: **Delete** (button) — in the Actions column  
   - Notes: Versions marked as "In Use" cannot be deleted. The system enforces this protection.

3. Confirm deletion if prompted by a dialog  
   - Notes: Deletion is permanent and cannot be undone.

## FAQ

Q: Where can I find the Cava Configurations page in the OpenSearch console?  
A: Navigate via Console > OpenSearch > Configuration Management (left menu) > Cava Configurations (top tab).

Q: Can I edit a Cava configuration after publishing it?  
A: No. Published versions are immutable snapshots. To make changes, you must modify a draft (or create a new one) and publish a new version.

Q: What file formats are allowed for Cava script uploads?  
A: Allowed extensions are .cava, .json, .txt, and .xml. The total upload size must not exceed 20 MB.

Q: Why can’t I delete a Cava version even though I see the Delete button?  
A: Only versions with "Unused" status can be deleted. If a version is currently applied to a cluster ("In Use"), the system disables deletion to prevent disruption.

Q: How do I know when my Cava configuration is active on the cluster?  
A: After applying the configuration, monitor the **Change History** page in the Extended Features module. The finite-state machine (FSM) process must complete successfully before the configuration takes effect.

## Pricing & Billing

### Billing Model
Free — Cava scripting functionality is included as part of the standard OpenSearch service with no additional charge.

### Free Tier
No explicit pricing mentioned; assumed free as part of OpenSearch service.

### Quota Limits
- Maximum file size: 20 MB  
- Directory name length: 1–100 characters (letters, digits, underscores only)

### Billing Notes
No billing information provided; Cava configuration management is likely included in the base cost of the OpenSearch instance.