Multi-value data models for time series data

A multi-value data model is created based on data sources. Each data entry is created for a specific data source at a specific time and contains the values of multiple fields. For example, a data entry can contain the values of the following fields of a server: CPU, memory, and load. This allows you to manage multiple fields at a time. Data modeling

Use a multi-value model to write data

Request path and method
Request method Description
POST Writes multiple data points at a time.
Notice You must use different API operations to write single-value data points and multi-value data points. To write a single-value data point, call the /api/put operation. To query multi-value data points, call the /api/mquery operation. To query 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/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
Notice The metric name must be 1 to 255 bytes in length.
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
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 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, /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. 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 [4284768,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 (-∞,4284768) or (9999999999999,+∞), the timestamp is invalid.

Field values

You can write two data points that contain values of different data types only if the data points contain different metrics or different fields. For example, the following two data writing requests are allowed: The metric parameter has the same value in the two data points in each request. Both data points in each request contain the same tag. However, the data points in each request contain different fields. Therefore, you can write field values of different data types in these data points.

[{"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736000, "values":{"field1":"val", "field2": 111.11}, {"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736030, "values":{"field1":"val2", "field2": 222.22}}]
[{"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736000, "values":{"field1":"aaa", "field2": 333.33}}, {"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736030, "values":{"field1":"bbb", "field2": 444.44}}}]
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
        }
    ]

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.
errors 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/mput?Request body:

    [
        {
            "metric" : "wind",
            "fields" : {
                "speed" : 50.2,
                "level" : 7,
                "direction" : "North",
                "description" : "Fresh breeze"
            },
            "tags" : {
                "sensor":"IOTE_8859_0003",
                "city":"hangzhou",
                "province":"zhejiang",
                "country":"china"
            },
            "timestamp" : 401
        }
    ]

Response:

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

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/mput?Request body:

    [
        {
            "metric" : "wind",
            "fields" : {
                "speed" : 50.2_string,
                "level" : 7,
                "direction" : "North",
                "description" : "Fresh breeze"
            },
            "tags" : {
                "sensor":"IOTE_8859_0003",
                "city":"hangzhou",
                "province":"zhejiang",
                "country":"china"
            },
            "timestamp" : 400
        }
    ]
                

Response:

        {
            "errors": [
                {
                    "datapoint": {
                        "metric" : "wind",
                        "fields" : {
                            "speed" : 50.2,
                            "level" : 7,
                            "direction" : "North",
                            "description" : "Fresh breeze"
                        },
                        "tags" : {
                            "sensor":"IOTE_8859_0003",
                            "city":"hangzhou",
                            "province":"zhejiang",
                            "country":"china"
                        },
                        "timestamp" : 400
                    },
                    "error": "Invalid timestamp"
                }
            ],
            "failed": 1,
            "success": 0
        }
                

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.