【翻译】OpenTSDB 2.3 文档-查询过滤器（Query Filters）

查询过滤器（Query Filters）

任何数据库系统的关键功能是使用某种形式的过滤来启用获取完整数据集的子集。自版本1.x以来，OpenTSDB提供了过滤功能，扩展功能从2.2及更高版本开始。过滤器目前对标签值进行操作。这意味着在获取数据时，必须是数据库中存在的指标和tag。

示例数据

下面解释了每个过滤器的用法，需要使用数据，本文中用到的是以下数据。它由一个单一的指标metric 组成，在各种标签tag上定义了多个时间序列。T1中仅给出一个数据点作为示例。

分组

分组，是使用聚合函数和过滤器把多个时间序列组合成一个时间序列的过程。默认情况下，OpenTSDB按指标metric对所有内容进行分组，如果查询返回10个时间序列并且聚合器为sum时，则所有10个时间序列将随时间相加聚合成一个值。有关如何合并时间系列的详细信息，请参阅[聚合]（http://opentsdb.net/docs/build/html/user_guide/query/aggregators.html）。

要避免在没有任何聚合的情况下对序列进行分组和获取，在OpenTSDB2.2以后可以使用聚合none。或者，可以使用OpenTSDB 2.2及更高版本，每个过滤器基都可以禁用分组。有关如何操作的信息，请参阅API文档。

OpenTSDB 1.x - 2.1

在最初的OpenTSDB版本中，最多只有2.1，只有两种类型的过滤器可供使用，它们是隐式配置的，用于分组。允许的两个操作符是：

• • 星号（或通配符）将为检测到的每个唯一标记值返回单独的分组结果。例如，如果标签键host与有web01和web02两个值，返回结果中将分为两组，一个在web01和一个上web02。
    | - 管道（或literal_or）将仅为指定的确切标记值返回单独的结果。即它将仅匹配具有给定标签值的时间序列和每个匹配的组。

可以为每个查询提供多个过滤器，并且结果始终一起进行AND运算。这些过滤器仍可在2.x及更高版本中使用。

示例

以下示例使用v1 HTTP URI语法，其中m指定由聚合器，冒号后面是指标，括号中的是metric和值，这里使用的是等号。

例1： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01}

在这种情况下，聚合标签集将为空，因为时间序列4和5具有与整个集合不相同的标签。

例2： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01,dc=dal}

例3： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=*,dc=dal}

这次host为*，dc为dal。这将对host标记键进行分组，并返回每个唯一主机标记值的时间序列。

例4： http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{dc=dal|lax}

这里，|运算符仅用于匹配dc查询中提供的标记键的值。因此，TSD将任何时间序列与这些值组合在一起。该host标签被移动到聚集标签列表中由于每个时间序列有一个host标签，并有用于标记键多个值。

**警告：**由于这些过滤器是有限的，如果用户编写＃1，＃4和＃5这样的时间序列，则可能会因聚合时间序列而返回意外结果，这些时间序列可能包含一个公共tag但不同的附加tag。2.3和显式标记在某种程度上解决了这个问题。

OpenTSDB 2.2

在OpenTSDB 2.2中，添加了一个更灵活的过滤器框架，允许禁用分组以及其他过滤器类型，如正则表达式和通配符。过滤器框架是可插入的，允许绑定到外部系统，例如资产管理或供应系统。

**允许在同一标记键上使用多个过滤器，并且在处理时，它们将进行AND运算，**例如，如果我们有两个过滤器host=literal_or(web01),并且host=literal_or(web02)查询将始终返回空。如果同一个标记键包含两个或更多个过滤器，其中一个启用了分组group by，则另一个不启用，则对于该标记键上的所有过滤器，分组group by实际上将是启用的true。

警告:某些类型的过滤器可以导致查询慢，特别是正则表达式regexp，通配符wildcard和不区分大小写的过滤器。在从存储中获取数据之前，会基于配置的过滤器生成基于UID创的数据库过滤器，因此使用区分大小写的literal_or过滤器总是比正则表达式regexp好，因为我们可以将字符串解析为UID并将其发送到存储系统进行过滤。相反，如果您要求使用pre，post或infix过滤的正则表达式或通配符，TSD必须使用标记键UID从存储中检索所有行，然后对于每个唯一行，将UID解析回字符串，然后在生成结果。此外，有大量字符的过滤器集将在后存储处理，为了避免为后端存储系统处理创建大量过滤器，将限制过滤器数据量。此限制默认为4096并可通过tsd.query.filter.expansion_limit参数进行配置。

显式标签

