Influx Query Language (InfluxQL) reference

Introduction

Find Influx Query Language (InfluxQL) definitions and details, including:

To learn more about InfluxQL, browse the following topics:

InfluxQL is a SQL-like query language for interacting with InfluxDB and 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 programming language specification, which can be found here. Not so coincidentally, InfluxDB is written in Go.

  1. Production  = production_name "=" [ Expression ] "." .
  2. Expression  = Alternative { "|" Alternative } .
  3. Alternative = Term { Term } .
  4. Term        = production_name | token [ "…" token ] | Group | Option | Repetition .
  5. Group       = "(" Expression ")" .
  6. Option      = "[" Expression "]" .
  7. Repetition  = "{" Expression "}" .

Notation operators in order of increasing precedence:

  1. |   alternation
  2. ()  grouping
  3. []  option (0 or 1 times)
  4. {}  repetition (0 to n times)

Query representation

Characters

InfluxQL is Unicode text encoded in UTF-8.

  1. newline             = /* the Unicode code point U+000A */ .
  2. 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.

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

Identifiers

Identifiers are tokens which refer to database names, retention policy names, user names, measurement names, tag keys, and field keys.

The rules:

  • double quoted identifiers can contain any unicode character other than a new line
  • double quoted identifiers can contain escaped " characters (i.e., \")
  • double quoted identifiers can contain InfluxQL keywords
  • unquoted identifiers must start with an upper or lowercase ASCII character or “_”

  • unquoted identifiers may contain only ASCII letters, decimal digits, and “_”

    1. identifier          = unquoted_identifier | quoted_identifier .
    2. unquoted_identifier = ( letter ) { letter | digit } .
    3. quoted_identifier   = `"` unicode_char { unicode_char } `"` .

Examples

  1. cpu
  2. _cpu_stats
  3. "1h"
  4. "anything really"
  5. "1_Crazy-1337.identifier>NAME👍"

Keywords

  1. ALL           ALTER         ANY           AS            ASC           BEGIN
  2. BY            CREATE        CONTINUOUS    DATABASE      DATABASES     DEFAULT
  3. DELETE        DESC          DESTINATIONS  DIAGNOSTICS   DISTINCT      DROP
  4. DURATION      END           EVERY         EXPLAIN       FIELD         FOR
  5. FROM          GRANT         GRANTS        GROUP         GROUPS        IN
  6. INF           INSERT        INTO          KEY           KEYS          KILL
  7. LIMIT         SHOW          MEASUREMENT   MEASUREMENTS  NAME          OFFSET
  8. ON            ORDER         PASSWORD      POLICY        POLICIES      PRIVILEGES
  9. QUERIES       QUERY         READ          REPLICATION   RESAMPLE      RETENTION
  10. REVOKE        SELECT        SERIES        SET           SHARD         SHARDS
  11. SLIMIT        SOFFSET       STATS         SUBSCRIPTION  SUBSCRIPTIONS TAG
  12. TO            USER          USERS         VALUES        WHERE         WITH
  13. WRITE

If you use an InfluxQL keywords as an identifier you will need to double quote that identifier in every query.

The keyword time is a special case. time can be a continuous query name, database name, measurement name, retention policy name, subscription name, and user name. In those cases, time does not require double quotes in queries. time cannot be a field key or tag key; InfluxDB rejects writes with time as a field key or tag key and returns an error. See Frequently Asked Questions for more information.

Literals

Integers

InfluxQL supports decimal integer literals. Hexadecimal and octal literals are not currently supported.

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

Floats

InfluxQL supports floating-point literals. Exponents are not currently supported.

  1. 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., \').

  1. 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. Durations can be specified with mixed units.

Duration units

UnitsMeaning
nsnanoseconds (1 billionth of a second)
u or µmicroseconds (1 millionth of a second)
msmilliseconds (1 thousandth of a second)
ssecond
mminute
hhour
dday
wweek
  1. duration_lit        = int_lit duration_unit .
  2. duration_unit       = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" .

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

  1. time_lit            = "2006-01-02 15:04:05.999999" | "2006-01-02" .

Booleans

  1. bool_lit            = TRUE | FALSE .

Regular Expressions

  1. regex_lit           = "/" { unicode_char } "/" .

Comparators: =~ matches against !~ doesn’t match against

Note: InfluxQL supports using regular expressions when specifying:

Currently, InfluxQL does not support using regular expressions to match non-string field values in the WHERE clause, databases, and retention polices.

Queries

