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
Notice
  • 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 configure the details and summary parameters, the API operation returns only the details.

Parameters in a data point

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

Parameter Type Required Limit Description Example
metric String Yes The value can contain only letters, digits, and the following special characters: hyphens (-), underscores (_), periods (.), forward slashes (/), parentheses (), colons (:), commas (,), brackets [], equal signs (=), apostrophes ('), and number signs (#). The name of the metric to be stored. sys.cpu
timestamp Long Yes None The timestamp. Unit: seconds or milliseconds. For more information about how Lindorm TSDB determines the unit of a timestamp, see the "The timestamp parameter" section of this topic. 1499158925
value Long,Double,String,Boolean Yes None The value in the data point. 42.5, true
tags Map No A value can contain letters, digits, and the following special characters: hyphens (-), underscores (_), periods (.), forward slashes (/), parentheses (), colons (:), commas (,), brackets [], equal signs (=), apostrophes ('), and number signs (#). Key-value pairs. Tag keys and tag values are strings. You must specify at least one key-value pair. For example, specify the key-value pair {"host":"web01"}. Tag keys and tag values that are not of the STRING type are automatically converted to the STRING type.
The timestamp parameter
This section describes how Lindorm TSDB determines the unit of a timestamp. The descriptions apply to the following API operations: /api/put and /api/query. The /api/put operation is used to write data. The /api/query operation is used to query data. Timestamps can be measured in seconds or milliseconds. Lindorm TSDB determines the unit of a timestamp based on the numeric value of the timestamp. The following content describes the rule:
  • If the value falls within the range [4294768,9999999999], the unit is seconds. The time range is [1970-02-20 00:59:28, 2286-11-21 01:46:39].
  • If the value falls within the range [10000000000,9999999999999], the unit is milliseconds. The time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].
  • If the value falls within the range (-∞,4294768) or (9999999999999,+∞), the timestamp is invalid.
The value parameter

The values in two data points can be of different data types only if the metric parameter has different values in the data points. For example, the following two data writing requests are allowed: The metric parameter has different values in the two requests. Therefore, you can write values of different data types.

1.  [{"metric":"fakemetric1", "tags":{"tagk":"tagv1"},"timestamp":1514736000, "value":"val"}, {"metric":"fakemetric1", "tags":{"tagk":"tagv1"},"timestamp":1514736030, "value":"val2"}]
2.  [{"metric":"fakemetric2", "tags":{"tagk":"tagv2"},"timestamp":1514736000, "value":12.34}, {"metric":"fakemetric2", "tags":{"tagk":"tagv2"},"timestamp":1514736030, "value":34.56}]

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

The tag parameter

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 Lindorm TSDB instance, as listed in the following table.

Instance type 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 body:
1. [
2.    {
3.        "metric": "sys.cpu.nice",
4.        "timestamp": 1346846400,
5.        "value": 18,
6.        "tags": {
7.           "host": "web01",
8.           "dc": "lga"
9.        }
10.    },
11.    {
12.        "metric": "sys.cpu.nice",
13.        "timestamp": 1346846400,
14.        "value": 9,
15.        "tags": {
16.           "host": "web02",
17.           "dc": "lga"
18.        }
19.    },
20.    {
21.        "metric": "sys.cpu.alter",
22.        "timestamp": 1346846400,
23.        "value": "High CPU Load",
24.        "tags": {
25.           "host": "web03",
26.           "dc": "lga"
27.        }
28.    },
29.    {
30.        "metric": "sys.cpu.nice",
31.        "timestamp": 1346846400,
32.        "value": true,
33.        "tags": {
34.           "host": "web04",
35.           "dc": "lga"
36.        }
37.    }
38. ]

Responses

If all data points are written, the status code 204 is returned. If some data points fail to be written, the status code 400 is returned and the response contains the error details. If you specify the summary or details parameter in the request, the response includes the following attributes:
Name Data type Description
success Integer The number of data points that were written.
failed Integer The number of data points that failed to be written.
Array An array that lists the data points that failed to be written and the causes of the failures. This parameter is valid only if the details parameter is specified.
Sample responses

Sample response returned if the summary parameter is specified

Request line: POST /api/put?summary

Request body:

1. [
2.    {
3.        "metric": "sys.cpu.nice",
4.        "timestamp": 1346846400,
5.        "value": 9,
6.        "tags": {
7.           "host": "web02",
8.           "dc": "lga"
9.        }
10.  }
11. ]
Response:
1.   {
2.        "failed": 1,
3.        "success": 0
4.    }

The response indicates that no data points were written and one data point failed to be written.

Sample response returned if the details parameter is specified:

Request line: POST /api/put?details

Request body:

1.    [
2.        {
3.                      "metric": "sys.cpu.nice",
4.                      "timestamp": 1365465600,
5.                      "value": "NaN",
6.                      "tags": {
7.                          "host": "web01"
8.                      }
9.        }
10.    ]
Response:
1.    {
2.        "errors": [
3.            {
4.                "datapoint": {
5.                    "metric": "sys.cpu.nice",
6.                    "timestamp": 1365465600,
7.                    "value": "NaN",
8.                    "tags": {
9.                        "host": "web01"
10.                    }
11.                },
12.                "error": "Unable to parse value to a number"
13.            }
14.        ],
15.        "failed": 1,
16.        "success": 0
17.    }

The response indicates that no data points were written and one data point failed to be written. The datapoint parameter indicates the data points that failed to be written. The error parameter indicates the cause of the failure.