从2.3及更高版本开始，如果您知道给metric的所有tag，则可以使用该explicitTags功能大大提高查询延迟。这有两个好处：

• 对于具有高基数的metric，后端可以切换到更高效的查询，以从存储中获取较小的数据子集。（特别是在2.4）
• 对于具有不同tag的度量标准，可以使用此标准来避免聚合不应包含在最终结果中的时间序列。

显式标记将创建一个底层存储查询，该查询仅获取具有给定tag的那些行。这可以允许数据库跳过不相关的行并在更短的时间内回答。

例子

以下示例使用v2 HTTP URI语法，其中m参数由聚合器，冒号，explicit_tagsURI标志组成，然后括号中的tag标签和标签过滤器由等号分隔。

例1： http://host:4242/q?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=web01}

这解决了标签键不一致的问题，允许我们只挑选＃4时间序列。

例2： http://host:4242/q?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=}{dc=}

此查询使用v2 URI语法，以避免将dc标记键放在第二组花括号中进行分组。这允许我们仅筛选出具有a host和dctag键的时间序列，同时仅对host值进行分组。它跳过时间序列＃4和＃5。

注意:使用HBase（0.98及更高版本）或Bigtable时，请确保tsd.query.enable_fuzzy_filter在配置中启用（默认情况下启用）。向后端提供了一个特殊的过滤器，它允许向前跳到我们查询所需的行，而不是迭代每个行键并比较正则表达式。

注意:使用2.4，TSDB将get针对后端发出多个请求，而不是使用扫描程序。这可以通过多个因素减少查询时间，特别是对于高基数时间序列。但是，过滤器必须只包含literal_or。

内置2.x过滤器

以下列表是OpenTSDB附带的内置过滤器。可以将其他过滤器作为插件加载。每个标题都是type在URI或JSON查询中使用的过滤器。在编写URI查询时，通过在标记键的等号后面放置过滤器名称并将过滤器值放在括号中来使用过滤器。例如{host=regexp(web[0-9]+.lax.mysite.com)}。对于JSON查询，只需使用过滤器名称作为type参数，并使用过滤器值作为filter参数，例如

{ 
  “type” ： “regexp” ，
  “filter” ： “web [0-9] +。lax.mysite.com” ，
  “tagk” ： “host” ，
  “groupBy” ： false 
}

以下示例使用URI语法。

literal_or
采用单个文字值或以|管道分隔的值列表，并返回与区分大小写的基础上的结果匹配的任何时间系列。这是一个非常有效的过滤器，因为它可以将字符串解析为UID并将其发送到存储层以进行预过滤。在SQL中，这类似于IN或=谓词。

例子

host=literal_or(web01|web02|web03) 在SQL中： WHERE host IN ('web01', 'web02', 'web03')
host=literal_or(web01) 在SQL中： WHERE host = 'web01'

ilteral_or

与literal_or功能相同但不区分大小写。请注意，这不像lteral一样有效，因为它必须从存储中后处理所有行。

not_literal_or
区分大小的literal_or，将返回与给定值列表不匹配的系列。高效，因为它可以通过存储进行预处理。

not_iliteral_or
不区分大小写not_literal_or。

wildcard
提供区分大小写的后缀，前缀，中缀和多中缀过滤。通配符是星号（星号）*。可以使用多个通配符。如果仅给出星号，则过滤器有效地返回包含标记键的任何时间序列（并且是可以预处理的有效过滤器）。在SQL领域，这类似于LIKE谓词，具有更大的灵活性。

例子

host=wildcard(*mysite.com) 在SQL中： WHERE host='%mysite.com'
host=wildcard(web*)
host=wildcard(web*mysite.com)
host=wildcard(web*mysite*)
host=wildcard(*) 这相当于v1中基本分组，并且效率很高。 

iwildcard
同样wildcard但不区分大小写。

正则表达式
从存储中提取后使用POSIX兼容正则表达式的过滤器。过滤器使用Java的内置正则表达式操作。根据使用的查询方法，请小心转义特殊字符。

例子

regexp(web.) 在SQL中： WHERE host REGEXP 'web.’
regexp(web[0-9].mysite.com)

加载过滤器
要在OpenTSDB 2.2及更高版本中显示已加载的过滤器，请调用HTTP /api/config/filters端点。这将列出加载的插件以及描述和示例用法。

插件
当开发人员添加插件时，我们会在这里列出它们。

要开发插件，只需扩展net.opentsdb.query.filter.TagVFilter类，根据插件文档创建JAR 并将其放在plugins目录中。一开始，TSD将搜索插件并加载它。如果执行错误，TSD将无法启动并将记录异常。