Drop-down suggestions

How it works

OpenSearch generates drop-down suggestions through a two-stage pipeline:

1. Index your documents. OpenSearch selects millions of documents from your application and processes the values of up to three fields you designate. This produces a candidate pool of potential recommendations.

2. Score and filter historical searches. OpenSearch analyzes search queries from the past N days (seven days by default) using term weights, result counts, number of search times, and whether a query returned results in the last day. Only queries that pass the scoring thresholds appear as suggestions.

When a user types a query in Chinese, OpenSearch matches suggestions using six input methods simultaneously:

By default, OpenSearch also matches homophones automatically. To disable this behavior, set the re_search parameter to disable in your search request.

Choose an extraction method

When creating a drop-down suggestion model, select how OpenSearch derives suggestions from historical queries:

Suggested queries come only from search requests that include the raw_query parameter. Include raw_query in your search requests so OpenSearch can recognize and learn from the original user input. For details, see Initiate search requests.

Prerequisites

Before you begin, ensure that you have:

• An advanced OpenSearch application (standard applications do not support this feature)

• More than 1,000 data entries in the application table, including raw_query search data and application documents

• Fields of type TEXT, SHORT_TEXT, LITERAL, or INT that are configured as index fields

Create a drop-down suggestion model

1. Log in to the OpenSearch console. In the left-side navigation pane, choose Search Algorithm Center > Search Guidance.

2. On the Drop-down Suggestions page, click Create.

   

3. On the Create Drop-down Suggestions Model page, configure the following settings, then click Submit:

   • Model name — Enter a unique name. Model names must be unique across all model types (drop-down suggestion, popularity, category prediction, top search, and hint models) within the same Alibaba Cloud account.

   • Training fields — Select up to three fields from your application schema as the data source.

   • Extraction method — Choose Extract terms or Retain original value for each field. See Choose an extraction method.

   • Historical Search Queries — Turn on to incorporate historical query data. This feature incurs a training fee based on billable hours. See Billing overview.

   • Filter condition — (Optional) Enter filter conditions to restrict the documents used as the data source.

   

4. On the Drop-down Suggestions page, find the model you created and click Train in the Actions column.

   

5. Wait for training to complete (typically 20–30 minutes). If training exceeds 30 minutes, contact the OpenSearch team.

6. Test the model. The following figures show sample suggestions for each extraction method.

   Retain original value

   

   Extract terms

   

7. Query the model from your application using the API or SDK. See Query drop-down suggestions.

Filter conditions

Filter conditions restrict which documents contribute to suggestions. After you apply a filter, OpenSearch generates recommendations only from documents that match.

Configure filter conditions based on fields in your application schema. The following rules apply:

• Supported operators: <, >, <=, >=, =, !=

• Supported field types: numeric and string. The ARRAY type is not supported.

• Multiple conditions: Separate conditions with commas (,). All conditions are applied with AND logic. OR logic is not supported.

Example: status=1,level=1 — only documents where status equals 1 and level equals 1 are used.

The following figure shows how to configure filter conditions in the OpenSearch console.

Manage suggestions with blacklists and whitelists

Use blacklists and whitelists to control which suggestions appear.

• Blacklist: Any suggestion containing a blacklisted keyword is suppressed from drop-down results. If a suggestion in your whitelist also contains a blacklisted keyword, the blacklist takes precedence and the suggestion is hidden.

• Whitelist: Suggestions in the whitelist are ranked at the top of drop-down results when they meet recommendation conditions. Use this to surface high-priority queries that would otherwise rank low or not appear.

Each list supports up to 500 entries (keywords for blacklists, search queries for whitelists). Changes to blacklists and whitelists take effect immediately.

For setup instructions, see Blacklists and whitelists.

Call the API

Use the following endpoint to query suggestions:

GET v3/openapi/suggestions/{suggestion_name}/actions/search?hit=10&query={your_query}&re_search=homonym&user_id=xxx

Key parameters:

Java SDK — Maven dependency:

<dependency>
    <groupId>com.aliyun.opensearch</groupId>
    <artifactId>aliyun-sdk-opensearch</artifactId>
    <version>4.0.0</version>
</dependency>

For the latest release, see Release notes.

Java SDK — example:

package com.example.opensearch;

import com.aliyun.opensearch.OpenSearchClient;
import com.aliyun.opensearch.SuggestionClient;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;

import java.nio.charset.Charset;

