Data processing

Updated at:

Upload documents

Supports add, update, and delete operations, as well as the corresponding batch operations.

URL

/v3/openapi/apps/$app_name/$table_name/actions/bulk
  • $app_name specifies the name of the application that you want to manage.

  • $table_name specifies the name of the table in the application to which you want to push data.

  • The preceding URL omits request header parameters, encoding, and other factors.

  • The preceding URL omits the host address that is used to access the application.

Supported formats

JSON

HTTP request method

POST

Request parameters

For information about the signatures involved in pushing data and how to set request headers, see V3 API signature mechanism.

Document data format

Note

Standard Edition applications do not support the timestamp parameter. If you specify the timestamp option, the push returns the 4007 error code.

The following example uses the data format of an Advanced Edition application:

[
    {
        "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. Records the time when the document was actually generated, in milliseconds. The system uses this timestamp to determine the update order of documents that have the same primary key. This option is supported only by Advanced Edition applications. Standard Edition applications do not have the timestamp option. If you specify this option for a Standard Edition application, the push returns the 4007 error code. If the timestamp option is not specified, the time when the document is sent to OpenSearch is used as the document update time by default.

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

    • add: Adds a document. If a document with the same primary key already exists, the system deletes the existing document and then adds the new one.

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

    • update: Updates a document. Specific fields of the document with the specified primary key are updated.

    • upsert: Updates or inserts a document. If a document with the specified primary key already exists, update is performed. Otherwise, add is performed.

      Note

      Standard Edition does not support update or upsert.

      We recommend that you perform batch updates in a single request to improve network interaction and processing efficiency.

  • fields: Required. The content of the document to be processed. The primary key field is required because all system operations are performed based on the primary key. For "delete", you need to provide only the primary key of the document.

  • For the Array type, use JsonArray, for example, [{“fields”: { “id”: “0”,”int_array”: [14,85],”string_array”: [“abc”,”xyz”]},”cmd”: “ADD”}].

  • Note: The outermost layer is of the JsonArray type, which supports batch operations on multiple documents.

Response

Parameter

Type

Description

errors

array

The error details of the push. message indicates the error message, params indicates the error parameters, and code indicates the error code.

request_id

string

The ID of the request record, which is mainly used for troubleshooting.

status

string

The execution result. OK indicates success and FAIL indicates failure. If the request fails, troubleshoot the issue based on the returned error code.

result

string

This parameter is returned with a value of true if the execution succeeds. It is not returned if an error occurs.

Example

Request: (request header parameters, encoding, and other factors are omitted)

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

//The following data to be uploaded must be placed in the request body
[{"cmd":"ADD","fields":{"id":1,"name":"Test Data Push"}}]

Success response

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

Error response (application not found)

{
    "errors": [
        {
            "code": 2001,
            "message": "\u5f85\u67e5\u5e94\u7528\u4e0d\u5b58\u5728.\u5f85\u67e5\u5e94\u7528\u4e0d\u5b58\u5728\u3002",
            "params": {
                "friendly_message": "\u5f85\u67e5\u5e94\u7528\u4e0d\u5b58\u5728\u3002"
            }
        }
    ],
    "request_id": "150116732819940316116461",
    "status": "FAIL"
}

Precautions

  • When you push data by using the API or SDK, the field names of the application are case-insensitive.

  • Pushing data by using the API or SDK is subject to limits on the number of pushes and data size, which vary by application. For more information, see Limits.

  • After you upload data, make sure to check the return value and retry requests that return relevant error codes (especially error 3007). Otherwise, data loss may occur. In addition, data processing is asynchronous. A response of "OK" only indicates that the system has successfully received the data. Errors that occur during data processing are displayed in the error messages in the console. Check them in a timely manner.

  • The size of POST data is limited. If the total size of the documents that you upload is too large (2 MB before encoding), the server rejects all parameters and returns an exception.

  • If the body of a POST push request contains Chinese characters, the data must be UTF-8 encoded. The same applies to the Content-MD5 parameter in the header: the data must be UTF-8 encoded before its MD5 value is calculated. Otherwise, push errors occur.