Request path and method

Request path Request method Description
/api/mquery POST Queries data.
Notice The request path that you use to insert a univariate data point is different from that you use to insert a multivariate data point. To insert a univariate data point, use /api/put. To query a multivariate data point, use /api/mquery. To query a univariate data point, use /api/query.

Request parameters

Parameter Type Required Description Default value Example
start Long Yes The beginning of the timestamp range to query. Unit: seconds or milliseconds. For more information about how to determine the unit of a timestamp, see the "Timestamp units" section. None 1499158925
end Long No The end of the timestamp range to query. Unit: seconds or milliseconds. For more information about how to determine the unit of a timestamp, see the "Timestamp units" section. By default, the current system time of the Lindorm TSDB server is used. Current system time 1499162916
queries Array Yes The 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 is valid only for data point timestamps in seconds. If you set the value to true, Lindorm TSDB returns the timestamps in milliseconds. Otherwise, Lindorm TSDB returns the timestamps in the unit of the timestamps specified in the query conditions. The configuration of this parameter does not affect the timestamps in milliseconds.

Timestamp units

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

  • If a timestamp has a range of [4284768,9999999999], Lindorm TSDB determines that the timestamp is in seconds. In this case, the timestamp has a range of [1970-02-20 00:59:28,2286-11-21 01:46:39] in UTC.
  • If a timestamp has a range of [10000000000,9999999999999], Lindorm TSDB determines that the timestamp is in milliseconds. In this case, the timestamp has a range of [1970-04-27 01:46:40.000,2286-11-21 01:46:39.999] in UTC.
  • If a timestamp has a range of (-∞,4284768) or (9999999999999,+∞), Lindorm TSDB determines that the timestamp is invalid. Take note of this point: This rule is applicable to the following request paths: /api/put, /api/mput, /api/query, and /api/mquery. /api/put and /api/mput are used to insert data. /api/query and /api/mquery are used to query data.

Query data points at a specified timestamp

Lindorm TSDB allows you to query data points at a specified timestamp. In this scenario, you set the start timestamp and the end timestamp to the same value. For example, you set the start and end parameters to 1356998400.

Parameters for subqueries in the JSON format

Parameter Type Required Description Default value Example
metric String Yes The name of the metric. None wind
fields List Yes The fields to return. None -
limit Integer No The maximum number of data points to return for the subquery. The query result is paginated. 0 1000
offset Integer No The offset from which Lindorm TSDB starts to return the data points for the subquery. The query result is paginated. 0 500
tags Map No The tags of the data points to return. This parameter conflicts with the filters parameter. None -
filters List No The filters. This parameter conflicts with the tags parameter. None -
Note
  • You can specify a maximum of 200 fields in each query.

    In this example, you include three subqueries in a query. In the first subquery, you specify three fields. In the second subquery, you specify two fields. In the third subquery, you specify six fields. Therefore, the total number of fields in the query equals 11. Before you perform the query, make sure that the number of fields in the query does not exceed 200.

  • If you specify the tags and filters parameters in a query, the parameter that you specify in the latter position takes effect.

Parameters for field queries in the JSON format

Parameter Type Required Description Default value Example
aggregator String Yes The aggregator. For more information, see the "Use the aggregator parameter" section. None sum
field String Yes The name of the field. You can use an asterisk (*) to query all the fields for the metric. None -
alias String No The alias of the field to return. None None
downsample String No The configuration for downsampling time series. None 60m-avg
rate Boolean No Specifies whether to calculate the growth rate between metric values. The growth rate is calculated based on the following formula: Growth rate = (Vt - Vt-1)/(Tt - Tt-1). false true
dpValue String No Filters data points based on the specified conditions. The following operators are supported: >, <, =, <=, >=, and !=. None >=1000

Sample requests

Request line: POST/api/mquery

Request body:

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "sum",
                    "downsample" : "2s-last",
                      "alias" : "speed_sum"
                },
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count"
                }
            ]
        }
    ]
}
            

Use the limit and offset parameters

limit: the maximum number of data points to return for a subquery. By default, the value is 0. This indicates that no limit is imposed on the number of data points to return.

offset: the offset from which Lindorm TSDB starts to return the data points for a subquery. By default, the value is 0. This indicates that Lindorm TSDB returns data from the first data point that meets the query conditions.

Notice You cannot set the limit parameter or the offset parameter to a negative value. The limit and offset parameters work on the multivariate data points to return for a paged query. You cannot use the two parameters for a single field query.
Example

Use limit and offset to query data points. In this example, you set limit to 500 and offset to 1000. This specifies that Lindorm TSDB returns 500 data points that come after the first 1000 data points.

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ],
            "limit" : 500,
            "offset" : 1000
        }
    ]
}
                

Use the dpValue parameter

You can use dpValue to filter the data points to return based on numeric literals. The following operators are supported: >, <, =, <=, >=, and !=.

Notice If you use dpValue in subqueries to query data for multiple fields, dpValue in each subquery works in a separate way.
Example
{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "level",
                    "aggregator" : "avg",
                    "downsample" : "2s-avg",
                    "dpValue" : ">=8.0"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}
                

Use the downsample parameter

If you query data over a wide time span, you can reduce the resolution of the data to return. You can use the following sample code:

<interval><units>-<aggregator>[-fill policy]          

