Push demo-OpenSearch(Open Search)-阿里云帮助中心

This page demonstrates how to push documents to an OpenSearch application using the OpenSearch SDK for Java V3.1. The example covers ADD, UPDATE, and DELETE operations in a single batch push, followed by a search query to verify the results.

Prerequisites

Before you begin, ensure that you have:

An OpenSearch application with at least one table configured
The AccessKey ID and AccessKey secret of a Resource Access Management (RAM) user with the required permissions granted to the AliyunServiceRoleForOpenSearch role. For role details, see AliyunServiceRoleForOpenSearch. For permission details, see Access authorization rules
The OpenSearch SDK for Java V3.1 added to your project

Important

Use a RAM user's AccessKey pair instead of your Alibaba Cloud account's AccessKey pair. The account-level AccessKey pair grants access to all API operations and is a higher security risk. To create a RAM user, see Create a RAM user. To create an AccessKey pair, see Create an AccessKey pair.

Set up credentials

Store your AccessKey pair as environment variables. This keeps credentials out of your source code.

Linux and macOS

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

Replace <access_key_id> and <access_key_secret> with the AccessKey ID and AccessKey secret of your RAM user.

Windows

Create an environment variable file and add ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET to it, setting each to the corresponding value.
Restart Windows for the changes to take effect.

How it works

The push workflow follows three steps:

Build each document as a Map object containing field values, then wrap it in a JSONObject with a command (ADD or DELETE).
Collect all JSONObject entries into a JSONArray, then call documentClient.push() to submit the batch to the application.
After the push, run a search query using SearcherClient to verify the documents appear in results.

You can only push fields that belong to the same table in a single push call. Pushing fields from different tables in one call is not supported.

Constraints and data format

Datasets must be in the valid format. To download a sample file as a template, log in to the OpenSearch console, go to the Instance Management page, find your application, and choose More > Upload File in the Actions column.
Build documents using JSONObject and JSONArray objects directly, as shown in the example below.
If the number of documents in a single push exceeds the limit, the push fails with an error.
Standard applications support the ADD command for both adding and fully replacing documents. The UPDATE command (partial field update) is only supported by advanced applications.

Push and query documents

The following example pushes four documents in one call — adding two documents (doc1, doc2), updating one (doc2 replaced by doc3), and deleting one (doc1) — then queries by primary key to verify the results.

package com.aliyun.opensearch;

import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Maps;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONArray;
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.commons.OpenSearchResult;
import com.aliyun.opensearch.sdk.generated.document.Command;
import com.aliyun.opensearch.sdk.generated.document.DocumentConstants;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.sdk.generated.search.general.SearchResult;

import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
import java.util.Map;
import java.util.Random;

public class testPushSearch2 {

    private String appName = "Name of the OpenSearch application that you want to manage"; // (1)
    private String tableName = "Name of the table to which data is to be uploaded";          // (2)
    private String host = "Endpoint of the OpenSearch API in your region";                  // (3)


