All Products
Search
Document Center

Write multi-value data

Last Updated: Jun 18, 2020

Multi-value data model for time series data

The multi-value data model is created based on data sources. Each row of data in a multi-value data model is specific to a data source, and the metrics of each data source are listed in one column. Therefore, a row of data is available for each data source at each time point. For example, a server has the following metrics: cpu, mem, and load. You can perform operations on these metrics at a time based on your business needs.

Write multi-value data

Request path and method

Request path Request method Description
/api/mput POST Writes multiple data points at a time.

Note:

  • You must use different API endpoints to write single-value data and multi-value data. To write single-value data, you must use the /api/put API endpoint. To query the multi-value data that has been written, you must use the /api/mquery API endpoint. To query the single-value data that has been written, you must use the /api/query API endpoint.

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 time-out period. Unit: milliseconds. The value 0 indicates the request never times out. 0 /api/put/? sync&sync_timeout=60000

Note:

  • The value of an untyped parameter is considered as true if the parameter is specified. For example, you can set the summary parameter to true or false. In both scenarios, the value of the summary parameter is considered as true.
  • If you specify both the details and summary parameters, the API operation returns the details.

Request parameters

Data points are JSON formatted data. The following table describes the parameters.

Parameter Type Required Limit Description Example
metric String Yes The metric name can contain only letters, digits, and the following special characters: -_. /():,[]=# The metric name that is stored. sys.cpu
timestamp Long Yes N/A The timestamp. Unit: second or millisecond. For more information about the rules for determining the unit, see the “Timestamp” section. 1499158925
fields Map Yes The limits for field names are the same as those for metric names. The data type of the parameter values must be string, number, or boolean. The values of fields. “fields” : {“speed” : 20.8, “level” : 4, “direction” : “East”, “description” : “Fresh breeze”}
tags Map Yes The value can contain letters, digits, and the following special characters: -_. /():,[]=# The tag keys and tag values that are of the string type. Tag keys and tag values consist of key-value pairs. At least one key-value pair must be available. An example value is {“host”:”web01”}. Tag keys and tag values that are not of the string type are explicitly converted to those of the string type.

Timestamp

This section describes the rules of determining the timestamp unit. These rules apply to the following API endpoints: /api/put and /api/mput, /api/query and /api/mquery. The first two endpoints are used to write data, and the other two endpoints are used to read data. The timestamp unit is second or millisecond. Time Series Database (TSDB) determines the unit based on the numeric value and the following rules:

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

Data points

  • For each metric, you can write data of only one data type for a field.
  • The data values of the string type can be any characters and can be stored as JSON strings. The maximum size is 20 KB.

Example of writing data

This topic provides a sample request: POST/api/mput.The request body is described as follows:

  1. [
  2. {
  3. "metric" : "wind",
  4. "fields" : {
  5. "speed" : 20.8,
  6. "level" : 4,
  7. "direction" : "East",
  8. "description" : "Fresh breeze"
  9. },
  10. "tags" : {
  11. "sensor":"IOTE_8859_0001",
  12. "city":"hangzhou",
  13. "province":"zhejiang",
  14. "country":"china"
  15. },
  16. "timestamp" : 1346846400
  17. },
  18. {
  19. "metric" : "wind",
  20. "fields" : {
  21. "speed" : 40.2,
  22. "level" : 6,
  23. "direction" : "South",
  24. "description" : "Fresh breeze"
  25. },
  26. "tags" : {
  27. "sensor":"IOTE_8859_0002",
  28. "city":"hangzhou",
  29. "province":"zhejiang",
  30. "country":"china"
  31. },
  32. "timestamp" : 1346846401
  33. }
  34. ]

Response description

If all data points are written as expected, the return code is 204. If some data points fail to be written, the return code is 400, and the response contains the error details. If you specify the summary or details parameter in the request, the response contains the following attributes:Name|Data type|Description-|-|-success|Integer|The number of data points that were written as expectedfailed|Integer|The number of data points that failed to be writtenerrors|Array|An array that describes the data points that failed to be written, and the causes of failures. This parameter is valid only when the details parameter is specified.

Sample responses

Sample response if the summary parameter is specified

This topic provides a sample response of the request: POST/api/mput? summary.The request body is described as follows:

```json Invalid Timestamp[ { “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 } ]

  1. **The response is described as follows:**
  2. ```json
  3. {
  4. "failed": 1,
  5. "success": 0
  6. }

This response indicates that no data points were written as expected, and one data point failed to be written.

Sample response example if the details parameter is specified

This topic provides a sample response of the request: POST/api/mput? details.The request body is described as follows:

  1. [
  2. {
  3. "metric" : "wind",
  4. "fields" : {
  5. "speed" : 50.2_string,
  6. "level" : 7,
  7. "direction" : "North",
  8. "description" : "Fresh breeze"
  9. },
  10. "tags" : {
  11. "sensor":"IOTE_8859_0003",
  12. "city":"hangzhou",
  13. "province":"zhejiang",
  14. "country":"china"
  15. },
  16. "timestamp" : 400
  17. }
  18. ]

The response is described as follows:

  1. {
  2. "errors": [
  3. {
  4. "datapoint": {
  5. "metric" : "wind",
  6. "fields" : {
  7. "speed" : 50.2,
  8. "level" : 7,
  9. "direction" : "North",
  10. "description" : "Fresh breeze"
  11. },
  12. "tags" : {
  13. "sensor":"IOTE_8859_0003",
  14. "city":"hangzhou",
  15. "province":"zhejiang",
  16. "country":"china"
  17. },
  18. "timestamp" : 400
  19. },
  20. "error": "Invalid timestamp"
  21. }
  22. ],
  23. "failed": 1,
  24. "success": 0
  25. }

This response indicates that no data points were written as expected, 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 causes of failures.