14 KiB
14 KiB
The Influx Query Language Specification
Introduction
This is a reference for the Influx Query Language ("InfluxQL").
InfluxQL is a SQL-like query language for interacting with InfluxDB. It has been lovingly crafted to feel familiar to those coming from other SQL or SQL-like environments while providing features specific to storing and analyzing time series data.
Notation
This specification uses the same notation used by Google's Go programming language, which can be found at http://golang.org. The syntax is specified in Extended Backus-Naur Form ("EBNF"):
Production = production_name "=" [ Expression ] "." .
Expression = Alternative { "|" Alternative } .
Alternative = Term { Term } .
Term = production_name | token [ "…" token ] | Group | Option | Repetition .
Group = "(" Expression ")" .
Option = "[" Expression "]" .
Repetition = "{" Expression "}" .
Notation operators in order of increasing precedence:
| alternation
() grouping
[] option (0 or 1 times)
{} repetition (0 to n times)
Characters & Digits
newline = /* the Unicode code point U+000A */ .
unicode_char = /* an arbitrary Unicode code point except newline */ .
ascii_letter = "A" .. "Z" | "a" .. "z" .
decimal_digit = "0" .. "9" .
Database name
Database names are more limited than other identifiers because they appear in URLs.
The rules:
- must start with an upper or lowercase ASCII letter
- may contain only ASCII leters, decimal digits, "_", and "-"
db_name = ascii_letter { ascii_letter | decimal_digit | "_" | "-" } .
Examples:
mydb
MyDB
my-db_3
Identifiers
Identifiers are things like measurement names, retention policy names, tag keys, etc.
The rules:
- double quoted identifiers can contain any unicode character other than a new
- double quoted identifiers can contain escaped
"characters (i.e.,\") - unquoted identifiers must start with an upper or lowercase ASCII character
- unquoted identifiers may contain only ASCII letters, decimal digits, "_", and "."
identifier = unquoted_identifier | quoted_identifier .
unquoted_identifier = ascii_letter { ascii_letter | decimal_digit | "_" | "." } .
quoted_identifier = `"` unicode_char { unicode_char } `"` .
Examples:
cpu
"1h.cpu"
"1_Crazy-1337.identifer>NAME"
Keywords
ALL ALTER AS ASC BEGIN BY
CREATE CONTINUOUS DATABASE DATABASES DEFAULT DELETE
DESC DROP DURATION END EXISTS EXPLAIN
FIELD FROM GRANT GROUP IF IN
INNER INSERT INTO KEY KEYS LIMIT
SHOW MEASUREMENT MEASUREMENTS OFFSET ON ORDER
PASSWORD POLICY POLICIES PRIVILEGES QUERIES QUERY
READ REPLICATION RETENTION REVOKE SELECT SERIES
TAG TO USER USERS VALUES WHERE
WITH WRITE
Literals
Numbers
InfluxQL supports decimal integer literals and float literals. Hex, octal, etc. are not currently supported.
int_lit = decimal_lit .
decimal_lit = ( "1" .. "9" ) { decimal_digit } .
float_lit = decimals "." decimals .
Strings
String literals must be surrounded by single quotes. Strings may contain ' characters as long as they are escaped (i.e., \').
string_lit = `'` { unicode_char } `'`' .
Durations
Duration literals specify a length of time and are specified by an integer followed by (without spaces) the duration units.
| Units | Meaning |
|---|---|
| u or µ | microseconds (1 millionth of a second) |
| ms | milliseconds (1 thousandth of a second) |
| s | second |
| m | minute |
| h | hour |
| d | day |
| w | week |
duration_lit = decimals duration_unit .
duration_unit = "u" | "µ" | "s" | "h" | "d" | "w" | "ms" .
Dates & Times
The date & time literal format is not specified in EBNF like the rest of this document. It is specified using Go's date / time parsing format, which is a reference date written in the format required by InfluxQL. The reference date time is:
January 2nd, 2006 at 3:04:05 PM
time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02"
Boolean
bool_lit = TRUE | FALSE .
Queries
A query is composed of one or more statements separated by a semicolon.
query = statement { ; statement } .
statement = alter_retention_policy_stmt |
create_continuous_query_stmt |
create_database_stmt |
create_retention_policy_stmt |
create_user_stmt |
delete_stmt |
drop_continuous_query_stmt |
drop_database_stmt |
drop_measurement_stmt |
drop_retention_policy_stmt |
drop_series_stmt |
drop_user_stmt |
grant_stmt |
show_continuous_queries_stmt |
show_databases_stmt |
show_field_keys_stmt |
show_measurements_stmt |
show_retention_policies |
show_series_stmt |
show_tag_keys_stmt |
show_tag_values_stmt |
show_users_stmt |
revoke_stmt |
select_stmt .
Statements
ALTER RETENTION POLICY
alter_retention_policy_stmt = "ALTER RETENTION POLICY" policy_name "ON"
db_name retention_policy_option
[ retention_policy_option ]
[ retention_policy_option ] .
policy_name = identifier .
retention_policy_option = retention_policy_duration |
retention_policy_replication |
"DEFAULT" .
retention_policy_duration = "DURATION" duration_lit .
retention_policy_replication = "REPLICATION" int_lit
Examples:
-- Set default retention policy for mydb to 1h.cpu.
ALTER RETENTION POLICY "1h.cpu" ON mydb DEFAULT;
-- Change duration and replication factor.
ALTER RETENTION POLICY policy1 ON somedb DURATION 1h REPLICATION 4
CREATE CONTINUOUS QUERY
create_continuous_query_stmt = "CREATE CONTINUOUS QUERY" query_name "ON" db_name
"BEGIN" select_stmt "END" .
query_name = identifier .
Examples:
CREATE CONTINUOUS QUERY 10m_event_count
ON db_name
BEGIN
SELECT count(value)
INTO 10m.events
FROM events
GROUP BY time(10m)
END;
-- this selects from the output of one continuous query and outputs to another series
CREATE CONTINUOUS QUERY 1h_event_count
ON db_name
BEGIN
SELECT sum(count) as count
INTO 1h.events
FROM events
GROUP BY time(1h)
END;
CREATE DATABASE
create_database_stmt = "CREATE DATABASE" db_name
Example:
CREATE DATABASE foo
CREATE RETENTION POLICY
create_retention_policy_stmt = "CREATE RETENTION POLICY" policy_name "ON"
db_name retention_policy_duration
retention_policy_replication
[ "DEFAULT" ] .
Examples
-- Create a retention policy.
CREATE RETENTION POLICY "10m.events" ON somedb DURATION 10m REPLICATION 2;
-- Create a retention policy and set it as the default.
CREATE RETENTION POLICY "10m.events" ON somedb DURATION 10m REPLICATION 2 DEFAULT;
CREATE USER
create_user_stmt = "CREATE USER" user_name "WITH PASSWORD" password
[ "WITH ALL PRIVILEGES" ] .
Examples:
-- Create a normal database user.
CREATE USER jdoe WITH PASSWORD "1337password";
-- Create a cluster admin.
-- Note: Unlike the GRANT statement, the "PRIVILEGES" keyword is required here.
CREATE USER jdoe WITH PASSWORD "1337password" WITH ALL PRIVILEGES;
DELETE
delete_stmt = "DELETE" from_clause where_clause .
Example:
-- delete data points from the cpu measurement where the region tag
-- equals 'uswest'
DELETE FROM cpu WHERE region = 'uswest';
DROP CONTINUOUS QUERY
drop_continuous_query_stmt = "DROP CONTINUOUS QUERY" query_name .
Example:
DROP CONTINUOUS QUERY myquery;
DROP DATABASE
drop_database_stmt = "DROP DATABASE" db_name .
Example:
DROP DATABASE mydb;
DROP MEASUREMENT
drop_measurement_stmt = "DROP MEASUREMENT" measurement .
Examples:
-- drop the cpu measurement
DROP MEASUREMENT cpu;
DROP RETENTION POLICY
drop_retention_policy_stmt = "DROP RETENTION POLICY" policy_name "ON" db_name .
Example:
-- drop the retention policy named 1h.cpu from mydb
DROP RETENTION POLICY "1h.cpu" ON mydb;
DROP SERIES
drop_series_stmt = "DROP SERIES" [ from_clause ] [ where_clause ]
Example:
DROP USER
drop_user_stmt = "DROP USER" user_name .
Example:
DROP USER jdoe;
GRANT
NOTE: Users can be granted privileges on databases that do not exist.
grant_stmt = "GRANT" privilege [ on_clause ] to_clause
Examples:
-- grant cluster admin privileges
GRANT ALL TO jdoe;
-- grant read access to a database
GRANT READ ON mydb TO jdoe;
SHOW CONTINUOUS QUERIES
show_continuous_queries_stmt = "SHOW CONTINUOUS QUERIES"
Example:
-- show all continuous queries
SHOW CONTINUOUS QUERIES;
SHOW DATABASES
show_databases_stmt = "SHOW DATABASES" .
Example:
-- show all databases
SHOW DATABASES;
SHOW FIELD
show_field_keys_stmt =
Examples:
SHOW MEASUREMENTS
show_measurements_stmt = [ where_clause ] [ group_by_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 RETENTION POLICIES
show_retention_policies = "SHOW RETENTION POLICIES" db_name .
Example:
-- show all retention policies on a database
SHOW RETENTION POLICIES mydb;
SHOW SERIES
show_series_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ]
[ limit_clause ] [ offset_clause ] .
Example:
SHOW TAG KEYS
show_tag_keys_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ]
[ limit_clause ] [ offset_clause ] .
Examples:
-- 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 sll tag keys where the host key = 'serverA'
SHOW TAG KEYS WHERE host = 'serverA';
SHOW TAG VALUES
show_tag_values_stmt = [ from_clause ] with_tag_clause [ where_clause ]
[ group_by_clause ] [ limit_clause ] [ offset_clause ] .
Examples:
-- show all tag values across all measurements for the region tag
SHOW TAG VALUES WITH TAG = 'region';
-- show tag values from the cpu measurement for the region tag
SHOW TAG VALUES FROM cpu WITH TAG = 'region';
-- show tag values from the cpu measurement for region & host tag keys where service = 'redis'
SHOW TAG VALUES FROM cpu WITH TAG IN (region, host) WHERE service = 'redis';
SHOW USERS
show_users_stmt = "SHOW USERS" .
Example:
-- show all users
SHOW USERS;
REVOKE
revoke_stmt = privilege [ "ON" db_name ] "FROM" user_name
Examples:
-- revoke cluster admin from jdoe
REVOKE ALL PRIVILEGES FROM jdoe;
-- revoke read privileges from jdoe on mydb
REVOKE READ ON mydb FROM jdoe;
SELECT
select_stmt = fields from_clause [ into_clause ] [ where_clause ]
[ group_by_clause ] [ order_by_clause ] [ limit_clause ]
[ offset_clause ] .
Examples:
-- select mean value from the cpu measurement where region = 'uswest' grouped by 10 minute intervals
SELECT mean(value) FROM cpu WHERE region = 'uswest' GROUP BY time(10m);
Clauses
from_clause = "FROM" measurements .
group_by_clause = "GROUP BY" dimensions .
limit_clause = "LIMIT" int_lit .
offset_clause = "OFFSET" int_lit .
on_clause = db_name .
order_by_clause = "ORDER BY" sort_fields .
to_clause = user_name .
where_clause = "WHERE" expr .
Expressions
binary_op = "+" | "-" | "*" | "/" | "AND" | "OR" | "=" | "!=" | "<" |
"<=" | ">" | ">=" .
expr = unary_expr { binary_op unary_expr } .
unary_expr = "(" expr ")" | var_ref | time_lit | string_lit |
number_lit | bool_lit | duration_lit .
## Other
decimals = decimal_digit { decimal_digit } .
dimenson = expr .
dimensons = dimenson { "," dimenson } .
field = expr [ alias ] .
fields = field { "," field } .
measurement = measurement_name |
( policy_name "." measurement_name ) |
( db_name "." [ policy_name ] "." measurement_name ) .
measurements = measurement { "," measurement } .
measurement_name = identifier .
password = identifier .
policy_name = identifier .
privilege = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" .
series_id = int_lit .
sort_field = field_name [ ASC | DESC ] .
sort_fields = sort_field { "," sort_field } .
user_name = identifier .