Query the latest data point of a time series - Time Series Database| Alibaba Cloud Documentation Center

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

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 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
        }
    }
]