public class SuggestDemo {
    // Replace placeholders with your actual values
    static private final String accesskey = "<your-access-key-id>";
    static private final String secret = "<your-access-key-secret>";
    static private final String host = "<opensearch-endpoint>";         // Endpoint of the region where your application is deployed
    static private final byte hits = 8;                                 // Max suggestions to return
    static private final String suggestionName = "<suggestion-model-name>";

    OpenSearch openSearch;
    OpenSearchClient openSearchClient;

    @Before
    public void setUp() {
        openSearch = new OpenSearch(accesskey, secret, host);
        openSearchClient = new OpenSearchClient(openSearch);
    }

    @Test
    public void TestEnv() {
        System.out.println(String.format("file.encoding: %s", System.getProperty("file.encoding")));
        System.out.println(String.format("defaultCharset: %s", Charset.defaultCharset().name()));

        SuggestionClient suggestionClient = new SuggestionClient("<application-name>", suggestionName, openSearchClient);
        String query = "<search-query>";

        try {
            SuggestParams suggestParams = new SuggestParams();
            suggestParams.setQuery(query);          // The search query
            suggestParams.setHits(10);              // Max suggestions to return (1-30)
            suggestParams.setUserId("12345678");    // User ID for personalization
            // ReSearch.findByValue(0) enables homophone matching (default)
            // ReSearch.findByValue(1) disables homophone matching
            suggestParams.setReSearch(ReSearch.findByValue(1));

            SearchResult result = suggestionClient.execute(suggestParams);
            System.out.println(result);
        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }
    }

    @After
    public void clean() {
        openSearch.clear();
    }
}

Replace the following placeholders:

For a complete Java SDK walkthrough, see Demo code for calling the drop-down suggestion model.

Sample response:

{
  "request_id": "159851481919726888064081",
  "searchtime": 0.006246,
  "suggestions": [
    { "suggestion": "skirt fashion" },
    { "suggestion": "skirt shorty dress" },
    { "suggestion": "skirt dotted dress" },
    { "suggestion": "skirt young" },
    { "suggestion": "skirt dotted" },
    { "suggestion": "skirt shorty" },
    { "suggestion": "skirt shorty dotted" }
  ]
}

The request_id in the response is used to associate a suggestion request with a subsequent search request. See the next section.

Associate a suggestion request with a search request

Linking a suggestion request to the search it triggers lets you measure the impact of suggestions on search performance — including page views (PVs), click-through rate (CTR), and the rate of search engine results pages (SERPs) with few or zero results. This data also feeds back into model training to improve suggestion quality over time.

To associate a suggestion request with a search request, include from_request_id={request_id} in the search request, where {request_id} is the request_id returned by the suggestion API.

Example: The suggestion request returned request_id: 159851481919726888064081. Include this value in the subsequent search:

SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("title:'skirt shorty'"); // Query selected from drop-down suggestions

// Pass the suggestion request ID to link the two requests
Map<String, String> customParam = new HashMap<>();
customParam.put("from_request_id", "159851481919726888064081");
searchParams.setCustomParam(customParam);

SearchResult execute = searcherClient.execute(searchParams);
String result = execute.getResult();
System.out.println(result);

For details on the from_request_id, raw_query, and user_id parameters, see Initiate search requests.

Limitations

Additional constraints:

• Fields used as a data source for a model cannot be modified when the model's application schema is being updated.

• Deleting an application also deletes all its drop-down suggestion models.

• Model names must be unique across all model types within the same Alibaba Cloud account.

• Only fields of type TEXT, SHORT_TEXT, LITERAL, and INT that are configured as index fields can be used as the data source.

• After a model is created, scheduled training is enabled by default. The model data is updated after each training run.

• To enable the high-frequency search query feature by default, your search request must contain the raw_query parameter, or the query clause must contain the default index.

• Independent raw_query: To improve model training performance, specify the raw_query parameter in your search requests. The value must be an independent and unique search query that can be used to retrieve documents.

Monitor suggestion performance

The model details page shows key metrics in a table and a line chart, filterable by time range. Sections include:

• Basic information — creation time, status, latest training time, and version status. If the model is in the Abnormal Data state, the exception report is available here.

• Configuration information — training fields, filter conditions, whitelists, blacklists, and whether scheduled training and historical search query features are enabled.

• Data verification — data integrity and integrity level of the model.

• Training history — training records.

For metric definitions, see Drop-down suggestion report.

Next steps

• Query drop-down suggestions — API reference for the suggestion endpoint

• Drop-down suggestion report — Metrics and analytics for suggestion performance

• Blacklists and whitelists — Configure keyword filtering for suggestions

• Initiate search requests — Parameters including raw_query, user_id, and from_request_id

• Billing overview — Costs for the historical search query feature