SortScript is a Python-based command-line tool for managing sort scripts in OpenSearch. Use it to create, upload, compile, publish, and delete sort scripts written in Cava — the scripting language built into OpenSearch. Once published, a sort script can be applied to live queries to sort results.
Sort script lifecycle
A sort script moves through the following stages before it can be used in queries:
| Stage | Description | Reversible? |
|---|---|---|
| Create | Register the script with a name under a specific application version. | Yes |
| Upload | Upload one or more Cava source files. You can re-upload as many times as needed before publishing. | Yes |
| Compile | Verify syntax. You can recompile as many times as needed before publishing. | Yes |
| Publish | Deploy the script to your live application. After publishing, you cannot upload or recompile. The only available action is delete. | No |
| Delete | Remove a script. Make sure the script is not active in queries before deleting — otherwise, queries return an error. | — |
| View | Check the status of a script at any stage. | — |
Prerequisites
Before you begin, make sure you have:
Python later than version 2.7 installed
Your AccessKey ID and AccessKey secret
Downloaded SortScript and extracted the archive
Set up SortScript
Open tools_conf.py in the extracted directory and set your AccessKey ID and AccessKey secret.
Manage sort scripts
All commands follow this pattern:
python ./sortscript <command> [parameters]Create a sort script
python ./sortscript create --appName script_test --appVersionId 12345678 --scriptName script1| Parameter | Description |
|---|---|
--appName | Name of the application |
--appVersionId | Version ID of the application |
--scriptName | Name to assign to the sort script. Use a name that is distinct from expression names in the OpenSearch console to avoid confusion. |
Upload script code
Upload each Cava source file separately. For Cava syntax, see Data types and variable types.
python ./sortscript updatecontent --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName BasicSimilarityScorer.cava --localFile ./BasicSimilarityScorer.cava
python ./sortscript updatecontent --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName IntelligenceAlgorithmScorer.cava --localFile ./IntelligenceAlgorithmScorer.cava| Parameter | Description |
|---|---|
--appName | Name of the application |
--appVersionId | Version ID of the application |
--scriptName | Name of the sort script to update |
--scriptFileName | Name of the script file as stored in OpenSearch |
--localFile | Path to the local file to upload |
Compile the sort script
python ./sortscript compile --appName script_test --appVersionId 12345678 --scriptName script1If syntax errors are returned, fix them in your local files, re-upload, and recompile.
Publish the sort script
Once the script compiles without errors, publish it to make it available in queries.
Publishing is irreversible. After a script is published, you cannot upload new code or recompile. To make changes, delete the script and create a new one.
python ./sortscript release --appName script_test --appVersionId 12345678 --scriptName script1View sort scripts
To view a specific script:
python ./sortscript list --appName script_test --appVersionId 12345678 --scriptName script1To list all scripts in an application version:
python ./sortscript list --appName script_test --appVersionId 12345678View script file contents
python ./sortscript getcontent --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName BasicSimilarityScorer.cava
python ./sortscript getcontent --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName IntelligenceAlgorithmScorer.cavaDelete script files
python ./sortscript deleteScriptFile --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName BasicSimilarityScorer.cava
python ./sortscript deleteScriptFile --appName script_test --appVersionId 12345678 --scriptName script1 --scriptFileName IntelligenceAlgorithmScorer.cavaDelete a sort script
Before deleting, make sure the script is not referenced in any active queries. Deleting a script that is in use causes those queries to return an error.
python ./sortscript delete --appName script_test --appVersionId 12345678 --scriptName script1To confirm the script is removed, run list and verify it no longer appears.
Use a sort script in queries
After publishing a sort script, reference it in queries to apply custom ranking. Set the following parameters in your query request:
| Parameter | Value |
|---|---|
second_rank_name | The name of the published sort script |
second_rank_type | cava_script |
If the script specified in second_rank_name does not exist, query results are still returned, but an error is also included in the response.
Related topics
Data types and variable types — Cava language reference