All Products
Search
Document Center

Process data

Last Updated: Sep 09, 2021

Upload documents

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 your application.

  • 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 more 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 set 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 specified primary key value is managed. Only advanced applications support this parameter. You cannot set this parameter if you are using a standard application. Otherwise, the error code 4007 is returned. If this parameter is not set, OpenSearch regards the timestamp when OpenSearch receives the document as the timestamp when the operation is performed 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 indicates 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 indicates that the specified fields in the document are to be updated. A value of delete indicates 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 only to 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

Parameter

Type

Description

errors

STRING

The error information, in which the message parameter indicates the error message, the params parameter indicates the error parameters, and the code parameter indicates the error code. For more information about error codes, see Error codes.

request_id

STRING

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

status

STRING

The execution result of the request. Valid values: OK and FAIL. A value of OK indicates that the request is successful. A value of FAIL indicates that the request failed. In this case, troubleshoot errors based on the error code.

result

STRING

The result of the request. A value of true is returned for successful requests. This parameter is not returned for failed requests.

Examples

A sample API request for data processing, which omits information such as request headers 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

  • You can push data for a limited number of times and of a limited size by calling API operations or using 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.