All Products
Search
Document Center

Query a multivariate data point

Last Updated: May 19, 2022

This topic describes how to query a multivariate data point.

Use mquery to query a multivariate data point

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 write a univariate data point, call the /api/put operation. To query multivariate data points, call the /api/mquery operation. To query univariate data points, call the /api/query operation.

Parameters in a data point

Parameter

Type

Required

Description

Default value

Example

start

Long

Yes

The start time. Unit: seconds or milliseconds. For information about the rules to determine the unit, see the "Timestamp units" section.

None

1499158925

end

Long

No

The end time. Unit: seconds or milliseconds. For information about the rules to determine the unit, see the "Timestamp units" section. The default value is the current time of the Time Series Database (TSDB) server.

Current time

1499162916

queries

Array

Yes

The subquery array.

None

For more information, see the "Parameters for subqueries in the JSON format" section.

msResolution

boolean

No

The subquery array.

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, the unit of the timestamps in the query result is milliseconds. Otherwise, the original timestamp unit is retained. If the timestamp of a data point that you query is milliseconds, the timestamp unit in the query result is milliseconds regardless of whether the value of this parameter is true or false.

hint

Map

No

The query hint.

None

For more information, see the "Parameter: hint" section.

Timestamp units

Timestamps can be measured in seconds or milliseconds. TSDB uses the following rules to determine the unit of a timestamp based on the numeric value of the timestamp:

  • If a timestamp has a range of [4284768,9999999999], 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], 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,+∞), TSDB determines that the timestamp has an invalid range.

    Note

    This section describes the rules for determining the unit of a timestamp. These rules apply to the following API operations: /api/put, /api/mput, /api/query, and /api/mquery. /api/put and /api/mput are used to write data. /api/query and /api/mquery are used to query data.

Query data points at a single point in time

TSDB allows you to query data points at a single point in time. To query data points at a single point in time, 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

metric

String

Yes

The metric name.

None

wind

fields

List

Yes

The fields to return.

None

-

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)/(t1 - t-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 in each timeline to return on each page for a subquery.

0

1000

offset

Integer

No

The number of data points that you want to skip in each timeline on each page for a subquery.

0

500

dpValue

String

No

The filtering conditions based on which the returned data points are filtered. 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

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

The downsampling configuration.

None

60m-avg

tags

Map

No

The tags of the data points to return. This parameter conflicts with the filters parameter.

None

-

filters

List

No

Specifies the filtering condition. This parameter conflicts with the tags parameter.

None

-

hint

Map

No

The query hint.

None

For more information, see the "Parameter: hint" section.

Note

  • You can specify a maximum of 200 values for the field parameter in each query. The following example describes the details:

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

  • If you specify both the tags and filters parameters, the parameter that you specify at the latter position in the JSON-formatted data takes effect.

Parameters for field queries 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

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

-

downsample

String

No

The downsampling configuration.

None

60m-avg

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)/(t1 - t-1).

false

true

dpValue

String

No

The filtering conditions based on which the returned data points are filtered. The following operators are supported: >, <, =, <=, >=, and!=.

None

>=1000

where

String

No

If the field parameter is set to the wildcard character (*), you can use the where parameter to specify which field is to be filtered when the results are calculated after a query. The where parameter works in the same manner as dpValue. The two parameters filter the results that are calculated after a query.

None

f1>=100

Note

For more information about the limit, dpValue, downsample, tags, and filters parameters, see the following descriptions.

Sample requests

Request body: POST/api/query

{
    "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",
                    "where":"speed>10"
                }
            ]
        }
    ]
}

Use the limit and offset parameters

The limit parameter specifies the maximum number of data points to return in each timeline for a subquery. The default value of the limit parameter is 0. The default value 0 specifies that no limits are placed on the number of returned data points.

The offset parameter specifies the number of the data points that you want to skip in each timeline for a subquery. The default value of the offset parameter is 0. The default value 0 specifies that no data points are skipped.

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

  • 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.

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.

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

