Basic search

Configure environment variables

Configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.

Important

• The AccessKey pair of an Alibaba Cloud account can be used to access all API operations. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. For information about how to use a RAM user, see Create a RAM user.

• For information about how to create an AccessKey pair, see Create an AccessKey pair.

• If you use the AccessKey pair of a RAM user, make sure that the required permissions are granted to the AliyunServiceRoleForOpenSearch role by using your Alibaba Cloud account. For more information, see AliyunServiceRoleForOpenSearch and Access authorization rules.

• We recommend that you do not include your AccessKey pair in materials that are easily accessible to others, such as the project code. Otherwise, your AccessKey pair may be leaked and resources in your account become insecure.

• Linux and macOS

  Run the following commands. Replace <access_key_id> and <access_key_secret> with the AccessKey ID and AccessKey secret of the RAM user that you use.

  export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id> 
  export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

• Windows

  1. Create an environment variable file, add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to the file, and then set the environment variables to your AccessKey ID and AccessKey secret.

  2. Restart Windows for the AccessKey pair to take effect.

V4.0.0 SDK sample code for document search

Search error handling: Check the code and message fields to determine if an error occurred, not the status field.

For more information about error codes, see Error codes.

SDK demo:

Replace the parameters in the following sample code with your actual parameter values.

In the OpenSearch console, on the instance details page, find the application name in the page title. In the endpoint section, find the host, which is the public endpoint or the VPC endpoint.

• appName: The name of your application.

• host: The endpoint of the service. This can be a public or VPC endpoint.

