data processing considerations-OpenSearch(Open Search)-阿里云帮助中心

Pushes documents to an OpenSearch application in batches. Use the bulk document API to add, update, and delete documents in a single request, reducing network overhead and improving indexing throughput.

Upload documents

Prerequisites

Before you begin, ensure that you have:

An OpenSearch application with at least one data-receiving table
The application name and the target table name
A valid request signature — see V3 API Signature Mechanism for how to calculate signature strings and configure request headers

Endpoint

POST /v3/openapi/apps/<app_name>/<table_name>/actions/bulk

Replace <app_name> with your application name and <table_name> with the name of the data-receiving table. The URL excludes the host address and request headers.

Request body format

The request body is a JSON array. Each element represents one document operation. Sending multiple operations in a single request reduces network calls and speeds up indexing — batch whenever possible.

Premium Edition example:

[
    {
        "cmd": "add",
        "timestamp": 1401342874777,
        "fields": {
            "id": "1",
            "title": "This is the title",
            "body": "This is the body"
        }
    },
    {
        "cmd": "update",
        "timestamp": 1401342874778,
        "fields": {
            "id": "2",
            "title": "This is the new title"
        }
    },
    {
        "cmd": "delete",
        "fields": {
            "id": "3"
        }
    }
]

Fields

Field	Required	Description
`cmd`	Yes	The operation to perform. See Operations.
`fields`	Yes	The document fields. The primary key field is always required. For `delete`, only the primary key is needed.
`timestamp`	No	The operation timestamp in milliseconds. OpenSearch uses this to resolve ordering conflicts when multiple operations target the same primary key. If omitted, OpenSearch uses the time it receives the request. Premium Edition only — Standard Edition returns error code `4007` if this field is set.

Operations

Choose the cmd value based on the idempotency behavior you need:

`cmd` value	Behavior	Edition support
`add`	Adds a document. If a document with the same primary key already exists, the existing document is deleted before the new one is added.	Premium and Standard
`delete`	Deletes the document with the specified primary key. If no matching document exists, the operation is still considered successful.	Premium and Standard
`update`	Updates specific fields of the document with the specified primary key.	Premium only
`upsert`	Updates the document if the primary key exists; otherwise adds a new document.	Premium only

Standard Edition does not support update or upsert.

For array-type fields, use a JSON array value:

[{"cmd": "add", "fields": {"id": "0", "int_array": [14, 85], "string_array": ["abc", "xyz"]}}]

Example

Request (headers and encoding omitted):

POST http://<host>/v3/openapi/apps/app_schema_demo/tab/actions/bulk

[{"cmd":"ADD","fields":{"id":1,"name":"Test Data Push"}}]

Successful response:

{
    "errors": [],
    "request_id": "150116724719940316170289",
    "status": "OK",
    "result": true
}

Error response:

{
    "errors": [
        {
            "code": 2001,
            "message": "The application to be managed does not exist. The application to be managed does not exist.",
            "params": {
                "friendly_message": "The application to be managed does not exist."
            }
        }
    ],
    "request_id": "150116732819940316116461",
    "status": "FAIL"
}

Response fields

Field	Type	Description
`status`	string	`OK` if the request was received; `FAIL` if it was rejected.
`result`	string	`true` for successful requests. Not returned for failed requests.
`request_id`	string	The request ID, used for troubleshooting.
`errors`	array	Error details when `status` is `FAIL`. Each error object contains `code` (error code), `message` (error description), and `params` (additional parameters). See Error codes.

Usage notes

Asynchronous processing

status: OK means OpenSearch received the request — not that the documents were indexed. OpenSearch processes data asynchronously. Check the OpenSearch console regularly for processing errors, and pay special attention to error code 3007.

Request size limit

The maximum request body size before encoding is 2 MB. OpenSearch rejects requests that exceed this limit.

Request body encoding

If the request body contains Chinese characters, encode it as UTF-8. Calculate the Content-MD5 header value based on the UTF-8-encoded body. Requests that do not follow this requirement will fail.

Field name case sensitivity

Field names are not case-sensitive when pushing data via API or SDK.

Frequency and size limits

Data push frequency and size limits vary by application type. See System Limits.

Error handling

Always check the return value after uploading data. Troubleshoot error codes promptly to prevent data loss.