文档

InfluxQL参考

更新时间:
一键部署

InfluxQL是一种类似SQL的查询语言,用于与TSDB For InfluxDB®进行交互并提供专门用于存储和分析时序数据的功能。本文档是Influx查询语言(InfluxQL)的参考文档。

符号

使用Extended Backus-Naur Form(“EBNF”)指定语法。EBNF与Go语言规范中使用的符号相同。这不是巧合,因为TSDB For InfluxDB®就是用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)的集合,下划线(U+005F)被认为是字母。

InfluxQL只支持十进制数字。

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

标识符

标识符指的是数据库名字、保留策略名字、用户名、measurement的名字、tag key和field key。

规则:

  • 用双引号括起来的标识符可以包含除换行符(new line)之外的任意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的名字、保留策略名字、subscription的名字和用户名。在这些情况下,不需要在查询中用双引号将time括起来。time不能是field key或tag key;TSDB For InfluxDB®拒绝写入将time作为field key或tag key的数据,对于这种数据写入,TSDB For InfluxDB®会返回错误。请查阅FAQ获得更多相关信息。

文字

整数

InfluxQL支持十进制的整数。目前不支持十六进制和八进制。

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

浮点数

InfluxQL支持浮点数。目前不支持指数。

float_lit           = int_lit "." int_lit .

字符串

字符串必须用单引号括起来。字符串可以包含转义的'字符(也就是\')。

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

持续时间

持续时间(duration)指定了一段时间的长度。整数后面紧跟着(没有空格)以下列出的一个时间单位表示duration literal。可使用混合单位指定持续时间。

持续时间单位

单位

含义

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支持使用正则表达式,当指定: SELECT子句中的field key和tag key FROM子句中的measurement WHERE子句中的tag value GROUP BY子句中的tag key 目前,InfluxQL不支持使用正则表达式匹配WHERE子句、数据库和保留策略中的非字符串类型的field value。

查询

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

query               = statement { ";" statement } .

statement           = alter_retention_policy_stmt |
                      create_continuous_query_stmt |
                      create_database_stmt |
                      create_retention_policy_stmt |
                      create_subscription_stmt |
                      create_user_stmt |
                      delete_stmt |
                      drop_continuous_query_stmt |
                      drop_database_stmt |
                      drop_measurement_stmt |
                      drop_retention_policy_stmt |
                      drop_series_stmt |
                      drop_shard_stmt |
                      drop_subscription_stmt |
                      drop_user_stmt |
                      explain_stmt |
                      explain_analyze_stmt |
                      grant_stmt |
                      kill_query_statement |
                      revoke_stmt |
                      select_stmt |
                      show_continuous_queries_stmt |
                      show_databases_stmt |
                      show_diagnostics_stmt |
                      show_field_key_cardinality_stmt |
                      show_field_keys_stmt |
                      show_grants_stmt |
                      show_measurement_cardinality_stmt |
                      show_measurement_exact_cardinality_stmt |
                      show_measurements_stmt |
                      show_queries_stmt |
                      show_retention_policies_stmt |
                      show_series_cardinality_stmt |
                      show_series_exact_cardinality_stmt |
                      show_series_stmt |
                      show_shard_groups_stmt |
                      show_shards_stmt |
                      show_stats_stmt |
                      show_subscriptions_stmt |
                      show_tag_key_cardinality_stmt |
                      show_tag_key_exact_cardinality_stmt |
                      show_tag_keys_stmt |
                      show_tag_values_stmt |
                      show_tag_values_cardinality_stmt |
                      show_users_stmt .

语句

DELETE

重要

阿里云InfluxDB数据库支持删除数据的操作,但InfluxDB内核对删除操作存在死锁风险,可能会引起读写失败,建议您避免执行删除操作。

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'

EXPLAIN

解析并计划查询,然后打印查询预计开销的摘要。

很多SQL引擎使用EXPLAIN语句来显示join顺序、join算法以及谓词和表达式下推(predicate and expression pushdown)。由于InfluxQL不支持join,一个InfluxQL查询的开销通常是一个关于访问的总时间序列、访问TSM文件的迭代器数量和需要扫描的TSM block的数量的函数。

