influxdb/influxql/INFLUXQL.md

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

db_name             = ascii_letter { ascii_letter | decimal_digit | "_" | "-" } .

Identifiers

identifier          = unquoted_identifier | quoted_identifier .
unquoted_identifier = ascii_letter { ascii_letter | decimal_digit | "_" | "." } .
quoted_identifier   = `"` unicode_char { unicode_char } `"` .

Keywords

ALL        ALTER    AS          ASC          BEGIN
BY         CREATE   CONTINUOUS  DATABASE     DEFAULT
DELETE     DESC     DROP        DURATION     END
EXISTS     EXPLAIN  FIELD       FROM         GRANT
GROUP      IF       INNER       INSERT       INTO
KEYS       LIMIT    LIST        MEASUREMENT  MEASUREMENTS
ON         ORDER    PASSWORD    POLICY       PRIVILEGES
QUERIES    QUERY    READ        REPLICATION  RETENTION
EVOKE      SELECT   SERIES      TAG          TO
USER       VALUES   WHERE       WITH         WRITE

Literals

Numbers

int_lit             = decimal_lit .
decimal_lit         = ( "1" .. "9" ) { decimal_digit } .
float_lit           = decimals "." decimals .
decimals            = decimal_digit { decimal_digit } .

Strings

string_lit          = '"' { unicode_char } '"' .

Durations

duration_lit        = decimals duration_unit .
duration_unit       = "u" | "µ" | "s" | "h" | "d" | "w" | "ms" .

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_retention_policy_stmt |
                      drop_series_stmt |
                      drop_user_stmt |
                      grant_stmt |
                      list_continuous_queries_stmt |
                      list_databases_stmt |
                      list_field_key_stmt |
                      list_field_value_stmt |
                      list_measurements_stmt |
                      list_retention_policies |
                      list_series_stmt |
                      list_tag_key_stmt |
                      list_tag_value_stmt |
                      list_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 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;

GRANT

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;

LIST DATABASES

list_databases_stmt = "LIST DATABASES" .

Example:

-- list all databases
LIST DATABASES;

LIST RETENTION POLICIES

list_retention_policies = "LIST RETENTION POLICIES" db_name .

Example:

-- list all retention policies on a database
LIST RETENTION POLICIES mydb;

LIST USERS

list_users_stmt = "LIST USERES" .

Example:

-- list all users
LIST USERS;

Clauses

from_clause  = "FROM" measurements .

where_clause = "WHERE" expr .

on_clause    = db_name .

to_clause    = user_name .

Other

expr =

measurements =

password         = identifier .

policy_name      = identifier .

user_name        = identifier .

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