Influx 查询语言 (InfluxQL) 2.x 规范

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

查找Influx查询语言（InfluxQL）的定义和详细信息，包括：

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

要了解更多关于InfluxQL的信息，请浏览以下主题：

符号

语法使用扩展巴克斯-诺尔范式（“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

如果您在查询中使用 InfluxQL 关键字作为标识符，您需要在每个查询中对该标识符进行双引号包围。

关键字 time 是一个特殊情况。 time 可以是一个数据库名称， measurement 名称， retention policy 名称， subscription 名称，以及 user 名称。在这些情况下，time 在查询中不需要双引号。 time 不能是 field key 或 tag key； InfluxDB 拒绝将 time 作为字段键或标签键的写入，并返回错误。请参阅 Frequently Asked Questions 了解更多信息。

字面量

整数

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" .

日期和时间

日期和时间文字格式在EBNF中未像本文档的其余部分那样指定。它是使用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 支持使用正则表达式来指定：

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

查询

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

query               = statement { ";" statement } .

statement           = delete_stmt |
                      drop_measurement_stmt |
                      explain_stmt |
                      explain_analyze_stmt |
                      select_stmt |
                      show_databases_stmt |
                      show_field_key_cardinality_stmt |
                      show_field_keys_stmt |
                      show_measurement_exact_cardinality_stmt |
                      show_measurements_stmt |
                      show_series_exact_cardinality_stmt |
                      show_series_stmt |
                      show_tag_key_cardinality_stmt |
                      show_tag_key_exact_cardinality_stmt |
                      show_tag_keys_stmt |
                      show_tag_values_with_key = stmt |
                      show_tag_values_cardinality_stmt .

语句

删除

delete_stmt = "DELETE" ( from_clause | where_clause | from_clause where_clause ) .

示例

DELETE FROM "cpu"
DELETE FROM "cpu" WHERE time < '2000-01-01T00:00:00Z'
DELETE WHERE time < '2000-01-01T00:00:00Z'

删除度量

drop_measurement_stmt = "DROP MEASUREMENT" measurement .

示例

-- drop the cpu measurement
DROP MEASUREMENT "cpu"

解释

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

许多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 Enterprise 中，分片可能位于远程节点上）。接下来，对于每个分片和每个测量值，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 分离存储块类型，并报告解码的总块数及其在磁盘上的大小（以字节为单位）。支持以下块类型：

有关存储块的更多信息，请参见 TSM files。

选择

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 CARDINALITY 命令有两种变体：估算和精确。估算值是使用草图计算的，适用于所有基数大小的安全默认值。精确值是直接来自 TSM（时间结构化合并树）数据的计数，但对于高基数数据运行成本很高。除非必要，使用估算变体。

当数据库启用时间序列索引（TSI）时，才能支持通过 time 进行过滤。

有关详细信息，请参阅特定的SHOW CARDINALITY命令：

显示字段键基数
显示系列基数
显示标签键基数
显示标签值基数

显示数据库

show_databases_stmt = "SHOW DATABASES" .

示例

-- show all databases
SHOW DATABASES

显示字段键基数

估算或准确计算当前数据库的字段键集的基数，除非使用 ON <database> 选项指定了一个数据库。

注意： ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>，以及 LIMIT/OFFSET 子句是可选的。使用这些查询子句时，查询将退回到精确计数。只有在启用时间序列索引（TSI）时，才支持按 time 过滤，并且 time 不支持在 WHERE 子句中。

show_field_key_cardinality_stmt = "SHOW FIELD KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_field_key_exact_cardinality_stmt = "SHOW FIELD KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

示例

-- show estimated cardinality of the field key set of current database
SHOW FIELD KEY CARDINALITY
-- show exact cardinality on field key set of specified database
SHOW FIELD KEY EXACT CARDINALITY ON mydb

显示字段键

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_series_stmt = "SHOW SERIES" [on_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

示例

SHOW SERIES FROM "telegraf"."autogen"."cpu" WHERE cpu = 'cpu8'

显示系列确切基数

估计或准确计算当前数据库系列的基数，除非使用 ON 选项指定了一个数据库。

示例

显示系列确切基数" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

SHOW SERIES EXACT CARDINALITY ON mydb

系列基数是影响RAM需求的主要因素。有关更多信息，请参见：
不要有太多系列。随着唯一系列数量的增长，内存使用量也会增加。高系列基数可能会导致宿主操作系统以超出内存（OOM）异常终止InfluxDB进程。

注意： ON ， FROM ， WITH KEY = ， WHERE ， GROUP BY 和 LIMIT/OFFSET 子句是可选的。当使用这些查询子句时，查询会回退到精确计数。通过 time 进行过滤在 WHERE 子句中不支持。

显示标签键基数

估计或准确计算当前数据库中标签键集合的基数，除非使用 ON <database> 选项指定了数据库。

注意： ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, 和 LIMIT/OFFSET 子句是可选的。使用这些查询子句时，查询将回退到精确计数。仅在启用TSI（时间序列索引）时支持按 time 过滤，并且在 WHERE 子句中不支持 time。

show_tag_key_cardinality_stmt = "SHOW TAG KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_tag_key_exact_cardinality_stmt = "SHOW TAG KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

示例

-- show estimated tag key cardinality
SHOW TAG KEY CARDINALITY
-- show exact tag key cardinality
SHOW TAG KEY EXACT CARDINALITY

显示标签键

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'

显示标签值基数

估算或准确计算当前数据库中指定标签键的标签键值的基数，除非使用 ON <database> 选项指定了一个数据库。

注意： ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, 和 LIMIT/OFFSET 子句是可选的。使用这些查询子句时，查询将回退到精确计数。仅在启用TSI（时间序列索引）时支持按 time 进行过滤。

show_tag_values_cardinality_stmt = "SHOW TAG VALUES CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause

show_tag_values_exact_cardinality_stmt = "SHOW TAG VALUES EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause

示例

-- show estimated tag key values cardinality for a specified tag key
SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey"
-- show estimated tag key values cardinality for a specified tag key
SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey"
-- show exact tag key values cardinality for a specified tag key
SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey"
-- show exact tag key values cardinality for a specified tag key
SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey"

条款

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 .

使用注释来描述您的 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 .