Parameter: dpValue

The dpValue parameter specifies the limit for data values. You can specify this parameter to filter data points that are to be returned. Valid values are >, <, =, <=, >=, and!=.

Notice

If you use dpValue in subqueries to query data for multiple fields, dpValue in each subquery works in a separate way.dpValue in each subquery does work in the same way across fields.

If this parameter is set to a string, the string can include only the operators: = and!=.

Examples

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

Operator: delta

If you specify a delta operator in a subquery, the value of a key-value pair in the dps data point returned by TSDB is the calculated delta.

Notice

If n key-value pairs are contained in the dps data point that is returned when the delta parameter is not specified, only n-1 key-value pairs are contained in the dps data point that is returned after the delta is calculated. The first key-value pair is not used because the delta of this pair cannot be calculated. The delta operator also applies to the values after downsampling.

After you specify a delta operator, you can configure deltaOptions in the subquery to further control how the delta is calculated. The following table describes the 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 abnormal. If you do not specify 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 specified and a calculated delta is abnormal, you can use the dropReset parameter to specify whether to discard the abnormal 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

    {
       "start":1346046400,
       "end":1347056500,
       "queries":[
          {
             "aggregator":"none",
             "downsample":"5s-avg",
             "delta":true,
             "deltaOptions":{
                 "counter":true,
                 "counterMax":100
             }
             "metric":"sys.cpu.0",
             "dpValue":">=50",
             "tags":{
                "host":"localhost",
                "appName":"hitsdb"
             }
          }
       ]
    }

Parameter: downsample

Use this parameter if you need to query data generated in a long time range and aggregate the data based on a specified time interval. A timeline is divided into multiple time ranges based on the specified time interval for downsampling. Each timestamp returned indicates the start of each time range. The following sample code provides an example on the format of the query:

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

After the downsample parameter is specified, a time window that has the same length as the specified interval for data aggregation is automatically added to the start and the end of the specified time range. For example, if the specified timestamp range is [1346846401,1346846499] and the specified interval is 5 minutes, the actual timestamp range for the query is [1346846101,1346846799].

The following section describes the parameters that are used in the query:

  • interval: specifies a numeric value, such as 5 or 60. The value 0all specifies that the data points in the time range are aggregated into a single value.

  • units: the unit. s represents seconds. m represents minute. h represents hour. d represents day. n represents month. y represents year.

    Note

    • By default, the modulo and truncation operation is performed to align timestamps. Timestamps are aligned by using the following formula: Aligned timestamp = Data timestamp - (Data timestamp % Time interval).

    • You can downsample data based on a calendar time interval. To use the calendar time interval, add c to the end of the value of 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 value.

count

Returns the number of data points.

first

Returns the first value.

last

Returns the last value.

min

Returns the minimum value.

max

Returns the maximum value.

sum

Returns the sum of values.

zimsum

Returns the sum of values.

rfirst

Returns the same data point as that returned by the first operator. The timestamp returned is the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after the data is downsampled.

rlast

Returns the same data point as that returned by the last operator. The timestamp returned is the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after the data is downsampled.

rmin

Returns the same data point as that data point returned by the min operator. The timestamp returned is the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after the data is downsampled.

rmax

Returns the same data point as the data point returned by the max operator. The timestamp returned is the original timestamp instead of the aligned timestamp. The timestamps of data points are aligned after the data is downsampled.

Note

If you set the aggregator to the rfirst, rlast, rmin, or rmax operator in a downsampling expression, you cannot configure the fill policy parameter in the downsampling expression.

Fill policy

You can specify the fill policy parameter to determine how to fill missing values with pre-defined values. During downsampling, all timelines are split based on a specified time interval, and data points in each time range are aggregated. If no value exists during a time range in the downsampling result, you can specify a fill policy to fill the missing value with a pre-defined value. An example is used to explain fill policies. In this example, the timestamps of a timeline after downsampling are t+0, t+20, and t+30. If you do not specify a fill policy, only three values are reported. If you set the fill policy to null, four values are reported. The missing value at the point in time t+10 is filled with null. The following table describes the fill policies and the values that are to be filled.

