Function Description

Query data from the OpenTSDB database.

URI

• URI format

  POST {OpenTSDB URL}/api/query

Request

• Sample request

  {
      "start": 1504527820,
      "end": 1504557820,
      "queries": [
          {
              "aggregator": "sum",
              "metric": "cpu.system",
              "rate": "true",
              "filters": [
                  {
                     "type":"regexp",
                     "tagk":"host",
                     "filter":"web[0-9]+.lax.mysite.com",
                     "groupBy":true
                  },
                  {
                     "type":"literal_or",
                     "tagk":"dc",
                     "filter":"lax|dal",
                     "groupBy":false
                  },
              ]
          }
      ]
  }

• Parameter description

  Table 1 Request parameters

  Parameter	Type	Mandatory	Description
  start	Integer	Yes	Start Time (unit: second) The query result contains the parameter value. NOTE: You are advised to set this parameter to a value between 4334400 seconds and 4291718400 seconds, that is, from 1970/02/20 12:00:00 to 2106/01/01 00:00:00. You can also set it to 0. Otherwise, the query result may be incorrect.
  end	Integer	No	End time (unit: second). The default value is the current system time of OpenTSDB. The query result contains the parameter value. NOTE: You are advised to set this parameter to a value between 4334400 seconds and 4291718400 seconds, that is, from 1970/02/20 12:00:00 to 2106/01/01 00:00:00. Otherwise, the query result may be incorrect.
  queries	Array	Yes	Multiple queries are supported. For details, see Table 2.
  delete	Boolean	No	If this parameter is set to true, all query results that meet the search criteria will be deleted. NOTE: Deleting data is performed in the unit of one hour. Therefore, data of all hours associated with the query result will be deleted.
  noAnnotations	Boolean	No	Whether to return comment information true: Not returned false: Returned The default value is false.
  globalAnnotations	Boolean	No	Whether to return global comments within the time span true: Returned false: Not returned The default value is false.
  showTSUIDs	Boolean	No	Whether to return the TSUID associated with the time series in the result true: If multiple time series are aggregated into a set, multiple TSUIDs will be returned in a sort manner. false: Not returned The default value is false.
  showSummary	Boolean	No	Whether to return the time summary in the result. For details, see https://opentsdb.net/docs/build/html/user_guide/query/stats.html. true: Returned false: Not returned The default value is false.
  showStats	Boolean	No	Whether to return the detailed time in the result. For details, see https://opentsdb.net/docs/build/html/user_guide/query/stats.html. true: Returned false: Not returned The default value is false.
  showQuery	Boolean	No	Whether to return the original subquery with the query result. true: Returned false: Not returned The default value is false.
  msResolution	Boolean	No	By default, the timestamp in the query result is expressed in seconds. If this parameter is set to true, the timestamp in the query result is expressed in milliseconds.
  returnCount	Boolean	No	Whether to return the number of query results. true: Returned false: Not returned The default value is false.
  reverse	Boolean	No	Whether to return query results in descending order of time. true: Yes false: No The default value is false.
  onlyDelete	Boolean	No	true: The result data that meets the query conditions is deleted, but the query result is not returned. false: This parameter is invalid. The default value is false.
  returnBoolean	Boolean	No	Whether to convert the returned value into a Boolean value. true: yes. If value is greater than 0, the value is converted into true. If value is equal to or less than 0, the value is converted into false. false: no The default value is false.

  Table 2 Subquery parameters

  Parameter	Type	Mandatory	Description
  aggregator	String	Yes	Aggregation function. For details, see aggregator description.
  metric	String	Yes	Metric
  rate	Boolean	No	Whether or not the data should be converted into deltas before returning. true: Returned false: Not returned The default value is false.
  downsample	String	No	An optional downsampling function to reduce the amount of data returned. For details, see •downsample description.
  filters	List	No	Filter. You can set multiple filters. For details about the format of each filter, see •filter parameter description.
  explicitTags	Boolean	No	Whether to return the series that include only the tag keys provided in the filters. true: Returned false: Not returned The default value is false.
  useMultiGets	Boolean	No	Whether to query data using MultiGet. The default value is false. This parameter is valid only when type of filters is set to literal_or and explicitTags is set to true.
  valueFilter	String	No	Specifies the expression for filtering values. For details, see •valueFilter description.

