Write data - Time Series Database - Alibaba Cloud Documentation Center

Request path and method

Request path	Request method	Description
/api/put	POST	Writes multiple data points at a time.

Request parameters

Parameter	Type	Required	Description	Default value	Example
summary	Untyped	No	Specifies whether to return the summary.	false	/api/put?summary
details	Untyped	No	Specifies whether to return the details.	false	/api/put?details
sync_timeout	Integer	No	The timeout period. Unit: milliseconds. The value 0 indicates that the request never times out.	0	/api/put/?sync&sync_timeout=60000
ignoreErrors	Untyped	No	Specifies whether to ignore the write exceptions of some data points.	false	/api/put/?ignoreErrors

Note:

The system determines that the value of an untyped parameter is true if the parameter is configured. For example, the system determines that the value of the summary parameter is true regardless of whether you set the parameter to true or false.
If you specify both the details parameter and the summary parameter, the API operation returns the details.

Request parameters

Specify a data point in the JSON format. The following table describes the parameters for a data point.

Parameter	Type	Required	Limit	Description	Example
metric	String	Yes	The value can contain only letters, digits, and the following special characters: `-_./():,[]='#`	The name of the metric to be stored.	sys.cpu Note In the High-availability Edition, the metric name can be up to 255 bytes in length.
timestamp	Long	Yes	None	The timestamp measured in seconds or milliseconds. For more information about the rules for determining the unit, see the Timestamp units section in this topic.	1499158925
value	Long,Double,String,Boolean	Yes	None	The value in the data point.	42.5, true
tags	Map	No	The value can contain only letters, digits, and the following special characters: `-_./():,[]='#`	The tag key-value pairs. Tag keys and tag values are character strings. Specify at least one tag key-value pair.	{"host":"web01"}. Tag keys and tag values that are not of the STRING data type are explicitly converted to the STRING type.

Timestamp units

This section describes the rules for determining the unit of a timestamp. These rules apply to the following API operations: /api/put and api/query. /api/put and is used to write data. /api/query is used to query data.

Timestamps can be measured in seconds or milliseconds. Time Series Database (TSDB) uses the following rules to determine the unit of a timestamp based on the numeric value:

If the value falls within the range of [4294968,4294967295], the unit is seconds. In this case, the date and time range is [1970-02-20 01:02:48, 2106-02-07 14:28:15].
If the value falls within the range of [4294967296,9999999999999], the unit is milliseconds. In this case, the date and time range is [1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999].
If the value falls within the range of (-∞,4294968) or (9999999999999,+∞), the timestamp is invalid.

Description of values in data points

Values of the STRING data type can contain all characters and can be stored in the JSON format. The size of a string value cannot exceed 20 KB.

Tag description

When you write data in a time series, you can specify only a limited number of tag keys. The maximum number of tag keys varies based on the instance type of the TSDB instance, as listed in the following table.

The type of the instance.	Maximum number of tag keys in a single time series
mLarge	16
Large	16
3xLarge	20
4xLarge	20
6xLarge	20
12xLarge	20
24xLarge	24
48xLarge	24
96xLarge	24

Sample requests

Request line: POST /api/put

Request line:

[
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":18,
"tags":{
"host":"web01",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":9,
"tags":{
"host":"web02",
"dc":"lga"
}
},
{
"metric":"sys.cpu.alter",
"timestamp":1346846400,
"value":"High CPU Load",
"tags":{
"host":"web03",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":true,
"tags":{
"host":"web04",
"dc":"lga"
}
}
]

Write modes and responses

TSDB supports four write modes. To use each of the modes, configure the request parameters based on the following instructions:

Simple mode
To use this mode, do not configure the parameters when you call the api/put operation. If data is written to TSDB as expected, the status code 204 is returned. If data fails to be written, only the corresponding error code and error message are returned.
This mode is suitable for reporting monitoring data of general business.
Statistical mode
To use this mode, configure the summary parameter when you call the api/put operation. The success and failed parameters are returned, regardless of whether data is written to TSDB as expected. This helps you collect statistics of your business. The success parameter indicates the number of data points that were written. The failed parameter indicates the number of data points that failed to be written.
Parameter
Type
Description
success
Integer
The number of data points that were written as expected.
failed
Integer
The number of data points that failed to be written.
Example:
```
{
    "failed":0,
    "success": 20
}
```
Notice
In statistical mode, the data points in an api/put request are all written as expected or all fail to be written. If a data write fails, the failed parameter indicates the number of data points specified in your request.
The statistical mode is suitable for reporting monitoring data of general business that requires statistics on the reported data.

Detailed mode

The detailed mode is an extension of the statistical mode. To use this mode, configure the details parameter when you call the api/put operation. The success, failed, and errors parameters are returned regardless of whether data is written to TSDB as expected. The success parameter indicates the number of data points that were written. The failed parameter indicates the number of data points that failed to be written. The errors parameter indicates the direct cause of the write failure.

Parameter	Type	Description
success	Integer	The number of data points that were written as expected.
failed	Integer	The number of data points that failed to be written.
errors	Array	The direct cause of the failure of the first data point that failed to be written. The value is an array that consists of the information about the data point and the failure cause.

Example:

{
    "errors":[{
            "datapoint":{
                "metric":"sys.cpu.nice",
                "timestamp":1365465600,
                "value":"NaN",
                "tags":{
                    "host":"web01"
                }
            },
            "error":"Unable to parse value to a number"
        }],
    "failed":1,
    "success":0
}

Notice

In detailed mode, the data points in one request that calls the api/put operation are all written or all fail to be written. The value of errors contains only the information about the first data point that failed to be written and the direct cause of the failure. To view the number of data points that failed to be written, view the value of the failed parameter.

This mode is suitable for reporting monitoring data of business that requires statistics on the reported data and fault location.

Fault-tolerant mode

To use this mode, configure the ignoreErrors parameter when you call the api/put operation. When you send a request to write a batch of data points to TSDB in fault-tolerant mode, the write failure of one data point has no impact on the writes of the other data points. This mode ensures that most data points can be written to TSDB when valid and invalid data points exist in the same batch. The data points that failed to be written are enumerated in the response. The response contains the same parameters as those returned when you configure the details parameter in your request. However, the errors parameter contains the name of each data point that failed to be written and the failure cause. The data points that are not included in the value of the errors parameter were written to TSDB as expected.

Parameter	Type	Description
success	Integer	The number of data points that were written as expected.
failed	Integer	The number of data points that failed to be written.
errors	Array	An array of each data point that failed to be written and the corresponding failure cause.

Example:

Notice

In fault-tolerant mode, if not all data points in a batch failed to be written, the status code 200 is returned. If all data points in a batch failed to be written due to a critical error such as a failure of underlying storage, a status code other than 200 is returned. In fault-tolerant mode, the failed parameter indicates the number of data points failed to be written.

This mode is suitable for reporting monitoring data of business that requires the integrity of the reported data and the fault rectification and rewrites of failed data points.