Parameter description

  • interval: the interval time across which Lindorm TSDB aggregates the data points. For example, you can set interval to 5 or 60. The 0all value specifies that Lindorm TSDB aggregates all the data points in a time series into a data point.
  • units: the unit of the interval time. Valid values: s, m, h, d, n, and y. s specifies seconds, m specifies minutes, h specifies hours, d specifies days, n specifies months, and y specifies years.
    Note Lindorm TSDB supports calendar-based downsampling. To use calendar boundaries, append c to the unit specified by units. For example, 1dc specifies a calendar day from 00:00 to 24:00.
  • aggregator: the operator for downsampling. The following table describes the operators.
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.
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 rfirst, rlast, rmin, or rmax for downsampling, you cannot specify a fill policy.

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 time series data, 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 timestamp t+10. If you specify a fill policy that emits null, Lindorm TSDB emits null at timestamp t+10. The following table describes the fill policies.

Fill Policy Value
none The default behavior that does not emit values.
nan NaN
null null
zero 0
linear Performs linear interpolation.
previous Emits the previous value.
near Emits the value that is the nearest to the missing data point.
after Emits the next value.
fixed Emits the pre-defined value. For more information, see the following description.

Fixed Fill Policy

To emit a pre-defined value, append the pre-defined value to the number sign (#). A pre-defined value can be a positive or negative number. You can use the following sample code:

<interval><units>-<aggregator>-fixed#<number>

For example, you can use 1h-sum-fixed#6 or 1h-avg-fixed#-8.

Examples for downsampling

For example, you can use 1m-avg, 1h-sum-zero, or 1h-sum-near.

Notice The downsample parameter is optional for field queries. You can set this parameter to null or leave this parameter empty. For example, you can use {"downsample": null} or {"downsample": ""}. This specifies that data points are not downsampled. If you specify the downsample parameter in a field query, specify this parameter in the other field queries that belong to the same subquery. You must specify the same interval time to downsample field data in all the field queries that belong to the same subquery.

Use the aggregator parameter

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. When Lindorm TSDB aggregates data points in time series, each time series must have a data point at an aligned timestamp. If a time series does not have a data point at a given timestamp, Lindorm TSDB interpolates a value for the missing data point. For more information, see the "Interpolation" section.
Notice In field queries, the aggregator parameter is required. You can set this parameter to none. This specifies that data is not aggregated. If you specify the aggregator parameter in a field query, you must also specify this parameter in other field queries that belong to the same subquery. Lindorm TSDB does not allow you to aggregate only part of field data in a subquery.

Interpolation

If a time series does not have a data point at a timestamp, Lindorm TSDB interpolates a value for the missing data point. This happens 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 data point at this timestamp.

For example, you use the following expression to downsample and aggregate time series: {"downsample": "10s-avg", "aggregator": "sum"}. In this example, you use the sum operator to aggregate two time series. 10s-avg specifies that the average of all the data points in the two time series at a specified timestamp is calculated every 10 seconds. After data is downsampled, the timestamps of the two time series are aligned:

The timestamps of time series 1 are t+0, t+10, t+20, and t+30. The timestamps of time series 2 are t+0, t+20, and t+30.

In this example, time series 2 does not have a data point at timestamp t+10. Therefore, before Lindorm TSDB aggregates data points, Lindorm TSDB interpolates a value for time series 2 at timestamp t+10. The result of interpolation varies based on aggregation operators. The following table describes the operators.

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.

Use the filters parameter

You can use the following methods to specify filters:

  • 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 data points that have the specified tag values that are paired with a tag key.
  • Specify filters in the JSON format. The following table describes the parameters.
Parameter Type Required Description Default value Example
type String Yes The type of the filter. For more information, see the "Filter types" section. None literal_or
tagk String Yes The key of the tag. None host
filter String Yes The expression of the filter. 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 Aggregates data points that have the specified tag values. Filters of this type are case-sensitive.
wildcard *mysite.com Aggregates data points that have the tag values that meet the specified wildcard filter. Filters of this type are case-sensitive.

Sample requests

Use filters to query data. Request body:
{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "none",
                    "alias" : "column_speed"
                },
                {
                    "field" : "*",
                    "aggregator" : "none",
                    "alias" : "column_"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}
            

Responses

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

Parameter Description
metric The name of the metric.
columns The columns returned.
tags The tags for which the tag values are not aggregated.
aggregateTags The tags for which the tag values are aggregated.
values The tuples returned.

Sample responses

  • The following sample code shows the query result when the aggregator parameter is set to none.
[
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0005"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846406000, null, "Fresh breeze", "East", 0.5, null ],
         [ 1346846407000, null, "Fresh breeze", "South", 1.5, null ]
   },
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0004"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4 ],
         [ 1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4 ],
         [ 1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4 ],
         [ 1346846403000, 43.4, "Fresh breeze", "North", 3.4,43.4 ]
   }
]
            
  • The following sample code shows the query result when the aggregator parameter is set to avg. The result indicates the average wind speed and the average wind level based on all the sensors in the Hangzhou city.
[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "avg_level",
      "avg_speed"
    ],
    "tags": {
      "city": "hangzhou"
    },
    "aggregatedTags": [
      "country",
      "province",
      "sensor"
    ],
    "values": [
      [1346846400000, 0.25, 40.25],
      [1346846401000, 1.25, 41.25],
      [1346846402000, 2.5, 42.5],
      [1346846411000, 5.5, null]
    ]
  }
]