• downsample description

  If a user queries for data over an hour time span, for example, the temperature data is written to OpenTSDB every second, the user will receive 3600 data points. If the user query data of a week, 604800 data points are returned. It becomes messy to display so much data and usually it is unnecessary to provide data to such precision degree. Using a downsampler, multiple data points within a time range are aggregated into one data point. For example, data points over an hour time span are aggregated into one data point. In this way, only 168 data points will be displayed.

  Syntax:

  <Interval><units>-<aggregator>[c][-<fill policy>]

  • Interval: A time range across which to aggregate the values. The units parameter indicates a time unit, such as s for second, m for minute, h for hour, and d for day. Example: 1h, 30m, 24h
  • aggregator: aggregation policy, that is, a policy to aggregate time points in a period of time into one data point. For details, see •aggregator description.
  • fill policy: fill policy. When the aggregator calculates the aggregated value within a period, this policy is used to supplement data when a data point is missing. For details, see Table 3.

    Table 3 Fill policy parameters

    Parameter	Description
    none	Default behavior that does not emit missing values
    nan	Emits a NaN.
    null	Emits a null.
    zero	Zero if missing
    pre	Emits the previous value (after aggregation).

    

    downsample aggregates data of time lines into a new time line, and then filters the start and end time in the query condition.

• aggregator description

  aggregator is used when downsampling is performed and multiple time lines are aggregated. An operator is used to aggregate multiple data points into one data point. For details about aggregation operators, see Table 4.

  Table 4 Operators

  Operator	Description	Value Filling Method
  avg	Averages the data points.	Linear interpolation
  count	Number of raw data points in the set	Zero if missing
  dev	Calculates the standard deviation.	Linear interpolation
  ep50r3	Calculates the estimated 50th percentile with the R-3 method.	Linear interpolation
  ep50r7	Calculates the estimated 50th percentile with the R-7 method.	Linear interpolation
  ep75r3	Calculates the estimated 75th percentile with the R-3 method.	Linear interpolation
  ep75r7	Calculates the estimated 75th percentile with the R-7 method.	Linear interpolation
  ep90r3	Calculates the estimated 90th percentile with the R-3 method.	Linear interpolation
  ep90r7	Calculates the estimated 90th percentile with the R-7 method.	Linear interpolation
  ep95r3	Calculates the estimated 95th percentile with the R-3 method.	Linear interpolation
  ep95r7	Calculates the estimated 95th percentile with the R-7 method.	Linear interpolation
  ep99r3	Calculates the estimated 99th percentile with the R-3 method.	Linear interpolation
  ep99r7	Calculates the estimated 99th percentile with the R-7 method.	Linear interpolation
  ep999r3	Calculates the estimated 99.9th percentile with the R-3 method.	Linear interpolation
  ep999r7	Calculates the estimated 99.9th percentile with the R-7 method.	Linear interpolation
  first	Returns the first data point in the set.	-
  last	Returns the last data point in the set.	-
  mimmin	Selects the smallest data point.	Maximum if missing
  mimmax	Selects the largest data point.	Minimum if missing
  min	Selects the smallest data point.	Linear interpolation
  max	Selects the largest data point.	Linear interpolation
  none	Skips group by aggregation of all time series.	Zero if missing
  p50	Calculates the 50th percentile.	Linear interpolation
  p75	Calculates the 75th percentile.	Linear interpolation
  p90	Calculates the 90th percentile.	Linear interpolation
  p95	Calculates the 95th percentile.	Linear interpolation
  p99	Calculates the 99th percentile.	Linear interpolation
  p999	Calculates the 99.9th percentile.	Linear interpolation
  sum	Adds the data points together.	Linear interpolation
  zimsum	Adds the data points together.	Zero if missing

  

  For details about the R-3 and R-7 methods, see https://en.wikipedia.org/wiki/Quantile.

