Retrieve Real-Time Data Points via TSDB Multi-Value API - Time Series Database

Queries the latest data points from a multi-value model time series. Each returned data point contains the latest values of the specified fields for the specified metric.

Important

/api/query/mlast only works with time series that use the multi-value data model. To query the latest data point from a single-value model time series, use /api/query/last.

Request syntax

Request path	Method
`/api/query/mlast`	`POST`

Request parameters

Parameter	Type	Required	Default	Description
`queries`	Array	Yes	—	The subquery array. See Subquery parameters.
`timestamp`	Long	No	—	A UNIX timestamp in seconds or milliseconds. Returns the latest data points at or before this timestamp. If omitted, returns the latest data points at or before the current time.
`tupleFormat`	Boolean	No	`false`	Specifies whether to return the tuple structure of the latest data point.
`tupleOffset`	Long	No	`0`	The offset for tuple pagination. Takes effect only when `tupleFormat` is `true`.
`tupleLimit`	Long	No	`0`	The maximum number of tuples to return. Takes effect only when `tupleFormat` is `true`.
`hint`	Map	No	—	The query hint for index optimization. See Query hint.
`limit`	Map	No	—	Limits the number of latest data points to return. By default, only the single latest data point per time series is returned. See Query limit.

Subquery parameters

Each object in the queries array supports the following parameters:

Parameter	Type	Required	Default	Description
`metric`	String	Yes	—	The metric to query.
`fields`	List	Yes	—	The metric fields to return. Set to `*` to return all fields in the metric.
`tags`	Map	No	—	The tag key-value pairs to filter the time series.
`hint`	Map	No	—	A query hint scoped to this subquery. See Query hint.

Examples

Request

Query the latest data points for the usage_system and usage_idle fields in the cpu metric, filtered by host_name: host1. Return up to 100 tuples starting from offset 5, for timestamps at or before 1551851846.

POST /api/query/mlast

{
    "tupleFormat": true,
    "tupleOffset": 5,
    "tupleLimit": 100,
    "timestamp": 1551851846,
    "queries": [
        {
            "metric": "cpu",
            "fields": ["usage_system", "usage_idle"],
            "tags": {
                "host_name": "host1"
            }
        }
    ]
}

Response

A successful request returns HTTP 200. The response body is a JSON array where each object represents a matching time series. If no time series matches the query conditions, an empty array is returned.

Field	Description
`metric`	The name of the metric.
`columns`	The column names in the result set, starting with `timestamp` followed by the queried field names.
`tags`	The tag key-value pairs associated with the time series.
`values`	The field values for each data point, in the same order as `columns`.

If tupleFormat is false, the response format is the same as the /api/query/last response. For details, see the /api/query/last documentation.

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "level",
      "speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0001"
    },
    "values": [
      [1346846405000, 5.1, 45.1]
    ]
  }
]

Query hint

Use a query hint to reduce query response time. A hint is useful when the time series matched by one tag set is a known subset of the time series matched by another tag set—the API can skip reading data from the larger set and go directly to the smaller one.

Supported parameters

Currently, only the tagk parameter is supported in a hint.

In the tagk map, each key is a tag key and each value controls whether its index is used:

1 — use the index for this tag key
0 — do not use the index for this tag key

All values in a single tagk map must be either 0 or 1. Mixing 0 and 1 in the same hint returns an error.

Version requirement: TSDB V2.6.1 or later.

Hint scoped to a subquery

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"],
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

Hint scoped to the entire query

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"]
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1
    }
  }
}

Error responses

Mixed `0` and `1` values

{
  "hint": {
    "tagk": {
      "dc": 1,
      "host": 0
    }
  }
}

Returns:

{
    "error": {
        "code": 400,
        "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1"
    }
}

Value other than `0` or `1`

{
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

Returns:

{
    "error": {
        "code": 400,
        "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in"
    }
}

Query limit

By default, the API returns only the single latest data point per time series. Use the limit parameter to retrieve multiple recent data points within a time range.

Parameter	Type	Required	Description
`size`	Integer	Yes	The maximum number of latest data points to return per time series.
`from`	Long	Yes	The start of the time range (UNIX timestamp).

Example

Query the latest 300 data points for timestamps between 1551850000 and 1551851846:

{
  "tupleFormat": true,
  "limit": {
    "size": 300,
    "from": 1551850000
  },
  "timestamp": 1551851846,
  "queries": [
    {
      "metric": "cpu",
      "fields": ["usage_system", "usage_idle"],
      "tags": {
        "host_name": "host1"
      }
    }
  ]
}

What's next

To query the latest data point from a single-value model time series, see the /api/query/last documentation.
For details on the limit parameter behavior, see the "Query limit description" section in the single-value model query topic.