OpenTSDB的/ API / query（opentsdb的查询的api）简介（一）

写在前面，这里是补充宇毅的博客内容翻译几篇文档，补充下java代码的一些实现，参考文献和其他文章列表放在末尾

翻译原文档http://opentsdb.net/docs/build/html/api_http/query/index.html

---

这篇文章讲的是http查询需要的api，通过以下的结构可以实现查询和返回。尤其是子查询这种结构，与UI介绍的有很大区别，值得注意。建议和文章《OpenTSDB 查询介绍——opentsdb关于查询的基础知识和UI操作》对比来看https://blog.csdn.net/jyj1100/article/details/81324017

---

可能是API中最有用的端点，/api/query能够以所选序列化程序确定的各种格式从存储系统中提取数据。可以通过1.0查询字符串格式或正文内容提交查询。

查询API端点

/api/query/exp

/api/query/gexp

/api/query/last

该/query端点在后面介绍。从2.2数据匹配开始，可以使用DELETE动词删除查询。tsd.http.query.allow_delete必须启用配置参数才能允许删除。删除的数据将在查询结果中返回。第二次执行查询应该返回空结果。

警告

删除数据是永久性的。还要注意，删除时，可能会删除开始和结束时间边界之外的某些数据，因为数据是按小时存储的。

Verbs

• 得到

• POST

• 删除

要求

请求参数包括：

名称	数据类型	是否为必须	描述	默认	QS	RW	例
start	String, Integer	是	查询的开始时间。这可以是相对或绝对时间戳。有关详细信息，请参阅查询或读取数据。		start		1h-ago
end	String, Intege	否	查询的结束时间。如果未提供，TSD将假定服务器上的本地系统时间。这可以是相对或绝对时间戳。有关详细信息，请参阅查询或读取数据。	当前时间	end		1s-ago
queries	Array	是	用于选择要返回的时间序列的一个或多个子查询。这些可以是度量m或TSUID tsuids查询		m or tsuids		见下文
noAnnotations	Boolean	否	是否返回带有查询的注释。默认设置是返回请求的时间跨度的注释，但此标志可以禁用返回。这会影响本地和全局注释和覆盖globalAnnotations	false	no_annotations		false
globalAnnotations	Boolean	否	查询是否应检索所请求的时间跨度的全局注释	false	global_annotations		true
msResolution (or ms)	Boolean	否	是否以毫秒或秒为单位输出数据点时间戳。建议使用msResolution标志。如果未提供此标志且一秒内有多个数据点，则将使用查询的聚合函数对这些数据点进行下采样。	false	ms		true
showTSUIDs	Boolean	否	是否在结果中输出与时间序列关联的TSUID。如果将多个时间序列聚合到一个集合中，则将以排序的方式返回多个TSUID	false	show_tsuids		true
showSummary (2.2)	Boolean	否	是否在结果中显示查询周围的计时摘要。这将在地图中创建另一个与数据点对象不同的对象。请参阅查询详细信息和统计信息	false	show_summary		true
showStats (2.2)	Boolean	否	是否在结果中显示有关查询的详细计时。这将在地图中创建另一个与数据点对象不同的对象。请参阅查询详细信息和统计信息	false	show_stats		true
showQuery (2.2)	Boolean	否	是否使用查询结果返回原始子查询。如果请求包含许多子查询，那么这是确定哪些结果属于哪个子查询的好方法。请注意，在*通配符或通配符查询的情况下，这会产生大量重复输出。	false	show_query		true
delete	Boolean	否	可以使用POST传递给JSON以删除与给定查询匹配的任何数据点。	false		w	true
timezone (2.3)	String	否	基于日历的下采样的可选时区。必须是TSD服务器上安装的JRE支持的有效时区数据库名称。	世界标准时间	timezone		Asia/Kabul
useCalendar (2.3)	Boolean	否	是否使用基于给定时区的日历来进行下采样间隔	false			true

子查询（queries ）

OpenTSDB查询至少需要一个子查询，这是一种选择应该在结果集中包含哪些时间序列的方法。有两种类型：

• Metric查询 - 提供度量标准的全名以及可选的标记列表。这被优化用于将多个时间序列聚合成一个结果。

