Uploads and deletes documents in an OpenSearch Vector Search Edition table using a single bulk request.
Request basics
| Property | Value |
|---|---|
| Method | POST |
| Format | JSON |
| Endpoint path | /update/$table_name/actions/bulk |
Set $table_name to {instance_id}_{table_name}. For example, if the instance ID is ha-843qfng6ydhb and the table name is test, use ha-843qfng6ydhb_test.
Request headers
| Header | Type | Description |
|---|---|---|
authorization | String | The authentication signature. Format: Basic <Base64-encoded-credentials>. See Generate the authorization header. |
X-Opensearch-Swift-PK-Field | String | The primary key field of the index table. Example: id. |
host | String | The endpoint of the OpenSearch instance. Find it in the API Endpoint section of the Instance Details page. Example: ha-cn-**********.ha.aliyuncs.com. |
Generate the authorization header
The authorization header value is a Base64-encoded string of username:password.
Parameters
| Parameter | Type | Description |
|---|---|---|
accessUserName | String | The username. Find it in the API Endpoint section of the Instance Details page. |
accessPassWord | String | The password. You can modify the password in the API Endpoint section of the Instance Details page. |
Generate the value
import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;
public class GenerateAuthorization {
public static void main(String[] args) throws Exception {
String accessUserName = "username";
String accessPassWord = "password";
String realmStr = "" + accessUserName + ":" + accessPassWord + "";
String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
System.out.println(authorization);
}
}The code outputs a Base64-encoded string such as cm9vdDp******mdhbA==.
Add the Basic prefix when setting the header in your HTTP request:
authorization: Basic cm9vdDp******mdhbA==Request body
The request body is a JSON array. Each element represents one document operation.
[
{
"cmd": "add",
"fields": {
"id": "1",
"title": "This is the title",
"body": "This is the body"
}
},
{
"cmd": "delete",
"fields": {
"id": "3"
}
}
]Fields
| Field | Required | Description |
|---|---|---|
cmd | Yes | The operation to perform. Valid values: add, delete. Batch multiple operations in a single request to improve network and processing efficiency. |
fields | Yes | The document fields to operate on. Must include the primary key field — OpenSearch identifies each document by its primary key value. |
`cmd` behavior
| Value | Behavior |
|---|---|
add | Uploads the document. If a document with the same primary key already exists, the original is deleted before the new document is written. |
delete | Deletes the document with the specified primary key. If no matching document exists, the operation still succeeds. |
ARRAY type fields
Specify ARRAY type fields as JSON arrays:
[{"cmd": "add", "fields": {"id": "0", "int_array": [14, 85], "string_array": ["abc", "xyz"]}}]Example request
POST http://ha-cn-**********.ha.aliyuncs.com/update/$table_name/actions/bulkRequest body:
[{
"cmd": "add",
"fields": {
"id": 1,
"name": "Test Data Push"
}
}]Responses
Success
No response body is returned on success.
Error
[
{
"code": 3012,
"message": "Resource not found."
}
]Usage notes
Field names are not case-sensitive when pushing data via the API or OpenSearch SDK.
Push frequency and data size limits vary by application. See the limits documentation for your application type.
After pushing data, check the response for error codes. Error code
3007requires immediate troubleshooting — unresolved data errors can cause data loss. OpenSearch processes data asynchronously: a successful response means the data was received, not that processing is complete. Monitor the OpenSearch console for processing errors.The maximum request body size before encoding is 2 MB. Requests exceeding this limit are rejected.