InfluxQL 参考文档

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

InfluxQL 功能支持

InfluxQL 正在进行重构，以适应 InfluxDB 3 存储引擎。此过程正在进行中，部分 InfluxQL 功能仍在实现中。有关 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 .

Strings

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

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

持续时间

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

持续时间单位

单位	含义
ns	纳秒（一秒的十亿分之一）
u 或 µ	微秒（一秒的百万分之一）
ms	毫秒（一秒的千分之一）
s	second
m	minute
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/core/reference/glossary/> #tag-key) 在 SELECT 子句中
[FROM 子句](/influxdb3/core/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 .

语句

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 执行以下步骤：

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

iterator type

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

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

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

cursor type

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

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

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

block types

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

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

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

示例

按时区分组从度量中选择

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

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 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'

子句

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 .

此页面是否有帮助？

感谢您的反馈！

支持和反馈

感谢您成为我们社区的一员！我们欢迎并鼓励您对 InfluxDB 3 Core 和本文档提供反馈和错误报告。要获得支持，请使用以下资源

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

编辑此页面提交文档问题提交 InfluxDB 3 Core 问题