All Products
Search
Document Center

Write multi-value data points

Last Updated: Aug 27, 2021

Multi-value data model for time series data

The multi-value data model is created based on data sources. Each data entry is created for a specific data source at a specific point in time and contains the values of multiple metric fields. For example, a data entry can contain the values of the following metric fields of a server: cpu, mem, and load. This allows you to manage these fields at the same time.

Use the multi-value data model to write data

Request path and method

Request path

Request method

Description

/api/mput

POST

Writes multiple data points at a time.

Note:

  • You must call different API operations to write single-value data points and multi-value data points. To write single-value data points, call the /api/put operation. To query multi-value data points, call the /api/mquery operation. To write single-value data points, call the /api/query operation.

Request parameters

Parameter

Type

Required

Description

Default value

Example

summary

Untyped

No

Specifies whether to return the summary.

false

/api/mput?summary

details

Untyped

No

Specifies whether to return the details.

false

/api/mput?details

sync_timeout

Integer

No

The timeout period. Unit: milliseconds. The value 0 specifies that the request never times out.

0

/api/mput/?sync&sync_timeout=60000

ignoreErrors

Untyped

No

Specifies whether to ignore write errors and continue writing other data points.

false

/api/mput/?ignoreErrors

Note:

  • The system determines that the value of an untyped parameter is true if the parameter is specified. 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

N/A

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

fields

Map

Yes

The limits on field names are the same as those on metric names. The data type of a field value must be STRING, NUMBER, or BOOLEAN.

The values of the fields.

"fields" : {"speed" : 20.8, "level" : 4, "direction" : "East", "description" : "Fresh breeze"}

tags

Map

Yes

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, /api/mput, /api/query, and /api/mquery. /api/put and /api/mput are used to write data. /api/query and /api/mquery are 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 multi-value 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.

    Sample requests

    Request line:POST/api/mput Request body:

    [
    {
    "metric":"wind",
    "fields":{
    "speed":20.8,
    "level":4,
    "direction":"East",
    "description":"Fresh breeze"
    },
    "tags":{
    "sensor":"IOTE_8859_0001",
    "city":"hangzhou",
    "province":"zhejiang",
    "country":"china"
    },
    "timestamp":1346846400
    },
    {
    "metric":"wind",
    "fields":{
    "speed":40.2,
    "level":6,
    "direction":"South",
    "description":"Fresh breeze"
    },
    "tags":{
    "sensor":"IOTE_8859_0002",
    "city":"hangzhou",
    "province":"zhejiang",
    "country":"china"
    },
    "timestamp":1346846401
    }
    ]

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/mput 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/mput 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.

    failed

    Integer

    The number of data points that failed to be written.

    Example:

    {
        "failed":0,
        "success": 20
    }

    Notice

    1. In statistical mode, the data points in an api/mput 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.

    2. When you write multi-value data points, the value of the success parameter or the failed parameter is calculated based on the single-value data model. This indicates that a single multi-value data point is counted more than one time. The number of times that a multi-value data point is counted is equal to the number of the fields of the multi-value data point.

    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/mput 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.

    Notice

    In detailed mode, the data points in an api/mput request are all written as expected 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/mput 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.

    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 as well as the fault rectification and rewrites of the data points that failed to be written.