A query is composed of one or more statements separated by a semicolon.

  1. query               = statement { ";" statement } .
  3. statement           = alter_retention_policy_stmt |
  4.                       create_continuous_query_stmt |
  5.                       create_database_stmt |
  6.                       create_retention_policy_stmt |
  7.                       create_subscription_stmt |
  8.                       create_user_stmt |
  9.                       delete_stmt |
  10.                       drop_continuous_query_stmt |
  11.                       drop_database_stmt |
  12.                       drop_measurement_stmt |
  13.                       drop_retention_policy_stmt |
  14.                       drop_series_stmt |
  15.                       drop_shard_stmt |
  16.                       drop_subscription_stmt |
  17.                       drop_user_stmt |
  18.                       explain_stmt |
  19.                       explain_analyze_stmt |
  20.                       grant_stmt |
  21.                       kill_query_statement |
  22.                       revoke_stmt |
  23.                       select_stmt |
  24.                       show_continuous_queries_stmt |
  25.                       show_databases_stmt |
  26.                       show_diagnostics_stmt |
  27.                       show_field_key_cardinality_stmt |
  28.                       show_field_keys_stmt |
  29.                       show_grants_stmt |
  30.                       show_measurement_cardinality_stmt |
  31.                       show_measurement_exact_cardinality_stmt |
  32.                       show_measurements_stmt |
  33.                       show_queries_stmt |
  34.                       show_retention_policies_stmt |
  35.                       show_series_cardinality_stmt |
  36.                       show_series_exact_cardinality_stmt |
  37.                       show_series_stmt |
  38.                       show_shard_groups_stmt |
  39.                       show_shards_stmt |
  40.                       show_stats_stmt |
  41.                       show_subscriptions_stmt |
  42.                       show_tag_key_cardinality_stmt |
  43.                       show_tag_key_exact_cardinality_stmt |
  44.                       show_tag_keys_stmt |
  45.                       show_tag_values_stmt |
  46.                       show_tag_values_cardinality_stmt |
  47.                       show_users_stmt .

Statements

ALTER RETENTION POLICY

  1. alter_retention_policy_stmt  = "ALTER RETENTION POLICY" policy_name on_clause
  2.                                retention_policy_option
  3.                                [ retention_policy_option ]
  4.                                [ retention_policy_option ]
  5.                                [ retention_policy_option ] .

Examples

  1. -- Set default retention policy for mydb to 1h.cpu.
  2. ALTER RETENTION POLICY "1h.cpu" ON "mydb" DEFAULT
  4. -- Change duration and replication factor.
  5. -- REPLICATION (replication factor) not valid for OSS instances.
  6. ALTER RETENTION POLICY "policy1" ON "somedb" DURATION 1h REPLICATION 4

CREATE CONTINUOUS QUERY

  1. create_continuous_query_stmt = "CREATE CONTINUOUS QUERY" query_name on_clause
  2.                                [ "RESAMPLE" resample_opts ]
  3.                                "BEGIN" select_stmt "END" .
  5. query_name                   = identifier .
  7. resample_opts                = (every_stmt for_stmt | every_stmt | for_stmt) .
  8. every_stmt                   = "EVERY" duration_lit
  9. for_stmt                     = "FOR" duration_lit

Examples

  1. -- selects from DEFAULT retention policy and writes into 6_months retention policy
  2. CREATE CONTINUOUS QUERY "10m_event_count"
  3. ON "db_name"
  4. BEGIN
  5.   SELECT count("value")
  6.   INTO "6_months"."events"
  7.   FROM "events"
  8.   GROUP (10m)
  9. END;
  11. -- this selects from the output of one continuous query in one retention policy and outputs to another series in another retention policy
  12. CREATE CONTINUOUS QUERY "1h_event_count"
  13. ON "db_name"
  14. BEGIN
  15.   SELECT sum("count") as "count"
  16.   INTO "2_years"."events"
  17.   FROM "6_months"."events"
  18.   GROUP BY time(1h)
  19. END;
  21. -- this customizes the resample interval so the interval is queried every 10s and intervals are resampled until 2m after their start time
  22. -- when resample is used, at least one of "EVERY" or "FOR" must be used
  23. CREATE CONTINUOUS QUERY "cpu_mean"
  24. ON "db_name"
  25. RESAMPLE EVERY 10s FOR 2m
  26. BEGIN
  27.   SELECT mean("value")
  28.   INTO "cpu_mean"
  29.   FROM "cpu"
  30.   GROUP BY time(1m)
  31. END;

CREATE DATABASE

  1. create_database_stmt = "CREATE DATABASE" db_name
  2.                        [ WITH
  3.                            [ retention_policy_duration ]
  4.                            [ retention_policy_replication ]
  5.                            [ retention_policy_shard_group_duration ]
  6.                            [ retention_policy_name ]
  7.                        ] .

Replication factors do not serve a purpose with single node instances.

Examples

  1. -- Create a database called foo
  2. CREATE DATABASE "foo"
  4. -- Create a database called bar with a new DEFAULT retention policy and specify the duration, replication, shard group duration, and name of that retention policy
  5. CREATE DATABASE "bar" WITH DURATION 1d REPLICATION 1 SHARD DURATION 30m NAME "myrp"
  7. -- Create a database called mydb with a new DEFAULT retention policy and specify the name of that retention policy
  8. CREATE DATABASE "mydb" WITH NAME "myrp"

