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.

Notice

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

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.

Notice

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 are 1, 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.