All Products
Search
Document Center

Query the latest data points from time series in which the multi-value data model is used

Last Updated: Aug 25, 2021

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

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.

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.