Request path and method

Request path Request method Description
/api/query POST Queries data.

Parameters in requests in the JSON format

Parameter Type Required Description Default value Example
start Long Yes The beginning of the time range to query. Unit: seconds or milliseconds. For more information about how to determine the unit of a timestamp, see the "Timestamp units" section of this topic. None 1499158925
end Long No The end of the time range to query. Unit: seconds or milliseconds. For more information about how to determine the unit of a timestamp, see the "Timestamp units" section of this topic. The current time of the Lindorm TSDB server 1499162916
queries Array Yes The array of subqueries. None For more information, see the "Parameters for subqueries in the JSON format" section.
msResolution boolean No Specifies whether to return data point timestamps in milliseconds. false This parameter takes effect only if the timestamps of the data points that you query are measured in seconds. If you set the value to true, Lindorm TSDB returns the timestamps in milliseconds. Otherwise, Lindorm TSDB returns the original timestamps.

Timestamp units

Timestamps can be measured in seconds or milliseconds. Lindorm TSDB determines the unit of a timestamp based on the numeric value of a timestamp and the following rules are used:

  • If a timestamp has a range of [4284768,9999999999], Lindorm TSDB determines that the timestamp is measured in seconds. In this case, the corresponding date and time range is [1970-02-20 00:59:28, 2286-11-21 01:46:39].
  • If a timestamp has a range of [10000000000,9999999999999], Lindorm TSDB determines that the timestamp is measured in milliseconds. In this case, the corresponding date and time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].
  • If a timestamp has a range of (-∞,4284768) or (9999999999999,+∞), Lindorm TSDB determines that the timestamp has an invalid range.
Note These rules apply to the following API endpoints: /api/put and api/query. The first API endpoint is used to write data. The other API endpoint is used to query data.

Query data points at a single point in time

Lindorm TSDB allows you to query data points at a single point in time. To query data points at a single point in time, you set the start time and the end time to the same value. For example, you can set the start and end parameters to 1356998400.

Parameters for subqueries in the JSON format

Parameter Type Required Description Default value Example
aggregator String Yes The aggregate function. For more information, see the "Parameter: aggregator" section. None sum
metric String Yes The name of the metric. None sys.cpu0
rate Boolean No Specifies whether to calculate the growth rate between the values of a specified metric. The growth rate is calculated based on the following formula: Growth rate = (Vt - Vt - 1)/(Tt - Tt - 1). false true
delta Boolean No Specifies whether to calculate the delta between the values of a specified metric. This delta is calculated based on the following formula: Delta = Vt - (Vt - 1). false true
limit Integer No The maximum number of data points to return on each page for a subquery. The query results are paginated. 0 1000
offset Integer No The number of the returned data points that you want to skip for a subquery. The query results are paginated. 0 500
dpValue String No The filtering conditions based on which the data points are returned. The following operators are supported: >, <, =, <=, >=, and!=. None >=1000
preDpValue String No The filtering conditions based on which the raw data points are scanned. The following operators are supported: >, <, =, <=, >=, and!=. Note: preDpValue differs from dpValue. preDpValue is used to filter the data points to be stored during scanning. dpValue is used to filter the results that are calculated after a query. If you use preDpValue, the data points that do not meet the filtering conditions are not included in queries and calculations. None >=1000
downsample String No Downsamples data points to cover a wider time span. None 60m-avg
tags Map No Specifies the tag condition based on which the data is filtered. This parameter conflicts with the filters parameter. None -
filters List No Specifies the filtering condition. This parameter conflicts with the tags parameter. None -
Note
  • A query contains a maximum of 200 subqueries.
  • If you configure both the tags and filters parameters, the parameter you specify at the latter position in the JSON-formatted data takes effect.
  • For more information about the limit, dpValue, downsample, tags, and filters parameters, see the following descriptions.

Sample requests

Request line: POST/api/query

Request body:

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0"
    },
    {
      "aggregator": "sum",
      "metric": "sys.cpu.1"
    }
  ]
}

Parameters: limit and offset

Limit: specifies the maximum number of data points that are returned on each page for a subquery. By default, the value is 0. This value specifies that the number of data points to return is unlimited.

Offset: specifies the number of data points that you want to skip for a subquery. By default, the value is 0. This value specifies that the returned data points are not skipped.

Notice You cannot set the limit or offset parameter to a negative number.

Examples

If you want to obtain the data points whose rankings are 1001 to 1500, set the limit parameter to 500 and the offset parameter to 1000.

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"avg",
7.             "downsample":"2s-sum",
8.             "metric":"sys.cpu.0",
9.             "limit":"500",
10.             "offset":"1000",
11.             "tags":{
12.                "host":"localhost",
13.                "appName":"hitsdb"
14.             }
15.          }
16.       ]
17.    }

Parameter: dpValue