EXPLAIN查询计划的内容包括:

  • 表达式(expression)

  • 辅助field(auxiliary fields)

  • shard的数量(number of shards)

  • 序列的数量(number of series)

  • 缓存的值(cached values)

  • 文件的数量(number of files)

  • block的数量(number of blocks)

  • block的大小(size of blocks)

示例:

> 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

执行查询并计算运行时的实际开销。

explain_analyze_stmt = "EXPLAIN ANALYZE" select_stmt .

示例:

> explain analyze select sum(pointReq) from "_internal"."monitor"."write" group by hostname;
> EXPLAIN ANALYZE
-----------
.
└── select
├── execution_time: 242.167µs
├── planning_time: 2.165637ms
├── total_time: 2.407804ms
└── field_iterators
├── labels
│   └── statement: SELECT sum(pointReq::integer) FROM "_internal"."monitor"."write" GROUP BY hostname
└── expression
├── labels
│   └── expr: sum(pointReq::integer)
├── create_iterator
│   ├── labels
│   │   ├── measurement: write
│   │   └── shard_id: 57
│   ├── cursors_ref: 1
│   ├── cursors_aux: 0
│   ├── cursors_cond: 0
│   ├── float_blocks_decoded: 0
│   ├── float_blocks_size_bytes: 0
│   ├── integer_blocks_decoded: 1
│   ├── integer_blocks_size_bytes: 931
│   ├── 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: 1.401099ms
└── create_iterator
├── labels
│   ├── measurement: write
│   └── shard_id: 58
├── cursors_ref: 1
├── cursors_aux: 0
├── cursors_cond: 0
├── float_blocks_decoded: 0
├── float_blocks_size_bytes: 0
├── 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: 76.192µs

KILL QUERY

中断当前正在运行的查询。

kill_query_statement = "KILL QUERY" query_id .

其中,query_id是查询ID,在SHOW QUERIES输出中显示为”qid”。

示例:

-- kill query with qid of 36 on the local host
KILL QUERY 36

SELECT

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

示例:

从所有以”cpu”开头的measurement中选择数据,并将数据写入相同的measurement但保留策略为”cpu_1h”中。

SELECT mean("value") INTO "cpu_1h".:MEASUREMENT FROM /cpu.*/

查询measurement中的数据,并将结果按天进行分组(带有时区)。

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

SHOW CARDINALITY

指用于估计或精确计算measurement、序列、tag key、tag value和field key的基数的一组命令。

SHOW CARDINALITY命令有两种可用的版本:估计和精确。估计值使用草图进行计算,对于所有基数大小来说,这是一个安全默认值。精确值是直接对TSM(Time-Structured Merge Tree)数据进行计数,但是,对于基数大的数据来说,运行成本很高。除非必须要使用,否则,请使用估计的方法。

当数据库启用Time Series Index(TSI)时,才支持对time进行过滤。

请查看特定的SHOW CARDINALITY命令获得更多信息:

  • SHOW FIELD KEY CARDINALITY

  • SHOW MEASUREMENT CARDINALITY

  • SHOW SERIES CARDINALITY

  • SHOW TAG KEY CARDINALITY

  • SHOW TAG VALUES CARDINALITY

SHOW CONTINUOUS QUERIES

show_continuous_queries_stmt = "SHOW CONTINUOUS QUERIES" .

示例:

-- show all continuous queries
SHOW CONTINUOUS QUERIES

SHOW DATABASES

show_databases_stmt = "SHOW DATABASES" .

示例:

-- show all databases
SHOW DATABASES

SHOW DIAGNOSTICS

显示节点信息,例如构建信息、运行时间、主机名、服务器配置、内存使用情况和Go运行时诊断。

show_diagnostics_stmt = "SHOW DIAGNOSTICS"

SHOW FIELD KEY CARDINALITY

除非使用ON <database>指定数据库,否则估计或精确计算当前数据库的field key集的基数。