CREATE RETENTION POLICY

  1. create_retention_policy_stmt = "CREATE RETENTION POLICY" policy_name on_clause
  2.                                retention_policy_duration
  3.                                retention_policy_replication
  4.                                [ retention_policy_shard_group_duration ]
  5.                                [ "DEFAULT" ] .

Replication factors do not serve a purpose with single node instances.

Examples

  1. -- Create a retention policy.
  2. CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2
  4. -- Create a retention policy and set it as the DEFAULT.
  5. CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 DEFAULT
  7. -- Create a retention policy and specify the shard group duration.
  8. CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 SHARD DURATION 30m

CREATE SUBSCRIPTION

Subscriptions tell InfluxDB to send all the data it receives to Kapacitor.

  1. create_subscription_stmt = "CREATE SUBSCRIPTION" subscription_name "ON" db_name "." retention_policy "DESTINATIONS" ("ANY"|"ALL") host { "," host} .

Examples

  1. -- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that send data to 'example.com:9090' via UDP.
  2. CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ALL 'udp://example.com:9090'
  4. -- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that round robins the data to 'h1.example.com:9090' and 'h2.example.com:9090'.
  5. CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ANY 'udp://h1.example.com:9090', 'udp://h2.example.com:9090'

CREATE USER

  1. create_user_stmt = "CREATE USER" user_name "WITH PASSWORD" password
  2.                    [ "WITH ALL PRIVILEGES" ] .

Examples

  1. -- Create a normal database user.
  2. CREATE USER "jdoe" WITH PASSWORD '1337password'
  4. -- Create an admin user.
  5. -- Note: Unlike the GRANT statement, the "PRIVILEGES" keyword is required here.
  6. CREATE USER "jdoe" WITH PASSWORD '1337password' WITH ALL PRIVILEGES

Note: The password string must be wrapped in single quotes.

DELETE

  1. delete_stmt = "DELETE" ( from_clause | where_clause | from_clause where_clause ) .

Examples

  1. DELETE FROM "cpu"
  2. DELETE FROM "cpu" WHERE time < '2000-01-01T00:00:00Z'
  3. DELETE WHERE time < '2000-01-01T00:00:00Z'

DROP CONTINUOUS QUERY

  1. drop_continuous_query_stmt = "DROP CONTINUOUS QUERY" query_name on_clause .

Example

  1. DROP CONTINUOUS QUERY "myquery" ON "mydb"

DROP DATABASE

  1. drop_database_stmt = "DROP DATABASE" db_name .

Example

  1. DROP DATABASE "mydb"

DROP MEASUREMENT

  1. drop_measurement_stmt = "DROP MEASUREMENT" measurement .

Examples

  1. -- drop the cpu measurement
  2. DROP MEASUREMENT "cpu"

DROP RETENTION POLICY

  1. drop_retention_policy_stmt = "DROP RETENTION POLICY" policy_name on_clause .

Example

  1. -- drop the retention policy named 1h.cpu from mydb
  2. DROP RETENTION POLICY "1h.cpu" ON "mydb"

DROP SERIES

  1. drop_series_stmt = "DROP SERIES" ( from_clause | where_clause | from_clause where_clause ) .

Note: Filtering by time is not supported in the WHERE clause.

Example

  1. DROP SERIES FROM "telegraf"."autogen"."cpu" WHERE cpu = 'cpu8'

DROP SHARD

  1. drop_shard_stmt = "DROP SHARD" ( shard_id ) .

Example

  1. DROP SHARD 1

DROP SUBSCRIPTION

  1. drop_subscription_stmt = "DROP SUBSCRIPTION" subscription_name "ON" db_name "." retention_policy .

Example

  1. DROP SUBSCRIPTION "sub0" ON "mydb"."autogen"

DROP USER

  1. drop_user_stmt = "DROP USER" user_name .

Example

  1. DROP USER "jdoe"

EXPLAIN

Parses and plans the query, and then prints a summary of estimated costs.

Many SQL engines use the EXPLAIN statement to show join order, join algorithms, and predicate and expression pushdown. Since InfluxQL does not support joins, the cost of a InfluxQL query is typically a function of the total series accessed, the number of iterator accesses to a TSM file, and the number of TSM blocks that need to be scanned.

The elements of EXPLAIN query plan include:

  • expression
  • auxillary fields
  • number of shards
  • number of series
  • cached values
  • number of files
  • number of blocks

  • size of blocks

    1. explain_stmt = "EXPLAIN" select_stmt .

Example

  1. > explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname;
  2. > QUERY PLAN
  3. ------
  4. EXPRESSION: sum(pointReq::integer)
  5. NUMBER OF SHARDS: 2
  6. NUMBER OF SERIES: 2
  7. CACHED VALUES: 110
  8. NUMBER OF FILES: 1
  9. NUMBER OF BLOCKS: 1
  10. SIZE OF BLOCKS: 931

