diff --git a/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md b/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md index 68a1cb908..43a42e3de 100644 --- a/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md +++ b/content/enterprise_influxdb/v1/administration/configure/config-meta-nodes.md @@ -341,7 +341,7 @@ The shared secret used by the internal API for JWT authentication for inter-node communication within the cluster. Set this to a long pass phrase. This value must be the same value as the -[`[meta] meta-internal-shared-secret`](/enterprise_influxdb/v1/administration/config-data-nodes#meta-internal-shared-secret) in the data node configuration file. +[`[meta] meta-internal-shared-secret`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#meta-internal-shared-secret) in the data node configuration file. To use this option, set [`auth-enabled`](#auth-enabled) to `true`. Environment variable: `INFLUXDB_META_INTERNAL_SHARED_SECRET` @@ -452,7 +452,7 @@ Environment variable: `INFLUXDB_META_ENSURE_FIPS` Default is `false`. Require Raft clients to authenticate with server using the -[`meta-internal-shared-secret`](#meta-internal-shared-secret). +[`meta-internal-shared-secret`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#meta-internal-shared-secret). This requires that all meta nodes are running InfluxDB Enterprise v1.12.0+ and are configured with the correct `meta-internal-shared-secret`. @@ -465,7 +465,7 @@ Environment variable: `INFLUXDB_META_RAFT_PORTAL_AUTH_REQUIRED` Default is `false`. Require Raft servers to authenticate Raft clients using the -[`meta-internal-shared-secret`](#meta-internal-shared-secret). +[`meta-internal-shared-secret`](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#meta-internal-shared-secret). This requires that all meta nodes are running InfluxDB Enterprise v1.12.0+, have `raft-portal-auth-required=true`, and are configured with the correct `meta-internal-shared-secret`. For existing clusters, it is recommended to enable `raft-portal-auth-required` and restart diff --git a/content/enterprise_influxdb/v1/query_language/spec.md b/content/enterprise_influxdb/v1/query_language/spec.md index 0b050ed6c..58fa4144d 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 @@ -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,21 @@ regex_lit = "/" { unicode_char } "/" . `=~` matches against `!~` doesn't match against -> **Note:** InfluxQL supports using regular expressions when specifying: +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 > -* [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) -> ->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 policies](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). ## Queries @@ -637,7 +631,7 @@ SIZE OF BLOCKS: 931 ### EXPLAIN ANALYZE -Executes the specified SELECT statement and returns data on the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution-time) and [planning time](#planning-time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). +Executes the specified SELECT statement and returns data on the query performance and storage during runtime, visualized as a tree. Use this statement to analyze query performance and storage, including [execution time](#execution_time) and [planning time](#planning_time), and the [iterator type](#iterator-type) and [cursor type](#cursor-type). For example, executing the following statement: @@ -683,11 +677,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. @@ -700,16 +694,16 @@ 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: - `create_iterator` node represents work done by the local influxd instance──a complex composition of nested iterators combined and merged to produce the final query output. - (InfluxDB Enterprise only) `remote_iterator` node represents work done on remote machines. -For more information about iterators, see [Understanding iterators](#understanding-iterators). +For more information about iterators, see [Understanding iterators](/influxdb/v1/query_language/spec/#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: @@ -717,9 +711,9 @@ EXPLAIN ANALYZE distinguishes 3 cursor types. While the cursor types have the sa - cursor_aux: Auxiliary cursor created for simple expression projections (not selectors or an aggregation). For example, `SELECT foo FROM m` or `SELECT foo+bar FROM m`, where `foo` and `bar` are fields. - cursor_cond: Condition cursor created for fields referenced in a WHERE clause. -For more information about cursors, see [Understanding cursors](#understanding-cursors). +For more information about cursors, see [Understanding cursors](/influxdb/v1/query_language/spec/#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: @@ -733,7 +727,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 . @@ -751,29 +746,27 @@ GRANT READ ON "mydb" TO "jdoe" ### KILL QUERY -Stop currently-running query. +Stop a currently-running query. -``` -kill_query_statement = "KILL QUERY" query_id . +#### Syntax + +```text +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`. +Replace the following: -> ***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 "" -``` +- `query_id`: your query ID (`qid`) from [`SHOW QUERIES`](/influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) +- `host`: your TCP host (for example, `myhost:8088`) from [`SHOW QUERIES`](/influxdb/v1/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) + +To kill queries on a cluster, specify both the query ID and the TCP host. #### Examples ```sql -- kill query with qid of 36 on the local host KILL QUERY 36 -``` -```sql -- kill query on InfluxDB Enterprise cluster KILL QUERY 53 ON "myhost:8088" ``` @@ -1010,7 +1003,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. @@ -1072,7 +1066,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. @@ -1105,18 +1099,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 ``` @@ -1133,7 +1126,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. @@ -1155,7 +1149,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 ] . ``` @@ -1173,6 +1167,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 @@ -1202,7 +1199,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.