All Products
Search
Document Center

Tutorial

Last Updated: Sep 09, 2021

Before you begin

Create an application in the OpenSearch console

  • Log on to the OpenSearch console. Create an application and manually configure an application schema based on your business needs. Other configurations that you need to complete include index fields, attribute fields, data sources, and filter conditions.

  • OpenSearch provides an application schema template. You can download the template and use it to configure an application schema. On the application configuration page, click Import Template, upload the application schema template, and then complete the subsequent operations.You can use this application schema template to test the demo code for implementing the search and data push features by using OpenSearch SDK for Java that supports standard applications.

Obtain your AccessKey ID and secret

To obtain your AccessKey ID and secret, log on to the OpenSearch console, move the pointer over your profile picture in the upper-right corner, and then click AccessKey Management. You can also log on to the User Management console and click Security Management in the left-side navigation pane to manage your AccessKey pairs.

Add OpenSearch SDK for Java to your project

You can add OpenSearch SDK for Java to your project in the following ways:

  • Download the following source code packages to your computer: the latest version of OpenSearch SDK for Java and the slf4j-api-1.7.25 dependency JAR package. Then, import the two JAR packages to your project. If the dependency JAR package is not imported to the project, errors occur when the project is run.

  • Import OpenSearch SDK for Java as a Maven dependency.

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

Create an application client

This section describes how to use OpenSearch SDK for Java to create an application client. You can also create an application client in the OpenSearch console. In this example, import OpenSearch SDK for Java to your project first. Then, use your AccessKey ID and secret to instantiate a SearcherClient object, as shown in the following sample code. The application client that is created in this section is also used for demonstration in the subsequent sections.

import com.aliyun.opensearch.*;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.search.Config;
import com.aliyun.opensearch.sdk.generated.search.SearchFormat;

String appName = "The application name";
String accesskey = "The AccessKey ID of your Alibaba Cloud account";
String secret = "The AccessKey secret of your Alibaba Cloud account";
String host = "The endpoint of the OpenSearch API in your region, which you can obtain on the details page of the application";

// Create an OpenSearch object.
OpenSearch openSearch = new OpenSearch(accesskey, secret, host);

// Use the OpenSearch object as a parameter to create an OpenSearchClient object.
OpenSearchClient serviceClient = new OpenSearchClient(openSearch);

## Upload documents.
A document that can be uploaded to an OpenSearch application must be a JSON string. The following code shows the structure of a document.
I In the OpenSearch console, you can choose More > Upload File in the Actions column for an application. In the Upload File dialog box, you can download the sample file and upload it to the application to test the search feature. The file you upload must use UTF-8 encoding and cannot contain a BOM header. Otherwise, the upload fails. 
[
    {
        "fields":{...},
        "cmd":"..."
    }
    ...
]

A document is a structure that consists of two fields named fields and cmd. The fields field contains the core data of a document. The cmd field contains an operation that is to be performed on the document. The cmd field supports different operations for standard and advanced applications.

For standard applications, the cmd field supports only the ADD and DELETE operations. If you need to update a document in a standard application, you must specify all the fields of the document instead of only the fields that you want to update. Therefore, updates of documents are also implemented by the ADD operation.

You can also set the cmd field to DELETE to delete data. The following code shows two sample documents:

[
    {
        "fields": {
            "id": "0",
            "name": "Small- and medium-sized enterprises need to support the searching of various structured data. Most of these enterprises rely on the built-in search feature of databases or use open source search software. This not only consumes the resources on their websites, but also provides poor performance and relevance. Developed based on the advanced cloud computing and search technologies provided by Alibaba Cloud, OpenSearch provides a cost-effective, high-quality, high-performance, and customizable data search solution for small- and medium-sized enterprises. The focus of OpenSearch is slightly different than that of regular cloud-based search solutions. OpenSearch focuses on the searching of structured data, whereas regular cloud-based search solutions focuses on data on websites."
        },
        "cmd": "ADD"
    },
    {
      "fields": {
            "id": "1",
            "name": "Cloud Search Engine is a search engine that is developed based on cloud computing technologies. It allows you to bind multiple domain names and define search scopes and types. In addition, you can use personalized programs that run on Elastic Compute Service (ECS) instances to design different user interfaces (UIs) and processes for different domain names. Traditional search engines require users to specify multiple keywords for searching. Cloud Search Engine allows users to specify the density of each keyword. All keywords are stored in the search cloud with different sizes and font weights, which indicate their different densities.  "
        },
        "cmd": "ADD"
    }
]

