Data push demo

How it works

All three operations call client.pushDocuments(tableName, pkField, requestModel) with a list of document objects. Each document object contains a cmd field and a fields map. The operation is determined by the cmd value:

Prerequisites

Before you begin, ensure that you have:

• An OpenSearch Retrieval Engine Edition instance

• The instance endpoint, instance name, username, and password — all available in the API Endpoint section of the Instance Details page

• The Java SDK (com.aliyun.ha3engine) installed in your project

Initialize the client

All operations share the same client configuration. Set up the Config object with your instance credentials before calling any push operation.

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

Config config = new Config();
// Instance name. Find it in the upper-left corner of the Instance Details page.
// Example: ha-cn-i7*****605
config.setInstanceId("<instance_id>");
// API endpoint. Find it in the API Endpoint section of the Instance Details page.
// Example: ha-cn-i7*****605.public.ha.aliyuncs.com
config.setEndpoint("<instance_services_domain>");
// Username and password from the API Endpoint section.
config.setAccessUserName("<user_name>");
config.setAccessPassWord("<user_password>");

Client client = new Client(config);

Replace the following placeholders with your actual values:

Upload a document

Use the add command to upload a document.

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

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

// The data source table to push documents to.
String tableName = "<table_name>";
// The primary key field of the document.
String pkField = "<field_pk>";

try {
    ArrayList<Map<String, ?>> documents = new ArrayList<>();

    Map<String, Object> document = new HashMap<>();
    Map<String, Object> fields = new HashMap<>();

    // Field values — keys and values must be matched in pairs.
    // The primary key field value must match pkField.
    fields.put("<field_pk>", "<field_pk_value>");
    fields.put("<field_map_key_1>", "<field_map_value_1>");
    fields.put("<field_map_key_2>", "<field_map_value_2>");

    // Multi-value fields: set multi_value to true when configuring the index table.
    ArrayList<Object> multiValueField = new ArrayList<>();
    multiValueField.add("multi_value_1");
    multiValueField.add("multi_value_2");
    fields.put("<multi_value_key>", multiValueField);

    document.put("fields", fields);
    document.put("cmd", "add");
    documents.add(document);

    PushDocumentsRequestModel requestModel = new PushDocumentsRequestModel();
    requestModel.setBody(documents);
    PushDocumentsResponseModel responseModel = client.pushDocuments(tableName, pkField, requestModel);

    System.out.println("result: " + responseModel.getBody());

} catch (TeaException e) {
    System.out.println(e.getCode());
    System.out.println(e.getMessage());
    System.out.println(com.aliyun.teautil.Common.toJSONString(e.getData()));
}

Sample request payload:

[
    {
        "cmd": "add",
        "fields": {
            "id": "1",
            "title": "This is the title",
            "body": "This is the body",
            "tags": [1, 2, 3]
        }
    }
]

requestModel.headers = new HashMap<>();
requestModel.headers.put("X-Opensearch-Validate-Data", "false");

Update a document

Use the update_field command to partially update an existing document. Only the fields included in the payload are updated; all other fields remain unchanged.

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

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

// The data source name. To find it, go to the OpenSearch console > Instance Details page.
// In the left-side navigation pane, choose Configuration Center > Data Source.
String tableName = "<instance_datasource_table_name>";
String pkField = "<field_pk>";

try {
    ArrayList<Map<String, ?>> documents = new ArrayList<>();

    Map<String, Object> document = new HashMap<>();
    Map<String, Object> fields = new HashMap<>();

    fields.put("<field_pk>", "<field_pk_value>");
    fields.put("<field_map_key_1>", "<field_map_value_1>");
    fields.put("<field_map_key_2>", "<field_map_value_2>");

    // Multi-value fields.
    ArrayList<Object> multiValueField = new ArrayList<>();
    multiValueField.add("multi_value_1");
    multiValueField.add("multi_value_2");
    fields.put("<multi_value_key>", multiValueField);

    document.put("fields", fields);
    document.put("cmd", "update_field");
    documents.add(document);

    PushDocumentsRequestModel requestModel = new PushDocumentsRequestModel();
    requestModel.setBody(documents);
    PushDocumentsResponseModel responseModel = client.pushDocuments(tableName, pkField, requestModel);

    System.out.println("result: " + responseModel.getBody());

} catch (TeaException e) {
    System.out.println(e.getMessage());
    System.out.println(com.aliyun.teautil.Common.toJSONString(e.getData()));
}

Sample request payload:

[
    {
        "cmd": "update_field",
        "fields": {
            "id": "2",
            "title": "This is the new title"
        }
    }
]

Delete a document

Use the delete command to remove a document. Only the primary key field is required in the payload.

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

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

// The data source name. To find it, go to the OpenSearch console > Instance Details page.
// In the left-side navigation pane, choose Configuration Center > Data Source.
String tableName = "<instance_datasource_table_name>";
String pkField = "<field_pk>";

try {
    ArrayList<Map<String, ?>> documents = new ArrayList<>();

    Map<String, Object> document = new HashMap<>();
    Map<String, Object> fields = new HashMap<>();

    // Only the primary key field is required for delete operations.
    fields.put("<field_pk>", "<field_pk_value>");

    document.put("fields", fields);
    document.put("cmd", "delete");
    documents.add(document);

    PushDocumentsRequestModel requestModel = new PushDocumentsRequestModel();
    requestModel.setBody(documents);
    PushDocumentsResponseModel responseModel = client.pushDocuments(tableName, pkField, requestModel);

    System.out.println("result: " + responseModel.getBody());

} catch (TeaException e) {
    System.out.println(e.getMessage());
    System.out.println(com.aliyun.teautil.Common.toJSONString(e.getData()));
}

Sample request payload:

[
    {
        "cmd": "delete",
        "fields": {
            "id": "3"
        }
    }
]