# 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 The syntax is specified using Extended Backus-Naur Form ("EBNF"). EBNF is the same notation used in the [Go](http://golang.org) programming language specification, which can be found [here](https://golang.org/ref/spec). Not so coincidentally, InfluxDB is written in 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 "}" . ``` Notation operators in order of increasing precedence: ``` | alternation () grouping [] option (0 or 1 times) {} repetition (0 to n times) ``` ## Query representation ### Characters InfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8). ``` newline = /* the Unicode code point U+000A */ . unicode_char = /* an arbitrary Unicode code point except newline */ . ``` ## Letters and digits Letters are the set of ASCII characters plus the underscore character _ (U+005F) is considered a letter. Only decimal digits are supported. ``` letter = ascii_letter | "_" . ascii_letter = "A" … "Z" | "a" … "z" . digit = "0" … "9" . ``` ## Identifiers Identifiers are tokens which refer to database names, retention policy names, user names, measurement names, tag keys, and field names. The rules: - double quoted identifiers can contain any unicode character other than a new line - double quoted identifiers can contain escaped `"` characters (i.e., `\"`) - unquoted identifiers must start with an upper or lowercase ASCII character or "_" - unquoted identifiers may contain only ASCII letters, decimal digits, and "_" ``` identifier = unquoted_identifier | quoted_identifier . unquoted_identifier = ( letter ) { letter | digit } . quoted_identifier = `"` unicode_char { unicode_char } `"` . ``` #### Examples: ``` cpu _cpu_stats "1h" "anything really" "1_Crazy-1337.identifier>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 SLIMIT SOFFSET TAG TO USER USERS VALUES WHERE WITH WRITE ``` ## Literals ### Integers InfluxQL supports decimal integer literals. Hexadecimal and octal literals are not currently supported. ``` int_lit = ( "1" … "9" ) { digit } . ``` ### Floats InfluxQL supports floating-point literals. Exponents are not currently supported. ``` float_lit = int_lit "." int_lit . ``` ### 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. An integer literal followed immediately (with no spaces) by a duration unit listed below is interpreted as a duration literal. ``` Duration unit definitions ------------------------- | 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 = int_lit duration_unit . duration_unit = "u" | "µ" | "s" | "h" | "d" | "w" | "ms" . ``` ### Dates & Times The date and 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: InfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM ``` time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" ``` ### Booleans ``` bool_lit = TRUE | FALSE . ``` ### Regular Expressions ``` regex_lit = "/" { unicode_char } "/" . ``` ## 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 ] . db_name = identifier . 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: ```sql -- 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: ```sql -- selects from default retention policy and writes into 6_months retention policy CREATE CONTINUOUS QUERY "10m_event_count" ON db_name BEGIN SELECT count(value) INTO "6_months".events FROM events GROUP BY time(10m) END; -- this selects from the output of one continuous query in one retention policy and outputs to another series in another retention policy CREATE CONTINUOUS QUERY "1h_event_count" ON db_name BEGIN SELECT sum(count) as count INTO "2_years".events FROM "6_months".events GROUP BY time(1h) END; ``` ### CREATE DATABASE ``` create_database_stmt = "CREATE DATABASE" db_name ``` #### Example: ```sql 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 ```sql -- 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: ```sql -- 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: ```sql -- 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: ```sql DROP CONTINUOUS QUERY myquery; ``` ### DROP DATABASE drop_database_stmt = "DROP DATABASE" db_name . #### Example: ```sql DROP DATABASE mydb; ``` ### DROP MEASUREMENT ``` drop_measurement_stmt = "DROP MEASUREMENT" measurement . ``` #### Examples: ```sql -- drop the cpu measurement DROP MEASUREMENT cpu; ``` ### DROP RETENTION POLICY ``` drop_retention_policy_stmt = "DROP RETENTION POLICY" policy_name "ON" db_name . ``` #### Example: ```sql -- 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: ```sql ``` ### DROP USER ``` drop_user_stmt = "DROP USER" user_name . ``` #### Example: ```sql 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: ```sql -- 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: ```sql -- show all continuous queries SHOW CONTINUOUS QUERIES; ``` ### SHOW DATABASES ``` show_databases_stmt = "SHOW DATABASES" . ``` #### Example: ```sql -- show all databases SHOW DATABASES; ``` ### SHOW FIELD show_field_keys_stmt = "SHOW FIELD KEYS" [ from_clause ] . #### Examples: ```sql -- show field keys from all measurements SHOW FIELD KEYS; -- show field keys from specified measurement SHOW FIELD KEYS FROM cpu; ``` ### SHOW MEASUREMENTS show_measurements_stmt = [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] . ```sql -- 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 ON" db_name . ``` #### Example: ```sql -- show all retention policies on a database SHOW RETENTION POLICIES ON mydb; ``` ### SHOW SERIES ``` show_series_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Example: ```sql ``` ### SHOW TAG KEYS ``` show_tag_keys_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Examples: ```sql -- 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 = [ from_clause ] with_tag_clause [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] . ``` #### Examples: ```sql -- 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: ```sql -- show all users SHOW USERS; ``` ### REVOKE ``` revoke_stmt = privilege [ "ON" db_name ] "FROM" user_name ``` #### Examples: ```sql -- 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 ] [ slimit_clause ] [ soffset_clause ]. ``` #### Examples: ```sql -- 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) fill(0); ``` ## Clauses ``` from_clause = "FROM" measurements . group_by_clause = "GROUP BY" dimensions fill(