Query the latest data points from time series in which the multi-value data model is used
Request path and method
Request path | Request method | Description |
---|---|---|
/api/query/mlast | POST | 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. |
Request parameters
Parameter | Type | Required | Description | Default value | Example |
---|---|---|---|---|---|
queries | Array | Yes | The subquery array. | N/A | For more information, see the "Parameters for subqueries in the JSON format" section. |
timestamp | Long | No | The UNIX timestamp. Unit: seconds or milliseconds. If you specify a timestamp, the API operation returns the latest data points associated with the specified timestamp and earlier timestamps. If you leave this parameter empty, the API operation returns the latest data points associated with the current timestamp and earlier timestamps. This parameter is at the same level as the queries parameter in the request. For more information, see the following sample request. | N/A | 1539763573 |
tupleFormat | Boolean | No | Specifies whether to return the tuple structure of the latest data point of the queried fields. For more information, see the following sample request and response. | false | false |
tupleOffset | Long | No | The offset of the tuples. This parameter only takes effect when the tupleFormat parameter is set to true. | 0 | 5 |
tupleLimit | Long | No | The maximum number of tuples. This parameter only takes effect when the tupleFormat parameter is set to true. | 0 | 100 |
hint | Map | No | The query hint. | N/A | For more information, see the "Query hint description" section. |
limit | Map | No | The limit on the latest data points that you want to query. | N/A | For more information, see the "Query limit description" section. |
You can use /api/query/mlast to query only the latest data points from a time series in which the multi-value data model is used. If you want to query the latest data point from a time series in which the single-value data model is used, use /api/query/last.
Parameters for subqueries in the JSON format
Parameter | Type | Required | Description | Default value | Example |
---|---|---|---|---|---|
metric | String | Yes | The metric associated with the latest data points that you want to query. | N/A | wind |
fields | List | Yes | The metric fields that you want to query. If you set this parameter to an asterisk (*), the values of all the fields in the specified metric are returned. | N/A | {speed, level, description} |
tags | String | No | The tags associated with the latest data points that you want to query. | N/A | sensor = IOTE_1988_0001 |
hint | Map | No | The query hint. | None | For more information, see the "Query hint description" section.
Sample requests in the JSON format
Objective: Query the latest data points that were written for the usage_system and usage_idle fields in a time series. These two fields are used to describe the cpu metric and the associated tag key-value pair is "host_name": "host1". Request line: POST/api/query/mlast
Request body:
{
"tupleFormat": true,
"tupleOffset":5,
"tupleLimit":100,
"timestamp" : 1551851846,
"queries": [
{
"metric": "cpu",
"fields": ["usage_system", "usage_idle"],
"tags": {
"host_name": "host1"
}
}
]
}
Response description
If the HTTP status code 200 is returned, the query is successful. In this case, the latest data points in the time series that meets the specified query conditions is returned in the JSON format. If no time series meets the query conditions, an empty set is returned. The following table describes the response parameters.
Parameter | Description |
---|---|
metric | The name of the metric. |
columns | The names of the columns in the returned result set. The value of this parameter contains the timestamp field name and the names of the metric fields that you want to query. |
tags | The set of tag key-value pairs associated with the data points. |
values | The values of the metric fields. The order of the values is the same as the order of the columns. |
If you set the tupleFormat parameter to false in the request, the format of the response is the same as the response format for the single-value data model. For more information, see the introduction of /api/query/last in the "Query the latest data point of a time series" topic.
Sample responses in the JSON format
[
{
"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 description
Scenarios
In most cases, a query hint is used to reduce the response time of queries. For example, Tags A and Tags B are specified and the time series hit by Tags B are obviously included by the time series hit by Tags A. In this case, data is not read from the time series hit by Tag A. The intersection between the set of time series hit by Tag A and the set of time series hit by Tag B is equal to the set of time series hit by Tag B.
Format description
The current TSDB version allows you to use only the tagk parameter in a hint to limit query indexes.
In the tag key-value pairs specified by the tagk parameter, the tag values of the tag keys must be the same. Valid values: 0 and 1. If the tag values are
0
, the indexes corresponding to the tag keys are not used. If the tag values are1
, the indexes corresponding to the tag keys are used.
Version description
The query hint feature is supported by TSDB V2.6.1 and later.
Sample requests
Hint that applies 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 that applies 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
}
}
}
Exceptions
An error is returned when the tag values in the key-value pairs specified by the tagk parameter contain both 0 and 1.
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1,
"host": 0
}
}
}
The following error message is returned:
{
"error": {
"code": 400,
"message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
An error is returned when a tag value in the key-value pairs specified by the tagk parameter is not 0 or 1.
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 100
}
}
}
The following error message is returned:
{
"error": {
"code": 400,
"message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
Query limit description
Limit: allows you to configure a limit on the latest data points to query. If you do not specify a limit, the query result contains only the latest data point in each time series.
Parameters for requests in the JSON format
Parameter | Type | Required | Description | Default value | Example |
---|---|---|---|---|---|
size | Integer | Yes | The maximum number of the latest data points of a time series. | N/A | 5 |
from | Long | Yes | The beginning of the time range where data is queried. | N/A | 1346846400 |
Examples
Query the latest 300 data points associated with the timestamps that range from 1551850000 to 1551851846.
{
"tupleFormat":true,
"limit":{
"size":300,
"from":1551850000
},
"timestamp":1551851846,
"queries":[
{
"metric":"cpu",
"fields":["usage_system","usage_idle"],
"tags":{
"host_name":"host1"
}
}
]
}
For more information, see the "Query limit description" section in the "Query the latest data points in a time series that use single-value model" topic.