All Products
Search
Document Center

Write data

Last Updated: Aug 25, 2021

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.