说明

ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions>和LIMIT/OFFSET子句是可选的。当使用这些查询子句时,查询将回退到精确计数(exact count)。当启用Time Series Index(TSI)时,才支持对time进行过滤。不支持在WHERE子句中使用time。

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 KEY

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 GRANTS

show_grants_stmt = "SHOW GRANTS FOR" user_name .

示例:

-- show grants for jdoe
SHOW GRANTS FOR "jdoe"

SHOW MEASUREMENT CARDINALITY

除非使用ON <database>指定数据库,否则估计或精确计算当前数据库的measurement集的基数。

说明

ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions>和LIMIT/OFFSET子句是可选的。当使用这些查询子句时,查询将回退到精确计数(exact count)。当启用Time Series Index(TSI)时,才支持对time进行过滤。不支持在WHERE子句中使用time。

show_measurement_cardinality_stmt = "SHOW MEASUREMENT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_measurement_exact_cardinality_stmt = "SHOW MEASUREMENT EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

示例:

-- show estimated cardinality of measurement set on current database
SHOW MEASUREMENT CARDINALITY

-- show exact cardinality of measurement set on specified database
SHOW MEASUREMENT EXACT CARDINALITY ON mydb

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 QUERIES

show_queries_stmt = "SHOW QUERIES" .

示例:

-- show all currently-running queries
SHOW QUERIES

SHOW RETENTION POLICIES

show_retention_policies_stmt = "SHOW RETENTION POLICIES" [on_clause] .

示例:

-- show all retention policies on a database
SHOW RETENTION POLICIES ON "mydb"

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 CARDINALITY

除非使用ON <database>指定数据库,否则估计或精确计算当前数据库的序列的基数。

序列基数是影响内存(RAM)使用量的主要因素。

说明

ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions>和LIMIT/OFFSET子句是可选的。当使用这些查询子句时,查询将回退到精确计数(exact count)。当启用Time Series Index(TSI)时,才支持对time进行过滤。不支持在WHERE子句中使用time。

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

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

示例:

-- show estimated cardinality of the series on current database
SHOW SERIES CARDINALITY

-- show estimated cardinality of the series on specified database
SHOW SERIES CARDINALITY ON mydb

-- show exact series cardinality
SHOW SERIES EXACT CARDINALITY

-- show series cardinality of the series on specified database
SHOW SERIES EXACT CARDINALITY ON mydb

SHOW SHARD GROUPS

show_shard_groups_stmt = "SHOW SHARD GROUPS" .

示例:

SHOW SHARD GROUPS

SHOW SHARD

show_shards_stmt = "SHOW SHARDS" .

示例:

SHOW SHARDS

SHOW STATS

返回一个TSDB For InfluxDB®节点和可用(以启用)的组件的可用组件的详细统计信息。

show_stats_stmt = "SHOW STATS [ FOR '<component>' | 'indexes' ]"

SHOW STATS

  • SHOW STATS命令不会列出关于索引的内存使用量—请使用SHOW STATS FOR 'indexes'命令。

  • SHOW STATS返回的统计信息存储在内存中,并且在节点重启时重新设置为0,但是,每10秒会触发一次SHOW STATS来填充数据库_internal

SHOW STATS FOR <component>

  • 该命令返回指定组件(\)的统计信息。

  • 对于runtime组件,该命令使用Go runtime返回TSDB For InfluxDB®系统的内存使用量概要。

SHOW STATS FOR 'indexes'

  • 该命令返回所有索引的内存使用量,这是一个估计值。SHOW STATS不会列出索引的内存使用量,因为这可能是一个很耗资源的操作。

示例:

> show stats
name: runtime
-------------
Alloc   Frees   HeapAlloc       HeapIdle        HeapInUse       HeapObjects     HeapReleased    HeapSys         Lookups Mallocs NumGC   NumGoroutine    PauseTotalNs    Sys             TotalAlloc
4136056 6684537 4136056         34586624        5816320         49412           0               40402944        110     6733949 83      44              36083006        46692600        439945704