• TSUID查询 - 共享公共度量的一个或多个TSUID的列表。这针对获取不需要聚合的单个时间序列进行了优化。

查询可以包括多个子查询以及两种类型的任何混合。通过内容正文提交查询时，如果提供了TSUID列表，则将忽略该特定子查询的度量标准和标记。

每个子查询可以检索单个或一组时间序列数据，对每个集合执行聚合或分组计算。每个子查询的字段包括：

名称	数据类型	是否为必须	描述	默认值	例
aggregator	String	是	要使用的聚合函数的名称。请参见/ api / aggregators		sum
metric	String	是	存储在系统中的度量标准的名称		sys.cpu.0
rate	Boolean	否	在返回之前是否应将数据转换为增量。如果度量标准是一个连续递增的计数器，并且您想要查看数据点之间的变化率，这将非常有用。	false	true
rateOptions	Map	否	单调增加柜台处理选项	见下文	见下文
downsample	String	否	可选的下采样功能，用于减少返回的数据量。	见下文	5m-avg
tags	Map	否	要深入查看特定时间序列或按标记对结果进行分组，请提供与查询字符串格式相同的一个或多个映射值。标签在2.2中转换为过滤器。请参阅以下有关转化的说明。请注意，如果未指定任何标记，系统中的所有指标都将汇总到结果中。在2.2中弃用		见下文
filters (2.2)	List	否	过滤结果中发出的时间序列。请注意，如果未指定过滤器，则给定度量标准的所有时间序列都将聚合到结果中。		见下文
explicitTags (2.3)	Boolean	否	返回仅包含过滤器中提供的标记键的系列。	false	true
percentiles (2.4)	List	否	获取度量的直方图数据，并计算数据上给定的百分位数列表。百分位数是从0到100的浮点值。更多详细信息如下。		[99.9, 95.0, 75.0]

Rate 选项

在查询字符串中传递速率选项时，必须将选项括在花括号中。例如： m=sum:rate{counter,,1000}:if.octets.in。如果您希望使用默认值counterMax但希望提供a resetValue，则必须添加两个逗号，如上例所示。rateOptions对象中的其他字段包括以下内容：

名称	数据类型	是否为必须	描述	默认	例
counter	Boolean	否	基础数据是否是可以翻转的单调递增计数器	false	true
counterMax	Integer	否	一个正整数，表示计数器的最大值。	Java Long.MaxValue	65535
resetValue	Integer	否	一个可选值，当超出该值时，将导致聚合器返回a 0而不是计算的速率。经常重置数据源以避免虚假尖峰时很有用。	0	65000
dropResets	Boolean	否	是否简单地丢弃翻转或重置数据点。	fasle	ture

下采样

如果间隔，时间单位，c使用基于日历的下采样（从2.3开始），聚合器和（从2.2开始）可选填充策略，则下采样规范const 。下采样规范的格式为：

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

举例

1h-sum
30m-avg-nan
24h-max-zero
1dc-sum
0all-sum 

有关下采样的详细信息，支持的填充策略列表以及基于日历的下采样的操作方式，请参阅下采样。

---

这篇文章比较长，前面是必须要的部分，后面是选看和示例，我放在下一篇中。

---

OpenTSDB系列

OpenTSDB的/ API / PUT（opentsdb的输入的api）简介https://blog.csdn.net/jyj1100/article/details/81323705

OpenTSDB使用/ API / PUT进行数据存储的java实现https://blog.csdn.net/jyj1100/article/details/81330623

（转）opentsdb查询的简介——基础知识和UI操作https://blog.csdn.net/jyj1100/article/details/81324017

OpenTSDB的/ API / query（opentsdb的查询的api）简介（一）https://blog.csdn.net/jyj1100/article/details/81326660

OpenTSDB的/ API / query（opentsdb的查询的api）简介（二）https://blog.csdn.net/jyj1100/article/details/81329290

OpenTSDB使用/ API / query进行数据查询的java实现https://blog.csdn.net/jyj1100/article/details/81347817

其他OpenTSDB系列文章见

OpenTSDB系列目录https://blog.csdn.net/jyj1100/article/details/83450282