How do I use the document search demo? - OpenSearch - Alibaba Cloud Documentation Center

Use the OpenSearch Retrieval Engine Edition Java SDK to query data from an instance. This page shows four methods — two for SQL queries and two for Havenask queries — using the com.aliyun.ha3engine SDK. All four methods use the same client initialization pattern.

Prerequisites

Before you begin, ensure that you have:

An OpenSearch Retrieval Engine Edition instance
The com.aliyun.ha3engine SDK added to your project dependencies

Client configuration

All four methods require the same four parameters to initialize the client. Retrieve them from the Instance Details page in the console.

Parameter	Description	Where to find it
`<userName>`	Username for authentication	API Endpoint section of the Instance Details page
`<password>`	Password for authentication	API Endpoint section of the Instance Details page (changeable)
`<instanceID>`	Instance name, for example, `ha-cn-i7*****605`	Upper-left corner of the Instance Details page
`<endpoint>`	Access address of the instance	Use the API endpoint for VPC access; use the public endpoint for Internet access

Only GET and POST request methods are supported. The default is GET. Switch to POST if the query length exceeds 30 KB.

SQL queries

Use SQL queries to run standard SQL statements against your OpenSearch data. You can build a SQL query as a structured object or pass a raw query string directly.

Method	When to use
Constructed query	When you need to set query fields and kvpairs programmatically
Query string	When the query is simple and you prefer a concise single-string format

SQL query using a constructed query

Build a SQLQuery object, set the query statement and kvpairs, then call client.buildSQLSearchQuery() to assemble the request.

import java.util.HashMap;
import java.util.Map;

import com.aliyun.ha3engine.Client;
import com.aliyun.ha3engine.models.*;
import com.aliyun.tea.TeaException;

/**
 * @author alibaba
 */
public class SearchDoc {

    public static void main(String[] args) throws Exception {

        Config config = new Config();
        // The username. You can view the username in the API Endpoint section of the Instance Details page.
        config.setAccessUserName("<userName>");
        // The password. You can change the password in the API Endpoint section of the Instance Details page.
        config.setAccessPassWord("<password>");
        // The name of the instance. You can view the name in the upper-left corner of the Instance Details page. Example: ha-cn-i7*****605.
        config.setInstanceId("<instanceID>");

        // The endpoint that is used to access the instance. Specify the API endpoint if the instance is accessed over a virtual private cloud (VPC). Specify the public endpoint if the instance is accessed over the Internet.
        config.setEndpoint("<endpoint>");

        Client client = new Client(config);

        try {
            SearchRequestModel searchRequestModel = new SearchRequestModel();
            SearchQuery searchQuery = new SearchQuery();
            SQLQuery sqlQuery = new SQLQuery();
            sqlQuery.setQuery("select * from table_odps");
            Map<String, String> sqlQueryKvpairs = new HashMap<>();
            sqlQueryKvpairs.put("trace", "INFO");
            sqlQueryKvpairs.put("formatType", "full_json");
            sqlQuery.setKvpairs(sqlQueryKvpairs);
            searchQuery.setSql(client.buildSQLSearchQuery(sqlQuery));

            searchRequestModel.setQuery(searchQuery);
            // The request method. Only the GET and POST methods are supported. Default value: GET. If the length of the query exceeds 30 KB, use the POST method.
            searchRequestModel.setMethod("POST");
            SearchResponseModel searchResponseModel = client.Search(searchRequestModel);
            System.out.println("result:" + searchResponseModel.getBody());
        } catch (TeaException e) {
            System.out.println(e.getMessage());
            Map<String, Object> abc = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(abc));
        }
    }
}

SQL query using a query string

Pass the SQL statement and kvpairs as a single formatted string directly to searchQuery.setSql(). Use this approach for simple queries where you do not need to configure individual fields programmatically.

import java.util.Map;

import com.aliyun.ha3engine.Client;
import com.aliyun.ha3engine.models.Config;
import com.aliyun.ha3engine.models.SearchQuery;
import com.aliyun.ha3engine.models.SearchRequestModel;
import com.aliyun.ha3engine.models.SearchResponseModel;
import com.aliyun.tea.TeaException;

/**
 * @author alibaba
 */
public class SearchDoc {

