InfluxQL 参考文档

InfluxQL（Influx 查询语言）是一种类似于 SQL 的查询语言，用于与 InfluxDB 交互并处理时间序列数据。

InfluxQL特性支持

InfluxQL 正在重新架构以与 InfluxDB 3 存储引擎配合使用。这个过程仍在进行中，一些 InfluxQL 功能仍在实施中。有关 InfluxQL 功能当前实施状态的信息，请参见 InfluxQL feature support。

符号
查询表示
查询
语句
子句
表达式
评论
其他
结果集

符号

语法使用扩展巴科斯-诺尔范式（“EBNF”）指定。 EBNF 是在 Go 编程语言规范中使用的相同表示法。

Production  = production_name "=" [ Expression ] "." .
Expression  = Alternative { "|" Alternative } .
Alternative = Term { Term } .
Term        = production_name | token [ "…" token ] | Group | Option | Repetition .
Group       = "(" Expression ")" .
Option      = "[" Expression "]" .
Repetition  = "{" Expression "}" .

按优先级递增顺序的符号运算符：

|   alternation
()  grouping
[]  option (0 or 1 times)
{}  repetition (0 to n times)

查询表示

字符

InfluxQL是以UTF-8编码的Unicode文本。

newline             = /* the Unicode code point U+000A */ .
unicode_char        = /* an arbitrary Unicode code point except newline */ .

字母和数字

字母是 ASCII 字母和下划线 (_, U+005F) 的集合。

仅支持十进制数字。

letter              = ascii_letter | "_" .
ascii_letter        = "A" … "Z" | "a" … "z" .
digit               = "0" … "9" .

标识符

标识符是指代数据库名称，保留策略名称，测量名称，标签键，和字段键的记号。

规则如下：

双引号标识符可以包含除换行符以外的任何Unicode字符。
双引号标识符也可以包含转义的 " 字符（即 \"）
双引号标识符可以包括 InfluxQL 关键字。
未引用的标识符必须以大写或小写ASCII字符或“_”开头。
未加引号的标识符只能包含ASCII字母、十进制数字和“_”。

identifier          = unquoted_identifier | quoted_identifier .
unquoted_identifier = ( letter ) { letter | digit } .
quoted_identifier   = `"` unicode_char { unicode_char } `"` .

示例

cpu
_cpu_stats
"1h"
"anything really"
"1_Crazy-1337.identifier>NAME👍"

关键词

ALL           ALTER         ANY           AS            ASC           BEGIN
BY            CREATE        CONTINUOUS    DATABASE      DATABASES     DEFAULT
DELETE        DESC          DESTINATIONS  DIAGNOSTICS   DISTINCT      DROP
DURATION      END           EVERY         EXPLAIN       FIELD         FOR
FROM          GRANT         GRANTS        GROUP         GROUPS        IN
INF           INSERT        INTO          KEY           KEYS          KILL
LIMIT         SHOW          MEASUREMENT   MEASUREMENTS  NAME          OFFSET
ON            ORDER         PASSWORD      POLICY        POLICIES      PRIVILEGES
QUERIES       QUERY         READ          REPLICATION   RESAMPLE      RETENTION
REVOKE        SELECT        SERIES        SET           SHARD         SHARDS
SLIMIT        SOFFSET       STATS         SUBSCRIPTION  SUBSCRIPTIONS TAG
TO            USER          USERS         VALUES        WHERE         WITH
WRITE

如果您在每个查询中使用InfulxQL关键字作为标识符，请将标识符用双引号括起来。

关键词 time 是一个特殊情况。time 可以是一个数据库名称，measurement 名称，retention policy 名称，以及 user 名称。

在这些情况下，您不需要在查询中对 time 进行双引号处理。

time 不能是一个 field key 或 tag key; InfluxDB 拒绝将 time 作为字段键或标签键的写入，并返回错误。

字面量

整数

InfluxQL支持十进制整数文字。十六进制和八进制文字目前不被支持。

int_lit             = ( "1" … "9" ) { digit } .

浮动数

InfluxQL 支持浮点字面量。目前不支持指数。

float_lit           = int_lit "." int_lit .

字符串

字符串字面量必须用单引号包围。
字符串可以包含 ' 字符，只要它们被转义（也就是说，\'）

string_lit          = `'` { unicode_char } `'` .

持续时间

持续时间文字指定了一段时间的长度。一个整数文字紧接着（没有空格）下面列出的某个持续时间单位被解释为持续时间文字。持续时间可以用混合单位来指定。

持续时间单位

单位	含义
ns	纳秒（十亿分之一秒）
u或µ	微秒（1百万分之一秒）
ms	毫秒 (千分之一秒)
s	秒
m	分钟
h	小时
d	天
w	周

duration_lit        = int_lit duration_unit .
duration_unit       = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" .

日期和时间

与InfluxQL中使用的其他表示法不同，日期和时间字面量格式未通过EBNF指定。 InfluxQL中的日期和时间是使用Go的时间解析格式指定的，以及参考日期按InfluxQL要求的格式书写。参考日期时间是：