EXPLAIN ANALYZE

Executes the specified SELECT statement and returns data on the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including execution time and planning time, and the iterator type and cursor type.

For example, executing the following statement:

  1. > explain analyze select mean(usage_steal) from cpu where time >= '2018-02-22T00:00:00Z' and time < '2018-02-22T12:00:00Z'

May produce an output similar to the following:

  1. EXPLAIN ANALYZE
  2. ---------------
  3. .
  4. └── select
  5.     ├── execution_time: 2.25823ms
  6.     ├── planning_time: 18.381616ms
  7.     ├── total_time: 20.639846ms
  8.     └── field_iterators
  9.         ├── labels
  10.         │   └── statement: SELECT mean(usage_steal::float) FROM telegraf."default".cpu
  11.         └── expression
  12.             ├── labels
  13.             │   └── expr: mean(usage_steal::float)
  14.             └── create_iterator
  15.                 ├── labels
  16.                 │   ├── measurement: cpu
  17.                 │   └── shard_id: 608
  18.                 ├── cursors_ref: 779
  19.                 ├── cursors_aux: 0
  20.                 ├── cursors_cond: 0
  21.                 ├── float_blocks_decoded: 431
  22.                 ├── float_blocks_size_bytes: 1003552
  23.                 ├── integer_blocks_decoded: 0
  24.                 ├── integer_blocks_size_bytes: 0
  25.                 ├── unsigned_blocks_decoded: 0
  26.                 ├── unsigned_blocks_size_bytes: 0
  27.                 ├── string_blocks_decoded: 0
  28.                 ├── string_blocks_size_bytes: 0
  29.                 ├── boolean_blocks_decoded: 0
  30.                 ├── boolean_blocks_size_bytes: 0
  31.                 └── planning_time: 14.805277ms
  2. > Note: EXPLAIN ANALYZE ignores query output, so the cost of serialization to JSON or CSV is not accounted for.
  4. #### execution\_time
  6. Shows the amount of time the query took to execute, including reading the time series data, performing operations as data flows through iterators, and draining processed data from iterators. Execution time doesn’t include the time taken to serialize the output into JSON or other formats.
  8. #### planning\_time
  10. Shows the amount of time the query took to plan. Planning a query in InfluxDB requires a number of steps. Depending on the complexity of the query, planning can require more work and consume more CPU and memory resources than the executing the query. For example, the number of series keys required to execute a query affects how quickly the query is planned and the required memory.
  12. First, InfluxDB determines the effective time range of the query and selects the shards to access (in InfluxDB Enterprise, shards may be on remote nodes). Next, for each shard and each measurement, InfluxDB performs the following steps:
  14. 1.  Select matching series keys from the index, filtered by tag predicates in the WHERE clause.
  15. 2.  Group filtered series keys into tag sets based on the GROUP BY dimensions.
  16. 3.  Enumerate each tag set and create a cursor and iterator for each series key.
  17. 4.  Merge iterators and return the merged result to the query executor.
  19. #### iterator type
  21. EXPLAIN ANALYZE supports the following iterator types:
  23. -   `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output.
  24. -   (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines.
  26. For more information about iterators, see [Understanding iterators](#understanding-iterators).
  28. #### cursor type
  30. EXPLAIN ANALYZE distinguishes 3 cursor types. While the cursor types have the same data structures and equal CPU and I/O costs, each cursor type is constructed for a different reason and separated in the final output. Consider the following cursor types when tuning a statement:
  32. -   cursor\_ref: Reference cursor created for SELECT projections that include a function, such as `last()` or `mean()`.
  33. -   cursor\_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields.
  34. -   cursor\_cond: Condition cursor created for fields referenced in a WHERE clause.
  36. For more information about cursors, see [Understanding cursors](#understanding-cursors).
  38. #### block types
  40. EXPLAIN ANALYZE separates storage block types, and reports the total number of blocks decoded and their size (in bytes) on disk. The following block types are supported:
  42. | `float` | 64-bit IEEE-754 floating-point number | | `integer` | 64-bit signed integer | | `unsigned` | 64-bit unsigned integer | | `boolean` | 1-bit, LSB encoded | | `string` | UTF-8 string |
  44. For more information about storage blocks, see [TSM files]($020e5d520792e422.md#tsm-files).
  46. ### GRANT
  48. > **NOTE:** Users can be granted privileges on databases that do not yet exist.

grant_stmt = “GRANT” privilege [ on_clause ] to_clause .

  2. #### Examples

— grant admin privileges GRANT ALL TO “jdoe”

— grant read access to a database GRANT READ ON “mydb” TO “jdoe”

  2. ### KILL QUERY
  4. Stop currently-running query.

kill_query_statement = “KILL QUERY” query_id .

  2. Where `query_id` is the query ID, displayed in the [`SHOW QUERIES`]($1101c924681ca3ec.md#list-currently-running-queries-with-show-queries) output as `qid`.
  4. > ***InfluxDB Enterprise clusters:*** To kill queries on a cluster, you need to specify the query ID (qid) and the TCP host (for example, `myhost:8088`), available in the `SHOW QUERIES` output.
  5. > 
  6. >

KILL QUERY ON ““ ```

