Top Searches and Search Hints

Create a model in the console

1. Log on to the OpenSearch console. In the left-side navigation pane, choose Search Algorithm Center > Search Guidance, then click Top Searches and Hints.

2. Click Create.

   

3. Configure the following parameters:

   Parameter	Description
   Model name	A name consisting of letters, digits, and underscores (_). The name cannot consist of only digits and must be no longer than 30 characters.
   Model type	Select Top Search Model or Hint Model.
   Filter condition	(Optional) Restrict which historical search queries are used for training. Format: [parameter][operator][value]. Supported parameters: biz_type and user_id. Supported operators: <, >, <=, >=, =, !=. Separate multiple conditions with commas — all conditions are applied with AND logic. Example: user_id=1,biz_type=1.

   

4. Find the model in Pending Training status and click Train in the Actions column.

   

5. After training completes, preview the results:

   • Top search preview: Click Preview Effects to see up to 10 recommended top searches per page, across up to 20 pages.

   • Hint preview: Click Preview Effects to see up to 30 recommended hints, one per page.

Create a model using the API or SDK

When you create a model using the API, the system immediately starts training the model upon receiving the creation request.

Add the Management and Control SDK to your project:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-opensearch</artifactId>
    <version>0.7.0</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.5.0</version>
</dependency>

The following example creates a top search model. Set type to "hot" for a top search model or "hint" for a hint model.

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.http.HttpResponse;
import com.aliyuncs.opensearch.model.v20171225.*;
import com.aliyuncs.profile.DefaultProfile;

public class CreateModel {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-beijing",
            System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
            System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        );
        IAcsClient client = new DefaultAcsClient(profile);

        CreateModelRequest request = new CreateModelRequest();
        request.setAppGroupIdentity("app_name");  // Replace with your application name

        // type: "hot" = top search model, "hint" = hint model
        // name: letters, digits, underscores only; max 30 characters
        String content = "{\"type\": \"hot\", \"name\": \"model_name\"}";
        request.setHttpContent(content.getBytes(), "UTF-8", FormatType.JSON);

        try {
            HttpResponse response = client.doAction(request);
            System.out.println(response.getHttpContentString());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
    }
}

Model list

The Top Searches and Hints page lists all models with their name, type, creation time, status, last training start time, and latest version status. Set one model as the default — when no model_name is specified in a request, the default model is used.

Model details

Click a model name to open its details page. The Basic Information section shows the current model status and training timestamps. The Training History section lists each training run with its version, status, start time, and end time.

Troubleshoot a failed training

On the model details page, hover over Exception Report to see the failure reason. Hover over View Conditions for Integrity Level Upgrade to see what criteria the model needs to meet for a higher integrity level.

Configure blacklists and whitelists

In the Configuration Information section, click Configure to set up a blacklist or whitelist for the model. For details, see Blacklists and whitelists.

Adjust top search list size

By default, the top search list displays up to 10,000 entries. Set a custom limit (minimum: 100) based on your business requirements.

Connect user behavioral data

Top searches and hints generated from raw search logs are a good starting point, but connecting user behavioral data improves recommendation quality over time.

Include the following parameters in search requests to enable behavioral tracking:

• from_request_id — Set this to the request_id value returned when a user clicks a top search or hint. This links the subsequent search to the recommendation that triggered it.

• user_id — Enables unique visitor (UV) metrics in business operation reports.

How it works end-to-end:

1. A user sees a list of top searches returned by the API. The response includes a request_id.

2. The user clicks a top search, triggering a new search request.

3. Set from_request_id in that search request to the request_id from step 1.

4. If the user pages through results, set from_request_id in each page-turn request as well — each page view counts as an independent page view (PV).

With this data connected, business operation reports will show:

• Page views (PVs) and unique visitors (UVs) of searches guided by top searches and hints

• Zero-result rate for guided searches

• Click rate on recommendations

• User interest trends for operational planning