Cava is the scripting language built into OpenSearch High-performance Search Edition for writing custom ranking plug-ins. When the built-in ranking rules don't match your scoring logic, write a Cava script, upload it, and deploy it to your dedicated cluster — no external dependencies required.
How it works
A Cava plug-in runs inside the OpenSearch ranking pipeline, which evaluates documents in two stages:
First-stage ranking (coarse ranking) — Runs across all candidate documents to narrow the result set. Cava plug-ins at this stage use lightweight custom scoring logic.
Second-stage ranking (fine ranking) — Runs on the narrowed candidate set with more precise scoring. Cava plug-ins at this stage support complex field-based and parameter-driven expressions.
The plug-in receives document field values and query parameters, computes a score, and returns it to the pipeline. OpenSearch sorts results by that score.
Prerequisites
Before you begin, ensure that you have:
An OpenSearch High-performance Search Edition dedicated cluster
A Cava script that compiles without errors
Permissions to call
SaveSortScriptFileandReleaseSortScript
Upload and deploy a Cava plug-in
Base64-encode your Cava script.
Call
SaveSortScriptFileto upload the encoded script to your cluster. Specify the script name and version.Call
ReleaseSortScriptto activate the script version. Only released versions are applied to live queries.Reference the script name in your query's sort configuration to start using the plug-in.
Releasing a new script version does not remove older versions. Manage versions explicitly to avoid accumulating stale scripts on the cluster.
Next steps
UpdateSortScript— Update an existing Cava scriptSaveSortScriptFile— Upload a script file to your clusterReleaseSortScript— Release a script version for live traffic