Examples

  1. -- kill query with qid of 36 on the local host
  2. KILL QUERY 36
  1. -- kill query on InfluxDB Enterprise cluster
  2. KILL QUERY 53 ON "myhost:8088"

REVOKE

  1. revoke_stmt = "REVOKE" privilege [ on_clause ] "FROM" user_name .

Examples

  1. -- revoke admin privileges from jdoe
  2. REVOKE ALL PRIVILEGES FROM "jdoe"
  4. -- revoke read privileges from jdoe on mydb
  5. REVOKE READ ON "mydb" FROM "jdoe"

SELECT

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

Examples

Select from all measurements beginning with cpu into the same measurement name in the cpu_1h retention policy

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

Select from measurements grouped by the day with a timezone

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

SHOW CARDINALITY

Refers to the group of commands used to estimate or count exactly the cardinality of measurements, series, tag keys, tag key values, and field keys.

The SHOW CARDINALITY commands are available in two variations: estimated and exact. Estimated values are calculated using sketches and are a safe default for all cardinality sizes. Exact values are counts directly from TSM (Time-Structured Merge Tree) data, but are expensive to run for high cardinality data. Unless required, use the estimated variety.

Filtering by time is only supported when Time Series Index (TSI) is enabled on a database.

See the specific SHOW CARDINALITY commands for details:

SHOW CONTINUOUS QUERIES

  1. show_continuous_queries_stmt = "SHOW CONTINUOUS QUERIES" .

Example

  1. -- show all continuous queries
  2. SHOW CONTINUOUS QUERIES

SHOW DATABASES

  1. show_databases_stmt = "SHOW DATABASES" .

Example

  1. -- show all databases
  2. SHOW DATABASES

SHOW DIAGNOSTICS

Displays node information, such as build information, uptime, hostname, server configuration, memory usage, and Go runtime diagnostics.

For more information on using the SHOW DIAGNOSTICS command, see Using the SHOW DIAGNOSTICS command for monitoring InfluxDB.

  1. show_diagnostics_stmt = "SHOW DIAGNOSTICS"

SHOW FIELD KEY CARDINALITY

Estimates or counts exactly the cardinality of the field key set for the current database unless a database is specified using the ON <database> option.

Note: ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, and LIMIT/OFFSET clauses are optional. When using these query clauses, the query falls back to an exact count. Filtering by time is only supported when Time Series Index (TSI) is enabled and time is not supported in the WHERE clause.

  1. show_field_key_cardinality_stmt = "SHOW FIELD KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]
  3. show_field_key_exact_cardinality_stmt = "SHOW FIELD KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Examples

  1. -- show estimated cardinality of the field key set of current database
  2. SHOW FIELD KEY CARDINALITY
  3. -- show exact cardinality on field key set of specified database
  4. SHOW FIELD KEY EXACT CARDINALITY ON mydb

SHOW FIELD KEYS

  1. show_field_keys_stmt = "SHOW FIELD KEYS" [on_clause] [ from_clause ] .

Examples

  1. -- show field keys and field value data types from all measurements
  2. SHOW FIELD KEYS
  4. -- show field keys and field value data types from specified measurement
  5. SHOW FIELD KEYS FROM "cpu"

SHOW GRANTS

  1. show_grants_stmt = "SHOW GRANTS FOR" user_name .

Example

  1. -- show grants for jdoe
  2. SHOW GRANTS FOR "jdoe"

SHOW MEASUREMENT CARDINALITY

Estimates or counts exactly the cardinality of the measurement set for the current database unless a database is specified using the ON <database> option.

Note: ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, and LIMIT/OFFSET clauses are optional. When using these query clauses, the query falls back to an exact count. Filtering by time is only supported when TSI (Time Series Index) is enabled and time is not supported in the WHERE clause.

  1. show_measurement_cardinality_stmt = "SHOW MEASUREMENT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]
  3. show_measurement_exact_cardinality_stmt = "SHOW MEASUREMENT EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Example

  1. -- show estimated cardinality of measurement set on current database
  2. SHOW MEASUREMENT CARDINALITY
  3. -- show exact cardinality of measurement set on specified database
  4. SHOW MEASUREMENT EXACT CARDINALITY ON mydb

SHOW MEASUREMENTS

  1. show_measurements_stmt = "SHOW MEASUREMENTS" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

Examples

  1. -- show all measurements
  2. SHOW MEASUREMENTS
  4. -- show measurements where region tag = 'uswest' AND host tag = 'serverA'
  5. SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA'
  7. -- show measurements that start with 'h2o'
  8. SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/

