Create a sorting script using the command line interface-OpenSearch(Open Search)-阿里云帮助中心

SortScript is a Python-based CLI tool for managing sort scripts in OpenSearch. Use it to create, upload, compile, publish, and delete Cava-based sort scripts that control how search results are ranked.

Note

Name sort scripts differently from expressions created in the OpenSearch console. Both can be referenced in queries by name, so distinct names prevent confusion.

Prerequisites

Before you begin, make sure you have:

Python later than version 2.7
SortScript CLI — download the tool
Your AccessKey ID and AccessKey secret configured in tools_conf.py

Sort script lifecycle

A sort script moves through the following stages:

Stage	Description	Repeatable before publish?
Create	Register a script name tied to an application version	No
Upload code	Upload `.cava` source files	Yes
Compile	Verify syntax	Yes
Publish	Promote to production; locks the script	No
Delete	Remove a script that is no longer needed	No
View	Inspect status or code at any point	N/A

Important

After publishing, the script is locked. You cannot upload new code or recompile it. Deletion is the only available operation.

Manage sort scripts

All commands use the following common parameters:

Parameter	Description	Example
`--appName`	Application name	`script_test`
`--appVersionId`	Application version ID	`12345678`
`--scriptName`	Sort script name	`script1`
`--scriptFileName`	Name of a Cava source file within the script	`BasicSimilarityScorer.cava`
`--localFile`	Local path to the file being uploaded	`./BasicSimilarityScorer.cava`

Create a sort script

python ./sortscript create --appName script_test --appVersionId 12345678 --scriptName script1

Upload script code

Upload each Cava source file individually. For Cava syntax, see the Cava guide.

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

You can re-upload files as many times as needed before publishing the script.

Compile the sort script

python ./sortscript compile --appName script_test --appVersionId 12345678 --scriptName script1

If syntax errors are returned, fix them and recompile. You can compile repeatedly before publishing.

Publish the sort script

python ./sortscript release --appName script_test --appVersionId 12345678 --scriptName script1

Important

Publishing locks the script. You cannot upload new code or recompile after this point.

View sort scripts

To view a specific sort script:

python ./sortscript list --appName script_test --appVersionId 12345678 --scriptName script1

To list all sort scripts in an application version:

python ./sortscript list --appName script_test --appVersionId 12345678

View code file details

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.cava

Delete code 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.cava

Delete the sort script

Warning

Before deleting a sort script, make sure it is not referenced in any active queries. Deleting a script that is in use causes those queries to return errors.

python ./sortscript delete --appName script_test --appVersionId 12345678 --scriptName script1

Use a sort script in a query

To apply a sort script to search results:

Confirm the sort script is published.
In the query, set second_rank_name to the name of the sort script.
Set second_rank_type to cava_script.

Example query parameters:

Parameter	Value	Description
`second_rank_name`	`script1`	Name of the published sort script
`second_rank_type`	`cava_script`	Specifies that the ranking source is a Cava script

Note

If the sort script specified in second_rank_name does not exist, the query still returns results but also returns an error.