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 可以是数据库名称、测量名称、保留策略名称、订阅名称和用户名称。在这些情况下，time 在查询中不需要双引号。 time 不能是字段键或标签键； InfluxDB 拒绝将 time 作为字段键或标签键的写入，并返回错误。有关更多信息，请参阅常见问题解答。

字面量

整数

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

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

浮点数

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

float_lit           = int_lit "." int_lit .

字符串

字符串字面量必须用单引号括起来。字符串可以包含 ' 字符，只要它们被转义（即 \'）。

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

持续时间

持续时间字面量指定一段时间长度。紧跟（无空格）在下面的持续时间单位列表之后的整数字面量被解释为持续时间字面量。持续时间可以使用混合单位指定。

持续时间单位

单位	含义
ns	纳秒 (十亿分之一秒)
u 或 µ	微秒 (百万分之一秒)
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

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

drop_measurement_stmt = "DROP MEASUREMENT" measurement .

示例：

-- drop the cpu measurement
DROP MEASUREMENT "cpu"

EXPLAIN

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

许多 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

EXPLAIN ANALYZE

执行指定的 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 的成本。

execution_time

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

planning_time

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

首先，InfluxDB 确定查询的有效时间范围，并选择要访问的分片（在 InfluxDB Enterprise 中，分片可能位于远程节点上）。接下来，对于每个分片和每个测量，InfluxDB 执行以下步骤：

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

iterator type

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

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

有关迭代器的更多信息，请参阅了解迭代器。

cursor type

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 子句中引用的字段创建的条件游标。

有关游标的更多信息，请参阅了解游标。

block types

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

有关存储块的更多信息，请参阅TSM 文件。

SELECT

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

示例

从按天分组的测量中选择，并带有 timezone

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

SHOW CARDINALITY

指用于估计或精确计数测量、序列、标签键、标签键值和字段键的基数的命令组。

SHOW CARDINALITY 命令有两种变体：估计和精确。估计值是使用草图计算的，对于所有基数大小都是安全的默认值。精确值是直接从 TSM（时间结构合并树）数据中计数的，但对于高基数数据运行成本很高。除非需要，否则请使用估计变体。

仅当数据库上启用时间序列索引 (TSI) 时，才支持按 time 过滤。

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

SHOW FIELD KEY CARDINALITY
SHOW SERIES CARDINALITY
SHOW TAG KEY CARDINALITY
SHOW TAG VALUES CARDINALITY

SHOW DATABASES

show_databases_stmt = "SHOW DATABASES" .

示例

-- show all databases
SHOW DATABASES

SHOW FIELD KEY CARDINALITY

估计或精确计数当前数据库的字段键集基数，除非使用 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

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

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

show_series_stmt = "SHOW SERIES" [on_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

示例

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

SHOW SERIES EXACT CARDINALITY

估计或精确计数当前数据库的序列基数，除非使用 ON选项指定数据库。

示例

SHOW SERIES EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

SHOW SERIES EXACT CARDINALITY ON mydb

序列基数是影响 RAM 需求的主要因素。有关更多信息，请参阅：
不要有太多的序列。随着唯一序列数量的增长，内存使用量也会随之增加。高序列基数可能会迫使主机操作系统因内存不足 (OOM) 异常而终止 InfluxDB 进程。

注意： ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions> 和 LIMIT/OFFSET 子句是可选的。当使用这些查询子句时，查询会回退到精确计数。WHERE 子句中不支持按 time 过滤。

SHOW TAG KEY CARDINALITY

估计或精确计算当前数据库上标签键集合的基数，除非使用 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

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

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'

SHOW TAG VALUES CARDINALITY

估计或精确计算当前数据库上指定标签键的标签键值的基数，除非使用 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 .

此页是否对您有帮助？

感谢您的反馈！

支持与反馈

感谢您成为我们社区的一份子！我们欢迎并鼓励您提供关于 InfluxDB 和本文档的反馈和错误报告。要寻求支持，请使用以下资源

拥有年度合同或支持合同的客户可以联系 InfluxData 支持。

编辑此页提交文档问题提交 InfluxDB 问题