SHOW QUERIES

  1. show_queries_stmt = "SHOW QUERIES" .

Example

  1. -- show all currently-running queries
  2. SHOW QUERIES
  3. --

SHOW RETENTION POLICIES

  1. show_retention_policies_stmt = "SHOW RETENTION POLICIES" [on_clause] .

Example

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

SHOW SERIES

  1. show_series_stmt = "SHOW SERIES" [on_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

Example

  1. SHOW SERIES FROM "telegraf"."autogen"."cpu" WHERE cpu = 'cpu8'

SHOW SERIES CARDINALITY

Estimates or counts exactly the cardinality of the series for the current database unless a database is specified using the ON <database> option.

Series cardinality is the major factor that affects RAM requirements. For more information, see:

Note: ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, and LIMIT/OFFSET clauses are optional. When using these query clauses, the query falls back to an exact count. Filtering by time is not supported in the WHERE clause.

  1. show_series_cardinality_stmt = "SHOW SERIES CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]
  3. show_series_exact_cardinality_stmt = "SHOW SERIES EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Examples

  1. -- show estimated cardinality of the series on current database
  2. SHOW SERIES CARDINALITY
  3. -- show estimated cardinality of the series on specified database
  4. SHOW SERIES CARDINALITY ON mydb
  5. -- show exact series cardinality
  6. SHOW SERIES EXACT CARDINALITY
  7. -- show series cardinality of the series on specified database
  8. SHOW SERIES EXACT CARDINALITY ON mydb

SHOW SHARD GROUPS

  1. show_shard_groups_stmt = "SHOW SHARD GROUPS" .

Example

  1. SHOW SHARD GROUPS

SHOW SHARDS

  1. show_shards_stmt = "SHOW SHARDS" .

Example

  1. SHOW SHARDS

SHOW STATS

Returns detailed statistics on available components of an InfluxDB node and available (enabled) components.

For more information on using the SHOW STATS command, see Using the SHOW STATS command to monitor InfluxDB.

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

SHOW STATS

  • The SHOW STATS command does not list index memory usage — use the SHOW STATS FOR 'indexes' command.
  • Statistics returned by SHOW STATS are stored in memory and reset to zero when the node is restarted, but SHOW STATS is triggered every 10 seconds to populate the _internal database.

SHOW STATS FOR <component>

  • For the specified component (<component>), the command returns available statistics.
  • For the runtime component, the command returns an overview of memory usage by the InfluxDB system, using the Go runtime package.

SHOW STATS FOR 'indexes'

  • Returns an estimate of memory use of all indexes. Index memory use is not reported with SHOW STATS because it is a potentially expensive operation.

Example

  1. > show stats
  2. name: runtime
  3. -------------
  4. Alloc   Frees   HeapAlloc       HeapIdle        HeapInUse       HeapObjects     HeapReleased    HeapSys         Lookups Mallocs NumGC   NumGoroutine    PauseTotalNs    Sys             TotalAlloc
  5. 4136056 6684537 4136056         34586624        5816320         49412           0               40402944        110     6733949 83      44              36083006        46692600        439945704
  7. name: graphite
  8. tags: proto=tcp
  9. batches_tx      bytes_rx        connections_active      connections_handled     points_rx       points_tx
  10. ----------      --------        ------------------      -------------------     ---------       ---------
  11. 159             3999750         0                       1                       158110          158110

SHOW SUBSCRIPTIONS

  1. show_subscriptions_stmt = "SHOW SUBSCRIPTIONS" .

Example

  1. SHOW SUBSCRIPTIONS

SHOW TAG KEY CARDINALITY

Estimates or counts exactly the cardinality of tag key set on the current database unless a database is specified using the ON <database> option.

Note: ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, and LIMIT/OFFSET clauses are optional. When using these query clauses, the query falls back to an exact count. Filtering by time is only supported when TSI (Time Series Index) is enabled and time is not supported in the WHERE clause.

  1. show_tag_key_cardinality_stmt = "SHOW TAG KEY CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]
  3. show_tag_key_exact_cardinality_stmt = "SHOW TAG KEY EXACT CARDINALITY" [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Examples

  1. -- show estimated tag key cardinality
  2. SHOW TAG KEY CARDINALITY
  3. -- show exact tag key cardinality
  4. SHOW TAG KEY EXACT CARDINALITY

SHOW TAG KEYS

  1. show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ]
  2.                      [ limit_clause ] [ offset_clause ] .

Examples

  1. -- show all tag keys
  2. SHOW TAG KEYS
  4. -- show all tag keys from the cpu measurement
  5. SHOW TAG KEYS FROM "cpu"
  7. -- show all tag keys from the cpu measurement where the region key = 'uswest'
  8. SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest'
  10. -- show all tag keys where the host key = 'serverA'
  11. SHOW TAG KEYS WHERE "host" = 'serverA'

SHOW TAG VALUES

  1. show_tag_values_stmt = "SHOW TAG VALUES" [on_clause] [ from_clause ] with_tag_clause [ where_clause ]
  2.                        [ limit_clause ] [ offset_clause ] .

Examples

  1. -- show all tag values across all measurements for the region tag
  2. SHOW TAG VALUES WITH KEY = "region"
  4. -- show tag values from the cpu measurement for the region tag
  5. SHOW TAG VALUES FROM "cpu" WITH KEY = "region"
  7. -- show tag values across all measurements for all tag keys that do not include the letter c
  8. SHOW TAG VALUES WITH KEY !~ /.*c.*/
  10. -- show tag values from the cpu measurement for region & host tag keys where service = 'redis'
  11. SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis'

SHOW TAG VALUES CARDINALITY

Estimates or counts exactly the cardinality of tag key values for the specified tag key on the current database unless a database is specified using the ON <database> option.

Note: ON <database>, FROM <sources>, WITH KEY = <key>, WHERE <condition>, GROUP BY <dimensions>, and LIMIT/OFFSET clauses are optional. When using these query clauses, the query falls back to an exact count. Filtering by time is only supported when TSI (Time Series Index) is enabled.

  1. 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
  3. 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

Examples

  1. -- show estimated tag key values cardinality for a specified tag key
  2. SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey"
  3. -- show estimated tag key values cardinality for a specified tag key
  4. SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey"
  5. -- show exact tag key values cardinality for a specified tag key
  6. SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey"
  7. -- show exact tag key values cardinality for a specified tag key
  8. SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey"

SHOW USERS

  1. show_users_stmt = "SHOW USERS" .

Example

  1. -- show all users
  2. SHOW USERS

Clauses

  1. from_clause     = "FROM" measurements .
  3. group_by_clause = "GROUP BY" dimensions fill(fill_option).
  5. into_clause     = "INTO" ( measurement | back_ref ).
  7. limit_clause    = "LIMIT" int_lit .
  9. offset_clause   = "OFFSET" int_lit .
  11. slimit_clause   = "SLIMIT" int_lit .
  13. soffset_clause  = "SOFFSET" int_lit .
  15. timezone_clause = tz(string_lit) .
  17. on_clause       = "ON" db_name .
  19. order_by_clause = "ORDER BY" sort_fields .
  21. to_clause       = "TO" user_name .
  23. where_clause    = "WHERE" expr .
  25. with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) .
  27. with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")"  ) .

