{"id":20259955,"url":"https://github.com/influxdata/influxql","last_synced_at":"2025-04-12T02:54:30.878Z","repository":{"id":26454798,"uuid":"108895482","full_name":"influxdata/influxql","owner":"influxdata","description":"Package influxql implements a parser for the InfluxDB query language.","archived":false,"fork":false,"pushed_at":"2025-03-21T16:44:18.000Z","size":896,"stargazers_count":167,"open_issues_count":13,"forks_count":48,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-05T00:01:31.336Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/influxdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-30T19:00:24.000Z","updated_at":"2025-03-18T13:14:58.000Z","dependencies_parsed_at":"2022-09-06T21:53:40.615Z","dependency_job_id":"0c588851-9faa-4e53-8646-c5f3f9d9e548","html_url":"https://github.com/influxdata/influxql","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Finfluxql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Finfluxql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Finfluxql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Finfluxql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/influxdata","download_url":"https://codeload.github.com/influxdata/influxql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248509892,"owners_count":21116125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T11:17:25.734Z","updated_at":"2025-04-12T02:54:30.849Z","avatar_url":"https://github.com/influxdata.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Influx Query Language Specification\n\n## Introduction\n\nThis is a reference for the Influx Query Language (\"InfluxQL\").\n\nInfluxQL is a SQL-like query language for interacting with InfluxDB.  It has\nbeen lovingly crafted to feel familiar to those coming from other SQL or\nSQL-like environments while providing features specific to storing and analyzing\ntime series data.\n\n\n## Notation\n\nThe syntax is specified using Extended Backus-Naur Form (\"EBNF\").  EBNF is the\nsame notation used in the [Go](http://golang.org) programming language\nspecification, which can be found [here](https://golang.org/ref/spec).  Not so\ncoincidentally, InfluxDB is written in Go.\n\n```\nProduction  = production_name \"=\" [ Expression ] \".\" .\nExpression  = Alternative { \"|\" Alternative } .\nAlternative = Term { Term } .\nTerm        = production_name | token [ \"…\" token ] | Group | Option | Repetition .\nGroup       = \"(\" Expression \")\" .\nOption      = \"[\" Expression \"]\" .\nRepetition  = \"{\" Expression \"}\" .\n```\n\nNotation operators in order of increasing precedence:\n\n```\n|   alternation\n()  grouping\n[]  option (0 or 1 times)\n{}  repetition (0 to n times)\n```\n\n## Comments\n\nBoth single and multiline comments are supported. A comment is treated\nthe same as whitespace by the parser.\n\n```\n-- single line comment\n/*\n    multiline comment\n*/\n```\n\nSingle line comments will skip all text until the scanner hits a\nnewline. Multiline comments will skip all text until the end comment\nmarker is hit. Nested multiline comments are not supported so the\nfollowing does not work:\n\n```\n/* /* this does not work */ */\n```\n\n## Query representation\n\n### Characters\n\nInfluxQL is Unicode text encoded in [UTF-8](http://en.wikipedia.org/wiki/UTF-8).\n\n```\nnewline             = /* the Unicode code point U+000A */ .\nunicode_char        = /* an arbitrary Unicode code point except newline */ .\n```\n\n## Letters and digits\n\nLetters are the set of ASCII characters plus the underscore character _ (U+005F)\nis considered a letter.\n\nOnly decimal digits are supported.\n\n```\nletter              = ascii_letter | \"_\" .\nascii_letter        = \"A\" … \"Z\" | \"a\" … \"z\" .\ndigit               = \"0\" … \"9\" .\n```\n\n## Identifiers\n\nIdentifiers are tokens which refer to database names, retention policy names,\nuser names, measurement names, tag keys, and field keys.\n\nThe rules:\n\n- double quoted identifiers can contain any unicode character other than a new line\n- double quoted identifiers can contain escaped `\"` characters (i.e., `\\\"`)\n- double quoted identifiers can contain InfluxQL keywords\n- unquoted identifiers must start with an upper or lowercase ASCII character or \"_\"\n- unquoted identifiers may contain only ASCII letters, decimal digits, and \"_\"\n\n```\nidentifier          = unquoted_identifier | quoted_identifier .\nunquoted_identifier = ( letter ) { letter | digit } .\nquoted_identifier   = `\"` unicode_char { unicode_char } `\"` .\n```\n\n#### Examples:\n\n```\ncpu\n_cpu_stats\n\"1h\"\n\"anything really\"\n\"1_Crazy-1337.identifier\u003eNAME👍\"\n```\n\n## Keywords\n\n```\nALL           ALTER         ANALYZE       ANY           AS            ASC\nBEGIN         BY            CREATE        CONTINUOUS    DATABASE      DATABASES\nDEFAULT       DELETE        DESC          DESTINATIONS  DIAGNOSTICS   DISTINCT\nDROP          DURATION      END           EVERY         EXPLAIN       FIELD\nFOR           FROM          GRANT         GRANTS        GROUP         GROUPS\nIN            INF           INSERT        INTO          KEY           KEYS\nKILL          LIMIT         SHOW          MEASUREMENT   MEASUREMENTS  NAME\nOFFSET        ON            ORDER         PASSWORD      POLICY        POLICIES\nPRIVILEGES    QUERIES       QUERY         READ          REPLICATION   RESAMPLE\nRETENTION     REVOKE        SELECT        SERIES        SET           SHARD\nSHARDS        SLIMIT        SOFFSET       STATS         SUBSCRIPTION  SUBSCRIPTIONS\nTAG           TO            USER          USERS         VALUES        WHERE\nWITH          WRITE\n```\n\n## Literals\n\n### Integers\n\nInfluxQL supports decimal integer literals.  Hexadecimal and octal literals are\nnot currently supported.\n\n```\nint_lit             = [ \"+\" | \"-\" ] ( \"1\" … \"9\" ) { digit } .\n```\n\n### Floats\n\nInfluxQL supports floating-point literals.  Exponents are not currently supported.\n\n```\nfloat_lit           = [ \"+\" | \"-\" ] ( \".\" digit { digit } | digit { digit } \".\" { digit } ) .\n```\n\n### Strings\n\nString literals must be surrounded by single quotes. Strings may contain `'`\ncharacters as long as they are escaped (i.e., `\\'`).\n\n```\nstring_lit          = `'` { unicode_char } `'` .\n```\n\n### Durations\n\nDuration literals specify a length of time.  An integer literal followed\nimmediately (with no spaces) by a duration unit listed below is interpreted as\na duration literal.\n\n### Duration units\n| Units  | Meaning                                 |\n|--------|-----------------------------------------|\n| u or µ | microseconds (1 millionth of a second)  |\n| ms     | milliseconds (1 thousandth of a second) |\n| s      | second                                  |\n| m      | minute                                  |\n| h      | hour                                    |\n| d      | day                                     |\n| w      | week                                    |\n\n```\nduration_lit        = int_lit duration_unit .\nduration_unit       = \"u\" | \"µ\" | \"ms\" | \"s\" | \"m\" | \"h\" | \"d\" | \"w\" .\n```\n\n### Dates \u0026 Times\n\nThe 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:\n\nInfluxQL reference date time: January 2nd, 2006 at 3:04:05 PM\n\n```\ntime_lit            = \"2006-01-02 15:04:05.999999\" | \"2006-01-02\" .\n```\n\n### Booleans\n\n```\nbool_lit            = TRUE | FALSE .\n```\n\n### Regular Expressions\n\n```\nregex_lit           = \"/\" { unicode_char } \"/\" .\n```\n\n**Comparators:**\n`=~` matches against\n`!~` doesn't match against\n\n\u003e **Note:** Use regular expressions to match measurements and tags.\nYou cannot use regular expressions to match databases, retention policies, or fields.\n\n## Queries\n\nA query is composed of one or more statements separated by a semicolon.\n\n```\nquery               = statement { \";\" statement } .\n\nstatement           = alter_retention_policy_stmt |\n                      create_continuous_query_stmt |\n                      create_database_stmt |\n                      create_retention_policy_stmt |\n                      create_subscription_stmt |\n                      create_user_stmt |\n                      delete_stmt |\n                      drop_continuous_query_stmt |\n                      drop_database_stmt |\n                      drop_measurement_stmt |\n                      drop_retention_policy_stmt |\n                      drop_series_stmt |\n                      drop_shard_stmt |\n                      drop_subscription_stmt |\n                      drop_user_stmt |\n                      explain_stmt |\n                      grant_stmt |\n                      kill_query_statement |\n                      show_continuous_queries_stmt |\n                      show_databases_stmt |\n                      show_field_keys_stmt |\n                      show_grants_stmt |\n                      show_measurements_stmt |\n                      show_queries_stmt |\n                      show_retention_policies |\n                      show_series_stmt |\n                      show_shard_groups_stmt |\n                      show_shards_stmt |\n                      show_subscriptions_stmt|\n                      show_tag_keys_stmt |\n                      show_tag_values_stmt |\n                      show_users_stmt |\n                      revoke_stmt |\n                      select_stmt .\n```\n\n## Statements\n\n### ALTER RETENTION POLICY\n\n```\nalter_retention_policy_stmt  = \"ALTER RETENTION POLICY\" policy_name on_clause\n                               retention_policy_option\n                               [ retention_policy_option ]\n                               [ retention_policy_option ]\n                               [ retention_policy_option ] .\n```\n\n\u003e Replication factors do not serve a purpose with single node instances.\n\n#### Examples:\n\n```sql\n-- Set default retention policy for mydb to 1h.cpu.\nALTER RETENTION POLICY \"1h.cpu\" ON \"mydb\" DEFAULT\n\n-- Change duration and replication factor.\nALTER RETENTION POLICY \"policy1\" ON \"somedb\" DURATION 1h REPLICATION 4\n```\n\n### CREATE CONTINUOUS QUERY\n\n```\ncreate_continuous_query_stmt = \"CREATE CONTINUOUS QUERY\" query_name on_clause\n                               [ \"RESAMPLE\" resample_opts ]\n                               \"BEGIN\" select_stmt \"END\" .\n\nquery_name                   = identifier .\n\nresample_opts                = (every_stmt for_stmt | every_stmt | for_stmt) .\nevery_stmt                   = \"EVERY\" duration_lit\nfor_stmt                     = \"FOR\" duration_lit\n```\n\n#### Examples:\n\n```sql\n-- selects from DEFAULT retention policy and writes into 6_months retention policy\nCREATE CONTINUOUS QUERY \"10m_event_count\"\nON \"db_name\"\nBEGIN\n  SELECT count(\"value\")\n  INTO \"6_months\".\"events\"\n  FROM \"events\"\n  GROUP BY time(10m)\nEND;\n\n-- this selects from the output of one continuous query in one retention policy and outputs to another series in another retention policy\nCREATE CONTINUOUS QUERY \"1h_event_count\"\nON \"db_name\"\nBEGIN\n  SELECT sum(\"count\") as \"count\"\n  INTO \"2_years\".\"events\"\n  FROM \"6_months\".\"events\"\n  GROUP BY time(1h)\nEND;\n\n-- this customizes the resample interval so the interval is queried every 10s and intervals are resampled until 2m after their start time\n-- when resample is used, at least one of \"EVERY\" or \"FOR\" must be used\nCREATE CONTINUOUS QUERY \"cpu_mean\"\nON \"db_name\"\nRESAMPLE EVERY 10s FOR 2m\nBEGIN\n  SELECT mean(\"value\")\n  INTO \"cpu_mean\"\n  FROM \"cpu\"\n  GROUP BY time(1m)\nEND;\n```\n\n### CREATE DATABASE\n\n```\ncreate_database_stmt = \"CREATE DATABASE\" db_name\n                       [ WITH\n                           [ retention_policy_duration ]\n                           [ retention_policy_replication ]\n                           [ retention_policy_shard_group_duration ]\n                           [ retention_policy_name ]\n                       ] .\n```\n\n\u003e Replication factors do not serve a purpose with single node instances.\n\n#### Examples:\n\n```sql\n-- Create a database called foo\nCREATE DATABASE \"foo\"\n\n-- 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\nCREATE DATABASE \"bar\" WITH DURATION 1d REPLICATION 1 SHARD DURATION 30m NAME \"myrp\"\n\n-- Create a database called mydb with a new DEFAULT retention policy and specify the name of that retention policy\nCREATE DATABASE \"mydb\" WITH NAME \"myrp\"\n```\n\n### CREATE RETENTION POLICY\n\n```\ncreate_retention_policy_stmt = \"CREATE RETENTION POLICY\" policy_name on_clause\n                               retention_policy_duration\n                               retention_policy_replication\n                               [ retention_policy_shard_group_duration ]\n                               [ \"DEFAULT\" ] .\n```\n\n\u003e Replication factors do not serve a purpose with single node instances.\n\n#### Examples\n\n```sql\n-- Create a retention policy.\nCREATE RETENTION POLICY \"10m.events\" ON \"somedb\" DURATION 60m REPLICATION 2\n\n-- Create a retention policy and set it as the DEFAULT.\nCREATE RETENTION POLICY \"10m.events\" ON \"somedb\" DURATION 60m REPLICATION 2 DEFAULT\n\n-- Create a retention policy and specify the shard group duration.\nCREATE RETENTION POLICY \"10m.events\" ON \"somedb\" DURATION 60m REPLICATION 2 SHARD DURATION 30m\n```\n\n### CREATE SUBSCRIPTION\n\nSubscriptions tell InfluxDB to send all the data it receives to Kapacitor or other third parties.\n\n```\ncreate_subscription_stmt = \"CREATE SUBSCRIPTION\" subscription_name \"ON\" db_name \".\" retention_policy \"DESTINATIONS\" (\"ANY\"|\"ALL\") host { \",\" host} .\n```\n\n#### Examples:\n\n```sql\n-- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that send data to 'example.com:9090' via UDP.\nCREATE SUBSCRIPTION \"sub0\" ON \"mydb\".\"autogen\" DESTINATIONS ALL 'udp://example.com:9090'\n\n-- 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'.\nCREATE SUBSCRIPTION \"sub0\" ON \"mydb\".\"autogen\" DESTINATIONS ANY 'udp://h1.example.com:9090', 'udp://h2.example.com:9090'\n```\n\n### CREATE USER\n\n```\ncreate_user_stmt = \"CREATE USER\" user_name \"WITH PASSWORD\" password\n                   [ \"WITH ALL PRIVILEGES\" ] .\n```\n\n#### Examples:\n\n```sql\n-- Create a normal database user.\nCREATE USER \"jdoe\" WITH PASSWORD '1337password'\n\n-- Create an admin user.\n-- Note: Unlike the GRANT statement, the \"PRIVILEGES\" keyword is required here.\nCREATE USER \"jdoe\" WITH PASSWORD '1337password' WITH ALL PRIVILEGES\n```\n\n\u003e **Note:** The password string must be wrapped in single quotes.\n\n### DELETE\n\n```\ndelete_stmt = \"DELETE\" ( from_clause | where_clause | from_clause where_clause ) .\n```\n\n#### Examples:\n\n```sql\nDELETE FROM \"cpu\"\nDELETE FROM \"cpu\" WHERE time \u003c '2000-01-01T00:00:00Z'\nDELETE WHERE time \u003c '2000-01-01T00:00:00Z'\n```\n\n### DROP CONTINUOUS QUERY\n\n```\ndrop_continuous_query_stmt = \"DROP CONTINUOUS QUERY\" query_name on_clause .\n```\n\n#### Example:\n\n```sql\nDROP CONTINUOUS QUERY \"myquery\" ON \"mydb\"\n```\n\n### DROP DATABASE\n\n```\ndrop_database_stmt = \"DROP DATABASE\" db_name .\n```\n\n#### Example:\n\n```sql\nDROP DATABASE \"mydb\"\n```\n\n### DROP MEASUREMENT\n\n```\ndrop_measurement_stmt = \"DROP MEASUREMENT\" measurement .\n```\n\n#### Examples:\n\n```sql\n-- drop the cpu measurement\nDROP MEASUREMENT \"cpu\"\n```\n\n### DROP RETENTION POLICY\n\n```\ndrop_retention_policy_stmt = \"DROP RETENTION POLICY\" policy_name on_clause .\n```\n\n#### Example:\n\n```sql\n-- drop the retention policy named 1h.cpu from mydb\nDROP RETENTION POLICY \"1h.cpu\" ON \"mydb\"\n```\n\n### DROP SERIES\n\n```\ndrop_series_stmt = \"DROP SERIES\" ( from_clause | where_clause | from_clause where_clause ) .\n```\n\n#### Example:\n\n```sql\nDROP SERIES FROM \"telegraf\".\"autogen\".\"cpu\" WHERE cpu = 'cpu8'\n\n```\n\n### DROP SHARD\n\n```\ndrop_shard_stmt = \"DROP SHARD\" ( shard_id ) .\n```\n\n#### Example:\n\n```\nDROP SHARD 1\n```\n\n### DROP SUBSCRIPTION\n\n```\ndrop_subscription_stmt = \"DROP SUBSCRIPTION\" subscription_name \"ON\" db_name \".\" retention_policy .\n```\n\n#### Example:\n\n```sql\nDROP SUBSCRIPTION \"sub0\" ON \"mydb\".\"autogen\"\n```\n\n### DROP USER\n\n```\ndrop_user_stmt = \"DROP USER\" user_name .\n```\n\n#### Example:\n\n```sql\nDROP USER \"jdoe\"\n```\n\n### EXPLAIN\n\n\u003e **NOTE:** This functionality is unimplemented.\n\n```\nexplain_stmt = \"EXPLAIN\" [ \"ANALYZE\" ] select_stmt .\n```\n\n### GRANT\n\n\u003e **NOTE:** Users can be granted privileges on databases that do not exist.\n\n```\ngrant_stmt = \"GRANT\" privilege [ on_clause ] to_clause .\n```\n\n#### Examples:\n\n```sql\n-- grant admin privileges\nGRANT ALL TO \"jdoe\"\n\n-- grant read access to a database\nGRANT READ ON \"mydb\" TO \"jdoe\"\n```\n\n### KILL QUERY\n\n```\nkill_query_statement = \"KILL QUERY\" query_id .\n```\n\n#### Examples:\n\n```\n--- kill a query with the query_id 36\nKILL QUERY 36\n```\n\n\u003e **NOTE:** Identify the `query_id` from the `SHOW QUERIES` output.\n\n### SHOW CONTINUOUS QUERIES\n\n```\nshow_continuous_queries_stmt = \"SHOW CONTINUOUS QUERIES\" .\n```\n\n#### Example:\n\n```sql\n-- show all continuous queries\nSHOW CONTINUOUS QUERIES\n```\n\n### SHOW DATABASES\n\n```\nshow_databases_stmt = \"SHOW DATABASES\" .\n```\n\n#### Example:\n\n```sql\n-- show all databases\nSHOW DATABASES\n```\n\n### SHOW FIELD KEYS\n\n```\nshow_field_keys_stmt = \"SHOW FIELD KEYS\" [ from_clause ] .\n```\n\n#### Examples:\n\n```sql\n-- show field keys and field value data types from all measurements\nSHOW FIELD KEYS\n\n-- show field keys and field value data types from specified measurement\nSHOW FIELD KEYS FROM \"cpu\"\n```\n\n### SHOW GRANTS\n\n```\nshow_grants_stmt = \"SHOW GRANTS FOR\" user_name .\n```\n\n#### Example:\n\n```sql\n-- show grants for jdoe\nSHOW GRANTS FOR \"jdoe\"\n```\n\n### SHOW MEASUREMENTS\n\n```\nshow_measurements_stmt = \"SHOW MEASUREMENTS\" [on_clause] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .\n```\n\n#### Examples:\n\n```sql\n-- show all measurements\nSHOW MEASUREMENTS\n\n-- show all measurements on all databases\nSHOW MEASUREMENTS ON *.*\n\n-- show all measurements on specific database and retention policy\nSHOW MEASUREMENTS ON mydb.myrp\n\n-- show measurements where region tag = 'uswest' AND host tag = 'serverA'\nSHOW MEASUREMENTS WHERE \"region\" = 'uswest' AND \"host\" = 'serverA'\n\n-- show measurements that start with 'h2o'\nSHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/\n```\n\n### SHOW QUERIES\n\n```\nshow_queries_stmt = \"SHOW QUERIES\" .\n```\n\n#### Example:\n\n```sql\n-- show all currently-running queries\nSHOW QUERIES\n```\n\n### SHOW RETENTION POLICIES\n\n```\nshow_retention_policies = \"SHOW RETENTION POLICIES\" on_clause .\n```\n\n#### Example:\n\n```sql\n-- show all retention policies on a database\nSHOW RETENTION POLICIES ON \"mydb\"\n```\n\n### SHOW SERIES\n\n```\nshow_series_stmt = \"SHOW SERIES\" [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .\n```\n\n#### Example:\n\n```sql\nSHOW SERIES FROM \"telegraf\".\"autogen\".\"cpu\" WHERE cpu = 'cpu8'\n```\n\n### SHOW SHARD GROUPS\n\n```\nshow_shard_groups_stmt = \"SHOW SHARD GROUPS\" .\n```\n\n#### Example:\n\n```sql\nSHOW SHARD GROUPS\n```\n\n### SHOW SHARDS\n\n```\nshow_shards_stmt = \"SHOW SHARDS\" .\n```\n\n#### Example:\n\n```sql\nSHOW SHARDS\n```\n\n### SHOW SUBSCRIPTIONS\n\n```\nshow_subscriptions_stmt = \"SHOW SUBSCRIPTIONS\" .\n```\n\n#### Example:\n\n```sql\nSHOW SUBSCRIPTIONS\n```\n\n### SHOW TAG KEYS\n\n```\nshow_tag_keys_stmt = \"SHOW TAG KEYS\" [ from_clause ] [ where_clause ] [ group_by_clause ]\n                     [ limit_clause ] [ offset_clause ] .\n```\n\n#### Examples:\n\n```sql\n-- show all tag keys\nSHOW TAG KEYS\n\n-- show all tag keys from the cpu measurement\nSHOW TAG KEYS FROM \"cpu\"\n\n-- show all tag keys from the cpu measurement where the region key = 'uswest'\nSHOW TAG KEYS FROM \"cpu\" WHERE \"region\" = 'uswest'\n\n-- show all tag keys where the host key = 'serverA'\nSHOW TAG KEYS WHERE \"host\" = 'serverA'\n```\n\n### SHOW TAG VALUES\n\n```\nshow_tag_values_stmt = \"SHOW TAG VALUES\" [ from_clause ] with_tag_clause [ where_clause ]\n                       [ group_by_clause ] [ limit_clause ] [ offset_clause ] .\n```\n\n#### Examples:\n\n```sql\n-- show all tag values across all measurements for the region tag\nSHOW TAG VALUES WITH KEY = \"region\"\n\n-- show tag values from the cpu measurement for the region tag\nSHOW TAG VALUES FROM \"cpu\" WITH KEY = \"region\"\n\n-- show tag values across all measurements for all tag keys that do not include the letter c\nSHOW TAG VALUES WITH KEY !~ /.*c.*/\n\n-- show tag values from the cpu measurement for region \u0026 host tag keys where service = 'redis'\nSHOW TAG VALUES FROM \"cpu\" WITH KEY IN (\"region\", \"host\") WHERE \"service\" = 'redis'\n```\n\n### SHOW USERS\n\n```\nshow_users_stmt = \"SHOW USERS\" .\n```\n\n#### Example:\n\n```sql\n-- show all users\nSHOW USERS\n```\n\n### REVOKE\n\n```\nrevoke_stmt = \"REVOKE\" privilege [ on_clause ] \"FROM\" user_name .\n```\n\n#### Examples:\n\n```sql\n-- revoke admin privileges from jdoe\nREVOKE ALL PRIVILEGES FROM \"jdoe\"\n\n-- revoke read privileges from jdoe on mydb\nREVOKE READ ON \"mydb\" FROM \"jdoe\"\n```\n\n### SELECT\n\n```\nselect_stmt = \"SELECT\" fields from_clause [ into_clause ] [ where_clause ]\n              [ group_by_clause ] [ order_by_clause ] [ limit_clause ]\n              [ offset_clause ] [ slimit_clause ] [ soffset_clause ]\n              [ timezone_clause ] .\n```\n\n#### Examples:\n\n```sql\n-- select mean value from the cpu measurement where region = 'uswest' grouped by 10 minute intervals\nSELECT mean(\"value\") FROM \"cpu\" WHERE \"region\" = 'uswest' GROUP BY time(10m) fill(0)\n\n-- select from all measurements beginning with cpu into the same measurement name in the cpu_1h retention policy\nSELECT mean(\"value\") INTO \"cpu_1h\".:MEASUREMENT FROM /cpu.*/\n\n-- select from measurements grouped by the day with a timezone\nSELECT mean(\"value\") FROM \"cpu\" GROUP BY region, time(1d) fill(0) tz(\"America/Chicago\")\n```\n\n## Clauses\n\n```\nfrom_clause     = \"FROM\" measurements .\n\ngroup_by_clause = \"GROUP BY\" dimensions fill(fill_option).\n\ninto_clause     = \"INTO\" ( measurement | back_ref ).\n\nlimit_clause    = \"LIMIT\" int_lit .\n\noffset_clause   = \"OFFSET\" int_lit .\n\nslimit_clause   = \"SLIMIT\" int_lit .\n\nsoffset_clause  = \"SOFFSET\" int_lit .\n\ntimezone_clause = tz(string_lit) .\n\non_clause       = \"ON\" db_name .\n\norder_by_clause = \"ORDER BY\" sort_fields .\n\nto_clause       = \"TO\" user_name .\n\nwhere_clause    = \"WHERE\" expr .\n\nwith_measurement_clause = \"WITH MEASUREMENT\" ( \"=\" measurement | \"=~\" regex_lit ) .\n\nwith_tag_clause = \"WITH KEY\" ( \"=\" tag_key | \"!=\" tag_key | \"=~\" regex_lit | \"IN (\" tag_keys \")\"  ) .\n```\n\n## Expressions\n\n```\nbinary_op        = \"+\" | \"-\" | \"*\" | \"/\" | \"%\" | \"\u0026\" | \"|\" | \"^\" | \"AND\" |\n                   \"OR\" | \"=\" | \"!=\" | \"\u003c\u003e\" | \"\u003c\" | \"\u003c=\" | \"\u003e\" | \"\u003e=\" .\n\nexpr             = unary_expr { binary_op unary_expr } .\n\nunary_expr       = \"(\" expr \")\" | var_ref | time_lit | string_lit | int_lit |\n                   float_lit | bool_lit | duration_lit | regex_lit .\n```\n\n## Other\n\n```\nalias            = \"AS\" identifier .\n\nback_ref         = ( policy_name \".:MEASUREMENT\" ) |\n                   ( db_name \".\" [ policy_name ] \".:MEASUREMENT\" ) .\n\ndb_name          = identifier .\n\ndimension        = expr .\n\ndimensions       = dimension { \",\" dimension } .\n\nfield_key        = identifier .\n\nfield            = expr [ alias ] .\n\nfields           = field { \",\" field } .\n\nfill_option      = \"null\" | \"none\" | \"previous\" | \"linear\" | int_lit | float_lit .\n\nhost             = string_lit .\n\nmeasurement      = measurement_name |\n                   ( policy_name \".\" measurement_name ) |\n                   ( db_name \".\" [ policy_name ] \".\" measurement_name ) .\n\nmeasurements     = measurement { \",\" measurement } .\n\nmeasurement_name = identifier | regex_lit .\n\npassword         = string_lit .\n\npolicy_name      = identifier .\n\nprivilege        = \"ALL\" [ \"PRIVILEGES\" ] | \"READ\" | \"WRITE\" .\n\nquery_id         = int_lit .\n\nquery_name       = identifier .\n\nretention_policy = identifier .\n\nretention_policy_option      = retention_policy_duration |\n                               retention_policy_replication |\n                               retention_policy_shard_group_duration |\n                               \"DEFAULT\" .\n\nretention_policy_duration    = \"DURATION\" duration_lit .\n\nretention_policy_replication = \"REPLICATION\" int_lit .\n\nretention_policy_shard_group_duration = \"SHARD DURATION\" duration_lit .\n\nretention_policy_name = \"NAME\" identifier .\n\nseries_id        = int_lit .\n\nshard_id         = int_lit .\n\nsort_field       = field_key [ ASC | DESC ] .\n\nsort_fields      = sort_field { \",\" sort_field } .\n\nsubscription_name = identifier .\n\ntag_key          = identifier .\n\ntag_keys         = tag_key { \",\" tag_key } .\n\nuser_name        = identifier .\n\nvar_ref          = measurement .\n```\n\n## Query Engine Internals\n\nOnce you understand the language itself, it's important to know how these\nlanguage constructs are implemented in the query engine. This gives you an\nintuitive sense for how results will be processed and how to create efficient\nqueries.\n\nThe life cycle of a query looks like this:\n\n1. InfluxQL query string is tokenized and then parsed into an abstract syntax\n   tree (AST). This is the code representation of the query itself.\n\n2. The AST is passed to the `QueryExecutor` which directs queries to the\n   appropriate handlers. For example, queries related to meta data are executed\n   by the meta service and `SELECT` statements are executed by the shards\n   themselves.\n\n3. The query engine then determines the shards that match the `SELECT`\n   statement's time range. From these shards, iterators are created for each\n   field in the statement.\n\n4. Iterators are passed to the emitter which drains them and joins the resulting\n   points. The emitter's job is to convert simple time/value points into the\n   more complex result objects that are returned to the client.\n\n\n### Understanding Iterators\n\nIterators are at the heart of the query engine. They provide a simple interface\nfor looping over a set of points. For example, this is an iterator over Float\npoints:\n\n```\ntype FloatIterator interface {\n    Next() (*FloatPoint, error)\n}\n```\n\nThese iterators are created through the `IteratorCreator` interface:\n\n```\ntype IteratorCreator interface {\n    CreateIterator(m *Measurement, opt IteratorOptions) (Iterator, error)\n}\n```\n\nThe `IteratorOptions` provide arguments about field selection, time ranges,\nand dimensions that the iterator creator can use when planning an iterator.\nThe `IteratorCreator` interface is used at many levels such as the `Shards`,\n`Shard`, and `Engine`. This allows optimizations to be performed when applicable\nsuch as returning a precomputed `COUNT()`.\n\nIterators aren't just for reading raw data from storage though. Iterators can be\ncomposed so that they provided additional functionality around an input\niterator. For example, a `DistinctIterator` can compute the distinct values for\neach time window for an input iterator. Or a `FillIterator` can generate\nadditional points that are missing from an input iterator.\n\nThis composition also lends itself well to aggregation. For example, a statement\nsuch as this:\n\n```\nSELECT MEAN(value) FROM cpu GROUP BY time(10m)\n```\n\nIn this case, `MEAN(value)` is a `MeanIterator` wrapping an iterator from the\nunderlying shards. However, if we can add an additional iterator to determine\nthe derivative of the mean:\n\n```\nSELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m)\n```\n\n\n### Understanding Auxiliary Fields\n\nBecause InfluxQL allows users to use selector functions such as `FIRST()`,\n`LAST()`, `MIN()`, and `MAX()`, the engine must provide a way to return related\ndata at the same time with the selected point.\n\nFor example, in this query:\n\n```\nSELECT FIRST(value), host FROM cpu GROUP BY time(1h)\n```\n\nWe are selecting the first `value` that occurs every hour but we also want to\nretrieve the `host` associated with that point. Since the `Point` types only\nspecify a single typed `Value` for efficiency, we push the `host` into the\nauxiliary fields of the point. These auxiliary fields are attached to the point\nuntil it is passed to the emitter where the fields get split off to their own\niterator.\n\n\n### Built-in Iterators\n\nThere are many helper iterators that let us build queries:\n\n* Merge Iterator - This iterator combines one or more iterators into a single\n  new iterator of the same type. This iterator guarantees that all points\n  within a window will be output before starting the next window but does not\n  provide ordering guarantees within the window. This allows for fast access\n  for aggregate queries which do not need stronger sorting guarantees.\n\n* Sorted Merge Iterator - This iterator also combines one or more iterators\n  into a new iterator of the same type. However, this iterator guarantees\n  time ordering of every point. This makes it slower than the `MergeIterator`\n  but this ordering guarantee is required for non-aggregate queries which\n  return the raw data points.\n\n* Limit Iterator - This iterator limits the number of points per name/tag\n  group. This is the implementation of the `LIMIT` \u0026 `OFFSET` syntax.\n\n* Fill Iterator - This iterator injects extra points if they are missing from\n  the input iterator. It can provide `null` points, points with the previous\n  value, or points with a specific value.\n\n* Buffered Iterator - This iterator provides the ability to \"unread\" a point\n  back onto a buffer so it can be read again next time. This is used extensively\n  to provide lookahead for windowing.\n\n* Reduce Iterator - This iterator calls a reduction function for each point in\n  a window. When the window is complete then all points for that window are\n  output. This is used for simple aggregate functions such as `COUNT()`.\n\n* Reduce Slice Iterator - This iterator collects all points for a window first\n  and then passes them all to a reduction function at once. The results are\n  returned from the iterator. This is used for aggregate functions such as\n  `DERIVATIVE()`.\n\n* Transform Iterator - This iterator calls a transform function for each point\n  from an input iterator. This is used for executing binary expressions.\n\n* Dedupe Iterator - This iterator only outputs unique points. It is resource\n  intensive so it is only used for small queries such as meta query statements.\n\n\n### Call Iterators\n\nFunction calls in InfluxQL are implemented at two levels. Some calls can be\nwrapped at multiple layers to improve efficiency. For example, a `COUNT()` can\nbe performed at the shard level and then multiple `CountIterator`s can be\nwrapped with another `CountIterator` to compute the count of all shards. These\niterators can be created using `NewCallIterator()`.\n\nSome iterators are more complex or need to be implemented at a higher level.\nFor example, the `DERIVATIVE()` needs to retrieve all points for a window first\nbefore performing the calculation. This iterator is created by the engine itself\nand is never requested to be created by the lower levels.\n\n### Subqueries\n\nSubqueries are built on top of iterators. Most of the work involved in\nsupporting subqueries is in organizing how data is streamed to the\niterators that will process the data.\n\nThe final ordering of the stream has to output all points from one\nseries before moving to the next series and it also needs to ensure\nthose points are printed in order. So there are two separate concepts we\nneed to consider when creating an iterator: ordering and grouping.\n\nWhen an inner query has a different grouping than the outermost query,\nwe still need to group together related points into buckets, but we do\nnot have to ensure that all points from one buckets are output before\nthe points in another bucket. In fact, if we do that, we will be unable\nto perform the grouping for the outer query correctly. Instead, we group\nall points by the outermost query for an interval and then, within that\ninterval, we group the points for the inner query. For example, here are\nseries keys and times in seconds (fields are omitted since they don't\nmatter in this example):\n\n    cpu,host=server01 0\n    cpu,host=server01 10\n    cpu,host=server01 20\n    cpu,host=server01 30\n    cpu,host=server02 0\n    cpu,host=server02 10\n    cpu,host=server02 20\n    cpu,host=server02 30\n\nWith the following query:\n\n    SELECT mean(max) FROM (SELECT max(value) FROM cpu GROUP BY host, time(20s)) GROUP BY time(20s)\n\nThe final grouping keeps all of the points together which means we need\nto group `server01` with `server02`. That means we output the points\nfrom the underlying engine like this:\n\n    cpu,host=server01 0\n    cpu,host=server01 10\n    cpu,host=server02 0\n    cpu,host=server02 10\n    cpu,host=server01 20\n    cpu,host=server01 30\n    cpu,host=server02 20\n    cpu,host=server02 30\n\nWithin each one of those time buckets, we calculate the `max()` value\nfor each unique host so the output stream gets transformed to look like\nthis:\n\n    cpu,host=server01 0\n    cpu,host=server02 0\n    cpu,host=server01 20\n    cpu,host=server02 20\n\nThen we can process the `mean()` on this stream of data instead and it\nwill be output in the correct order. This is true of any order of\ngrouping since grouping can only go from more specific to less specific.\n\nWhen it comes to ordering, unordered data is faster to process, but we\nalways need to produce ordered data. When processing a raw query with no\naggregates, we need to ensure data coming from the engine is ordered so\nthe output is ordered. When we have an aggregate, we know one point is\nbeing emitted for each interval and will always produce ordered output.\nSo for aggregates, we can take unordered data as the input and get\nordered output. Any ordered data as input will always result in ordered\ndata so we just need to look at how an iterator processes unordered\ndata.\n\n|                 | raw query        | selector (without group by time) | selector (with group by time) | aggregator     |\n|-----------------|------------------|----------------------------------|-------------------------------|----------------|\n| ordered input   | ordered output   | ordered output                   | ordered output                | ordered output |\n| unordered input | unordered output | unordered output                 | ordered output                | ordered output |\n\nSince we always need ordered output, we just need to work backwards and\ndetermine which pattern of input gives us ordered output. If both\nordered and unordered input produce ordered output, we prefer unordered\ninput since it is faster.\n\nThere are also certain aggregates that require ordered input like\n`median()` and `percentile()`. These functions will explicitly request\nordered input. It is also important to realize that selectors that are\ngrouped by time are the equivalent of an aggregator. It is only\nselectors without a group by time that are different.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Finfluxql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfluxdata%2Finfluxql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Finfluxql/lists"}