文档首页 > > 开发指南> 对外接口> OpenTSDB API> 查询数据

查询数据

分享
更新时间:2020/06/17 GMT+08:00

功能介绍

从OpenTSDB数据库中查询数据。

URI

  • URI格式

    POST {OpenTSDB URL}/api/query

请求

  • 请求样例
    {
        "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
                    },
                ]
            }
        ]
    }
  • 参数说明
    表1 请求参数说明

    名称

    类型

    是否必须

    描述

    start

    Integer

    起始时间,单位秒。查询结果包含该时间的值。

    说明:

    建议使用4334400秒到4291718400秒之间的时间,即从1970/02/20 12:00:00到2106/01/01 00:00:00,也可以为0。否则可能导致查询结果不正确。

    end

    Integer

    结束时间,单位秒,默认值为OpenTSDB的当前系统时间。查询结果包含该时间的值。

    说明:

    建议使用4334400秒到4291718400秒之间的时间,即从1970/02/20 12:00:00到2106/01/01 00:00:00。否则可能导致查询结果不正确。

    queries

    Array

    可以有多个查询,请参见表2

    delete

    Boolean

    如果为true,符合条件的查询结果数据都会被删除。

    说明:

    删除数据是以一小时的数据为单位的。即查询结果关联的所有小时的数据都会被删除。

    noAnnotations

    Boolean

    是否返回注释信息。

    • true:不返回。
    • false:返回。

    默认为false。

    globalAnnotations

    Boolean

    是否返回时间跨度内的全局注释。

    • true:返回。
    • false:不返回。

    默认为false。

    showTSUIDs

    Boolean

    是否在结果中返回与时间序列关联的TSUID。

    • true:如果多个时间序列被聚合成一个集合,则多个TSUID将以排序方式返回。
    • false:不返回。

    默认为false。

    showSummary

    Boolean

    是否在结果中返回时间摘要,详细信息请参见https://opentsdb.net/docs/build/html/user_guide/query/stats.html

    • true:返回。
    • false:不返回。

    默认为false。

    showStats

    Boolean

    是否在结果中返回详细时间,详细信息请参见https://opentsdb.net/docs/build/html/user_guide/query/stats.html

    • true:返回。
    • false:不返回。

    默认为false。

    showQuery

    Boolean

    是否返回带查询结果的原始子查询。

    • true:返回。
    • false:不返回。

    默认为false。

    msResolution

    Boolean

    默认情况下,查询结果中的时间戳是以秒为单位的。如果设置为true,则查询结果中的时间戳以毫秒为单位。

    returnCount

    Boolean

    是否返回查询结果的数量。

    • true:返回。
    • false:不返回。

    默认值为false。

    reverse

    Boolean

    是否以时间倒序的方式返回查询结果。

    • true:是。
    • false:否。

    默认值为false。

    onlyDelete

    Boolean

    • true:符合查询条件的结果数据都会被删除,但不返回查询结果。
    • false:该参数无效。

    默认值为false。

    returnBoolean

    Boolean

    是否将查询返回的“value”数据值转换为布尔值。

    • true:是,如果“value”数据值大于0,则转换为true,如果“value”数据值等于或小于0,则转换为false。
    • false:否。

    默认值为false。

    表2 子查询参数说明

    名称

    类型

    是否必须

    描述

    aggregator

    String

    聚合函数,请参见•aggregator说明

    metric

    String

    指标项。

    rate

    Boolean

    是否返回倾斜率。

    • true:返回。
    • false:不返回。

    默认为false。

    downsample

    String

    降时间精度采样,请参见•downsample说明

    filters

    List

    过滤器,可以设置多个过滤器,每个过滤器的格式请参见•filter参数说明

    explicitTags

    Boolean

    是否只返回filter指定的tag。

    • true:返回。
    • false:不返回。

    默认为false。

    useMultiGets

    Boolean

    是否使用MultiGet方式查询数据,默认为false。只有当“filters”“type”“literal_or”,同时“explicitTags”“true”时才会起作用。

    valueFilter

    String

    指定值过滤的表达式。请参见•valueFilter说明

  • downsample说明

    当查询的时间跨度很大,例如每秒都将温度作为数据写入OpenTSDB,每个小时会产生3600条数据点,当查询一周的数据时,会返回604800个数据点。展示如此多数据会显得很乱,通常也不需要这样精确的数据。使用降精度的方式将一段时间的数据点聚合后当作一个数据点,比如将每个小时的数据聚合为1个数据点,这样就会只显示168个数据点。

    格式:

    <Interval><units>-<aggregator>[c][-<fill policy>]
    • “Interval” :时间数值,“units”为时间单位,s秒,m分,h小时,d天。示例:1h , 30m, 24h
    • “aggregator” :聚合策略,将一段时间点聚合为一个数据点的策略。参见•aggregator说明
    • “fill policy” : 补值策略,当使用aggregator计算一段时间内的汇聚值时,遇到中间缺少的数据点时,会使用一定的策略补充数据。补值策略请参见表3
      表3 补值策略参数

      名称

      描述

      none

      默认,不补值

      nan

      补NaN

      null

      补null

      zero

      补0

      pre

      补前值(聚合后)

      downsample是先对时间线的数据聚合成为一个新的时间线后,再对查询条件的start和end时间进行过滤。

  • aggregator说明

    aggregator在降精度downsample和多条时间线聚合时使用。通过算子将多个数据点汇聚成一个数据点。汇聚的算子请参见表4

    表4 算子

    算子

    描述

    补值方式

    avg

    平均值

    线性插值

    count

    数据点数

    补0

    dev

    计算标准偏差

    线性插值

    ep50r3

    用R-3方法计算的50%都大于

    线性插值

    ep50r7

    用R-7方法计算的50%都大于

    线性插值

    ep75r3

    用R-3方法计算的75%都大于

    线性插值

    ep75r7

    用R-7方法计算的75%都大于

    线性插值

    ep90r3

    用R-3方法计算的90%都大于

    线性插值

    ep90r7

    用R-7方法计算的90%都大于

    线性插值

    ep95r3

    用R-3方法计算的95%都大于

    线性插值

    ep95r7

    用R-7方法计算的95%都大于

    线性插值

    ep99r3

    用R-3方法计算的99%都大于

    线性插值

    ep99r7

    用R-7方法计算的99%都大于

    线性插值

    ep999r3

    用R-3方法计算的99.9%都大于

    线性插值

    ep999r7

    用R-7方法计算的99.9%都大于

    线性插值

    first

    取第一个值

    -

    last

    取最后一个值

    -

    mimmin

    最小值

    补最大值

    mimmax

    最大值

    补最小值

    min

    最小值

    线性插值

    max

    最大值

    线性插值

    none

    不做计算

    补0

    p50

    50%的值都大于

    线性插值

    p75

    75%的值都大于

    线性插值

    p90

    90%的值都大于

    线性插值

    p95

    95%的值都大于

    线性插值

    p99

    99%的值都大于

    线性插值

    p999

    99.9%的值都大于

    线性插值

    sum

    求和

    线性插值

    zimsum

    求和

    补0

  • filter参数说明
    表5 filter参数

    名称

    类型

    是否必须

    描述

    示例

    type

    String

    filter类型,参见表6

    regexp

    tagk

    String

    要做filter的tag名

    host

    filter

    String

    filter的表达式值

    web[0-9]+.lax.mysite.com

    groupBy

    Boolean

    是否对tagv做groupBy,默认false

    false

    表6 file type参数

    名称

    说明

    示例

    literal_or

    tagv等于,区分大小写

    {"type":"literal_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}

    iliteral_or

    tagv等于,不区分大小写

    {"type":"iliteral_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}

    not_literal_or

    tagv不等于,区分大小写

    {"type":"not_literal_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}

    not_iliteral_or

    tagv不等于,不区分大小写

    {"type":"not_iliteral_or","tagk":"host","filter":"web01|web02|web03","groupBy":false}

    wildcard

    tagv需满足通配符表达式,区分大小写

    URI中:host=wildcard(*mysite.com)

    {"type":"wildcard","tagk":"host","filter":"web*.tsdb.net","groupBy":false}

    iwildcard

    tagv需满足通配符表达式,不区分大小写

    {"type":"iwildcard","tagk":"host","filter":"web*.tsdb.net","groupBy":false}

    regexp

    tagv需满足正则表达式

    {"type":"regexp","tagk":"host","filter":".*","groupBy":false}

    not_key

    tagk不等于

    {"type":"not_key","tagk":"host","filter":"","groupBy":false}

  • valueFilter说明

    根据设置的数值条件表达式,对最终的返回数据点进行过滤。支持 ">", "<", "=", "<=", ">=", "!=","&&","||"等操作符。

    其中 ">", "<", "=", "<=", ">=", "!=",都是单目操作符,用于操作数字;"&&","||"是双目操作符,用于操作表达式。

    表达式例子如下:

    1. 只返回value大于或等于10的的结果:>=10
    2. 只返回value小于5或者大于10的结果:<5||>10
    3. 只返回value大于等于6并且不等于11的结果:>=6&&!=11

    "&&""||"在一个表达式中同时存在时,"&&""||"的优先级高。即表达式">=6||>11&&!=15"相当于">=6||(>11&&!=15)"。

响应

  • 响应样例
    [
        {
            "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
            }
        }
    ]
  • 参数说明
    表7 响应参数说明

    名称

    描述

    metric

    指标名

    tags

    未做聚合的tagv,如果存在聚合,这个值为空。

    aggregateTags

    如果存在聚合,显示做聚合操作的tagv。

    dps

    数据点对,数据点由时间戳和值组成并做了序列化。如果查询请求中设置了“returnCount”“true”,那么“dps”不会返回。

    说明:

    如果值是浮点数,那么是以双精度(Double)方式进行显示,可根据需要转换为单精度(Float)或双精度(Double)浮点数。

    annotations

    注释信息

    globalAnnotations

    时间跨度内的全局注释

    count

    如果查询请求中设置了“returnCount”“true”,那么“count”才会返回,表示查询结果的数量。

状态码

状态码请参见响应码

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问