OpenSearch:Data processing

You can add, update, and delete documents individually or in batches.

URL

/v3/openapi/apps/$app_name/$table_name/actions/bulk

• Replace $app_name with your application name.

• Replace $table_name with the name of the data-receiving table in your application.

• This sample URL omits request headers and encoding information.

• This URL does not include the application host address.

Supported format

JSON

HTTP request method

POST

Request parameters

To learn how to calculate a signature string and configure request headers for data push, see V3 API Signature Mechanism.

Document data format

Note

Standard Edition applications do not support the timestamp parameter. If you specify this parameter, error code 4007 is returned.

The following example shows the Premium Edition data format:

[
    {
        "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"
        }
    }
]

• timestamp: Optional. The timestamp of the document operation, in milliseconds. OpenSearch uses this value to determine the processing order of operations on documents with the same primary key. This parameter is supported only by Premium Edition applications. If you specify it for a Standard Edition application, error code 4007 is returned. If not specified, OpenSearch uses the time it receives the document.

• cmd: Required. Specifies the operation to perform on the document:

  • add: Adds a document. If a document with the same primary key exists, the existing document is deleted before the new one is added.

  • delete: Deletes a document. If no document with the specified primary key exists, the operation is still considered successful.

  • update: Updates specific fields of the document with the specified primary key.

  • upsert: Updates the document if the specified primary key exists. Otherwise, adds a new document.

    Note

    Standard Edition applications do not support `update` or `upsert`.

    You can batch multiple operations in a single request to improve efficiency.

• fields: Required. The document fields to operate on. The primary key field is required because OpenSearch uses it to identify documents. For delete operations, only the primary key field is required.

• For Array type fields, use a JSON array, such as [{"fields": { "id": "0","int_array": [14,85],"string_array": ["abc","xyz"]},"cmd": "ADD"}].

• The outermost layer of the request body is a JSON array, which allows you to manage multiple documents in a single request.

Return results

Examples

Sample request (headers and encoding omitted):

http://host/v3/openapi/apps/app_schema_demo/tab/actions/bulk

// The document to be uploaded, which needs to be placed in the request body.
[{"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"
}

Usage notes

• When you push data by using the API or SDK, field names are not case-sensitive.

• Data push frequency and size limits vary by application type. For more information, see System Limits.

• Always check the return value after uploading data and troubleshoot any error codes promptly to prevent data loss. Pay special attention to error code 3007. Because OpenSearch processes data asynchronously, a return value of OK indicates only that the data was received, not that it was processed successfully. Check the OpenSearch console regularly for processing errors.

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

• If the request body contains Chinese characters, you must use UTF-8 encoding. The Content-MD5 header value must also be calculated based on the UTF-8-encoded body. Otherwise, the request fails.