Expressions

  1. binary_op        = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" |
  2.                    "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" .
  4. expr             = unary_expr { binary_op unary_expr } .
  6. unary_expr       = "(" expr ")" | var_ref | time_lit | string_lit | int_lit |
  7.                    float_lit | bool_lit | duration_lit | regex_lit .

Other

  1. alias            = "AS" identifier .
  3. back_ref         = ( policy_name ".:MEASUREMENT" ) |
  4.                    ( db_name "." [ policy_name ] ".:MEASUREMENT" ) .
  6. db_name          = identifier .
  8. dimension        = expr .
  10. dimensions       = dimension { "," dimension } .
  12. field_key        = identifier .
  14. field            = expr [ alias ] .
  16. fields           = field { "," field } .
  18. fill_option      = "null" | "none" | "previous" | int_lit | float_lit | "linear" .
  20. host             = string_lit .
  22. measurement      = measurement_name |
  23.                    ( policy_name "." measurement_name ) |
  24.                    ( db_name "." [ policy_name ] "." measurement_name ) .
  26. measurements     = measurement { "," measurement } .
  28. measurement_name = identifier | regex_lit .
  30. password         = string_lit .
  32. policy_name      = identifier .
  34. privilege        = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" .
  36. query_id         = int_lit .
  38. query_name       = identifier .
  40. retention_policy = identifier .
  42. retention_policy_option      = retention_policy_duration |
  43.                                retention_policy_replication |
  44.                                retention_policy_shard_group_duration |
  45.                                "DEFAULT" .
  47. retention_policy_duration    = "DURATION" duration_lit .
  49. retention_policy_replication = "REPLICATION" int_lit .
  51. retention_policy_shard_group_duration = "SHARD DURATION" duration_lit .
  53. retention_policy_name = "NAME" identifier .
  55. series_id        = int_lit .
  57. shard_id         = int_lit .
  59. sort_field       = field_key [ ASC | DESC ] .
  61. sort_fields      = sort_field { "," sort_field } .
  63. subscription_name = identifier .
  65. tag_key          = identifier .
  67. tag_keys         = tag_key { "," tag_key } .
  69. user_name        = identifier .
  71. var_ref          = measurement .

Comments

Use comments with InfluxQL statements to describe your queries.

  • A single line comment begins with two hyphens (--) and ends where InfluxDB detects a line break. This comment type cannot span several lines.
  • A multi-line comment begins with /* and ends with */. This comment type can span several lines. Multi-line comments do not support nested multi-line comments.

Query Engine Internals

