Request path and method
Request path | Request method | Description |
/api/query/last | POST | Queries the latest data point in a time series. |
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. |
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 |
You can perform the /api/search/lookup operation to query the TSUID of the time series.
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 are1
, 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": "0200000200000200****",
"version": 0,
"dps": {
"1514736040000": 1.0,
"1514736060000": 3.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736100000,
"value": 7.0,
"tags": {
"testmetric1_tagk": "testmetric1_tagv2"
},
"tsuid": "0400000200000200****",
"version": 0,
"dps": {
"1514736080000": 5.0,
"1514736100000": 7.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736070000,
"value": 4.0,
"tags": {
"testmetric2_tagk": "testmetric2_tagv1"
},
"tsuid": "0E00000200000300****",
"version": 0,
"dps": {
"1514736050000": 2.0,
"1514736070000": 4.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736090000,
"value": 6.0,
"tags": {
"testmetric2_tagk": "testmetric2_tagv2"
},
"tsuid": "1000000200000300****",
"version": 0,
"dps": {
"1514736090000": 6.0
}
}
]