All Products
Search
Document Center

Push data

Last Updated: Jan 21, 2021

Terms

data table

A data table is a collection of data that is organized based on data attributes. The types of data tables vary depending on specific scenes. In most cases, the following types of tables are required: user table, item table, and behavior table.

document

A document is the basic unit for data upload. The following document structure in the JSON format is applied:

{
    "fields": {
        "field_1": "value_1",
        "field_2": "value_2"
    },
    "cmd": "add"
}

field_1 and field_2 are content fields. For more information about field names and field values, see data specifications. cmd is a reserved field.

Reserved field

Field

Valid value

Description

cmd

add, update, and delete

You can specify this field to add, update, or remove a document.

Note:

1. The value add indicates an addition operation. The value update indicates an update operation.

2. If this field is set to add, add a document. If the document already exists, use the new one to replace the original document. You must submit a primary key and settings of all fields.

3. If this field is set to update, update an existing document. After the primary key is determined, you need only to upload the fields you want to update. If you update a document that does not exist, the update can take effect only after an internal scheduling period. We recommend that you do not use an update operation to add a document.

content field

Content fields constitute valid information of a document. To specify content fields, see data specifications.

push request

A push request can include multiple documents of a data table. As many documents as possible can be included in a request to improve the processing performance. For example, a push request that includes a maximum of 800 documents can be triggered or a push request can be triggered every 10s. The cmd field can be set to different values for documents that are included in a request.

quota

If a user table or item table contains too much data and the purchased quota is exceeded, an error code is returned, which indicates that the quota is exceeded. For more information, see Error codes. You can include only the documents for which the cmd field is set to delete in a push request. Unnecessary documents are removed.

Manage documents

The cmd field specifies the operation to be performed on a data table. If the cmd field is set to add, documents are added to a specific data table. If existing documents in the data table have the same unique identifiers as the documents you want to add, the existing documents will be removed. If the cmd field is set to update, existing documents in a specific data table are updated. If the cmd field is set to delete, existing documents in a specific data table are removed. The following table provides unique identifiers of user tables, item tables, and behavior tables. A unique identifier is a combination of fields.

Table

Unique identifier

User table

user_id and imei.

Item table

item_id and item_type.

Behavior table

N/A. In a behavior table, documents cannot be updated or removed.

The following table describes the requirements on the data integrity of documents you want to push based on the setting of the cmd field.

Setting of cmd field

Reserved field

Content field

add

All reserved fields

The combination of fields that form a unique identifier in a data table and the required fields specified in data specifications.

update

All reserved fields

The combination of fields that form a unique identifier in a data table and the required fields specified in data specifications.

delete

All reserved fields

The combination of fields that form a unique identifier in a data table.

Description of API operations

If you call an API operation, you must specify the instance ID, the data table name, and documents you want to push. Document data is displayed as a JSON array. Note: You can add or modify specific fields. For more information, see data specifications.

1. Add data.

//Push added item data.
[
    {
        "cmd": "add",
        "fields": {
            "item_id": "1",
            "item_type": "article",
            "title": "XXX",
            "content": "Content",
            "pub_time": "1590327038"
        }
    },
    {
        "cmd": "add",
        "fields": {
            "item_id": "2",
            "item_type": "article",
            "title": "XXX",
            "content": "Content",
            "pub_time": "1590327038"
        }
    }
]



//Push added behavior data.
[{
        "cmd": "add",
        "fields": {
            "item_id": "1024233",
            "item_type": "article",
            "bhv_type": "expose",
            "bhv_value": "1",
            "trace_id": "Alibaba",
            "trace_info": "1007.5911.12351.1002000:::::::",
            "scene_id": "testScene01,testScene02",
            "bhv_time": "1600852251",
            "user_id": "1"
        }
    },
    {
        "cmd": "add",
        "fields": {
            "item_id": "1024234",
            "item_type": "article",
            "bhv_type": "expose",
            "bhv_value": "1",
            "trace_id": "Alibaba",
            "trace_info": "1007.5911.12351.1002000:::::::",
            "scene_id": "testScene01,testScene02",
            "bhv_time": "1600852251",
            "user_id": "1"
        }
    }
]

2. Update data. You must specify an item table as well as the field and content you want to update. Example:

[
    {
        "cmd": "update",
        "fields": {
            "item_id": "2",
            "item_type": "article",
            "title": "Title of an updated item"
        }
    }
]

3. Remove data. You must specify an item table you want to remove. Example:

[
    {
        "cmd": "delete",
        "fields": {
            "item_id": "2",
            "item_type": "article"
        }
    }
]

Data requirements:

  1. If a request includes only one document, the document data must also be displayed as a JSON array.

  2. You can use the Pretty Print JSON format, or use a compact style without line breaks or indentations.

Limits

  1. A single request can include a maximum of 800 documents.

  2. The data size in a single request cannot exceed 1 MB.

  3. The size of a document cannot exceed 10 KB.

  4. The data size in a field cannot exceed 5 KB.

Parameters

Parameter
Type
Description
Required
Valid value
tableName
String
The table you want to push.
Yes
user
item
behavior
content
JSON
The document.
Yes
-
content-cmd
String
The operation command, which is required.
Yes
add
update
delete

Causes of common failures when you push data by using server SDKs

For more information, see question 17 in the data interaction topic of FAQ.

Sample code

package com.aliyun.airec;

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.airec.model.v20181012.PushDocumentRequest;
import com.aliyuncs.airec.model.v20181012.PushDocumentResponse;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;

public class PushDocument {
    private static final String accessKeyId = "Your AccessKey ID";
    private static final String accessKeySecret = "Your AccessKey secret";

    public static void main(String args[]) {
        //Note: The region in the following code must be the same as the region where the instance resides. For example, if the instance is deployed in the China (Beijing) region, enter cn-beijing in the following code.
        IClientProfile profile = DefaultProfile.getProfile("cn-hangzhou", accessKeyId, accessKeySecret);
        //Note: The region in the following code must be the same as the region where the instance resides. For example, if the instance is deployed in the China (Beijing) region, enter ("cn-beijing", "Airec", "airec.cn-beijing.aliyuncs.com") in the following code.
        DefaultProfile.addEndpoint("cn-hangzhou", "Airec", "airec.cn-hangzhou.aliyuncs.com");

        DefaultAcsClient client = new DefaultAcsClient(profile);

        PushDocumentRequest request = new PushDocumentRequest();
        request.setAcceptFormat(FormatType.JSON);

        // Enter the instance ID.
        request.setInstanceId("airec-xxxx");
        // Enter the data table name, which can be user, item, or behavior.
        request.setTableName("item");

        String content = "JSON data you want to upload to the AIRec instance";
        request.setHttpContent(content.getBytes(), "UTF-8", FormatType.JSON);

        try {
            PushDocumentResponse response = client.getAcsResponse(request);
            System.out.println(response.getResult());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}