Fill Policy

Value

none

No values are filled. This is the default value.

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 user-specified fixed value. For more information, see the description in the "Fixed Fill Policy" 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 an example on the valid format:

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

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

Downsampling examples

Three downsampling examples are 1m-avg, 1h-sum-zero, and 1h-sum-near.

Notice

The downsample parameter is optional for field queries. You can set this parameter to null or leave this parameter empty in the ("") format: {"downsample": null} or {"downsample": ""}. In this case, data is 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.

Parameter: aggregator

After data is downsampled, values along multiple timelines are obtained and timestamps of these timelines are aligned. You can perform aggregation to merge these timelines into one by aggregating the values at each aligned timestamp. Aggregation is not performed if only one timeline exists. During aggregation, each timeline 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.

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. TSDB does not allow you to aggregate only part of field data in a subquery.

Interpolation

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

An example is used to explain interpolation. In this example, you want to merge two timelines by using the sum operator. The downsampling and aggregation settings are {"downsample": "10s-avg", "aggregator": "10s-avg", "aggregator": "sum"}. After the data is downsampled based on 10s-avg, values can be found on the following timestamps along the two timelines:

The timestamps of timeline 1 on which values can be found are t+0, t+10, t+20, and t+30. The timestamps of timeline 2 on which values can be found are t+0, t+20, and t+30.

Along timeline 2, the value at the t+10 timestamp is missing. Before the data is aggregated, a value is interpolated for timeline 2 at this timestamp. The interpolation method varies based on aggregation operators. The following table lists the operators and interpolation methods.

Operator

Description

Interpolation method

avg

Returns the average value.

Performs linear interpolation based on a linear slope.

count

Returns the number of data points.

Interpolates zero.

mimmin

Returns the minimum value.

Interpolates the maximum value.

mimmax

Returns the maximum value.

Interpolates the minimum value.

min

Returns the minimum value.

Performs linear interpolation.

max

Returns the maximum value.

Performs linear interpolation.

none

Skips data aggregation.

Interpolates zero.

sum

Returns the sum of values.

Performs linear interpolation.

zimsum

Returns the sum of values.

Interpolates zero.

Parameter: filters

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

  • Use tagk to specify filters.

    • tagk = *: You can group the tag values of a tag key to aggregate the same tag values.

    • tagk = tagv1|tagv2: You can aggregate the tagv1 values of the tag key and aggregate the tagv2 values of the 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 filter type. For more information, see the "Filter types" section of this topic.

None

literal_or

tagk

String

Yes

The key of the tag.

None

host

filter

String

Yes

The filter expression.

None

web01|web02

groupBy

Boolean

No

Specifies whether to group by tag values.

false

false

Filter types

Parameter

Example

Description

literal_or

web01|web02

The values of each tagv are aggregated. This filter is case-sensitive.

wildcard

*mysite.com

The tag values that contain the specified wildcard for each tagv are aggregated. This filter is case-sensitive.

Sample requests

Sample requests with filters

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

Query result

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

Parameter

Description

metric

The metric name.

columns

The columns returned.

tags

The tags whose values were not aggregated.

aggregateTags

The tags whose values were 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]
    ]
  }
]

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 timelines hit by Tags B are included by the timelines hit by Tags A. In this case, data is not read from the timelines hit by Tag A. The intersection between the set of timelines hit by Tag A and the set of timelines hit by Tag B is equal to the set of timelines 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.

Version description

The query hint feature is supported by TSDB V2.6.1 and later.

Sample requests

Hint that applies to a subquery

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ],
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

Hint that applies to the entire query

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ]
    }
  ],
  "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=[])"
    }
}