The dpValue parameter specifies the limit for data values. You can use this parameter to filter the data points to be returned. The following operators are supported: >, <, =, <=, >=, and!=.

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"avg",
7.             "downsample":"2s-sum",
8.             "metric":"sys.cpu.0",
9.             "dpValue":">=500",
10.            "tags":{
11.                "host":"localhost",
12.                "appName":"hitsdb"
13.             }
14.          }
15.       ]
16.    }

Parameter: delta

If you specify a delta operator in a subquery, the value of a key-value pair in the dps data point is the delta after calculation. The dps data point is returned in the query results from Lindorm TSDB. Take note of the following information: If n key-value pairs in the dps data point are returned when the delta parameter is not specified, only (n-1) key-value pairs in dps are returned after the delta is calculated. The first key-value pair is abandoned because the delta of this pair cannot be calculated. The delta operator also applies to the values of which data is downsampled.

In addition, after you configure the delta operator, you can configure deltaOptions in the subquery to further control how the delta is calculated. The following table shows the supported parameters that can be used for deltaOptions.

Parameter Type Required Description Default value Example
counter Boolean No If you specify this marker bit, you can regard the metric values assumed for calculating deltas as the cumulative values that monotonically increase or decrease. The cumulative values are similar to values in a counter. The server does not check the metric values. false true
counterMax Integer No If the counter parameter is set to true, the counterMax parameter specifies the threshold of the delta. If the absolute value of the delta exceeds the threshold, the delta is an exception. If you do not configure the value of the counterMax parameter, the delta does not have a threshold. None 100
dropReset Boolean No You must use this marker bit together with counterMax. If the counterMax parameter is configured and a delta is calculated and causes an exception, you can use the dropReset parameter to determine whether to drop the delta. If the dropReset parameter is set to true, the delta that causes an exception is dropped. If this parameter is set to or defaults to false, the delta that causes an exception is reset to 0. false true

Examples

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"none",
7.             "downsample":"5s-avg",
8.             "delta":true,
9.             "deltaOptions":{
10.                 "counter":true,
11.                 "counterMax":100
12.             }
13.             "metric":"sys.cpu.0",
14.             "dpValue":">=50",
15.             "tags":{
16.                "host":"localhost",
17.                "appName":"hitsdb"
18.             }
19.          }
20.       ]
21.    }

Parameter: downsample

If you query data over a long period of time, you can downsample the data to retrieve the query results in reduced precision. The following sample code provides the valid format of the query:
<interval><units>-<aggregator>[-fill policy]

The query format is the downsample expression.

where:

  • interval: specifies a numeric value, such as 5 or 60. The value 0all indicates that the data points in the time range are aggregated into a single value.
  • units: the unit. s represents second, m represents minute, h represents hour, d represents day, n represents month, and y represents year.
    Note You can downsample data based on a calendar time interval. To use the calendar time interval, add c to the end of the value for the units parameter. For example, 1dc specifies the 24-hour period from 00:00 of the current day to 00:00 of the next day.
  • aggregator: the aggregation settings. The following table describes the operators that are used for downsampling.
Operator Description
avg Returns the average of all data points.
count Returns the number of data points.
first Returns the first data point.
last Returns the last data point.
min Returns the smallest data point.
max Returns the largest data point.
median Returns the median data point value.
sum Calculates the sum of all data points.
zimsum Calculates the sum of all data points.
rfirst Returns the same data point as that returned by the first operator. However, the rfirst operator returns the data point at the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after data is downsampled.
rlast Returns the same data point as that returned by the last operator. However, the rlast operator returns the data point at the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after data is downsampled.
rmin Returns the same data point as that returned by the min operator. However, the rmin operator returns the data point at the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after data is downsampled.
rmax Returns the same data point as that returned by the max operator. However, the rmax operator returns the data point at the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after data is downsampled.
Note If you use the rfirst, rlast, rmin, or rmax operator in a downsample expression, you cannot configure the fill policy parameter in the downsample expression.
Fill policy

A fill policy emits a pre-defined value when a data point at a specified timestamp is missing. When you downsample data, all time series are segmented at a specified interval and the data points at each interval are aggregated. If a data point is missing at a specified timestamp, you can specify a fill policy to emit a pre-defined value. For example, after you downsample data in a time series, the aligned timestamps are t+0, t+20, and t+30. In this scenario, if you do not specify a fill policy, a data point is missing at the t+10 timestamp. If you specify a fill policy that emits null, Lindorm TSDB emits null at the t+10 timestamp.

The following table describes the fill policies and the values to be filled.

