All Products
Search

This Product

    Write data

    Document Center

    Write data

    Last Updated: Jul 23, 2018

    Request path and method

    Path Method Description
    /api/put POST Writes multiple data points at a time

    Request parameters

    Name Type Required Description Default value Example
    summary Untyped No Whether to return the summary false /api/put?summary
    details Untyped No Whether to return the details false /api/put?details
    sync_timeout Integer No Timeout, in millisecond (ms). “0” indicates the request never times out. 0 /api/put/?sync&sync_timeout=60000

    Note:

    • The value of the untyped parameters is deemed to be “true” as long as they are provided, for example, both “summary=false” and “summary=true” are treated as “summary=true”.
    • If “details” and “summary” are set at the same time, the API returns the “details”.

    Request content

    The data point is in JSON format. The following table describe the attributes:

    Name Type Required Restrictions Description Example
    metric String Yes Can only contain English letters (case in-sensitive), Chinese characters, numbers, and special characteristics, such as -_./():,[]=‘# Stored metric name sys.cpu
    timestamp Long Yes None Timestamp in seconds or milliseconds. For details about how to judge the unit, see Timestamp description below. 1499158925
    value Long, Double, String, Boolean Yes None Value of the data point 42.5, true
    tags Map Yes Can contain English letters (case in-sensitive), Chinese characters, numbers, and special characteristics, such as -_./():,[]=‘# The tag key-value pair. At least one tag key-value pair is required. {“host”:”web01”}

    Timestamp Description

    This description is only applicable to the data read/write (/api/put) and data query (api/query) APIs.

    The timestamp unit is second or millisecond.TSDB judges the time unit by the numeric value according to the following rules:

    • When the timestamp range is [4284768,9999999999]: the unit is second, and the time range is [1970-02-20 00:59:28, 2286-11-21 01:46:39].
    • When the timestamp range is [10000000000,9999999999999]: the unit is millisecond, and the time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].
    • When the timestamp range is (-∞,4284768) or (9999999999999,+∞): the time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].

    Example of data writing request

    Request: POST/api/put

    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. ]

    Response Description

    If the data writing request succeeds at all data points, the error code 204 is returned. If the data writing request fails at some data points, the error code 400 is returned and the response content contains the error details.

    If the request parameter contains summary or details, the returned information contains the following attributes:

    Name Data type Description
    success Integer Number of data points to which the data is successfully written
    failed Integer Number of data points to which the data fails to be written
    errors Array An array which indicates to which data points the data fails to be written and the cause. It is valid only when the parameter “details” is specified.

    Response example

    Response example when “summary” is specified:

    Request: POST/api/put?summary

    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 content:

    1.     {
    2.         "failed": 1,
    3.         "success": 0
    4.     }

    It indicates that no time point succeeded in data writing, and one time point failed in data writing.

    Response example when “details” is specified:

    Request: POST/api/put?details

    Body:

    1.     [
    2.         {
    3.                       "metric": "sys.cpu.nice",
    4.                       "timestamp": 1365465600,
    5.                       "value": "NaN",
    6.                       "tags": {
    7.                           "host": "web01"
    8.                       }
    9.         }
    10.     ]

    Response content:

    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.     }

    It indicates that no time point succeeded in data writing, and one time point failed in data writing. The failed data point is specified by “datapoint”. The cause for the writing failure is specified by the “error” field.

    Free Trial Free Trial