    public static void main(String[] args) throws Exception {

        Config config = new Config();
        // The username. You can view the username in the API Endpoint section of the Instance Details page.
        config.setAccessUserName("<userName>");
        // The password. You can change the password in the API Endpoint section of the Instance Details page.
        config.setAccessPassWord("<password>");
        // The name of the instance. You can view the name in the upper-left corner of the Instance Details page. Example: ha-cn-i7*****605.
        config.setInstanceId("<instanceID>");

        // The endpoint that is used to access the instance. Specify the API endpoint if the instance is accessed over a VPC. Specify the public endpoint if the instance is accessed over the Internet.
        config.setEndpoint("<endpoint>");

        Client client = new Client(config);

        try {
            SearchRequestModel searchRequestModel = new SearchRequestModel();
            SearchQuery searchQuery = new SearchQuery();
            searchQuery.setSql("query=select * from table_odps&&kvpair=trace:INFO;formatType:full_json");
            searchRequestModel.setQuery(searchQuery);
            // The request method. Only the GET and POST methods are supported. Default value: GET. If the length of the query exceeds 30 KB, use the POST method.
            searchRequestModel.setMethod("POST");
            SearchResponseModel searchResponseModel = client.Search(searchRequestModel);
            System.out.println("result:" + searchResponseModel.getBody());
        } catch (TeaException e) {
            System.out.println(e.getMessage());
            Map<String, Object> abc = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(abc));
        }
    }
}

Havenask queries

Use Havenask queries to access Havenask-specific features such as aggregate clauses, distinct clauses, and sort clauses. As with SQL queries, you can build a Havenask query as a structured object or pass a raw query string.

Method	When to use
Constructed query	When you need fine-grained control over aggregate, distinct, sort, filter, or kvpairs clauses
Query string	When the query is simple and you prefer a concise single-string format

Havenask query using a constructed query

Build a HaQuery object and configure each clause — aggregate, distinct, sort, filter, kvpairs, and custom query — then call client.buildHaSearchQuery() to assemble the request.

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

import com.aliyun.ha3engine.Client;
import com.aliyun.ha3engine.models.*;
import com.aliyun.tea.TeaException;

/**
 * @author alibaba
 */
public class SearchDoc {

    public static void main(String[] args) throws Exception {

        Config config = new Config();
        // The username. You can view the username in the API Endpoint section of the Instance Details page.
        config.setAccessUserName("<userName>");
        // The password. You can change the password in the API Endpoint section of the Instance Details page.
        config.setAccessPassWord("<password>");
        // The name of the instance. You can view the name in the upper-left corner of the Instance Details page. Example: ha-cn-i7*****605.
        config.setInstanceId("<instanceID>");

        // The endpoint that is used to access the instance. Specify the API endpoint if the instance is accessed over a VPC. Specify the public endpoint if the instance is accessed over the Internet.
        config.setEndpoint("<endpoint>");

        Client client = new Client(config);

        try {
            HaQuery haQuery = new HaQuery();
            // Specify a query clause that contains the index and query content.
            haQuery.setQuery("id:8148508889615505646");
            // Specify the name of the cluster to be requested.
            haQuery.setCluster("general");

            // Specify an aggregate clause.
            ArrayList<HaQueryAggregateClause> aggregateClauses = new ArrayList<>();

            HaQueryAggregateClause agg = new HaQueryAggregateClause();
            agg.setGroupKey("cate_id"); // Specify a field to be aggregated.
            agg.setAggFun("count()"); // Specify an aggregation function.
            agg.setAggFilter("cate_id=1"); // Specify an aggregation filter.
            agg.setRange("0~10"); // Specify an aggregation range.
            agg.setAggSamplerThresHold("5"); // Specify a threshold value for sampled aggregation.
            agg.setAggSamplerStep("5"); // Specify a step size for sampling.
            agg.setMaxGroup("5"); // Specify the maximum number of groups that can be returned.
            // Add one or more Aggregate objects.
            aggregateClauses.add(agg);

            haQuery.setAggregate(aggregateClauses);

            // Configure a distinct clause.
            ArrayList<HaQueryDistinctClause> DistinctClauses = new ArrayList<>();

            HaQueryDistinctClause dist = new HaQueryDistinctClause();
            dist.setDistKey("cate_id"); // Specify the name of a field to be extracted.
            dist.setDistCount(1); // Specify the number of documents that are extracted each time.
            dist.setDistTimes(1); // Specify the number of extraction times.
            dist.setReserved(false); // Specify whether to retain the remaining documents after extraction.
            dist.setUpdateTotalHit(false); // Specify whether to subtract the number of discarded documents from the value of the totalHits parameter if the reserved parameter is set to false.
            dist.setDistFilter("cate_id<=3"); // Specify a filter condition to be used to select documents to be extracted.
            dist.setGrade("1.2"); // Specify a threshold value for distinct extraction.
            // Add one or more Distinct objects. The value of the dist parameter must be unique.
            DistinctClauses.add(dist);
            haQuery.setDistinct(DistinctClauses);

            // Specify a sorting condition.
            ArrayList<HaQuerySortClause> SortList = new ArrayList<>();
            HaQuerySortClause sorter = new HaQuerySortClause();
            // Specify the field that you want to sort.
            sorter.setSortKey("id");
            // Specify a sorting order. The plus sign (+) specifies an ascending order. The minus sign (-) specifies a descending order.
            sorter.setSortOrder("+");
            // Specify one or more sorting conditions.
            SortList.add(sorter);
            haQuery.setSort(SortList);

            // Create a Config object and use the config clause to configure parameters for paging and for the data format of return results.
            HaQueryconfigClause Queryconfig = new HaQueryconfigClause();
            Queryconfig.setStart("1");
            Queryconfig.setHit("100");
            // Specify a format of return results. Formats such as XML, JSON, and Protobuf are supported.
            Queryconfig.setFormat("JSON");
            // Specify parameters for a custom config object.
            Map<String, String> CustomConfig = new HashMap<>();
            CustomConfig.put("no_summary", "yes");
            CustomConfig.put("qrs_chain", "search");
            Queryconfig.setCustomConfig(CustomConfig);
            haQuery.setConfig(Queryconfig);

            // Specify filter conditions.
            // You can specify one or more filter conditions. If you want to specify more than one filter condition, use AND or OR to join the filter conditions.
            // The supported operators are equal to (=), greater than (>), less than (<), less than or equal to (<=), greater than or equal to (>=), and not equal to (!=).
            haQuery.setFilter("id>100 AND id<=1000");

            // Specify parameters in the kvpairs clause.
            Map<String, String> haKvpairs = new HashMap<>();
            haKvpairs.put("duniqfield", "cate_id");
            haQuery.setKvpairs(haKvpairs);

            // Specify a custom query clause.
            Map<String, String> CustomQuery = new HashMap<>();
            CustomQuery.put("searcher_cache", "use:no");
            haQuery.setCustomQuery(CustomQuery);

            SearchRequestModel searchRequestModel = new SearchRequestModel();
            SearchQuery searchQuery = new SearchQuery();
            searchQuery.setQuery(client.buildHaSearchQuery(haQuery));
            searchRequestModel.setQuery(searchQuery);
            // The request method. Only the GET and POST methods are supported. Default value: GET. If the length of the query exceeds 30 KB, use the POST method.
            searchRequestModel.setMethod("POST");
            SearchResponseModel responseModel = client.Search(searchRequestModel);
            System.out.println("result:" + responseModel.getBody());
        } catch (TeaException e) {
            System.out.println(e.getMessage());
            Map<String, Object> abc = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(abc));
        }
    }
}

