OpenSearch:Process data

You can call API operations to create, update, and delete one or more documents as needed.

URL

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

• Replace $app_name with the name of the application that you want to manage.

• Replace $table_name with the name of the table that is used to receive data in your application.

• The sample URL omits information such as request headers and the encoding method.

• The sample URL also omits the endpoint that is used to connect to OpenSearch.

Supported format

JSON

HTTP request method

POST

Request parameters

For information about how to calculate a signature string and specify headers for a request to push data, see Signature method of OpenSearch API V3.

Command syntax of data processing

Note

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

The following sample code provides an example on how to process data for an advanced 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. The timestamp when the operation is performed on the document. Unit: milliseconds. OpenSearch uses timestamps to identify the sequence in which a document with a specific primary key value is managed. Only advanced applications support this parameter. You cannot specify this parameter if you are using a standard application. Otherwise, the error code 4007 is returned. By default, if this parameter is not specified, OpenSearch uses the time when OpenSearch receives the document as the timestamp to perform operations on the document.

• cmd: required. The operation to be performed on the document. Valid values: add, update, and delete. A value of update is not supported for standard applications. We recommend that you send a request to perform multiple operations at a time. This improves the interaction efficiency over the network and the processing efficiency. A value of add specifies that the document is to be created. If a document with the specified primary key value exists, the original document is deleted before the new document is created. A value of update specifies that the specified fields in the document are to be updated. A value of delete specifies that the document is to be deleted. If no document with the specified primary key value exists, the document is deleted.

• fields: required. The fields on which the operation is to be performed in the document. You must specify the primary key field. OpenSearch identifies a document based on its primary key value. If you want to delete a document, you need to only specify the primary key field of the document.

• To specify a field of the ARRAY type, you need to specify it in the form of a JSON array. Example: {"fields": { "id": "0","int_array": [14,85],"string_array": ["abc","xyz"]},"cmd": "ADD"}].

• In the sample code, the outermost layer is a JSON array that is used to manage multiple documents at a time.

Response parameters

Examples

A sample API request for data processing, which omits information such as parameters in the request header and the encoding method:

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

Sample success response

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

Sample 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 calling an API operation or using an OpenSearch SDK, the field names of the application are not case-sensitive.

• You can push data for a limited number of times and of a limited size by calling an API operation or using an OpenSearch SDK. Different limits are imposed on different applications. For more information, see Limits.

• After you send a request to upload data, you must check the return value. If an error code is returned, troubleshoot errors based on the error code to prevent data losses. Pay special attention to the error code 3007. OpenSearch processes data in an asynchronous manner. A return value of OK indicates that OpenSearch receives the data. This does not indicate that data is properly processed. If an error occurs during data processing, the relevant error message is displayed in the OpenSearch console. Check error messages at the earliest opportunity.

• You can upload only a limited size of data when you send an HTTP POST request. If the size of data before encoding exceeds 2 MB, OpenSearch rejects the request and returns an error.

• If the body of an HTTP POST request to push data contains Chinese characters, you must encode the body in UTF-8. In addition, the value of the Content-MD5 header must also be encoded in UTF-8 before the MD5 value is calculated. Otherwise, an error is returned and the request fails.