• filter parameter description

  Table 5 filter parameters

  Parameter	Type	Mandatory	Description	Example Value
  type	String	Yes	Filter type. For details, see Table 6.	regexp
  tagk	String	Yes	Tag key to invoke the filter on	host
  filter	String	Yes	filter expression	web[0-9]+.lax.mysite.com
  groupBy	Boolean	No	Whether or not to group the results by each value matched by the filter. The default value is false.	false

  Table 6 file type parameters

  Parameter	Description	Example Value
  literal_or	Values that tagv is equal to. The values are case sensitive.	{"type":"literal_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}
  iliteral_or	Values that tagv is equal to. The values are case insensitive.	{"type":"iliteral_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}
  not_literal_or	Values that tagv is not equal to. The values are case sensitive.	{"type":"not_literal_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}
  not_iliteral_or	Values that tagv is not equal to. The values are case insensitive.	{"type":"not_iliteral_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}
  wildcard	Asterisk wildcard that tagv must comply with. The values are case sensitive.	In the URI: host=wildcard(*mysite.com) {"type":"wildcard","tagk":"host","filter":"web*.tsdb.net","groupBy":false}
  iwildcard	Asterisk wildcard that tagv must comply with. The values are case insensitive.	{"type":"iwildcard","tagk":"host","filter":"web*.tsdb.net","groupBy":false}
  regexp	Regular expression that tagv must comply with	{"type":"regexp","tagk":"host","filter":".*","groupBy":false}
  not_key	Values that tagk is not equal to	{"type":"not_key","tagk":"host","filter":"","groupBy":false}

• valueFilter description

  Filter the returned data points based on the configured numeric condition expression. Operators such as ">" , "<" , "=" , "<=" , ">=" , "!=" , "&&" , and "||" are supported.

  Operators such as ">" , "<" , "=" , "<=" , ">=" , and "!=" are unary operators and used for number operations. Operators "&&" and "||" are binary operators used for expression operations.

  An example expression is as follows:

  1. >=10: indicates that only the result whose value is greater than or equal to 10 is returned.
  2. <5||>10: indicates that only the result whose value is less than 5 or greater than 10 is returned.
  3. >=6&&!=11: indicates that only the result whose value is greater than or equal to 6 and not equal to 11 is returned.
  

  When both operators "&&" and "||" exist in an expression, operator "&&" takes priority over operator "||" . That is, expression >=6||>11&&!=15 is equivalent to expression >=6||(>11&&!=15).

Response

• Sample response

  [
      {
          "metric": "tsd.hbase.puts",
          "tags": {
              "host": "tsdb-1.mysite.com"
          },
          "aggregatedTags": [],
          "dps": {
              "1365966001": 3758788892,
              "1365966061": 3758804070,
  ...
              "1365974281": 3778141673
          }
      },
      {
          "metric": "tsd.hbase.puts",
          "tags": {
              "host": "tsdb-2.mysite.com"
          },
          "aggregatedTags": [],
          "dps": {
              "1365966001": 3902179270,
              "1365966062": 3902197769,
  ...
              "1365974281": 3922266478
          }
      }
  ]

• Parameter description

  Table 7 Response parameters

  Parameter	Description
  metric	Metric
  tags	Tagv that is not aggregated. If aggregation exists, the value is null.
  aggregateTags	If aggregation exists, this parameter indicates the aggregated tagv.
  dps	Data point pair. A data point consists of a timestamp and a value and is serialized. If returnCount is set to true in the query request, dps will not be returned. NOTE: If the value is a floating-point number, it is displayed in double-precision (Double) mode and can be converted to a single-precision (Float) or double-precision (Double) floating point number as required.
  annotations	Comment information
  globalAnnotations	Global comments within the time span
  count	If returnCount is set to true in the query request, count indicating the number of query results will be returned.

Status Code

For details about status codes, see Response Code.