Fill Policy Value
none None. By default, no values are filled.
nan NaN
null null
zero 0
linear The value that is calculated based on linear interpolation.
previous The previous value.
near The adjacent value.
after The next value.
fixed A fixed value that you specify. For more information, see the description in the "Fill policy (fixed value)" section of this topic.
Fixed Fill Policy
To fill a missing value with a fixed value, you can add the fixed value to the end of the number sign (#). You can specify the fixed value as a positive or negative number. The following sample code provides anexample of the valid format:
 <interval><units>-<aggregator>-fixed#<number>

Examples: 1h-sum-fixed#6 and 1h-avg-fixed#-8

Downsampling examples

Examples: 1m-avg, 1h-sum-zero, and 1h-sum-near

Notice When you query data, the downsample parameter is optional. You can set this parameter to null or leave this parameter empty: {"downsample": null} or {"downsample": ""}. In this case, data points are not downsampled.

Parameter: aggregator

After data is downsampled, you can obtain the downsampled data points for each time series. The timestamps of these time series are aligned. In this case, if you aggregate the time series, the data points within a time range for each time series are aggregated into a single data point at an aligned timestamp. If a single time series is downsampled, the data points cannot be aggregated. During aggregation, each time series must have a value at each aligned timestamp. If no value can be found at an aligned timestamp, interpolation is performed. For more information, see the following "Interpolation" section.

Interpolation

If a time series has no value at a timestamp, a value is interpolated to this time series at the timestamp. This occurs only if you do not specify a fill policy for the time series, and one of the other time series to be aggregated has a value at this timestamp.

For example, you want to merge two time series by using the sum operator. The downsampling and aggregation settings are {"downsample": "10s-avg", "aggregator": "sum"}. After you perform downsampling, the timestamps in which values can be found are provided in the following part:

Time series 1: t+0, t+10, t+20, t+30

Time series 2: t+0, t+20, t+30

In time series 2, the value at the t+10 timestamp is missing. Then, before the aggregation is performed, a value is interpolated for time series 2 at the t+10 timestamp. The interpolation method varies based on aggregation operators. The following table describes the operators and the interpolation methods.

Operator Description Interpolation method
avg Returns the average of all data points. Performs linear interpolation based on a linear slope.
count Returns the number of data points. Interpolates zero.
mimmin Returns the smallest data point. Interpolates the largest data point.
mimmax Returns the largest data point. Interpolates the smallest data point.
min Returns the smallest data point. Performs linear interpolation.
max Returns the largest data point. Performs linear interpolation.
none Skips data aggregation. Interpolates zero.
sum Calculates the sum of all data points. Performs linear interpolation.
zimsum Calculates the sum of all data points. Interpolates zero.

Parameter: filters

You can use the following methods to configure the filters parameter:

  • Use tagk to specify filters.
    • tagk = *: performs a GROUP BY operation on all the tag values that are paired with a specified tag key and then aggregates the same tag values.
    • tagk = tagv1|tagv2: aggregates time series that have the specified tag values that are paired with a tag key.
  • Use the JSON format.
Parameter Type Required Default value Example
type String Yes The filter type. For more information, see the "Filter types" section of this topic. None literal_or
tagk String Yes The name of the tag key. None host
filter String Yes The filter expression. None web01|web02
groupBy Boolean No Specifies whether to perform a GROUP BY operation on the tag values. false false
Filter types
Filter type Example Description
literal_or web01|web02 Aggregation is separately performed on multiple case-sensitive tag values.
wildcard *mysite.com Aggregation is separately performed on the tag values that contain the specified wildcard. These tag values are case-sensitive.
Sample requests

Sample requests without filters

Request Body:

1.    {
2.        "start": 1356998400,
3.        "end": 1356998460,
4.        "queries": [
5.            {
6.                "aggregator": "sum",
7.                "metric": "sys.cpu.0",
8.                "rate": "true",
9.                "tags": {
10.                    "host": "*",
11.                    "dc": "lga"
12.                }
13.            }
14.        ]
15.    }
Sample requests with filters

Request body:

1. {
2.  "start": 1356998400,
3.  "end": 1356998460,
4.  "queries": [
5.    {
6.      "aggregator": "sum",
7.      "metric": "sys.cpu.0",
8.      "rate": "true",
9.      "filters": [
10.        {
11.          "type": "wildcard",
12.          "tagk": "host",
13.          "filter": "*",
14.          "groupBy": true
15.        },
16.        {
17.          "type": "literal_or",
18.          "tagk": "dc",
19.          "filter": "lga|lga1|lga2",
20.          "groupBy": false
21.        }
22.      ]
23.    }
24.  ]
25. }

Query results

If a query is successful, the HTTP status code is 200 and the response in the JSON format is returned. The following table describes the response parameters.

Parameter Description
metric The name of the metric.
tags The tags whose values are not aggregated.
aggregateTags The tags whose values are aggregated.
dps The pairs of data points.
Sample responses:
1.  [
2.    {
3.        "metric": "tsd.hbase.puts",
4.        "tags": {"appName": "hitsdb"},
5.        "aggregateTags": [
6.            "host"
7.        ],
8.        "dps": {
9.            "1365966001": 25595461080,
10.           "1365966061": 25595542522,
11.           "1365966062": 25595543979, 
12.           "1365973801": 25717417859 
13.       } 
14.   }
15.  ]