All Products
Search
Document Center

Query the latest data point of a time series

Last Updated: Aug 25, 2021

Request path and method

Request path

Request method

Description

/api/query/last

POST

Queries the latest data point in a time series.

Notice

This operation is fully compatible with OpenTSDB.

Request parameters

Parameters for requests in the JSON format

Parameter

Type

Required

Description

Default value

Example

queries

Array

Yes

The array of subqueries.

None

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, you can query the latest data point at the specified timestamp. If you leave this parameter empty, you can query the latest data point at the current timestamp.

None

1539763573

hint

Map

No

The query hint.

None

For more information, see the "Parameter: hint" section.

limit

Map

No

The limits on the latest data points that you want to query.

None

For more information, see the "Parameter: limit" section.

Parameters for subqueries in the JSON format

You can perform a subquery based on a metric or a TSUID. If you query data based on a metric, use the metric and tags parameters to specify query criteria. If you query data based on a TSUID, use the tsuid parameter to specify query criteria. The tsuid parameter specifies the unique ID of a time series. You can include metric queries and TSUID queries in a list of subqueries.

Metric query

Parameter

Type

Required

Description

Default value

Example

metric

String

Yes

The metric of the latest data point that you want to query.

None

cpu.usage

tags

String

No

The tags of the latest data point that you want to query.

None

host_name=host1

hint

Map

Map

The query hint.

None

For more information, see the "Parameter: hint" section.

Notice

You can use only the tags parameter to specify query criteria. The filters parameter is not supported.

TSUID query

Parameter

Type

Required

Description

Default value

Example

tsuid

String

Yes

The TSUID of the time series in which you want to query the latest data point.

None

00005B00005C0000F000005D0000EE00005E0000EF

Notice

  1. You can perform the /api/search/lookup operation to query the TSUID of the time series.

  2. For TSDB High-availability Edition, you can specify the tsuid parameter in a request. However, the configuration of this parameter does not take effect. When you use /api/search/lookup in the high-availability edition, TSDB does not return the TSUID of a time series.

Sample requests in the JSON format

Objective:

Query the latest data point in each time series. In the first subquery, the metric parameter is set to cpu.usage and the tags parameter is set to host_name: host1.

In the second subquery, tsuids is set to 00005B00005C00002E00005D0000EE00005E0000EF and 00005B00005C0000F000005D0000EE00005E0000EF and the latest data point is queried in each time series.

Request line: POST/api/query/last

Request body:

{
    "queries" : [
        {
            "metric":"cpu.usage",
            "tags" : {
                "host_name": "host1"
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

Response description

If the HTTP status code 200 is returned, the query is successful. The result indicates that the latest data point in the time series that meets the specified query criteria is returned. The result is in the JSON format. If no time series meets the query criteria, an empty set is returned. The following table describes the response parameters.

Parameter

Description

metric

The metric name.

timestamp

The timestamp of the latest data point.

value

The value for the metric.

tags

The tag pairs of the data point. A tag consists of a tag key and a tag value.

tsuid

The ID of the time series in which the data point exists.

Sample requests:

[{
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 30.3,
    "tags": {
        "host_name": "host1"
    },
    "tsuid": "00005B00005C00001D",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 25.6,
    "tags": {
        "host_name": "host2",
        "cluster": "cluster1"
        "zone": "zone1"
    },
    "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 43.1,
    "tags": {
        "host_name": "host3",
        "cluster": "cluster1"
        "zone": "zone1"
    },
    "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF",
}]

Parameter: hint

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.

Release notes

The query hint feature is supported by TSDB V2.6.1 and later.

Sample requests

Hint that applies to a subquery

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      },
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

Hint that applies to the entire query

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      }
    }
  ],
  "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=[])"
    }
}

Parameter: limit

Limit: You can specify the limit parameter to query multiple latest data points. If you do not specify the limit parameter in a request, each time series returns only one latest data point.

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 for each time series.

None

5

from

Long

Yes

The beginning of the time range in which data is queried.

None

1346846400

Examples

Write four time series. Each time series has two data points.

[{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736040, "value":1}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736050, "value":2},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736060, "value":3}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736070, "value":4},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736080, "value":5}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736090, "value":6},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736100, "value":7}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736110, "value":8}]

The size parameter is set to 2. Seven data points are available in the timestamp range of 1514736040 to 1514736100.

{
    "timestamp": 1514736100,
    "limit": {
        "size": 2,
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric"
        }
    ]
}

The following code shows the query result. In the time range, each time series has a maximum of two data points.

[
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "02000002000002000003",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "04000002000002000005",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E000002000003000004",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "10000002000003000006",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]