package com.aliyun.opensearch;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONObject;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.sdk.generated.search.general.SearchResult;
import com.aliyun.opensearch.search.SearchParamsBuilder;
import com.aliyun.opensearch.search.SearchResultDebug;
import java.nio.charset.Charset;
public class testSearch {
  private static String appName = "your_opensearch_app_name";
  private static String host = "your_app_api_endpoint";
  public static void main(String[] args) {
    // User credentials.
    // Read the AccessKey ID and AccessKey Secret from environment variables. You must configure the environment variables before you run this sample code.
    String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
    // View the file and default encoding formats.
    System.out.println(
      String.format("file.encoding: %s", System.getProperty("file.encoding"))
    );
    System.out.println(
      String.format("defaultCharset: %s", Charset.defaultCharset().name())
    );
    // Create and initialize an OpenSearch object.
    OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
    // Create an OpenSearchClient object and pass the OpenSearch object to its constructor.
    OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
    // Create a SearcherClient object and pass the OpenSearchClient object to its constructor.
    SearcherClient searcherClient = new SearcherClient(serviceClient);
    // Define a Config object to set config clause parameters, such as paging, return format, and application name.
    Config config = new Config(Lists.newArrayList(appName));
    config.setStart(0);
    config.setHits(5);
    // Set the return format to FULLJSON. Supported formats: XML, JSON, and FULLJSON.
    config.setSearchFormat(SearchFormat.FULLJSON);
    // Specify the fields to be returned in the search results.
    config.setFetchFields(
      Lists.newArrayList(
        "id",
        "name",
        "phone",
        "int_arr",
        "literal_arr",
        "float_arr",
        "cate_id"
      )
    );
    // Note: The rerank_size parameter in the config clause is set in the Rank object.
    // Set kvpairs clause parameters. In this example, the uniq plug-in is added for the distinct clause to resolve inaccuracies in total and viewtotal values when reserved is set to false.
    //config.setKvpairs("duniqfield:cate_id");
    // Create a parameters object.
    SearchParams searchParams = new SearchParams(config);
    // Set the query clause. To query multiple indexes, you must combine them in the setQuery method, for example, by using the OR operator. If you call the setQuery method multiple times, each call overrides the previous one.
    searchParams.setQuery("name:'opensearch' OR title:'opensearch'");
    // Set the distinct clause.
    Distinct dist = new Distinct();
    dist.setKey("cate_id"); // Set the dist_key parameter.
    dist.setDistCount(1); // Set the dist_count parameter.
    dist.setDistTimes(1); // Set the dist_times parameter.
    dist.setReserved(false); // Set the reserved parameter.
    dist.setUpdateTotalHit(false); // Set the update_total_hit parameter.
    dist.setDistFilter("cate_id<=3"); // Set a filter condition.
    dist.setGrade("1.2"); // Set the grade parameter.
    // The duniqfield parameter is added in the kvpairs clause of the config clause.
    // Add the Distinct object.
    searchParams.addToDistincts(dist);
    // Set the aggregation clause.
    Aggregate agg = new Aggregate();
    agg.setGroupKey("cate_id"); // Set the group_key parameter.
    agg.setAggFun("count()"); // Set the agg_fun parameter.
    agg.setAggFilter("cate_id=1"); // Set the agg_filter parameter.
    agg.setRange("0~10"); // Enable range statistics.
    agg.setAggSamplerThresHold("5"); // Set the sampling threshold.
    agg.setAggSamplerStep("5"); // Set the sampling step.
    agg.setMaxGroup("5"); // Set the maximum number of groups to be returned.
    // Add the Aggregate object.
    //searchParams.addToAggregates(agg);
    // The following code provides an example of how to specify multiple aggregation fields.
    Set<Aggregate> Aggregates = new HashSet();
    Aggregate aggregate1 = new Aggregate();
    aggregate1.setGroupKey("cate_id");
    aggregate1.setAggFun("count()");
    Aggregates.add(aggregate1);
    Aggregate aggregate2 = new Aggregate();
    aggregate2.setGroupKey("cate_id_1");
    aggregate2.setAggFun("count()");
    Aggregates.add(aggregate2);
    searchParams.setAggregates(Aggregates);
    // Set the biz parameter.
    Map hashMap = new HashMap();
    hashMap.put("biz", "type:web");
    searchParams.setCustomParam(hashMap);
    // Set filter conditions for the query.
    // searchParams.setFilter("id > \"0\""); // You can also use ParamsBuilder to add a filter condition.
    // Set sort conditions.
    Sort sorter = new Sort();
    sorter.addToSortFields(new SortField("id", Order.DECREASE)); // Sort the results by the id field in descending order.
    sorter.addToSortFields(new SortField("RANK", Order.INCREASE)); // If the values of the id field are the same, sort the results by the RANK field in ascending order.
    // The following code provides an example of how to use tag_match for sorting. You must set the Kvpairs parameter in the config clause.
    //sorter.addToSortFields(new SortField("tag_match(\"kk1\",int_array,10,\"max\",\"false\",\"false\")", Order.INCREASE));
    //config.setKvpairs("kk1:10");
    // Add the Sort object.
    searchParams.setSort(sorter);
    // Set expressions for rough and fine sorting. In this example, the default expressions are used.
    Rank rank = new Rank();
    rank.setFirstRankName("default");
    rank.setSecondRankName("default");
    rank.setReRankSize(5); // Set the number of documents for fine sorting.
    // Add the Rank object.
    searchParams.setRank(rank);
    // Set re-search parameters.
    // strategy:threshold,params:total_hits#10: strategy:threshold specifies the re-search policy. This is the only supported policy.
    // The parameter for the threshold is `total_hits`. A re-search is triggered if the number of total hits in the initial search is less than this value.
    Map<String, String> reSearchParams = new HashMap<String, String>();
    reSearchParams.put("re_search", "strategy:threshold,params:total_hits#10");
    // Set from_request_id to associate the request with search suggestions.
    reSearchParams.put("from_request_id", "159851481919726888064081");
    //searchParams.setCustomParam(reSearchParams);
    // Set the summary information for search results. We recommend that you use the SearchParamsBuilder object to add summary information.
    Summary summ = new Summary("name");
    summ.setSummary_field("name"); // The field for which the summary is generated. The field must be of the TEXT type and allow tokenization.
    summ.setSummary_len("50"); // The length of the snippet.
    summ.setSummary_element("em"); // The tag that is used to highlight keywords.
    summ.setSummary_ellipsis("..."); // The ellipsis.
    summ.setSummary_snippet("1"); // The number of snippets.
    // Add the Summary object.
    //searchParams.addToSummaries(summ);
    // Add the raw_query parameter. The value of this parameter must be the same as the value of the query parameter.
    searchParams.setRawQuery("opensearch");
    // SearchParamsBuilder is a utility class that simplifies parameter construction.
    SearchParamsBuilder paramsBuilder = SearchParamsBuilder.create(
      searchParams
    );
    // Use the SearchParamsBuilder object to add a summary for the search results.
    paramsBuilder.addSummary("name", 50, "em", "...", 1);
    // Set a filter condition.
    paramsBuilder.addFilter("id>=0", "AND");
    // Set the disable parameter to disable the re-search feature.
    //searchParams.putToCustomParam("disable", "re_search");
    try {
      // Execute the query and return the results. You must check the code and message to handle exceptions. For more information about the error messages that correspond to the error codes, see the relevant documentation.
      SearchResult searchResult = searcherClient.execute(paramsBuilder);
      String result = searchResult.getResult();
      JSONObject obj = new JSONObject(result);
      // Print the search results.
      System.out.println(obj.toString());
      // The following code shows how to retrieve the request URL for debugging.
      SearchResultDebug searchdebugrst = searcherClient.executeDebug(
        searchParams
      );
      // Print the URL of the last query request.
      System.out.println(searchdebugrst.getRequestUrl());
    } catch (OpenSearchException e) {
      e.printStackTrace();
    } catch (OpenSearchClientException e) {
      e.printStackTrace();
    }
  }
}