OpenSearch:data processing

Upload documents

This Application Programming Interface (API) supports adding, updating, and deleting documents. Batch operations for these actions are also supported.

• URL

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

  • $app_name specifies the name of your application.

  • $table_name specifies 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 signing requests and setting request 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. Specifies the operation to perform on the document. Valid values are add and delete. To improve network efficiency, you can perform batch updates in a single request. The add operation adds a new document. If a document with the same primary key exists, the system first deletes the existing document 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. Specifies the content of the document. The primary key field is required because all system operations use the primary key. For a delete operation, you only need to provide the primary key of the document.

• 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 content. message indicates the error message. params indicates the error parameters. code indicates the error code.
request_id	string	The ID of the request. Use this ID for troubleshooting.
status	string	The result of the operation. OK indicates success. FAIL indicates failure. If the operation fails, troubleshoot based on the returned error code.
result	string	This parameter is returned if the operation is successful. The value is true. This parameter is not returned if an error occurs.

Examples

Request: (This example omits request header parameters and encoding details.)

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.

• Pushing data using an API or an SDK is subject to limits on frequency and size. These limits vary by application. For more information, see Limits.

• After you upload data, check the return value. To prevent data loss, you must 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 successfully received the data. Errors that occur during data processing appear in the console. You must promptly check the console 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.