Call the api query last HTTP API to query the latest data point of a time series - Time Series Database

Queries the latest data point in one or more time series. Fully compatible with OpenTSDB.

Endpoint

POST /api/query/last

Request parameters

Parameter	Type	Required	Description	Example
`queries`	Array	Yes	The subqueries to run. Each subquery targets a metric or a TSUID.	See Subquery parameters.
`timestamp`	Long	No	The UNIX timestamp to query against, in seconds or milliseconds. If omitted, the query uses the current timestamp.	`1539763573`
`hint`	Map	No	A query hint that controls which indexes are used. Applies to all subqueries in the request.	See hint.
`limit`	Map	No	Returns multiple latest data points per time series instead of one.	See limit.

Subquery parameters

Each subquery in the queries array must target either a metric or a TSUID.

Metric subquery

Parameter	Type	Required	Description	Example
`metric`	String	Yes	The metric to query.	`cpu.usage`
`tags`	Map	No	The tag key-value pairs to filter the query.	`{"host_name": "host1"}`
`hint`	Map	No	A query hint scoped to this subquery only.	See hint.

Important

Only the tags parameter is supported for filtering. The filters parameter is not supported.

TSUID subquery

Parameter	Type	Required	Description	Example
`tsuids`	Array	Yes	The TSUIDs of the time series to query.	`["00005B00005C0000F000005D0000EE00005E0000EF"]`

Important

To get the TSUID of a time series, call the /api/search/lookup operation. TSDB High-availability Edition: The tsuid parameter is accepted but does not take effect. The /api/search/lookup operation does not return TSUIDs in the high-availability edition.

You can include both metric subqueries and TSUID subqueries in the same request.

Example request

The following request runs two subqueries: a metric subquery for cpu.usage on host1, and a TSUID subquery across two time series.

POST /api/query/last

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

Response elements

A 200 status code indicates success. The response body is a JSON array where each object represents the latest data point of a matching time series. If no time series matches the query criteria, an empty array is returned.

Parameter	Description
`metric`	The metric name.
`timestamp`	The timestamp of the latest data point.
`value`	The metric value at the timestamp.
`tags`	The tag pairs of the data point. Each tag consists of a tag key and a tag value.
`tsuid`	The ID of the time series.

Example response

[{
    "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"
}]

hint

Use a query hint to reduce response time by controlling which indexes the query engine uses.

Supported since: TSDB V2.6.1

Only the tagk parameter is supported inside a hint. Set each tag key to 0 or 1:

0: do not use the index for this tag key
1: use the index for this tag key

All values in tagk must be the same — mixing 0 and 1 in a single hint returns an error.

A hint can apply to a single subquery or to the entire request. Set hint inside a subquery object to scope it to that subquery; set hint at the top level to apply it to all subqueries.

Hint scoped to a subquery

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

Hint applied to all subqueries

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

Error cases

Mixing 0 and 1 in the same tagk map returns HTTP 400. The following request triggers this error:

{
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 1,
            "host": 0
        }
    }
}

{
    "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=[])"
    }
}

Passing a value other than 0 or 1 (for example, 100) also returns HTTP 400. The following request triggers this error:

{
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 100
        }
    }
}

{
    "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=[])"
    }
}

limit

By default, /api/query/last returns one data point per time series. Set the limit parameter to return multiple latest data points per time series within a specified time range.

Parameter	Type	Required	Description	Example
`size`	Integer	Yes	The maximum number of data points to return per time series.	`5`
`from`	Long	Yes	The start of the time range to query, as a UNIX timestamp.	`1346846400`

Example

The following data is written to four time series, with two data points per series:

[
    {"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}
]

This request sets size to 2 and queries the range 1514736040 to 1514736100, which contains seven data points:

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

The response returns up to two data points per time series within the time range:

[
    {
        "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
        }
    }
]