InfluxQL 参考日期时间：2006年1月2日下午3:04:05

time_lit            = "2006-01-02 15:04:05.999999" | "2006-01-02" .

布尔值

bool_lit            = TRUE | FALSE .

正则表达式

regex_lit           = "/" { unicode_char } "/" .

比较器： =~ 匹配 !~ 不匹配

InfluxQL支持在指定时使用正则表达式：

字段键和 [标签键](/influxdb3/clustered/reference/glossary/> #tag-key) 在 SELECT 子句中
测量在 [FROM 子句](/influxdb3/clustered/reference/> influxql/select/#from-clause) 中
标签值和字符串字段值在 WHERE 子句中
标签键在 GROUP BY 子句中

目前，InfluxQL不支持在WHERE子句中使用正则表达式匹配非字符串字段值，数据库，和保留策略。

查询

查询由一个或多个用分号 (;) 分隔的语句组成。

query               = statement { ";" statement } .

statement           = explain_stmt |
                      explain_analyze_stmt |
                      select_stmt |
                      show_field_keys_stmt |
                      show_measurements_stmt |
                      show_retention_policies_stmt |
                      show_tag_keys_stmt |
                      show_tag_values_with_key = stmt .

语句

解释

解析并规划查询，然后打印出估计成本的摘要。

许多 SQL 引擎使用 EXPLAIN 语句来显示连接顺序、连接算法以及谓词和表达式下推。由于 InfluxQL 不支持连接，InfluxQL 查询的成本通常是访问的总系列数量、对 TSM 文件的迭代器访问次数以及需要扫描的 TSM 块数量的函数。

由 EXPLAIN 生成的查询计划包含以下元素：

表达式
辅助字段
分片数量
序列的数量
缓存值
文件数量
块的数量
块的大小

explain_stmt = "EXPLAIN" select_stmt .

示例

> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname;
> QUERY PLAN
------
EXPRESSION: sum(pointReq::integer)
NUMBER OF SHARDS: 2
NUMBER OF SERIES: 2
CACHED VALUES: 110
NUMBER OF FILES: 1
NUMBER OF BLOCKS: 1
SIZE OF BLOCKS: 931

解释分析

执行指定的 SELECT 语句，并返回有关查询性能和运行时存储的数据，以树形方式可视化。使用此语句分析查询性能和存储，包括执行时间和规划时间，以及迭代器类型和光标类型。

例如，如果您执行以下语句：

> explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z'

输出类似于以下内容：

EXPLAIN ANALYZE
---------------
.
└── select
    ├── execution_time: 2.25823ms
    ├── planning_time: 18.381616ms
    ├── total_time: 20.639846ms
    └── field_iterators
        ├── labels
        │   └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu
        └── expression
            ├── labels
            │   └── expr: mean(usage_steal::float)
            └── create_iterator
                ├── labels
                │   ├── measurement: cpu
                │   └── shard_id: 608
                ├── cursors_ref: 779
                ├── cursors_aux: 0
                ├── cursors_cond: 0
                ├── float_blocks_decoded: 431
                ├── float_blocks_size_bytes: 1003552
                ├── integer_blocks_decoded: 0
                ├── integer_blocks_size_bytes: 0
                ├── unsigned_blocks_decoded: 0
                ├── unsigned_blocks_size_bytes: 0
                ├── string_blocks_decoded: 0
                ├── string_blocks_size_bytes: 0
                ├── boolean_blocks_decoded: 0
                ├── boolean_blocks_size_bytes: 0
                └── planning_time: 14.805277ms```

EXPLAIN ANALYZE 忽略查询输出，因此序列化为 JSON 或 CSV 的成本未被考虑。

执行时间

显示查询执行所需的时间，包括读取时间序列数据、在迭代器中进行操作，以及从迭代器中排出处理后的数据。执行时间不包括将输出序列化为JSON或其他格式所需的时间。

计划时间

显示查询计划所花费的时间。规划一个在 InfluxDB 中的查询需要若干步骤。根据查询的复杂性，规划可能需要比执行查询更多的工作并消耗更多的 CPU 和内存资源。例如，执行查询所需的系列键的数量会影响查询的规划速度以及规划所需的内存量。

首先，InfluxDB 确定查询的有效时间范围并选择要访问的分片。接下来，对于每个分片和每个测量，InfluxDB 执行以下步骤：

从索引中选择匹配的系列键，通过WHERE子句中的标签谓词进行过滤。
根据 GROUP BY 维度将过滤后的系列键分组到标签集。
枚举每个标签集，并为每个系列键创建一个游标和迭代器。
合并迭代器并将合并结果返回给查询执行器。

迭代器类型

EXPLAIN ANALYZE 支持以下迭代器类型：

create_iterator 节点表示本地 influxd 实例完成的工作──一个复杂的嵌套迭代器组合和合并，生成最终查询输出。
(仅限 InfluxDB Enterprise) remote_iterator 节点表示在远程机器上完成的工作。

有关迭代器的更多信息，请参见 Understanding iterators。

光标类型

EXPLAIN ANALYZE 区分了 3 种游标类型。虽然游标类型具有相同的数据结构，并且具有相等的 CPU 和 I/O 成本，但每种游标类型都是为了不同的理由构建的，并在最终输出中分开。调整语句时，请考虑以下游标类型：

cursor_ref: 为包含函数的 SELECT 投影创建的引用游标，例如 last() 或 mean()。
cursor_aux: 为简单表达式投影创建的辅助游标（不是选择器或聚合）。例如，SELECT foo FROM m 或 SELECT foo+bar FROM m，其中 foo 和 bar 是字段。
cursor_cond: 为在WHERE子句中引用的字段创建的条件游标。

有关游标的更多信息，请参阅 Understanding cursors。

区块类型

EXPLAIN ANALYZE 分别存储块类型，并报告解码的块总数及其在磁盘上的大小（以字节为单位）。支持以下块类型：

类型	描述
`float`	64位 IEEE-754 浮点数
`integer`	64位有符号整数
`unsigned`	64位无符号整数
`boolean`	1位，最低有效位编码
`string`	UTF-8 字符串

选择

select_stmt = "SELECT" fields from_clause [ where_clause ]
              [ group_by_clause ] [ order_by_clause ] [ limit_clause ]
              [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] .

示例

选择按天分组的测量数据，并带有时区

SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago')

显示字段键

show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] .

示例

-- show field keys and field value data types from all measurements
SHOW FIELD KEYS

-- show field keys and field value data types from specified measurement
SHOW FIELD KEYS FROM "cpu"

显示测量值

show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

示例

-- show all measurements
SHOW MEASUREMENTS

-- show measurements where region tag = 'uswest' AND host tag = 'serverA'
SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA'

-- show measurements that start with 'h2o'
SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/

显示标签键

show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ]
                     [ limit_clause ] [ offset_clause ] .

示例

-- show all tag keys
SHOW TAG KEYS

-- show all tag keys from the cpu measurement
SHOW TAG KEYS FROM "cpu"

-- show all tag keys from the cpu measurement where the region key = 'uswest'
SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest'

-- show all tag keys where the host key = 'serverA'
SHOW TAG KEYS WHERE "host" = 'serverA'

显示标签值

show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ]
                       [ limit_clause ] [ offset_clause ] .

示例

-- show all tag values across all measurements for the region tag
SHOW TAG VALUES WITH KEY = "region"

-- show tag values from the cpu measurement for the region tag
SHOW TAG VALUES FROM "cpu" WITH KEY = "region"

-- show tag values across all measurements for all tag keys that do not include the letter c
SHOW TAG VALUES WITH KEY !~ /.*c.*/

-- show tag values from the cpu measurement for region & host tag keys where service = 'redis'
SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis'

条款

from_clause     = "FROM" measurements .

group_by_clause = "GROUP BY" dimensions fill(fill_option).

limit_clause    = "LIMIT" int_lit .

offset_clause   = "OFFSET" int_lit .

slimit_clause   = "SLIMIT" int_lit .

soffset_clause  = "SOFFSET" int_lit .

timezone_clause = tz(string_lit) .

on_clause       = "ON" db_name .

order_by_clause = "ORDER BY" sort_fields .

where_clause    = "WHERE" expr .

with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) .

with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")"  ) .

表达式

binary_op        = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" |
                   "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" .

expr             = unary_expr { binary_op unary_expr } .

unary_expr       = "(" expr ")" | var_ref | time_lit | string_lit | int_lit |
                   float_lit | bool_lit | duration_lit | regex_lit .

默认时间范围

默认时间范围是 Unix 纪元 (1970-01-01T00:00:00Z) 到现在。

使用注释来描述您的 InfluxQL 查询。

单行注释以两个连字符 (--) 开始，并在 InfluxDB 检测到换行时结束。这种注释类型不能跨越多行。
多行注释以 /* 开始，以 */ 结束。这种注释类型可以跨越多行。多行注释不支持嵌套的多行注释。

其他

alias            = "AS" identifier .

back_ref         = ( policy_name ".:MEASUREMENT" ) |
                   ( db_name "." [ policy_name ] ".:MEASUREMENT" ) .

db_name          = identifier .

dimension        = expr .

dimensions       = dimension { "," dimension } .

field_key        = identifier .

field            = expr [ alias ] .

fields           = field { "," field } .

fill_option      = "null" | "none" | "previous" | int_lit | float_lit | "linear" .

host             = string_lit .

measurement      = measurement_name |
                   ( policy_name "." measurement_name ) |
                   ( db_name "." [ policy_name ] "." measurement_name ) .

measurements     = measurement { "," measurement } .

measurement_name = identifier | regex_lit .

policy_name      = identifier .

retention_policy = identifier .

retention_policy_name = "NAME" identifier .

series_id        = int_lit .

sort_field       = field_key [ ASC | DESC ] .

sort_fields      = sort_field { "," sort_field } .

tag_key          = identifier .

tag_keys         = tag_key { "," tag_key } .

var_ref          = measurement .