name: graphite
tags: proto=tcp
batches_tx      bytes_rx        connections_active      connections_handled     points_rx       points_tx
----------      --------        ------------------      -------------------     ---------       ---------
159             3999750         0                       1                       158110          158110

SHOW SUBSCRIPTIONS

show_subscriptions_stmt = "SHOW SUBSCRIPTIONS" .

示例:

SHOW SUBSCRIPTIONS

SHOW TAG KEY CARDINALITY

除非使用ON <database>指定数据库,否则估计或精确计算当前数据库的tag key集的基数。

说明

ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions>和LIMIT/OFFSET子句是可选的。当使用这些查询子句时,查询将回退到精确计数(exact count)。当启用Time Series Index(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>指定数据库,否则估计或精确计算当前数据库的指定tag key对应的tag value的基数。

说明

ON <database>、FROM <sources>、WITH KEY = <key>、WHERE <condition>、GROUP BY <dimensions>和LIMIT/OFFSET子句是可选的。当使用这些查询子句时,查询将回退到精确计数(exact count)。当启用Time Series Index(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"

SHOW USERS

show_users_stmt = "SHOW USERS" .

示例:

-- show all users
SHOW USERS

子句

from_clause     = "FROM" measurements .

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

into_clause     = "INTO" ( measurement | back_ref ).

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 .

to_clause       = "TO" user_name .

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 .

其它

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 .

password         = string_lit .

policy_name      = identifier .

privilege        = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" .

query_id         = int_lit .

query_name       = identifier .

retention_policy = identifier .

retention_policy_option      = retention_policy_duration |
                               retention_policy_replication |
                               retention_policy_shard_group_duration |
                               "DEFAULT" .

retention_policy_duration    = "DURATION" duration_lit .

retention_policy_replication = "REPLICATION" int_lit .

retention_policy_shard_group_duration = "SHARD DURATION" duration_lit .

retention_policy_name = "NAME" identifier .

series_id        = int_lit .

shard_id         = int_lit .

sort_field       = field_key [ ASC | DESC ] .

sort_fields      = sort_field { "," sort_field } .

subscription_name = identifier .

tag_key          = identifier .

tag_keys         = tag_key { "," tag_key } .

user_name        = identifier .

var_ref          = measurement .

注释

在InfluxQL语句中使用注释来描述您的查询。

  • 单行注释以两个连字符(--)开头,并且在TSDB For InfluxDB®检测到换行符时结束。这种注释方式不能跨越多行。

  • 多行注释以/*开头,并且以*/结束。这种注释方式可以跨越多行。多行注释不支持嵌套的多行注释。

查询引擎内部

一旦您理解了语言本身,了解如何在查询引擎中实现这些语言结构是十分重要的,因为这样可以使您直观地了解如何处理结果和如何创建有效的查询。

一个查询的生命周期如下所示:

  1. 符号化InfluxQL查询语句,然后解析成一个抽象语法树(abstract syntac tree,简称AST)。这是查询本身的代码表示。

  2. 将AST传给QueryExecutor,它将查询定向到合适的处理器(handler)。例如,与元数据相关的查询由元数据服务执行,SELECT语句由shard本身执行。

  3. 然后,查询引擎确定与SELECT语句中的时间范围匹配的shard。在这些shard中,为语句中的每个field创建迭代器(iterator)。

  4. 将迭代器传到发射器(emitter),发射器将它们排出并连接结果中的数据点。发射器的工作是将简单的time/value数据点转换为更复杂的结果返回给客户端。

理解迭代器

迭代器是查询引擎的核心。迭代器提供一个简单的接口,用于循环遍历一组数据点。例如,这是浮点数上的迭代器:

type FloatIterator interface {
    Next() *FloatPoint
}

通过接口IteratorCreator创建迭代器:

type IteratorCreator interface {
    CreateIterator(opt *IteratorOptions) (Iterator, error)
}

IteratorOptions提供关于field选择、时间范围和维度的参数,使得迭代器创建者在规划迭代器的时候可以使用这些参数。接口IteratorCreator可以在多个层面使用,例如ShardsShardEngine。这允许在适当的时候执行优化,例如返回预计算的COUNT()

迭代器不仅仅用于从存储中读取原始数据,迭代器还可以组合使用,以便它们为输入迭代器(input iterator)提供额外的功能。例如,迭代器DistinctIterator可以为输入迭代器计算每个时间窗口的不同的值,或者,迭代器FillIterator可以生成输入迭代器中缺少的数据点。

这种组合也很适合用于聚合。例如,以下语句:

SELECT MEAN(value) FROM cpu GROUP BY time(10m)

在这种情况下,MEAN(value)是一个迭代器MeanIterator,它从底层的shard中包装一个迭代器。然而,我们可以添加一个额外的迭代器来决定这些平均值的导数:

SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m)

理解辅助field

因为InfluxQL允许用户使用selector函数,例如,FIRST()LAST()MIN()MAX(),所以查询引擎必须提供一种与选定数据点同时返回相关数据的方法。

例如,以下查询:

SELECT FIRST(value), host FROM cpu GROUP BY time(1h)

我们查询每小时发生的第一个value,同时我们也要获得该数据点对应的host。因为效率问题,Point类型只指定了一个value类型,所以我们将host推送到该数据点的辅助field。这些辅助field将附加到数据点,直到它被传送到发射器(在那里field会被拆分到它们自己的迭代器)。

内置迭代器

有许多辅助迭代器(helper iterators)可以让我们构建查询:

  • Merge Iterator(合并迭代器):该迭代器将一个或多个迭代器合并成一个有相同类型的新的迭代器。该迭代器保证在开始下一个窗口之前输出当前窗口内的所有数据点,但是并不保证窗口内的数据点已经排好序,这使得不需要更高排序要求的聚合查询能够快速访问。

  • Sorted Merge Iterator(排序合并迭代器):该迭代器也将一个或多个迭代器合并成一个有相同类型的新的迭代器。但是,该迭代器保证每个数据点都是按时间排好序的。这使得它的速度比MergeIterator慢,但是对于返回原始数据点的非聚合查询,这种排序保证是必须的。

  • Limit Iterator(限制迭代器):该迭代器限制了每个name/tag组的数据点个数。这是LIMITOFFSET语法的实现。

  • Fill Iterator(填充迭代器):该迭代器用额外的数据点填充在输入迭代器中缺失的数据点,它可以提供null数据点、与前一个值相同的数据点、或者有特定值的数据点。

  • Buffered Iterator(缓冲迭代器):该迭代器提供将一个数据点”unread”(未读)并且返回缓冲区的能力,以便下次读取它。这被广泛用于为窗口提供前瞻。

  • Reduce Iterator(reduce迭代器):该迭代器为窗口中的每一个数据点调用reduction函数。当窗口内的所有运算完成后,该窗口的所有数据点会被输出。这用于简单聚合函数,例如COUNT()

  • Reduce Slice Iterator(reduce slice迭代器):该迭代器首先收集窗口内的所有数据点,然后立刻将它们全部传送到一个reduction函数。结果从迭代器返回。这用于聚合函数,例如DERIVATIVE()

  • Transform Iterator(转换迭代器):该迭代器对输入迭代器中的每个数据点调用转换函数。这用于执行二进制表达式。

  • Dedupe Iterator(去重迭代器)该迭代器只输出不同的数据点。因为该迭代器非常消耗资源,所以它只用于小查询,例如元查询语句(meta query statements)。

调用迭代器

InfluxQL中的函数调用分两个级别(level)实现:shard级别和引擎级别。

为了提高效率,有些调用可以在多个层被包装,例如,COUNT()可以在shard级别执行,然后一个CountIterator可以包装多个CountIterator来计算所有shard的个数。这些迭代器可以使用NewCallIterator()来创建。

有些迭代器更复杂或者需要在更高的级别实现。例如,DERIVATIVE()首先需要获得窗口内的所有数据点,然后再执行计算,该迭代器由引擎本身创建,并且永远不会由更低级别创建。

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.

  • 本页导读 (1)
文档反馈