The following sample code shows how to upload a document to a table in an application:

// Define a DocumentClient object, add a document in the form of a JSON string, and then submit the document.
DocumentClient documentClient = new DocumentClient(serviceClient);
table_name = "The name of the table to which the document is to be uploaded";
data = "[{"cmd":"add", "fields":{"id":"0","name":"blabla..."}}]";
// Call the push method to upload the data.
OpenSearchResult osr = documentClient.push(data, appName, table_name);

You can also use the add or remove method of the DocumentClient class to generate data, and then call the push method to upload the data.

Implement the search feature

OpenSearch allows you to customize configurations to meet personalized search requirements. To meet regular and basic search requirements, you need only to complete simple configurations, as shown in the following sample code:

// Use the OpenSearchClient object as a parameter to create a SearcherClient object.
SearcherClient searcherClient = new SearcherClient(serviceClient);
// Create a Config object and use the config clause to configure parameters such as the application name, paging-related parameters, and data format of return results.
Config config = new Config(Lists.newArrayList(appName));
config.setStart(0);
config.setHits(5);
// Specify the data format of return results. In this example, the format is set to JSON.
config.setSearchFormat(SearchFormat.JSON);
// Create a SearchParams object.
SearchParams searchParams = new SearchParams(config);
// Specify a query keyword. The specified keyword indicates the index field to be used. Index fields are specified in the schema of an application. If you do not specify a query keyword, the default index field is used. You can specify multiple keywords to perform a query based on multiple index fields. In this case, you must specify the index fields in one setQuery call. If you specify each index field in a separate setQuery call, the last clause overwrites the preceding clauses.
searchParams.setQuery("name:'Search'");
// Specify a filter condition.
searchParams.setFilter("id>0");
// Create a Sort object and configure two-dimensional sorting.
Sort sort = new Sort();
// Sort documents based on the id field in descending order.
sort.addToSortFields(new SortField("id", Order.DECREASE));
// If multiple documents have the same value of the id field, sort the documents based on the RANK field in ascending order. The RANK field indicates the relevance of a document to the query keyword.
sort.addToSortFields(new SortField("RANK", Order.INCREASE));
// Add the Sort object as a query parameter.
searchParams.setSort(sort);
// Run the query and return the results in the form of a SearchResult object.
SearchResult searchResult = searcherClient.execute(searchParams);
// Convert the SearchResult object into a string and return the string.
String result = searchResult.getResult();

Debugging

The preceding configurations are sufficient to meet basic search requirements. However, to optimize search performance and improve the relevance of search results requires a long process of trial and error and iterations. In this process, you may encounter issues or search results may not meet expectations. In these cases, you can call the getRequestUrl method in the following sample code to obtain detailed information about the requests in question, and then use the information for troubleshooting. When you encounter an issue, you can seek help from the TradeManager or DingTalk support group of OpenSearch. You must provide debugging information so that the support engineers can analyze and identify the cause based on the information. The debugging information that you provide includes abnormal queries, queries whose return results did not meet expectations, requests IDs, or HTTP request strings.

In some cases, you may need to record historical request strings. For example, you may need to display the request string of the last query, and copy and run part of the query clauses in the OpenSearch console for debugging. The following sample code shows how to obtain the request string:
SearchResultDebug searchdebugrst = searcherClient.executeDebug(searchParams);
System.out.println(searchdebugrst.getRequestUrl());