OpenSearch:data processing

Upload documents

This API supports adding, updating, and deleting documents, including batch operations.

• URL

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

  • $app_name: the name of your application.

  • $table_name: the name of the table to which you want to push data.

  • The preceding URL omits request header parameters and encoding details.

  • The preceding URL omits the host address of the application.

Supported format: JSON

HTTP request method: POST

Request parameters

For more information about request signing and headers, see v3 API signature mechanism.

Document data format

The following example shows the data format:

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

• cmd: Required. The operation to perform on the document. Valid values: add and delete. You can perform batch updates in a single request to improve network efficiency. The add operation adds a new document. If a document with the same primary key exists, the system deletes the existing document first and then adds the new one. The delete operation removes a document. If a document with the specified primary key does not exist, the operation is still considered successful.

• fields: Required. The document content. The primary key field is required because all system operations use the primary key. For a delete operation, only the primary key is needed.

• For Array types, use a JsonArray. For example: [{"fields": { "id": "0","int_array": [14,85],"string_array": ["abc","xyz"]},"cmd": "ADD"}].

• Note: The top-level element is a JsonArray that supports batch operations on multiple documents.

Return result

Parameter	Type	Description
errors	array	The error details. message: the error message. params: the error parameters. code: the error code.
request_id	string	The request ID. Use this ID for troubleshooting.
status	string	The operation result. OK indicates success. FAIL indicates failure. If the operation fails, troubleshoot based on the returned error code.
result	string	Returned only when the operation succeeds. The value is true.

Examples

Sample request (request header parameters and encoding details are omitted):

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

// Place the following data 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 specified application does not exist.",
            "params": {
                "friendly_message": "The specified application does not exist."
            }
        }
    ],
    "request_id": "150116732819940316116461",
    "status": "FAIL"
}

Notes

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

• Data push frequency and size are subject to limits that vary by application. For more information, see Limits.

• After you upload data, check the return value. To prevent data loss, retry the operation if certain error codes are returned, such as error code 3007. Data processing is asynchronous. A return value of "OK" only indicates that the system received the data. Errors that occur during processing appear in the console. Check the console promptly for error messages.

• The size of data in a POST request is limited. If the total size of the documents that you upload exceeds 2 MB before encoding, the server rejects the request and returns an error.

• If the body of a POST request contains Chinese characters, you must encode the data in UTF-8. You must also encode the data in UTF-8 before you calculate the MD5 value for the Content-MD5 header. Otherwise, the push operation fails.