From 970f906ba14d95616934003a034bbe65c270b406 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 2 Dec 2025 13:24:00 -0500 Subject: [PATCH 1/2] fix(influxdb-v1): correct FUTURE LIMIT and PAST LIMIT clause order and add to ALTER RETENTION POLICY - Fix clause order: FUTURE LIMIT must appear before PAST LIMIT (parser requirement) - Add FUTURE LIMIT and PAST LIMIT clauses to ALTER RETENTION POLICY syntax - Add grammar definitions for retention_future_limit and retention_past_limit - Add explicit note clarifying the required clause order - Fix "There are" style issue in spec.md closes #6590 --- .../v1/query_language/manage-database.md | 35 ++++++++++--------- .../v1/query_language/spec.md | 31 ++++++++++++---- .../v1/query_language/manage-database.md | 35 ++++++++++--------- content/influxdb/v1/query_language/spec.md | 31 ++++++++++++---- .../reference/release-notes/clustered.md | 16 +++++---- 5 files changed, 96 insertions(+), 52 deletions(-) diff --git a/content/enterprise_influxdb/v1/query_language/manage-database.md b/content/enterprise_influxdb/v1/query_language/manage-database.md index 4a1f09b7a4..0f94f45b72 100644 --- a/content/enterprise_influxdb/v1/query_language/manage-database.md +++ b/content/enterprise_influxdb/v1/query_language/manage-database.md @@ -62,15 +62,15 @@ Creates a new database. #### Syntax ```sql -CREATE DATABASE [WITH [DURATION ] [REPLICATION ] [SHARD DURATION ] [PAST LIMIT ] [FUTURE LIMIT ] [NAME ]] +CREATE DATABASE [WITH [DURATION ] [REPLICATION ] [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [NAME ]] ``` #### Description of syntax `CREATE DATABASE` requires a database [name](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#what-words-and-characters-should-i-avoid-when-writing-data-to-influxdb). -The `WITH`, `DURATION`, `REPLICATION`, `SHARD DURATION`, `PAST LIMIT`, -`FUTURE LIMIT, and `NAME` clauses are optional and create a single +The `WITH`, `DURATION`, `REPLICATION`, `SHARD DURATION`, `FUTURE LIMIT`, +`PAST LIMIT`, and `NAME` clauses are optional and create a single [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp) associated with the created database. If you do not specify one of the clauses after `WITH`, the relevant behavior @@ -258,7 +258,7 @@ You may disable its auto-creation in the [configuration file](/enterprise_influx #### Syntax ```sql -CREATE RETENTION POLICY ON DURATION REPLICATION [SHARD DURATION ] [PAST LIMIT ] [FUTURE LIMIT ] [DEFAULT] +CREATE RETENTION POLICY ON DURATION REPLICATION [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [DEFAULT] ``` #### Description of syntax @@ -306,27 +306,27 @@ See [Shard group duration management](/enterprise_influxdb/v1/concepts/schema_and_data_layout/#shard-group-duration-management) for recommended configurations. -##### `PAST LIMIT` {metadata="v1.12.0+"} +##### `FUTURE LIMIT` {metadata="v1.12.0+"} -The `PAST LIMIT` clause defines a time boundary before and relative to _now_ +The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_ in which points written to the retention policy are accepted. If a point has a -timestamp before the specified boundary, the point is rejected and the write +timestamp after the specified boundary, the point is rejected and the write request returns a partial write error. For example, if a write request tries to write data to a retention policy with a -`PAST LIMIT 6h` and there are points in the request with timestamps older than -6 hours, those points are rejected. +`FUTURE LIMIT 6h` and there are points in the request with future timestamps +greater than 6 hours from now, those points are rejected. -##### `FUTURE LIMIT` {metadata="v1.12.0+"} +##### `PAST LIMIT` {metadata="v1.12.0+"} -The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_ +The `PAST LIMIT` clause defines a time boundary before and relative to _now_ in which points written to the retention policy are accepted. If a point has a -timestamp after the specified boundary, the point is rejected and the write +timestamp before the specified boundary, the point is rejected and the write request returns a partial write error. For example, if a write request tries to write data to a retention policy with a -`FUTURE LIMIT 6h` and there are points in the request with future timestamps -greater than 6 hours from now, those points are rejected. +`PAST LIMIT 6h` and there are points in the request with timestamps older than +6 hours, those points are rejected. ##### `DEFAULT` @@ -363,14 +363,17 @@ See [Create a database with CREATE DATABASE](/enterprise_influxdb/v1/query_langu ### Modify retention policies with ALTER RETENTION POLICY -The `ALTER RETENTION POLICY` query takes the following form, where you must declare at least one of the retention policy attributes `DURATION`, `REPLICATION`, `SHARD DURATION`, or `DEFAULT`: +The `ALTER RETENTION POLICY` query takes the following form, where you must declare at least one of the retention policy attributes `DURATION`, `REPLICATION`, `SHARD DURATION`, `FUTURE LIMIT`, `PAST LIMIT`, or `DEFAULT`: ```sql -ALTER RETENTION POLICY ON [DURATION ] [REPLICATION ] [SHARD DURATION ] [DEFAULT] +ALTER RETENTION POLICY ON [DURATION ] [REPLICATION ] [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [DEFAULT] ``` {{% warn %}} Replication factors do not serve a purpose with single node instances. {{% /warn %}} +For information about the `FUTURE LIMIT` and `PAST LIMIT` clauses, see +[CREATE RETENTION POLICY](#create-retention-policies-with-create-retention-policy). + First, create the retention policy `what_is_time` with a `DURATION` of two days: ```sql > CREATE RETENTION POLICY "what_is_time" ON "NOAA_water_database" DURATION 2d REPLICATION 1 diff --git a/content/enterprise_influxdb/v1/query_language/spec.md b/content/enterprise_influxdb/v1/query_language/spec.md index 2da1caa11b..6d840d22fe 100644 --- a/content/enterprise_influxdb/v1/query_language/spec.md +++ b/content/enterprise_influxdb/v1/query_language/spec.md @@ -308,6 +308,8 @@ alter_retention_policy_stmt = "ALTER RETENTION POLICY" policy_name on_clause retention_policy_option [ retention_policy_option ] [ retention_policy_option ] + [ retention_policy_option ] + [ retention_policy_option ] [ retention_policy_option ] . ``` @@ -320,6 +322,9 @@ ALTER RETENTION POLICY "1h.cpu" ON "mydb" DEFAULT -- Change duration and replication factor. -- REPLICATION (replication factor) not valid for OSS instances. ALTER RETENTION POLICY "policy1" ON "somedb" DURATION 1h REPLICATION 4 + +-- Change future and past limits. +ALTER RETENTION POLICY "policy1" ON "somedb" FUTURE LIMIT 6h PAST LIMIT 6h ``` ### CREATE CONTINUOUS QUERY @@ -379,13 +384,16 @@ create_database_stmt = "CREATE DATABASE" db_name [ WITH [ retention_policy_duration ] [ retention_policy_replication ] - [ retention_past_limit ] - [ retention_future_limit ] [ retention_policy_shard_group_duration ] + [ retention_future_limit ] + [ retention_past_limit ] [ retention_policy_name ] ] . ``` +> [!Note] +> When using both `FUTURE LIMIT` and `PAST LIMIT` clauses, `FUTURE LIMIT` must appear before `PAST LIMIT`. + > [!Warning] > Replication factors do not serve a purpose with single node instances. @@ -404,8 +412,8 @@ CREATE DATABASE "bar" WITH DURATION 1d REPLICATION 1 SHARD DURATION 30m NAME "my CREATE DATABASE "mydb" WITH NAME "myrp" -- Create a database called bar with a new retention policy named "myrp", and --- specify the duration, past and future limits, and name of that retention policy -CREATE DATABASE "bar" WITH DURATION 1d PAST LIMIT 6h FUTURE LIMIT 6h NAME "myrp" +-- specify the duration, future and past limits, and name of that retention policy +CREATE DATABASE "bar" WITH DURATION 1d FUTURE LIMIT 6h PAST LIMIT 6h NAME "myrp" ``` ### CREATE RETENTION POLICY @@ -415,11 +423,14 @@ create_retention_policy_stmt = "CREATE RETENTION POLICY" policy_name on_clause retention_policy_duration retention_policy_replication [ retention_policy_shard_group_duration ] - [ retention_past_limit ] [ retention_future_limit ] + [ retention_past_limit ] [ "DEFAULT" ] . ``` +> [!Note] +> When using both `FUTURE LIMIT` and `PAST LIMIT` clauses, `FUTURE LIMIT` must appear before `PAST LIMIT`. + > [!Warning] > Replication factors do not serve a purpose with single node instances. @@ -435,8 +446,8 @@ CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 DEFA -- Create a retention policy and specify the shard group duration. CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 SHARD DURATION 30m --- Create a retention policy and specify past and future limits. -CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 12h PAST LIMIT 6h FUTURE LIMIT 6h +-- Create a retention policy and specify future and past limits. +CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 12h FUTURE LIMIT 6h PAST LIMIT 6h ``` ### CREATE SUBSCRIPTION @@ -1332,6 +1343,8 @@ retention_policy = identifier . retention_policy_option = retention_policy_duration | retention_policy_replication | retention_policy_shard_group_duration | + retention_future_limit | + retention_past_limit | "DEFAULT" . retention_policy_duration = "DURATION" duration_lit . @@ -1340,6 +1353,10 @@ retention_policy_replication = "REPLICATION" int_lit . retention_policy_shard_group_duration = "SHARD DURATION" duration_lit . +retention_future_limit = "FUTURE LIMIT" duration_lit . + +retention_past_limit = "PAST LIMIT" duration_lit . + retention_policy_name = "NAME" identifier . series_id = int_lit . diff --git a/content/influxdb/v1/query_language/manage-database.md b/content/influxdb/v1/query_language/manage-database.md index 554b8b8716..62e5e42851 100644 --- a/content/influxdb/v1/query_language/manage-database.md +++ b/content/influxdb/v1/query_language/manage-database.md @@ -62,15 +62,15 @@ Creates a new database. #### Syntax ```sql -CREATE DATABASE [WITH [DURATION ] [REPLICATION ] [SHARD DURATION ] [PAST LIMIT ] [FUTURE LIMIT ] [NAME ]] +CREATE DATABASE [WITH [DURATION ] [REPLICATION ] [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [NAME ]] ``` #### Description of syntax `CREATE DATABASE` requires a database [name](/influxdb/v1/troubleshooting/frequently-asked-questions/#what-words-and-characters-should-i-avoid-when-writing-data-to-influxdb). -The `WITH`, `DURATION`, `REPLICATION`, `SHARD DURATION`, `PAST LIMIT`, -`FUTURE LIMIT`, and `NAME` clauses are optional and create a single +The `WITH`, `DURATION`, `REPLICATION`, `SHARD DURATION`, `FUTURE LIMIT`, +`PAST LIMIT`, and `NAME` clauses are optional and create a single [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp) associated with the created database. If you do not specify one of the clauses after `WITH`, the relevant behavior @@ -259,7 +259,7 @@ You may disable its auto-creation in the [configuration file](/influxdb/v1/admin #### Syntax ```sql -CREATE RETENTION POLICY ON DURATION REPLICATION [SHARD DURATION ] [PAST LIMIT ] [FUTURE LIMIT ] [DEFAULT] +CREATE RETENTION POLICY ON DURATION REPLICATION [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [DEFAULT] ``` #### Description of syntax @@ -307,27 +307,27 @@ See [Shard group duration management](/influxdb/v1/concepts/schema_and_data_layout/#shard-group-duration-management) for recommended configurations. -##### `PAST LIMIT` {metadata="v1.12.0+"} +##### `FUTURE LIMIT` {metadata="v1.12.0+"} -The `PAST LIMIT` clause defines a time boundary before and relative to _now_ +The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_ in which points written to the retention policy are accepted. If a point has a -timestamp before the specified boundary, the point is rejected and the write +timestamp after the specified boundary, the point is rejected and the write request returns a partial write error. For example, if a write request tries to write data to a retention policy with a -`PAST LIMIT 6h` and there are points in the request with timestamps older than -6 hours, those points are rejected. +`FUTURE LIMIT 6h` and there are points in the request with future timestamps +greater than 6 hours from now, those points are rejected. -##### `FUTURE LIMIT` {metadata="v1.12.0+"} +##### `PAST LIMIT` {metadata="v1.12.0+"} -The `FUTURE LIMIT` clause defines a time boundary after and relative to _now_ +The `PAST LIMIT` clause defines a time boundary before and relative to _now_ in which points written to the retention policy are accepted. If a point has a -timestamp after the specified boundary, the point is rejected and the write +timestamp before the specified boundary, the point is rejected and the write request returns a partial write error. For example, if a write request tries to write data to a retention policy with a -`FUTURE LIMIT 6h` and there are points in the request with future timestamps -greater than 6 hours from now, those points are rejected. +`PAST LIMIT 6h` and there are points in the request with timestamps older than +6 hours, those points are rejected. ##### `DEFAULT` @@ -364,14 +364,17 @@ See [Create a database with CREATE DATABASE](/influxdb/v1/query_language/manage- ### Modify retention policies with ALTER RETENTION POLICY -The `ALTER RETENTION POLICY` query takes the following form, where you must declare at least one of the retention policy attributes `DURATION`, `REPLICATION`, `SHARD DURATION`, or `DEFAULT`: +The `ALTER RETENTION POLICY` query takes the following form, where you must declare at least one of the retention policy attributes `DURATION`, `REPLICATION`, `SHARD DURATION`, `FUTURE LIMIT`, `PAST LIMIT`, or `DEFAULT`: ```sql -ALTER RETENTION POLICY ON [DURATION ] [REPLICATION ] [SHARD DURATION ] [DEFAULT] +ALTER RETENTION POLICY ON [DURATION ] [REPLICATION ] [SHARD DURATION ] [FUTURE LIMIT ] [PAST LIMIT ] [DEFAULT] ``` {{% warn %}} Replication factors do not serve a purpose with single node instances. {{% /warn %}} +For information about the `FUTURE LIMIT` and `PAST LIMIT` clauses, see +[CREATE RETENTION POLICY](#create-retention-policies-with-create-retention-policy). + First, create the retention policy `what_is_time` with a `DURATION` of two days: ```sql > CREATE RETENTION POLICY "what_is_time" ON "NOAA_water_database" DURATION 2d REPLICATION 1 diff --git a/content/influxdb/v1/query_language/spec.md b/content/influxdb/v1/query_language/spec.md index 3805d558f8..4aa0aa8a31 100644 --- a/content/influxdb/v1/query_language/spec.md +++ b/content/influxdb/v1/query_language/spec.md @@ -306,6 +306,8 @@ alter_retention_policy_stmt = "ALTER RETENTION POLICY" policy_name on_clause retention_policy_option [ retention_policy_option ] [ retention_policy_option ] + [ retention_policy_option ] + [ retention_policy_option ] [ retention_policy_option ] . ``` @@ -318,6 +320,9 @@ ALTER RETENTION POLICY "1h.cpu" ON "mydb" DEFAULT -- Change duration and replication factor. -- REPLICATION (replication factor) not valid for OSS instances. ALTER RETENTION POLICY "policy1" ON "somedb" DURATION 1h REPLICATION 4 + +-- Change future and past limits. +ALTER RETENTION POLICY "policy1" ON "somedb" FUTURE LIMIT 6h PAST LIMIT 6h ``` ### CREATE CONTINUOUS QUERY @@ -378,12 +383,15 @@ create_database_stmt = "CREATE DATABASE" db_name [ retention_policy_duration ] [ retention_policy_replication ] [ retention_policy_shard_group_duration ] - [ retention_past_limit ] [ retention_future_limit ] + [ retention_past_limit ] [ retention_policy_name ] ] . ``` +> [!Note] +> When using both `FUTURE LIMIT` and `PAST LIMIT` clauses, `FUTURE LIMIT` must appear before `PAST LIMIT`. + > [!Warning] > Replication factors do not serve a purpose with single node instances. @@ -402,8 +410,8 @@ CREATE DATABASE "bar" WITH DURATION 1d REPLICATION 1 SHARD DURATION 30m NAME "my CREATE DATABASE "mydb" WITH NAME "myrp" -- Create a database called bar with a new retention policy named "myrp", and --- specify the duration, past and future limits, and name of that retention policy -CREATE DATABASE "bar" WITH DURATION 1d PAST LIMIT 6h FUTURE LIMIT 6h NAME "myrp" +-- specify the duration, future and past limits, and name of that retention policy +CREATE DATABASE "bar" WITH DURATION 1d FUTURE LIMIT 6h PAST LIMIT 6h NAME "myrp" ``` ### CREATE RETENTION POLICY @@ -413,11 +421,14 @@ create_retention_policy_stmt = "CREATE RETENTION POLICY" policy_name on_clause retention_policy_duration retention_policy_replication [ retention_policy_shard_group_duration ] - [ retention_past_limit ] [ retention_future_limit ] + [ retention_past_limit ] [ "DEFAULT" ] . ``` +> [!Note] +> When using both `FUTURE LIMIT` and `PAST LIMIT` clauses, `FUTURE LIMIT` must appear before `PAST LIMIT`. + > [!Warning] > Replication factors do not serve a purpose with single node instances. @@ -433,8 +444,8 @@ CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 DEFA -- Create a retention policy and specify the shard group duration. CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 60m REPLICATION 2 SHARD DURATION 30m --- Create a retention policy and specify past and future limits. -CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 12h PAST LIMIT 6h FUTURE LIMIT 6h +-- Create a retention policy and specify future and past limits. +CREATE RETENTION POLICY "10m.events" ON "somedb" DURATION 12h FUTURE LIMIT 6h PAST LIMIT 6h ``` ### CREATE SUBSCRIPTION @@ -1321,6 +1332,8 @@ retention_policy = identifier . retention_policy_option = retention_policy_duration | retention_policy_replication | retention_policy_shard_group_duration | + retention_future_limit | + retention_past_limit | "DEFAULT" . retention_policy_duration = "DURATION" duration_lit . @@ -1329,6 +1342,10 @@ retention_policy_replication = "REPLICATION" int_lit . retention_policy_shard_group_duration = "SHARD DURATION" duration_lit . +retention_future_limit = "FUTURE LIMIT" duration_lit . + +retention_past_limit = "PAST LIMIT" duration_lit . + retention_policy_name = "NAME" identifier . series_id = int_lit . @@ -1458,7 +1475,7 @@ iterator. ### Built-in iterators -There are many helper iterators that let us build queries: +InfluxDB provides 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 diff --git a/content/influxdb3/clustered/reference/release-notes/clustered.md b/content/influxdb3/clustered/reference/release-notes/clustered.md index dd2775fff8..939df219f2 100644 --- a/content/influxdb3/clustered/reference/release-notes/clustered.md +++ b/content/influxdb3/clustered/reference/release-notes/clustered.md @@ -82,14 +82,18 @@ spec: Tables can now be renamed and undeleted with [influxctl v2.10.5](https://docs.influxdata.com/influxdb3/clustered/reference/release-notes/influxctl/#2105) or later. -To enable hard delete of soft-deleted namespaces: +To enable hard delete of soft-deleted databases: + +> [!Note] +> In {{% product-name %}}, "namespace" in environment variable names refers to a database. + - Set `INFLUXDB_IOX_ENABLE_NAMESPACE_ROW_DELETION` to `true`. - - If needed, adjust how long a namespace remains soft-deleted (and eligible for undeletion) by setting `INFLUXDB_IOX_GC_NAMESPACE_CUTOFF` (default: `14d`) - - If needed, adjust how long the garbage collector should sleep between runs of the namespace deletion task with `INFLUXDB_IOX_GC_NAMESPACE_SLEEP_INTERVAL` The default is `24h` which should be suitable for ongoing cleanup, but if there is a backlog of soft-deleted namespaces to clean up, you may want to run this more frequently until the garbage collector has caught up. - - If needed, adjust the maximum number of namespaces that will get hard deleted in one run of the namespace deletion task with `INFLUXDB_IOX_GC_NAMESPACE_LIMIT` The default is `1000` which should be suitable for ongoing cleanup, but if you have a large number of namespaces and you're running the task very frequently, you may need to lower this to delete fewer records per run if each individual run is timing out. + - If needed, adjust how long a database remains soft-deleted (and eligible for undeletion) by setting `INFLUXDB_IOX_GC_NAMESPACE_CUTOFF` (default: `14d`) + - If needed, adjust how long the garbage collector should sleep between runs of the database deletion task with `INFLUXDB_IOX_GC_NAMESPACE_SLEEP_INTERVAL` The default is `24h` which should be suitable for ongoing cleanup, but if there is a backlog of soft-deleted databases to clean up, you may want to run this more frequently until the garbage collector has caught up. + - If needed, adjust the maximum number of databases that will get hard deleted in one run of the database deletion task with `INFLUXDB_IOX_GC_NAMESPACE_LIMIT` The default is `1000` which should be suitable for ongoing cleanup, but if you have a large number of databases and you're running the task very frequently, you may need to lower this to delete fewer records per run if each individual run is timing out. -To enable hard delete of soft-deleted tables in active namespaces (soft-deleted tables in soft-deleted namespaces get cleaned up when the namespace gets cleaned up): -- Set `INFLUXDB_IOX_ENABLE_TABLE_ROW_DELETION` to `true`, and if needed, adjust these settings that work in the same way as the corresponding namespace flags: +To enable hard delete of soft-deleted tables in active databases (soft-deleted tables in soft-deleted databases get cleaned up when the database gets cleaned up): +- Set `INFLUXDB_IOX_ENABLE_TABLE_ROW_DELETION` to `true`, and if needed, adjust these settings that work in the same way as the corresponding database flags: - `INFLUXDB_IOX_GC_TABLE_CUTOFF` (default: `14d`) - `INFLUXDB_IOX_GC_TABLE_SLEEP_INTERVAL` (default: `24h`) - `INFLUXDB_IOX_GC_TABLE_LIMIT` (default: `1000`) From ffbb3fcceddf8f6ddb19831d4cf4ec5553fb50b4 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 4 Dec 2025 16:46:59 -0600 Subject: [PATCH 2/2] style(influxdb-v1): clean up InfluxQL spec formatting influxdb/v1: - Simplify introduction and use relative anchor links - Convert notes to GitHub-style callout syntax - Fix heading hierarchy (Letters/digits, Identifiers, Keywords, Literals as h3) - Standardize Duration units table heading - Fix "keywords" typo - Reword "See FAQ" to "For more information, see" - Simplify KILL QUERY section - Fix SHOW MEASUREMENT CARDINALITY heading level - Replace "There are" with active voice enterprise_influxdb/v1: - Add related links to frontmatter - Simplify introduction and use relative anchor links - Convert notes to GitHub-style callout syntax - Add Characters and Letters/digits to TOC - Standardize Duration units table heading - Fix "keywords" typo - Reword "See FAQ" to "For more information, see" - Simplify KILL QUERY section for Enterprise clusters - Update SHOW TAG KEYS grammar to include with_key_clause - Remove backticks from SHOW STATS headings --- .../v1/query_language/spec.md | 144 +++++++------ content/influxdb/v1/query_language/spec.md | 192 +++++++++--------- 2 files changed, 164 insertions(+), 172 deletions(-) diff --git a/content/enterprise_influxdb/v1/query_language/spec.md b/content/enterprise_influxdb/v1/query_language/spec.md index 6d840d22fe..22bda1e316 100644 --- a/content/enterprise_influxdb/v1/query_language/spec.md +++ b/content/enterprise_influxdb/v1/query_language/spec.md @@ -1,49 +1,39 @@ --- title: Influx Query Language (InfluxQL) reference -description: Reference for Influx Query Language (InfluxQL). +description: InfluxQL is a SQL-like query language for interacting with InfluxDB and providing features specific to storing and analyzing time series data. menu: enterprise_influxdb_v1: name: InfluxQL reference weight: 90 parent: InfluxQL -aliases: - - /influxdb/v2/query_language/spec/ +related: + - /enterprise_influxdb/v1/query_language/internals/ + - /enterprise_influxdb/v1/query_language/explore-data/ + - /enterprise_influxdb/v1/query_language/explore-schema/ + - /enterprise_influxdb/v1/query_language/manage-database/ --- -## Introduction - InfluxQL is a SQL-like query language for interacting with InfluxDB and providing features specific to storing and analyzing time series data. -Find Influx Query Language (InfluxQL) definitions and details, including: - -* [Notation](/enterprise_influxdb/v1/query_language/spec/#notation) -* [Query representation](/enterprise_influxdb/v1/query_language/spec/#query-representation) - * [Characters](/enterprise_influxdb/v1/query_language/spec/#characters) - * [Letters and digits](/enterprise_influxdb/v1/query_language/spec/#letters-and-digits) - * [Identifiers](/enterprise_influxdb/v1/query_language/spec/#identifiers) - * [Keywords](/enterprise_influxdb/v1/query_language/spec/#keywords) - * [Literals](/enterprise_influxdb/v1/query_language/spec/#literals) -* [Queries](/enterprise_influxdb/v1/query_language/spec/#queries) -* [Statements](/enterprise_influxdb/v1/query_language/spec/#statements) -* [Clauses](/enterprise_influxdb/v1/query_language/spec/#clauses) -* [Expressions](/enterprise_influxdb/v1/query_language/spec/#expressions) -* [Comments](/enterprise_influxdb/v1/query_language/spec/#comments) -* [Other](/enterprise_influxdb/v1/query_language/spec/#other) - -To learn more about InfluxQL, browse the following topics: - -* [Explore your data with InfluxQL](/enterprise_influxdb/v1/query_language/explore-data/) -* [Explore your schema with InfluxQL](/enterprise_influxdb/v1/query_language/explore-schema/) -* [Database management](/enterprise_influxdb/v1/query_language/manage-database/) -* [Authentication and authorization](/enterprise_influxdb/v1/administration/authentication_and_authorization/). -* [Query engine internals](/enterprise_influxdb/v1/query_language/spec/#query-engine-internals) +- [Notation](#notation) +- [Query representation](#query-representation) + - [Characters](#characters) + - [Letters and digits](#letters-and-digits) + - [Identifiers](#identifiers) + - [Keywords](#keywords) + - [Literals](#literals) +- [Queries](#queries) +- [Statements](#statements) +- [Clauses](#clauses) +- [Expressions](#expressions) +- [Comments](#comments) +- [Other](#other) ## 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). +EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). ``` Production = production_name "=" [ Expression ] "." . @@ -95,7 +85,7 @@ 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](/enterprise_influxdb/v1/query_language/spec/#keywords) +- double quoted identifiers can contain InfluxQL [keywords](#keywords) - unquoted identifiers must start with an upper or lowercase ASCII character or "_" - unquoted identifiers may contain only ASCII letters, decimal digits, and "_" @@ -133,7 +123,7 @@ SUBSCRIPTIONS TAG TO USER USERS VALUES WHERE WITH WRITE ``` -If you use an InfluxQL keywords as an +If you use an InfluxQL keyword as an [identifier](/enterprise_influxdb/v1/concepts/glossary/#identifier) you will need to double quote that identifier in every query. @@ -149,7 +139,7 @@ In those cases, `time` does not require double quotes in queries. `time` cannot be a [field key](/enterprise_influxdb/v1/concepts/glossary/#field-key) or [tag key](/enterprise_influxdb/v1/concepts/glossary/#tag-key); InfluxDB rejects writes with `time` as a field key or tag key and returns an error. -See [Frequently Asked Questions](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#time) for more information. +For more information, see [Frequently Asked Questions](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#time). ### Literals @@ -186,7 +176,7 @@ 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 +#### Durations | Units | Meaning | | ------ | --------------------------------------- | @@ -199,6 +189,7 @@ Durations can be specified with mixed units. | d | day | | w | week | + ``` duration_lit = int_lit duration_unit . duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . @@ -232,18 +223,22 @@ regex_lit = "/" { unicode_char } "/" . `=~` matches against `!~` doesn't match against -> **Note:** InfluxQL supports using regular expressions when specifying: -> -* [field keys](/enterprise_influxdb/v1/concepts/glossary/#field-key) and [tag keys](/enterprise_influxdb/v1/concepts/glossary/#tag-key) in the [`SELECT` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-basic-select-statement) -* [measurements](/enterprise_influxdb/v1/concepts/glossary/#measurement) in the [`FROM` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-basic-select-statement) -* [tag values](/enterprise_influxdb/v1/concepts/glossary/#tag-value) and string [field values](/enterprise_influxdb/v1/concepts/glossary/#field-value) in the [`WHERE` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-where-clause). -* [tag keys](/enterprise_influxdb/v1/concepts/glossary/#tag-key) in the [`GROUP BY` clause](/enterprise_influxdb/v1/query_language/explore-data/#group-by-tags) + +InfluxQL supports using regular expressions when specifying: + +- [field keys](/enterprise_influxdb/v1/concepts/glossary/#field-key) and [tag keys](/enterprise_influxdb/v1/concepts/glossary/#tag-key) in the [`SELECT` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-basic-select-statement) +- [measurements](/enterprise_influxdb/v1/concepts/glossary/#measurement) in the [`FROM` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-basic-select-statement) +- [tag values](/enterprise_influxdb/v1/concepts/glossary/#tag-value) and string [field values](/enterprise_influxdb/v1/concepts/glossary/#field-value) in the [`WHERE` clause](/enterprise_influxdb/v1/query_language/explore-data/#the-where-clause). +- [tag keys](/enterprise_influxdb/v1/concepts/glossary/#tag-key) in the [`GROUP BY` clause](/enterprise_influxdb/v1/query_language/explore-data/#group-by-tags) + +> [!Note] +> #### Regular expressions and non-string field values > ->Currently, InfluxQL does not support using regular expressions to match ->non-string field values in the ->`WHERE` clause, ->[databases](/enterprise_influxdb/v1/concepts/glossary/#database), and ->[retention polices](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). +> Currently, InfluxQL does not support using regular expressions to match +> non-string field values in the +> `WHERE` clause, +> [databases](/enterprise_influxdb/v1/concepts/glossary/#database), and +> [retention polices](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). ## Queries @@ -688,11 +683,11 @@ EXPLAIN ANALYZE > Note: EXPLAIN ANALYZE ignores query output, so the cost of serialization to JSON or CSV is not accounted for. -##### execution_time +#### execution_time 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. -##### planning_time +#### planning_time 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. @@ -705,7 +700,7 @@ Next, for each shard and each measurement, InfluxDB performs the following steps 3. Enumerate each tag set and create a cursor and iterator for each series key. 4. Merge iterators and return the merged result to the query executor. -##### iterator type +#### iterator type EXPLAIN ANALYZE supports the following iterator types: @@ -714,7 +709,7 @@ EXPLAIN ANALYZE supports the following iterator types: For more information about iterators, see [Understanding iterators](#understanding-iterators). -##### cursor type +#### cursor type 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: @@ -724,7 +719,7 @@ EXPLAIN ANALYZE distinguishes 3 cursor types. While the cursor types have the sa For more information about cursors, see [Understanding cursors](#understanding-cursors). -##### block types +#### block types 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: @@ -738,7 +733,8 @@ For more information about storage blocks, see [TSM files](/enterprise_influxdb/ ### GRANT -> **NOTE:** Users can be granted privileges on databases that do not yet exist. +> [!Note] +> Users can be granted privileges on databases that do not yet exist. ``` grant_stmt = "GRANT" privilege [ on_clause ] to_clause . @@ -756,27 +752,24 @@ GRANT READ ON "mydb" TO "jdoe" ### KILL QUERY -Stop currently-running query. +Stop a currently-running query. -``` -kill_query_statement = "KILL QUERY" query_id . +```sql +KILL QUERY ON "" ``` -Where `query_id` is the query ID, displayed in the [`SHOW QUERIES`](/enterprise_influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) output as `qid`. +To kill queries on a cluster, specify the query ID (`qid`) and the TCP host (for example, `myhost:8088`) from the `SHOW QUERIES` output. -> ***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. -> -> ```sql -KILL QUERY ON "" +``` +kill_query_statement = "KILL QUERY" query_id ON "myhost:8088". ``` -#### Examples +Replace the following: -```sql --- kill query with qid of 36 on the local host -KILL QUERY 36 -``` +- `query_id`: your query ID (`qid`) from [`SHOW QUERIES`](/enterprise_influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) +- `myhost:8088`: your TCP host from [`SHOW QUERIES`](/enterprise_influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) + +#### Examples ```sql -- kill query on InfluxDB Enterprise cluster @@ -1015,7 +1008,8 @@ Estimates or counts exactly the cardinality of the series for the current databa - [When do I need more RAM?](/enterprise_influxdb/v1/guides/hardware_sizing/#when-do-i-need-more-ram) in [Hardware Sizing Guidelines](/enterprise_influxdb/v1/guides/hardware_sizing/) - [Don't have too many series](/enterprise_influxdb/v1/concepts/schema_and_data_layout/#avoid-too-many-series) -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. @@ -1077,7 +1071,7 @@ id database retention_policy shard_group start_time end_time - `id` column: Shard IDs that belong to the specified `database` and `retention policy`. - `shard_group` column: Group number that a shard belongs to. Shards in the same shard group have the same `start_time` and `end_time`. This interval indicates how long the shard is active, and the `expiry_time` columns shows when the shard group expires. No timestamps will show under `expiry_time` if the retention policy duration is set to infinite. - `owners` column: Shows the data nodes that own a shard. The number of nodes that own a shard is equal to the replication factor. In this example, the replication factor is 3, so 3 nodes own each shard. - + ### SHOW STATS Returns detailed statistics on available components of an InfluxDB node and available (enabled) components. @@ -1110,18 +1104,17 @@ batches_tx bytes_rx connections_active connections_handled 159 3999750 0 1 158110 158110 ``` -### `SHOW STATS FOR ` +### SHOW STATS FOR For the specified 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](https://golang.org/pkg/runtime/) package. -### `SHOW STATS FOR 'indexes'` +### 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. - ### SHOW SUBSCRIPTIONS ``` @@ -1138,7 +1131,8 @@ SHOW SUBSCRIPTIONS Estimates or counts exactly the cardinality of tag key set on the current database unless a database is specified using the `ON ` option. -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. @@ -1160,7 +1154,7 @@ SHOW TAG KEY EXACT CARDINALITY ### SHOW TAG KEYS ``` -show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [ from_clause ] [ where_clause ] +show_tag_keys_stmt = "SHOW TAG KEYS" [on_clause] [with_key_clause] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] . ``` @@ -1178,6 +1172,9 @@ SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest' -- show all tag keys where the host key = 'serverA' SHOW TAG KEYS WHERE "host" = 'serverA' + +-- show specific tag keys +SHOW TAG KEYS WITH KEY IN ("region", "host") ``` ### SHOW TAG VALUES @@ -1207,7 +1204,8 @@ SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'red 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 ` option. -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. diff --git a/content/influxdb/v1/query_language/spec.md b/content/influxdb/v1/query_language/spec.md index 4aa0aa8a31..51485cd9de 100644 --- a/content/influxdb/v1/query_language/spec.md +++ b/content/influxdb/v1/query_language/spec.md @@ -1,6 +1,6 @@ --- title: Influx Query Language (InfluxQL) reference -description: List of resources for Influx Query Language (InfluxQL). +description: InfluxQL is a SQL-like query language for interacting with InfluxDB and providing features specific to storing and analyzing time series data. menu: influxdb_v1: name: InfluxQL reference @@ -8,38 +8,31 @@ menu: parent: InfluxQL aliases: - /influxdb/v2/query_language/spec/ +related: + - /influxdb/v1/query_language/explore-data/ + - /influxdb/v1/query_language/explore-schema/ + - /influxdb/v1/query_language/manage-database/ --- -## Introduction - -Find Influx Query Language (InfluxQL) definitions and details, including: - -- [Notation](/influxdb/v1/query_language/spec/#notation) -- [Query representation](/influxdb/v1/query_language/spec/#query-representation) -- [Identifiers](/influxdb/v1/query_language/spec/#identifiers) -- [Keywords](/influxdb/v1/query_language/spec/#keywords) -- [Literals](/influxdb/v1/query_language/spec/#literals) -- [Queries](/influxdb/v1/query_language/spec/#queries) -- [Statements](/influxdb/v1/query_language/spec/#statements) -- [Clauses](/influxdb/v1/query_language/spec/#clauses) -- [Expressions](/influxdb/v1/query_language/spec/#expressions) -- [Other](/influxdb/v1/query_language/spec/#other) -- [Query engine internals](/influxdb/v1/query_language/spec/#query-engine-internals) - -To learn more about InfluxQL, browse the following topics: - -- [Explore your data with InfluxQL](/influxdb/v1/query_language/explore-data/) -- [Explore your schema with InfluxQL](/influxdb/v1/query_language/explore-schema/) -- [Database management](/influxdb/v1/query_language/manage-database/) -- [Authentication and authorization](/influxdb/v1/administration/authentication_and_authorization/). - -InfluxQL is a SQL-like query language for interacting with InfluxDB and providing features specific to storing and analyzing time series data. +InfluxQL is a SQL-like query language for interacting with InfluxDB +and providing features specific to storing and analyzing time series data. + +- [Notation](#notation) +- [Query representation](#query-representation) +- [Identifiers](#identifiers) +- [Keywords](#keywords) +- [Literals](#literals) +- [Queries](#queries) +- [Statements](#statements) +- [Clauses](#clauses) +- [Expressions](#expressions) +- [Other](#other) +- [Query engine internals](#query-engine-internals) ## 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. +EBNF is the same notation used in the [Go programming language specification](https://golang.org/ref/spec). ``` Production = production_name "=" [ Expression ] "." . @@ -71,7 +64,7 @@ newline = /* the Unicode code point U+000A */ . unicode_char = /* an arbitrary Unicode code point except newline */ . ``` -## Letters and digits +### Letters and digits Letters are the set of ASCII characters plus the underscore character _ (U+005F) is considered a letter. @@ -83,7 +76,7 @@ ascii_letter = "A" … "Z" | "a" … "z" . digit = "0" … "9" . ``` -## Identifiers +### Identifiers Identifiers are tokens which refer to [database](/influxdb/v1/concepts/glossary/#database) names, [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp) names, [user](/influxdb/v1/concepts/glossary/#user) names, [measurement](/influxdb/v1/concepts/glossary/#measurement) names, [tag keys](/influxdb/v1/concepts/glossary/#tag-key), and [field keys](/influxdb/v1/concepts/glossary/#field-key). @@ -91,7 +84,7 @@ 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](/influxdb/v1/query_language/spec/#keywords) +- double quoted identifiers can contain InfluxQL [keywords](#keywords) - unquoted identifiers must start with an upper or lowercase ASCII character or "_" - unquoted identifiers may contain only ASCII letters, decimal digits, and "_" @@ -111,7 +104,7 @@ _cpu_stats "1_Crazy-1337.identifier>NAME👍" ``` -## Keywords +### Keywords ``` ALL ALTER ANY AS ASC BEGIN @@ -129,7 +122,7 @@ SUBSCRIPTIONS TAG TO USER USERS VALUES WHERE WITH WRITE ``` -If you use an InfluxQL keywords as an +If you use an InfluxQL keyword as an [identifier](/influxdb/v1/concepts/glossary/#identifier) you will need to double quote that identifier in every query. @@ -145,11 +138,11 @@ In those cases, `time` does not require double quotes in queries. `time` cannot be a [field key](/influxdb/v1/concepts/glossary/#field-key) or [tag key](/influxdb/v1/concepts/glossary/#tag-key); InfluxDB rejects writes with `time` as a field key or tag key and returns an error. -See [Frequently Asked Questions](/influxdb/v1/troubleshooting/frequently-asked-questions/#time) for more information. +For more information, see [Frequently Asked Questions](/influxdb/v1/troubleshooting/frequently-asked-questions/#time). -## Literals +### Literals -### Integers +#### Integers InfluxQL supports decimal integer literals. Hexadecimal and octal literals are not currently supported. @@ -158,7 +151,7 @@ Hexadecimal and octal literals are not currently supported. int_lit = ( "1" … "9" ) { digit } . ``` -### Floats +#### Floats InfluxQL supports floating-point literals. Exponents are not currently supported. @@ -167,7 +160,7 @@ Exponents are not currently supported. float_lit = int_lit "." int_lit . ``` -### Strings +#### Strings String literals must be surrounded by single quotes. Strings may contain `'` characters as long as they are escaped (i.e., `\'`). @@ -176,13 +169,13 @@ Strings may contain `'` characters as long as they are escaped (i.e., `\'`). string_lit = `'` { unicode_char } `'` . ``` -### Durations +#### 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 +#### Durations | Units | Meaning | | ------ | --------------------------------------- | @@ -201,7 +194,7 @@ duration_lit = int_lit duration_unit . duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" . ``` -### Dates & Times +#### 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. @@ -213,13 +206,13 @@ 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 +#### Booleans ``` bool_lit = TRUE | FALSE . ``` -### Regular Expressions +#### Regular Expressions ``` regex_lit = "/" { unicode_char } "/" . @@ -229,19 +222,22 @@ regex_lit = "/" { unicode_char } "/" . `=~` matches against `!~` doesn't match against + +InfluxQL supports using regular expressions when specifying: + +- [field keys](/influxdb/v1/concepts/glossary/#field-key) and [tag keys](/influxdb/v1/concepts/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v1/query_language/explore-data/#the-basic-select-statement) +- [measurements](/influxdb/v1/concepts/glossary/#measurement) in the [`FROM` clause](/influxdb/v1/query_language/explore-data/#the-basic-select-statement) +- [tag values](/influxdb/v1/concepts/glossary/#tag-value) and string [field values](/influxdb/v1/concepts/glossary/#field-value) in the [`WHERE` clause](/influxdb/v1/query_language/explore-data/#the-where-clause). +- [tag keys](/influxdb/v1/concepts/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v1/query_language/explore-data/#group-by-tags) + > [!Note] -> InfluxQL supports using regular expressions when specifying: -> -> * [field keys](/influxdb/v1/concepts/glossary/#field-key) and [tag keys](/influxdb/v1/concepts/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v1/query_language/explore-data/#the-basic-select-statement) -> * [measurements](/influxdb/v1/concepts/glossary/#measurement) in the [`FROM` clause](/influxdb/v1/query_language/explore-data/#the-basic-select-statement) -> * [tag values](/influxdb/v1/concepts/glossary/#tag-value) and string [field values](/influxdb/v1/concepts/glossary/#field-value) in the [`WHERE` clause](/influxdb/v1/query_language/explore-data/#the-where-clause). -> * [tag keys](/influxdb/v1/concepts/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v1/query_language/explore-data/#group-by-tags) +> #### Regular expressions and non-string field values > ->Currently, InfluxQL does not support using regular expressions to match ->non-string field values in the ->`WHERE` clause, ->[databases](/influxdb/v1/concepts/glossary/#database), and ->[retention polices](/influxdb/v1/concepts/glossary/#retention-policy-rp). +> Currently, InfluxQL does not support using regular expressions to match +> non-string field values in the +> `WHERE` clause, +> [databases](/influxdb/v1/concepts/glossary/#database), and +> [retention polices](/influxdb/v1/concepts/glossary/#retention-policy-rp). ## Queries @@ -736,7 +732,8 @@ For more information about storage blocks, see [TSM files](/influxdb/v1/concepts ### GRANT -> **NOTE:** Users can be granted privileges on databases that do not yet exist. +> [!Note] +> Users can be granted privileges on databases that do not yet exist. ``` grant_stmt = "GRANT" privilege [ on_clause ] to_clause . @@ -754,20 +751,17 @@ GRANT READ ON "mydb" TO "jdoe" ### KILL QUERY -Stop currently-running query. +Stop a currently-running query. + +```sql +KILL QUERY +``` ``` kill_query_statement = "KILL QUERY" query_id . ``` -Where `query_id` is the query ID, displayed in the [`SHOW QUERIES`](/influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) output as `qid`. - -> ***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. -> -> ```sql -KILL QUERY ON "" -``` +Replace `query_id` with your query ID from [`SHOW QUERIES`](/influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries), output as `qid`. #### Examples @@ -776,11 +770,6 @@ KILL QUERY ON "" KILL QUERY 36 ``` -```sql --- kill query on InfluxDB Enterprise cluster -KILL QUERY 53 ON "myhost:8088" -``` - ### REVOKE ```sql @@ -923,7 +912,7 @@ show_grants_stmt = "SHOW GRANTS FOR" user_name . SHOW GRANTS FOR "jdoe" ``` -#### SHOW MEASUREMENT CARDINALITY +### 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 ` option. @@ -1013,7 +1002,8 @@ Estimates or counts exactly the cardinality of the series for the current databa - [When do I need more RAM?](/influxdb/v1/guides/hardware_sizing/#when-do-i-need-more-ram) in [Hardware Sizing Guidelines](/influxdb/v1/guides/hardware_sizing/) - [Don't have too many series](/influxdb/v1/concepts/schema_and_data_layout/#avoid-too-many-series) -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. @@ -1080,26 +1070,18 @@ id database retention_policy shard_group start_time end_time Returns detailed statistics on available components of an InfluxDB node and available (enabled) components. +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. + +The `SHOW STATS` command does not list index memory usage -- +use the [`SHOW STATS FOR 'indexes'`](#show-stats-for-indexes) command. + For more information on using the `SHOW STATS` command, see [Using the SHOW STATS command to monitor InfluxDB](/platform/monitoring/tools/show-stats/). ``` show_stats_stmt = "SHOW STATS [ FOR '' | 'indexes' ]" ``` -#### `SHOW STATS` - -- The `SHOW STATS` command does not list index memory usage -- use the [`SHOW STATS FOR 'indexes'`](#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 ` - -- For the specified 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](https://golang.org/pkg/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 ```sql @@ -1109,7 +1091,6 @@ name: runtime Alloc Frees HeapAlloc HeapIdle HeapInUse HeapObjects HeapReleased HeapSys Lookups Mallocs NumGC NumGoroutine PauseTotalNs Sys TotalAlloc 4136056 6684537 4136056 34586624 5816320 49412 0 40402944 110 6733949 83 44 36083006 46692600 439945704 - name: graphite tags: proto=tcp batches_tx bytes_rx connections_active connections_handled points_rx points_tx @@ -1117,6 +1098,17 @@ batches_tx bytes_rx connections_active connections_handled 159 3999750 0 1 158110 158110 ``` +### SHOW STATS FOR + +For the specified 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](https://golang.org/pkg/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. + ### SHOW SUBSCRIPTIONS ``` @@ -1129,11 +1121,12 @@ show_subscriptions_stmt = "SHOW SUBSCRIPTIONS" . SHOW SUBSCRIPTIONS ``` -#### SHOW TAG KEY CARDINALITY +### 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 ` option. -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. @@ -1201,11 +1194,12 @@ SHOW TAG VALUES WITH KEY !~ /.*c.*/ SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis' ``` -#### SHOW TAG VALUES CARDINALITY +### 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 ` option. -> **Note:** `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, and `LIMIT/OFFSET` clauses are optional. +> [!Note] +> `ON `, `FROM `, `WITH KEY = `, `WHERE `, `GROUP BY `, 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. @@ -1285,6 +1279,15 @@ unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | float_lit | bool_lit | duration_lit | regex_lit . ``` +## 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. + ## Other ``` @@ -1367,15 +1370,6 @@ user_name = identifier . 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 @@ -1475,7 +1469,7 @@ iterator. ### Built-in iterators -InfluxDB provides many helper iterators that let us build queries: +{{% product-name %}} provides many helper iterators for building 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