Cava is a programming language developed by the OpenSearch engine team, built on the low-level virtual machine (LLVM) project. It uses Java-like syntax and delivers performance comparable to C++. Cava is object-oriented, supports just-in-time (JIT) compilation, and includes built-in security checks for more robust programs.
Use Cava and the Cava libraries provided by OpenSearch to write custom sort plug-ins that go beyond what built-in expressions support.
Cava-based plug-ins work only in exclusive applications and take effect only during fine sorts. For Cava language syntax, see the Cava-based sort plug-in topics in the Developer Guide.
Expressions vs. Cava
| Expressions | Cava scripts | |
|---|---|---|
| Syntax | Simple formula syntax | Java-like, object-oriented |
| Customization | Limited to supported operators | For loops, functions, and classes |
| Maintainability | Hard to read at scale | Readable; easier to understand and maintain |
| Learning curve | Minimal | Low for Java developers |
Prerequisites
Before you begin, make sure you have:
An exclusive OpenSearch application
Access to the OpenSearch console
Create and deploy a Cava sort plug-in
Step 1: Create a policy
Log on to the OpenSearch console.
In the left-side navigation pane, choose Search Algorithm Center > Sort Configuration.
On the Policy Management page, click Create.
In the Basic Information step of the Create Policy wizard, select Fine Sort from the Scope drop-down list and select Cava Script from the Type drop-down list.
Step 2: Add a script file
In the Sort Configuration step, add your Cava script using one of the following methods:
Edit in the console — write or paste the Cava script directly in the editor.
Upload a local file — upload a script file in JSON format from your machine.
Step 3: Compile and publish
After editing the script files, click Compile to compile all files. The compilation status appears below the Compile button. After compilation succeeds, click Publish.
Published scripts cannot be modified. To change a published script, replicate the policy on the Policy Management page and create a new policy.
Step 4: Test the sorting effect
On the Search Test page of the policy, set the following parameters to activate the Cava sort policy:
| Parameter | Value |
|---|---|
second_rank_name | Name of the policy |
second_rank_type | cava_script |
SDK for Java example
To activate a Cava sort policy in code, configure the Rank object before sending a search request:
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
// Create a Rank object and configure the Cava sort policy.
Rank rank = new Rank();
// Specify the Cava script policy by name.
rank.setSecondRankName("Cava script name");
// Set the sort type to Cava scripts.
rank.setSecondRankType(RankType.CAVA_SCRIPT);
// Attach the rank policy to the search request.
searchParams.setRank(rank);Cava scripts configured in SDK calls must be published. Unpublished scripts are available only for search tests.
Get common parameters
Get a vector index score
Use the ProximaScore class to retrieve the relevance score from a vector index:
import com.aliyun.opensearch.cava.features.similarity.ProximaScore;
ProximaScore _proximaScoreVector;
// Replace {{indexes.vector_index}} with the name of your vector index.
_proximaScoreVector = ProximaScore.create(params, "{{indexes.vector_index}}");
float proximaScoreVector = _proximaScoreVector.evaluate(params);Limitations
| Constraint | Limit |
|---|---|
| Application type | Exclusive applications only |
| Sort phase | Fine sort only |
| Script file size | 10 KB per file |
| Script files per policy | 5 |
| Cava-based sort policies per application | 50 |
| Modifying published scripts | Not allowed; replicate the policy to create a new one |
| Scripts in SDK calls | Must be published; unpublished scripts are available only in search tests |
What's next
Learn the Cava language syntax in the Cava-based sort plug-in topics in the Developer Guide.
Test your sort policy using the Search Test page before applying it in production.