How to use algorithm module parameters
To use OpenSearch algorithm features in search requests, pass the custom parameters that each algorithm module requires through the SDK for Java. This topic lists the parameters for each algorithm module and shows how to set them in your code.
Parameters and where to set them
OpenSearch algorithm modules read their input from custom parameters that you set on the search request. Every search request in this topic follows the same pattern: create a SearchParams object, put the parameters into a Map<String, String>, apply the map by calling setCustomParam, and run the query with searcherClient.execute. Only the entries that you put into the map differ from module to module.
The following table describes the custom parameters used by the algorithm modules and the request that carries each one.
| Parameter | Description | Request |
raw_query |
The original search query string. | Search request, as a custom parameter. |
user_id |
The user identifier. | Search request as a custom parameter, or drop-down suggestion request through SuggestParams. |
from_request_id |
The request ID from the preceding search. | Search request, as a custom parameter. |
Two cases deviate from this pattern. To enable historical search terms, set user_id on the drop-down suggestion request through SuggestParams instead of on the search request. The Cava plug-in takes no custom parameters at all: you configure it on a Rank object.
All code examples in this topic are pseudocode. Lines shown as ... stand for omitted code, including the code that creates the config and searcherClient objects.
Query analysis
Query analysis powers text vectorization and named entity recognition (NER). The following table describes the custom parameter that query analysis requires.
| Parameter | Required | Description |
raw_query |
Yes | Used by the text vectorization and NER models. |
Set raw_query in the search request:
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("default:'OpenSearch'");
// Set the raw_query parameter.
Map<String, String> customParam = new HashMap<>();
customParam.put("raw_query", "OpenSearch");
searchParams.setCustomParam(customParam);
// Run the query and return the results as a SearchResult object.
SearchResult execute = searcherClient.execute(searchParams);
...Category prediction
Category prediction uses raw_query to train algorithm models such as category prediction models. The following table describes the custom parameter that category prediction requires.
| Parameter | Required | Description |
raw_query |
Yes | Used to train category prediction models. |
Set raw_query in the search request:
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("default:'apple'");
// Set the raw_query parameter.
Map<String, String> customParam = new HashMap<>();
customParam.put("raw_query", "apple");
searchParams.setCustomParam(customParam);
// Run the query and return the results as a SearchResult object.
SearchResult execute = searcherClient.execute(searchParams);
...Drop-down suggestions
Drop-down suggestions read three custom parameters. Pass them in combination depending on the capabilities that you want to enable.
| Parameter | Required | Description |
raw_query |
Yes | Enables high-frequency queries in drop-down suggestions. |
from_request_id |
No | Optimizes the drop-down suggestion ranking model and enables tracking of suggestion-guided search metrics. |
user_id |
No | Pass it in the search request together with raw_query and from_request_id to enable intelligent sorting. Pass it in the drop-down suggestion request through SuggestParams to enable historical search terms. |
Intelligent sorting
To enable intelligent sorting, pass raw_query, user_id, and from_request_id in the search request:
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("default:'apple'"); // driven by drop-down suggestion
// Set raw_query, user_id, and from_request_id to enable intelligent sorting.
Map<String, String> customParam = new HashMap<>();
customParam.put("raw_query", "apple");
customParam.put("user_id", "12345");
customParam.put("from_request_id", "159851481919726888064081");
searchParams.setCustomParam(customParam);
// Run the query and return the results as a SearchResult object.
SearchResult execute = searcherClient.execute(searchParams);
...Historical search terms
Historical search terms relies on two requests: pass raw_query in the search request, and pass user_id in the drop-down suggestion request through SuggestParams.
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("default:'apple'"); // driven by drop-down suggestion
// Set raw_query in the search request.
Map<String, String> customParam = new HashMap<>();
customParam.put("raw_query", "apple");
searchParams.setCustomParam(customParam);
// Run the query and return the results as a SearchResult object.
SearchResult execute = searcherClient.execute(searchParams);
...
// Set user_id in the drop-down suggestion request to enable historical search terms.
SuggestParams suggestParams = new SuggestParams();
suggestParams.setUserId("12345");Top searches and hints
Top searches and hints use raw_query to train algorithm models such as top search models and hint models. Pass from_request_id and user_id to improve ranking and collect guidance metrics.
| Parameter | Required | Description |
raw_query |
Yes | Used to train top search and hint models. |
from_request_id |
No | Improves top search and hint ranking and enables tracking of top search- and hint-guided search metrics. |
user_id |
No | Pass it together with from_request_id to enable tracking of top search- and hint-guided search metrics. |
Set the parameters in the search request:
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("default:'apple'");
// Set raw_query, user_id, and from_request_id.
Map<String, String> customParam = new HashMap<>();
customParam.put("raw_query", "apple");
customParam.put("user_id", "12345");
customParam.put("from_request_id", "160851481919726888064913");
searchParams.setCustomParam(customParam);
// Run the query and return the results as a SearchResult object.
SearchResult execute = searcherClient.execute(searchParams);
...Cava plug-in
The Cava plug-in applies a custom second-phase ranking policy through a Cava script. Unlike the other algorithm modules in this topic, it takes no custom parameters: set the script name and the sort type on a Rank object, and then apply that object to the search request.
| Parameter | Required | Description |
| Cava script name | Yes | The name of the Cava script to invoke for second-phase ranking. Set it by calling setSecondRankName. |
| Sort type | Yes | The ranking method. Set it to RankType.CAVA_SCRIPT by calling setSecondRankType to use Cava script-based ranking. |
Configure the ranking policy and apply it to the search request:
...
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
...
// Create a Rank object and configure Cava script-based ranking.
Rank rank = new Rank();
rank.setSecondRankName("test_cava");
rank.setSecondRankType(RankType.CAVA_SCRIPT);
// Apply the ranking policy to the search request.
searchParams.setRank(rank);