    public static void main(String[] args) {

        // Read credentials from environment variables                                       // (4)
        String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        System.out.println(String.format("file.encoding: %s", System.getProperty("file.encoding")));
        System.out.println(String.format("defaultCharset: %s", Charset.defaultCharset().name()));

        // ---- Build documents ----

        // Generate random primary key values for doc1 and doc2                              // (5)
        Random rand = new Random();
        int value1 = rand.nextInt(Integer.MAX_VALUE);
        int value2 = rand.nextInt(Integer.MAX_VALUE);

        // doc1: ADD — adds a new document                                                   // (6)
        Map<String, Object> doc1 = Maps.newLinkedHashMap();
        doc1.put("id", value1);

        String title_string = "Upload doc1 in push mode";// UTF-8.
        byte[] bytes;
        try {
            bytes = title_string.getBytes("utf-8");
            String utf8_string = new String(bytes, "utf-8");
            doc1.put("name", utf8_string);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc1.put("phone", "137****1111");

        int[] int_arr = {11,11};
        doc1.put("int_arr", int_arr);

        String[] literal_arr1 = {"Upload doc1 in push mode","Test uploading doc1 in push mode"};
        doc1.put("literal_arr", literal_arr1);

        float[] float_arr = {(float)1.1,(float)1.1};
        doc1.put("float_arr", float_arr);

        doc1.put("cate_id", 1);

        // Standard applications use ADD for both adding and fully replacing documents.      // (7)
        // UPDATE (partial field update) is not supported for standard applications.
        JSONObject json1 = new JSONObject();
        json1.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json1.put(DocumentConstants.DOC_KEY_FIELDS, doc1);

        // doc2: ADD — adds a new document                                                   // (8)
        Map<String, Object> doc2 = Maps.newLinkedHashMap();
        doc2.put("id", value2);

        String title_string2 = "Upload doc2 in push mode";// UTF-8.
        byte[] bytes2;
        try {
            bytes2 = title_string2.getBytes("utf-8");
            String utf8_string2 = new String(bytes2, "utf-8");
            doc2.put("name", utf8_string2);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc2.put("phone", "137****2222");

        int[] int_arr2 = {22,22};
        doc2.put("int_arr", int_arr2);

        String[] literal_arr2 = {"Upload doc2 in push mode","Test uploading doc2 in push mode"};
        doc2.put("literal_arr", literal_arr2);

        float[] float_arr2 = {(float)2.2,(float)2.2};
        doc2.put("float_arr", float_arr2);

        doc2.put("cate_id", 1);

        JSONObject json2 = new JSONObject();
        json2.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json2.put(DocumentConstants.DOC_KEY_FIELDS, doc2);

        // doc3: ADD with doc2's primary key — replaces doc2 with doc3's field values        // (9)
        Map<String, Object> doc3 = Maps.newLinkedHashMap();
        doc3.put("id", value2);   // same primary key as doc2

        String title_string3 = "Update doc2 to doc3 in push mode";// UTF-8.
        byte[] bytes3;
        try {
            bytes3 = title_string3.getBytes("utf-8");
            String utf8_string3 = new String(bytes3, "utf-8");
            doc3.put("name", utf8_string3);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc3.put("phone", "137****3333");

        int[] int_arr3 = {33,33};
        doc3.put("int_arr", int_arr3);

        String[] literal_arr3 = {"Update doc2 to doc3 in push mode","Update doc2 to doc3 in push mode"};
        doc3.put("literal_arr", literal_arr3);

        float[] float_arr3 = {(float)3.3,(float)3.3};
        doc3.put("float_arr", float_arr3);

        doc3.put("cate_id", 1);

        JSONObject json3 = new JSONObject();
        json3.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json3.put(DocumentConstants.DOC_KEY_FIELDS, doc3);

        // doc4: DELETE — removes doc1 by primary key only                                   // (10)
        Map<String, Object> doc4 = Maps.newLinkedHashMap();
        doc4.put("id", value1);   // only the primary key is needed for deletion

        JSONObject json4 = new JSONObject();
        json4.put(DocumentConstants.DOC_KEY_CMD, Command.DELETE.toString());
        json4.put(DocumentConstants.DOC_KEY_FIELDS, doc4);

        // ---- Push documents ----

        JSONArray docsJsonArr = new JSONArray();
        docsJsonArr.put(json1);  // add doc1
        docsJsonArr.put(json2);  // add doc2
        docsJsonArr.put(json3);  // replace doc2 with doc3
        docsJsonArr.put(json4);  // delete doc1
        String docsJson = docsJsonArr.toString();

        // Initialize the client                                                             // (11)
        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
        OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
        DocumentClient documentClient = new DocumentClient(serviceClient);

        try {
            OpenSearchResult osr = documentClient.push(docsJson, appName, tableName);       // (12)

            // A "true" result means the push request was accepted without errors.
            // Check the OpenSearch console error logs for any post-push processing errors
            // (such as field type conversion failures).
            if (osr.getResult().equalsIgnoreCase("true")) {
                System.out.println("Push accepted. Request ID: " + osr.getTraceInfo().getRequestId());
            } else {
                System.out.println("Push failed: " + osr.getTraceInfo());
            }

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }

        // ---- Query to verify ----

        // Wait 1 second for indexing to complete before querying                            // (13)
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        SearcherClient searcherClient = new SearcherClient(serviceClient);

        // Configure paging and return format                                                // (14)
        Config config = new Config(Lists.newArrayList(appName));
        config.setStart(0);
        config.setHits(30);
        config.setSearchFormat(SearchFormat.JSON);  // supported formats: XML, JSON (FULLJSON not supported)

        config.setFetchFields(Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"));

        SearchParams searchParams = new SearchParams(config);

        // Query by primary key — match either value1 or value2                              // (15)
        // To query on multiple index fields, combine them in one setQuery call.
        // Each additional setQuery call overwrites the previous one.
        searchParams.setQuery("id:'" + value1 + "'|'" + value2 + "'");

        searchParams.setFilter("cate_id<=3");

        // Sort by id descending; break ties by RANK ascending                              // (16)
        Sort sorter = new Sort();
        sorter.addToSortFields(new SortField("id", Order.DECREASE));
        sorter.addToSortFields(new SortField("RANK", Order.INCREASE));
        searchParams.setSort(sorter);

        try {
            SearchResult searchResult = searcherClient.execute(searchParams);
            String result = searchResult.getResult();
            JSONObject obj = new JSONObject(result);
            System.out.println(obj.toString());

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }
    }
}

Callout annotations:

#	Description
(1)	Set `appName` to the name of your OpenSearch application.
(2)	Set `tableName` to the name of the table in the application that you want to push data to.
(3)	Set `host` to the OpenSearch API endpoint for your region.
(4)	Credentials are read from environment variables set in Set up credentials.
(5)	Random integers serve as primary key values for this demo. In production, use your actual document IDs.
(6)	Each document is built as a `Map<String, Object>`, then wrapped in a `JSONObject` with `DOC_KEY_CMD` and `DOC_KEY_FIELDS`.
(7)	`Command.ADD` adds a new document if the primary key does not exist, or fully replaces the existing document if it does.
(8)	A second document (`doc2`) is added with its own unique primary key (`value2`).
(9)	`doc3` uses the same primary key as `doc2` (`value2`), so the `ADD` command replaces `doc2` entirely with `doc3`'s field values.
(10)	`Command.DELETE` removes a document by primary key. Only the primary key field is required in the payload.
(11)	Create an `OpenSearch` object with your credentials and endpoint, then use it to initialize `OpenSearchClient` and `DocumentClient`.
(12)	`documentClient.push()` submits the entire batch in one request. A `"true"` result means the request was accepted; check the console error logs for processing errors that occur after the push.
(13)	Indexing is asynchronous. A 1-second sleep gives the engine time to index documents before the verification query runs. In production, implement a retry or polling strategy instead.
(14)	`Config` sets the paging parameters (`start`, `hits`) and response format. `fetchFields` controls which fields are returned.
(15)	The query uses the `id` index field to match either primary key. Combining multiple fields in a single `setQuery` call is required — each call overwrites the previous one.
(16)	Results are sorted by `id` descending. When multiple documents share the same `id` value, they are sorted by relevance score (`RANK`) ascending.