Once you understand the language itself, it’s important to know how these language constructs are implemented in the query engine. This gives you an intuitive sense for how results will be processed and how to create efficient queries.

The life cycle of a query looks like this:

  1. InfluxQL query string is tokenized and then parsed into an abstract syntax tree (AST). This is the code representation of the query itself.

  2. The AST is passed to the QueryExecutor which directs queries to the appropriate handlers. For example, queries related to meta data are executed by the meta service and SELECT statements are executed by the shards themselves.

  3. The query engine then determines the shards that match the SELECT statement’s time range. From these shards, iterators are created for each field in the statement.

  4. Iterators are passed to the emitter which drains them and joins the resulting points. The emitter’s job is to convert simple time/value points into the more complex result objects that are returned to the client.

Understanding iterators

Iterators are at the heart of the query engine. They provide a simple interface for looping over a set of points. For example, this is an iterator over Float points:

  1. type FloatIterator interface {
  2.     Next() *FloatPoint
  3. }

These iterators are created through the IteratorCreator interface:

  1. type IteratorCreator interface {
  2.     CreateIterator(opt *IteratorOptions) (Iterator, error)
  3. }

The IteratorOptions provide arguments about field selection, time ranges, and dimensions that the iterator creator can use when planning an iterator. The IteratorCreator interface is used at many levels such as the Shards, Shard, and Engine. This allows optimizations to be performed when applicable such as returning a precomputed COUNT().

Iterators aren’t just for reading raw data from storage though. Iterators can be composed so that they provided additional functionality around an input iterator. For example, a DistinctIterator can compute the distinct values for each time window for an input iterator. Or a FillIterator can generate additional points that are missing from an input iterator.

This composition also lends itself well to aggregation. For example, a statement such as this:

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

In this case, MEAN(value) is a MeanIterator wrapping an iterator from the underlying shards. However, if we can add an additional iterator to determine the derivative of the mean:

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

Understanding cursors

A cursor identifies data by shard in tuples (time, value) for a single series (measurement, tag set and field). The cursor trasverses data stored as a log-structured merge-tree and handles deduplication across levels, tombstones for deleted data, and merging the cache (Write Ahead Log). A cursor sorts the (time, value) tuples by time in ascending or descending order.

For example, a query that evaluates one field for 1,000 series over 3 shards constructs a minimum of 3,000 cursors (1,000 per shard).

Understanding auxiliary fields

Because InfluxQL allows users to use selector functions such as FIRST(), LAST(), MIN(), and MAX(), the engine must provide a way to return related data at the same time with the selected point.

For example, in this query:

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

We are selecting the first value that occurs every hour but we also want to retrieve the host associated with that point. Since the Point types only specify a single typed Value for efficiency, we push the host into the auxiliary fields of the point. These auxiliary fields are attached to the point until it is passed to the emitter where the fields get split off to their own iterator.

Built-in iterators

There are many helper iterators that let us build queries:

  • Merge Iterator - This iterator combines one or more iterators into a single new iterator of the same type. This iterator guarantees that all points within a window will be output before starting the next window but does not provide ordering guarantees within the window. This allows for fast access for aggregate queries which do not need stronger sorting guarantees.

  • Sorted Merge Iterator - This iterator also combines one or more iterators into a new iterator of the same type. However, this iterator guarantees time ordering of every point. This makes it slower than the MergeIterator but this ordering guarantee is required for non-aggregate queries which return the raw data points.

  • Limit Iterator - This iterator limits the number of points per name/tag group. This is the implementation of the LIMIT & OFFSET syntax.

  • Fill Iterator - This iterator injects extra points if they are missing from the input iterator. It can provide null points, points with the previous value, or points with a specific value.

  • Buffered Iterator - This iterator provides the ability to “unread” a point back onto a buffer so it can be read again next time. This is used extensively to provide lookahead for windowing.

  • Reduce Iterator - This iterator calls a reduction function for each point in a window. When the window is complete then all points for that window are output. This is used for simple aggregate functions such as COUNT().

  • Reduce Slice Iterator - This iterator collects all points for a window first and then passes them all to a reduction function at once. The results are returned from the iterator. This is used for aggregate functions such as DERIVATIVE().

  • Transform Iterator - This iterator calls a transform function for each point from an input iterator. This is used for executing binary expressions.

  • Dedupe Iterator - This iterator only outputs unique points. It is resource intensive so it is only used for small queries such as meta query statements.

Call iterators

Function calls in InfluxQL are implemented at two levels. Some calls can be wrapped at multiple layers to improve efficiency. For example, a COUNT() can be performed at the shard level and then multiple CountIterators can be wrapped with another CountIterator to compute the count of all shards. These iterators can be created using NewCallIterator().

Some iterators are more complex or need to be implemented at a higher level. For example, the DERIVATIVE() needs to retrieve all points for a window first before performing the calculation. This iterator is created by the engine itself and is never requested to be created by the lower levels.