Havenask query using a query string

Pass the query, config, and cluster parameters as a single formatted string directly to haRawQuery.setQuery(). Use this approach for simple queries where constructing individual clause objects is unnecessary.

import java.util.Map;

import com.aliyun.ha3engine.Client;
import com.aliyun.ha3engine.models.Config;
import com.aliyun.ha3engine.models.SearchQuery;
import com.aliyun.ha3engine.models.SearchRequestModel;
import com.aliyun.ha3engine.models.SearchResponseModel;
import com.aliyun.tea.TeaException;

/**
 * @author alibaba
 */
public class SearchDoc {

    public static void main(String[] args) throws Exception {

        Config config = new Config();
        // The username. You can view the username in the API Endpoint section of the Instance Details page.
        config.setAccessUserName("<userName>");
        // The password. You can change the password in the API Endpoint section of the Instance Details page.
        config.setAccessPassWord("<password>");
        // The name of the instance. You can view the name in the upper-left corner of the Instance Details page. Example: ha-cn-i7*****605.
        config.setInstanceId("<instanceID>");

        // The endpoint that is used to access the instance. Specify the API endpoint if the instance is accessed over a VPC. Specify the public endpoint if the instance is accessed over the Internet.
        config.setEndpoint("<endpoint>");

        Client client = new Client(config);

        try {
            SearchRequestModel haQueryRequestModel = new SearchRequestModel();
            SearchQuery haRawQuery = new SearchQuery();
            haRawQuery.setQuery("query=index_id:1&&config=start:0,hit:100,format:json&&cluster=general");
            haQueryRequestModel.setQuery(haRawQuery);
            // The request method. Only the GET and POST methods are supported. Default value: GET. If the length of the query exceeds 30 KB, use the POST method.
            haQueryRequestModel.setMethod("POST");
            SearchResponseModel responseModel = client.Search(haQueryRequestModel);
            System.out.println("result:" + responseModel.getBody());
        } catch (TeaException e) {
            System.out.println(e.getMessage());
            Map<String, Object> abc = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(abc));
        }
    }
}

What's next

[OpenSearch Retrieval Engine Edition SQL syntax reference]()
[Havenask query syntax reference]()