From 37ab74fa25abda67edb894fbd54ff1156e08070f Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 14 May 2024 13:06:04 -0600 Subject: [PATCH] document influxql subqueries (#5470) --- assets/styles/layouts/_article.scss | 9 +- .../reference/influxql/feature-support.md | 8 - .../reference/influxql/select.md | 55 ++-- .../reference/influxql/subqueries.md | 246 ++++++++++++++++++ .../reference/influxql/feature-support.md | 8 - .../reference/influxql/select.md | 61 +++-- .../reference/influxql/subqueries.md | 246 ++++++++++++++++++ .../reference/influxql/feature-support.md | 8 - .../clustered/reference/influxql/select.md | 55 ++-- .../reference/influxql/subqueries.md | 246 ++++++++++++++++++ 10 files changed, 850 insertions(+), 92 deletions(-) create mode 100644 content/influxdb/cloud-dedicated/reference/influxql/subqueries.md create mode 100644 content/influxdb/cloud-serverless/reference/influxql/subqueries.md create mode 100644 content/influxdb/clustered/reference/influxql/subqueries.md diff --git a/assets/styles/layouts/_article.scss b/assets/styles/layouts/_article.scss index 543caccc5..e2a23703c 100644 --- a/assets/styles/layouts/_article.scss +++ b/assets/styles/layouts/_article.scss @@ -70,14 +70,19 @@ vertical-align: middle; } - &[date]::after { - content: attr(date); + &[date]::after, + &[note]::after { margin-left: .65rem; opacity: .4; font-size: .75em; font-weight: $medium; font-style: inherit; } + &[date]::after {content: attr(date);} + &[note]::after { + content: attr(note); + font-size: .85em; + } } h1 { diff --git a/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md b/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md index c239dfe74..0de04eaa5 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/feature-support.md @@ -18,7 +18,6 @@ InfluxQL features. - [In-progress features](#in-progress-features) - [Time zones](#time-zones) - - [Subqueries](#subqueries) - [SLIMIT clause](#slimit-clause) - [SOFFSET clause](#soffset-clause) - [Metaqueries](#metaqueries) @@ -37,13 +36,6 @@ which applies a time zone offset to UTC timestamps in query results. -### Subqueries - -InfluxQL in {{< product-name >}} does not currently support subqueries, which -let you query data from the results of another InfluxQL query. - - - ### SLIMIT clause InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, diff --git a/content/influxdb/cloud-dedicated/reference/influxql/select.md b/content/influxdb/cloud-dedicated/reference/influxql/select.md index 37ec6923e..5d5c246e4 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/select.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/select.md @@ -66,35 +66,41 @@ It requires one or more **field expressions** and optional **tag expressions**. ### FROM clause The `FROM` clause specifies the -[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to query. -It requires one or more comma-delimited **measurement expressions**. +[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) or +[subquery](/influxdb/cloud-dedicated/reference/influxql/subqueries/) to query. +It requires one or more comma-delimited +[measurement expressions](#measurement_expression) or [subqueries](#subquery). -- #### measurement_expression +#### measurement_expression - Expression to identify one or more measurements to query. - Can be a measurement name, fully-qualified measurement, constant, or - [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/). +A measurement expression identifies a measurement to query. +It can be a measurement name, fully-qualified measurement, constant, or +a [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/). - - ##### Measurement name +- **Measurement name**: When using just the measurement name, InfluxQL assumes + the default retention policy of the database specified in the query request. - ```sql - FROM measurement - ``` + ```sql + FROM measurement + ``` - - ##### Fully-qualified measurement +- **Fully-qualified measurement**: A fully qualified measurement includes a + database name, retention policy name, and measurement name, each separated by + a period (`.`). If the retention policy is not specified, InfluxQL uses the + default retention policy for the specified database. - ```sql - FROM database.retention_policy.measurement +```sql +FROM database.retention_policy.measurement - -- Fully-qualified measurement with default retention policy - FROM database..measurement - ``` +-- Fully-qualified measurement with default retention policy +FROM database..measurement +``` - {{% note %}} -#### InfluxDB retention policies +{{% note %}} +#### InfluxQL retention policies -In {{< product-name >}}, **retention policies** are not part of the data model like -they are in InfluxDB 1.x. +In {{< product-name >}}, **retention policies** are not part of the data model +like they are in InfluxDB 1.x. Each {{< product-name >}} database has a **retention period** which defines the maximum age of data to retain in the database. To use fully-qualified measurements in InfluxQL queries, use the following naming convention when @@ -103,7 +109,14 @@ measurements in InfluxQL queries, use the following naming convention when ``` database_name/retention_policy ``` - {{% /note %}} +{{% /note %}} + +#### Subquery + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +For more information, see [InfluxQL subqueries](/influxdb/cloud-dedicated/reference/influxql/subqueries/). ## Notable SELECT statement behaviors diff --git a/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md b/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md new file mode 100644 index 000000000..45626be6c --- /dev/null +++ b/content/influxdb/cloud-dedicated/reference/influxql/subqueries.md @@ -0,0 +1,246 @@ +--- +title: InfluxQL subqueries +description: > + An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. + The outer query queries results returned by the inner query (subquery). +menu: + influxdb_cloud_dedicated: + name: Subqueries + identifier: influxql-subqueries + parent: influxql-reference +weight: 207 +list_code_example: | + ```sql + SELECT_clause FROM ( SELECT_statement ) [...] + ``` +--- + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +- [Syntax](#syntax) +- [Examples](#examples) +- [Notable subquery behaviors](#notable-subquery-behaviors) + +{{% note %}} +InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer +functionality similar to the [SQL `HAVING` clause](/influxdb/cloud-dedicated/reference/sql/having/). +{{% /note %}} + +## Syntax + +```sql +SELECT_clause FROM ( SELECT_statement ) [...] +``` + +When using subqueries, InfluxQL **performs the inner query first**, then performs +the outer query. + +The outer query requires a [`SELECT` clause](/influxdb/cloud-dedicated/reference/influxql/select/#select-clause) +and a [`FROM` clause](/influxdb/cloud-dedicated/reference/influxql/select/#from-clause). +The inner query is enclosed in parentheses in the outer query's `FROM` clause. + +InfluxQL supports multiple nested subqueries: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] +``` + +## Examples + +{{% note %}} +#### Sample data + +The examples below use the following sample data sets: + +- [Get started home sensor data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data) +- [Random numbers sample data](/influxdb/cloud-dedicated/reference/sample-data/#random-numbers-sample-data) +{{% /note %}} + +{{< expand-wrapper >}} + +{{% expand "Apply an aggregate function to an aggregated result set" %}} + +```sql +SELECT + SUM(max) +FROM + ( + SELECT + MAX(temp) + FROM + home + GROUP BY + room + ) +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ---: | +| 1970-01-01T00:00:00Z | 46.1 | + +{{% /expand %}} + +{{% expand "Calculate the average difference between two fields" %}} + +```sql +SELECT + MEAN(difference) +FROM + ( + SELECT + a - b AS difference + FROM + numbers + ) +``` + +{{% influxql/table-meta %}} +Table: numbers +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | -0.03629771779732732 | + +{{% /expand %}} + +{{% expand "Filter aggregate values based on a threshold" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + co_change +FROM + ( + SELECT + SPREAD(co) AS co_change + FROM + home + GROUP BY + room, + time(2h) + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + AND co_change >= 4 +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | co_chnage | +| :------------------- | --------: | +| 2022-01-01T18:00:00Z | 4 | +| 2022-01-01T18:00:00Z | 5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Perform additional aggregate operations on aggregate values" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SUM(co_derivative) AS sum_derivative +FROM + ( + SELECT + DERIVATIVE(MEAN(co)) AS co_derivative + FROM + home + GROUP BY + time(12m), + room + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + room +``` + +{{% /influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | room | sum_derivative | +| :------------------- | :---------- | -------------: | +| 1970-01-01T00:00:00Z | Kitchen | 5.2 | +| 1970-01-01T00:00:00Z | Living Room | 3.4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable subquery behaviors + +- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) +- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) + +### Apply time bounds to the outer query to improve performance + +To improve the performance of InfluxQL queries that use subqueries and a +specified time range, apply the `WHERE` clause with time-based predicates to the +outer query rather than the inner query. +For example--the following queries return the same results, but **the query with +time-based predicate on the outer query is more performant than the query with +time-based predicate on the inner query**: + +{{% influxdb/custom-timestamps %}} + +#### Time bounds on the outer query {note="(Recommended)"} + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +#### Time bounds on the inner query + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + WHERE + time >= '2022-07-19T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ) +``` +{{% /influxdb/custom-timestamps %}} + +### Cannot use multiple SELECT statements in a subquery + +InfluxQL does not support multiple +[`SELECT` statements](/influxdb/cloud-dedicated/reference/influxql/select/) +per subquery: + +```sql +SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] +``` + +However, InfluxQL does support multiple nested subqueries per outer query: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] + ------------------ ---------------- + Subquery 1 Subquery 2 +``` diff --git a/content/influxdb/cloud-serverless/reference/influxql/feature-support.md b/content/influxdb/cloud-serverless/reference/influxql/feature-support.md index 91191e6b3..aaf0775c9 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/feature-support.md +++ b/content/influxdb/cloud-serverless/reference/influxql/feature-support.md @@ -18,7 +18,6 @@ InfluxQL features. - [In-progress features](#in-progress-features) - [Time zones](#time-zones) - - [Subqueries](#subqueries) - [SLIMIT clause](#slimit-clause) - [SOFFSET clause](#soffset-clause) - [Metaqueries](#metaqueries) @@ -37,13 +36,6 @@ which applies a time zone offset to UTC timestamps in query results. -### Subqueries - -InfluxQL in {{< product-name >}} does not currently support subqueries, which -let you query data from the results of another InfluxQL query. - - - ### SLIMIT clause InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, diff --git a/content/influxdb/cloud-serverless/reference/influxql/select.md b/content/influxdb/cloud-serverless/reference/influxql/select.md index 33c5587e9..c6bb5e42b 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/select.md +++ b/content/influxdb/cloud-serverless/reference/influxql/select.md @@ -66,44 +66,57 @@ It requires one or more **field expressions** and optional **tag expressions**. ### FROM clause The `FROM` clause specifies the -[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to query. -It requires one or more comma-delimited [measurement_expressions](#measurement_expression). +[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) or +[subquery](/influxdb/cloud-serverless/reference/influxql/subqueries/) to query. +It requires one or more comma-delimited +[measurement expressions](#measurement_expression) or [subqueries](#subquery). -- #### measurement_expression +#### measurement_expression - Expression to identify one or more measurements to query. - Can be a measurement name, fully-qualified measurement, constant, or - [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/). +A measurement expression identifies a measurement to query. +It can be a measurement name, fully-qualified measurement, constant, or +a [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/). - - ##### Measurement name +- **Measurement name**: When using just the measurement name, InfluxQL assumes + the default retention policy of the database specified in the query request. - ```sql - FROM measurement - ``` + ```sql + FROM measurement + ``` - - ##### Fully-qualified measurement +- **Fully-qualified measurement**: A fully qualified measurement includes a + database name, retention policy name, and measurement name, each separated by + a period (`.`). If the retention policy is not specified, InfluxQL uses the + default retention policy for the specified database. - ```sql - FROM database.retention_policy.measurement +```sql +FROM database.retention_policy.measurement - -- Fully-qualified measurement with default retention policy - FROM database..measurement - ``` +-- Fully-qualified measurement with default retention policy +FROM database..measurement +``` - {{% note %}} -#### InfluxDB retention policies +{{% note %}} +#### InfluxQL retention policies -In {{< product-name >}}, **retention policies** are not part of the data model like -they are in InfluxDB 1.x. -Each {{< product-name >}} bucket has a **retention period** which defines the -maximum age of data to retain in the bucket. To use fully-qualified +In {{< product-name >}}, **retention policies** are not part of the data model +like they are in InfluxDB 1.x. +Each {{< product-name >}} database has a **retention period** which defines the +maximum age of data to retain in the database. To use fully-qualified measurements in InfluxQL queries, use the following naming convention when -[creating a bucket](/influxdb/cloud-serverless/admin/buckets/create-bucket/): +[creating a database](/influxdb/cloud-serverless/admin/databases/create/): ``` database_name/retention_policy ``` - {{% /note %}} +{{% /note %}} + +#### Subquery + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +For more information, see [InfluxQL subqueries](/influxdb/cloud-serverless/reference/influxql/subqueries/). ## Notable SELECT statement behaviors diff --git a/content/influxdb/cloud-serverless/reference/influxql/subqueries.md b/content/influxdb/cloud-serverless/reference/influxql/subqueries.md new file mode 100644 index 000000000..aa609705c --- /dev/null +++ b/content/influxdb/cloud-serverless/reference/influxql/subqueries.md @@ -0,0 +1,246 @@ +--- +title: InfluxQL subqueries +description: > + An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. + The outer query queries results returned by the inner query (subquery). +menu: + influxdb_cloud_serverless: + name: Subqueries + identifier: influxql-subqueries + parent: influxql-reference +weight: 207 +list_code_example: | + ```sql + SELECT_clause FROM ( SELECT_statement ) [...] + ``` +--- + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +- [Syntax](#syntax) +- [Examples](#examples) +- [Notable subquery behaviors](#notable-subquery-behaviors) + +{{% note %}} +InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer +functionality similar to the [SQL `HAVING` clause](/influxdb/cloud-serverless/reference/sql/having/). +{{% /note %}} + +## Syntax + +```sql +SELECT_clause FROM ( SELECT_statement ) [...] +``` + +When using subqueries, InfluxQL **performs the inner query first**, then performs +the outer query. + +The outer query requires a [`SELECT` clause](/influxdb/cloud-serverless/reference/influxql/select/#select-clause) +and a [`FROM` clause](/influxdb/cloud-serverless/reference/influxql/select/#from-clause). +The inner query is enclosed in parentheses in the outer query's `FROM` clause. + +InfluxQL supports multiple nested subqueries: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] +``` + +## Examples + +{{% note %}} +#### Sample data + +The examples below use the following sample data sets: + +- [Get started home sensor data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data) +- [Random numbers sample data](/influxdb/cloud-serverless/reference/sample-data/#random-numbers-sample-data) +{{% /note %}} + +{{< expand-wrapper >}} + +{{% expand "Apply an aggregate function to an aggregated result set" %}} + +```sql +SELECT + SUM(max) +FROM + ( + SELECT + MAX(temp) + FROM + home + GROUP BY + room + ) +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ---: | +| 1970-01-01T00:00:00Z | 46.1 | + +{{% /expand %}} + +{{% expand "Calculate the average difference between two fields" %}} + +```sql +SELECT + MEAN(difference) +FROM + ( + SELECT + a - b AS difference + FROM + numbers + ) +``` + +{{% influxql/table-meta %}} +Table: numbers +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | -0.03629771779732732 | + +{{% /expand %}} + +{{% expand "Filter aggregate values based on a threshold" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + co_change +FROM + ( + SELECT + SPREAD(co) AS co_change + FROM + home + GROUP BY + room, + time(2h) + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + AND co_change >= 4 +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | co_chnage | +| :------------------- | --------: | +| 2022-01-01T18:00:00Z | 4 | +| 2022-01-01T18:00:00Z | 5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Perform additional aggregate operations on aggregate values" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SUM(co_derivative) AS sum_derivative +FROM + ( + SELECT + DERIVATIVE(MEAN(co)) AS co_derivative + FROM + home + GROUP BY + time(12m), + room + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + room +``` + +{{% /influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | room | sum_derivative | +| :------------------- | :---------- | -------------: | +| 1970-01-01T00:00:00Z | Kitchen | 5.2 | +| 1970-01-01T00:00:00Z | Living Room | 3.4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable subquery behaviors + +- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) +- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) + +### Apply time bounds to the outer query to improve performance + +To improve the performance of InfluxQL queries that use subqueries and a +specified time range, apply the `WHERE` clause with time-based predicates to the +outer query rather than the inner query. +For example--the following queries return the same results, but **the query with +time-based predicate on the outer query is more performant than the query with +time-based predicate on the inner query**: + +{{% influxdb/custom-timestamps %}} + +#### Time bounds on the outer query {note="(Recommended)"} + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +#### Time bounds on the inner query + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + WHERE + time >= '2022-07-19T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ) +``` +{{% /influxdb/custom-timestamps %}} + +### Cannot use multiple SELECT statements in a subquery + +InfluxQL does not support multiple +[`SELECT` statements](/influxdb/cloud-serverless/reference/influxql/select/) +per subquery: + +```sql +SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] +``` + +However, InfluxQL does support multiple nested subqueries per outer query: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] + ------------------ ---------------- + Subquery 1 Subquery 2 +``` diff --git a/content/influxdb/clustered/reference/influxql/feature-support.md b/content/influxdb/clustered/reference/influxql/feature-support.md index a09c04868..b0358de96 100644 --- a/content/influxdb/clustered/reference/influxql/feature-support.md +++ b/content/influxdb/clustered/reference/influxql/feature-support.md @@ -18,7 +18,6 @@ InfluxQL features. - [In-progress features](#in-progress-features) - [Time zones](#time-zones) - - [Subqueries](#subqueries) - [SLIMIT clause](#slimit-clause) - [SOFFSET clause](#soffset-clause) - [Metaqueries](#metaqueries) @@ -37,13 +36,6 @@ which applies a time zone offset to UTC timestamps in query results. -### Subqueries - -InfluxQL in {{< product-name >}} does not currently support subqueries, which -let you query data from the results of another InfluxQL query. - - - ### SLIMIT clause InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause, diff --git a/content/influxdb/clustered/reference/influxql/select.md b/content/influxdb/clustered/reference/influxql/select.md index e026f7c98..ba8ce3807 100644 --- a/content/influxdb/clustered/reference/influxql/select.md +++ b/content/influxdb/clustered/reference/influxql/select.md @@ -66,35 +66,41 @@ It requires one or more **field expressions** and optional **tag expressions**. ### FROM clause The `FROM` clause specifies the -[measurement](/influxdb/clustered/reference/glossary/#measurement) to query. -It requires one or more comma-delimited **measurement expressions**. +[measurement](/influxdb/clustered/reference/glossary/#measurement) or +[subquery](/influxdb/clustered/reference/influxql/subqueries/) to query. +It requires one or more comma-delimited +[measurement expressions](#measurement_expression) or [subqueries](#subquery). -- #### measurement_expression +#### measurement_expression - Expression to identify one or more measurements to query. - Can be a measurement name, fully-qualified measurement, constant, or - [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/). +A measurement expression identifies a measurement to query. +It can be a measurement name, fully-qualified measurement, constant, or +a [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/). - - ##### Measurement name +- **Measurement name**: When using just the measurement name, InfluxQL assumes + the default retention policy of the database specified in the query request. - ```sql - FROM measurement - ``` + ```sql + FROM measurement + ``` - - ##### Fully-qualified measurement +- **Fully-qualified measurement**: A fully qualified measurement includes a + database name, retention policy name, and measurement name, each separated by + a period (`.`). If the retention policy is not specified, InfluxQL uses the + default retention policy for the specified database. - ```sql - FROM database.retention_policy.measurement +```sql +FROM database.retention_policy.measurement - -- Fully-qualified measurement with default retention policy - FROM database..measurement - ``` +-- Fully-qualified measurement with default retention policy +FROM database..measurement +``` - {{% note %}} -#### InfluxDB retention policies +{{% note %}} +#### InfluxQL retention policies -In {{< product-name >}}, **retention policies** are not part of the data model like -they are in InfluxDB 1.x. +In {{< product-name >}}, **retention policies** are not part of the data model +like they are in InfluxDB 1.x. Each {{< product-name >}} database has a **retention period** which defines the maximum age of data to retain in the database. To use fully-qualified measurements in InfluxQL queries, use the following naming convention when @@ -103,7 +109,14 @@ measurements in InfluxQL queries, use the following naming convention when ``` database_name/retention_policy ``` - {{% /note %}} +{{% /note %}} + +#### Subquery + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +For more information, see [InfluxQL subqueries](/influxdb/clustered/reference/influxql/subqueries/). ## Notable SELECT statement behaviors diff --git a/content/influxdb/clustered/reference/influxql/subqueries.md b/content/influxdb/clustered/reference/influxql/subqueries.md new file mode 100644 index 000000000..7984f5e47 --- /dev/null +++ b/content/influxdb/clustered/reference/influxql/subqueries.md @@ -0,0 +1,246 @@ +--- +title: InfluxQL subqueries +description: > + An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. + The outer query queries results returned by the inner query (subquery). +menu: + influxdb_clustered: + name: Subqueries + identifier: influxql-subqueries + parent: influxql-reference +weight: 207 +list_code_example: | + ```sql + SELECT_clause FROM ( SELECT_statement ) [...] + ``` +--- + +An InfluxQL subquery is a query nested in the `FROM` clause of an InfluxQL query. +The outer query queries results returned by the inner query (subquery). + +- [Syntax](#syntax) +- [Examples](#examples) +- [Notable subquery behaviors](#notable-subquery-behaviors) + +{{% note %}} +InfluxQL does not support a `HAVING` clause, however InfluxQL subqueries offer +functionality similar to the [SQL `HAVING` clause](/influxdb/clustered/reference/sql/having/). +{{% /note %}} + +## Syntax + +```sql +SELECT_clause FROM ( SELECT_statement ) [...] +``` + +When using subqueries, InfluxQL **performs the inner query first**, then performs +the outer query. + +The outer query requires a [`SELECT` clause](/influxdb/clustered/reference/influxql/select/#select-clause) +and a [`FROM` clause](/influxdb/clustered/reference/influxql/select/#from-clause). +The inner query is enclosed in parentheses in the outer query's `FROM` clause. + +InfluxQL supports multiple nested subqueries: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] +``` + +## Examples + +{{% note %}} +#### Sample data + +The examples below use the following sample data sets: + +- [Get started home sensor data](/influxdb/clustered/reference/sample-data/#get-started-home-sensor-data) +- [Random numbers sample data](/influxdb/clustered/reference/sample-data/#random-numbers-sample-data) +{{% /note %}} + +{{< expand-wrapper >}} + +{{% expand "Apply an aggregate function to an aggregated result set" %}} + +```sql +SELECT + SUM(max) +FROM + ( + SELECT + MAX(temp) + FROM + home + GROUP BY + room + ) +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ---: | +| 1970-01-01T00:00:00Z | 46.1 | + +{{% /expand %}} + +{{% expand "Calculate the average difference between two fields" %}} + +```sql +SELECT + MEAN(difference) +FROM + ( + SELECT + a - b AS difference + FROM + numbers + ) +``` + +{{% influxql/table-meta %}} +Table: numbers +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | -0.03629771779732732 | + +{{% /expand %}} + +{{% expand "Filter aggregate values based on a threshold" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + co_change +FROM + ( + SELECT + SPREAD(co) AS co_change + FROM + home + GROUP BY + room, + time(2h) + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + AND co_change >= 4 +``` + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | co_chnage | +| :------------------- | --------: | +| 2022-01-01T18:00:00Z | 4 | +| 2022-01-01T18:00:00Z | 5 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} + +{{% expand "Perform additional aggregate operations on aggregate values" %}} +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + SUM(co_derivative) AS sum_derivative +FROM + ( + SELECT + DERIVATIVE(MEAN(co)) AS co_derivative + FROM + home + GROUP BY + time(12m), + room + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +GROUP BY + room +``` + +{{% /influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +Table: home +{{% /influxql/table-meta %}} + +| time | room | sum_derivative | +| :------------------- | :---------- | -------------: | +| 1970-01-01T00:00:00Z | Kitchen | 5.2 | +| 1970-01-01T00:00:00Z | Living Room | 3.4 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Notable subquery behaviors + +- [Apply time bounds to the outer query to improve performance](#apply-time-bounds-to-the-outer-query-to-improve-performance) +- [Cannot use multiple SELECT statements in a subquery](#cannot-use-multiple-select-statements-in-a-subquery) + +### Apply time bounds to the outer query to improve performance + +To improve the performance of InfluxQL queries that use subqueries and a +specified time range, apply the `WHERE` clause with time-based predicates to the +outer query rather than the inner query. +For example--the following queries return the same results, but **the query with +time-based predicate on the outer query is more performant than the query with +time-based predicate on the inner query**: + +{{% influxdb/custom-timestamps %}} + +#### Time bounds on the outer query {note="(Recommended)"} + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + ) +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +#### Time bounds on the inner query + +```sql +SELECT + inner_value AS value +FROM + ( + SELECT + raw_value as inner_value + WHERE + time >= '2022-07-19T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ) +``` +{{% /influxdb/custom-timestamps %}} + +### Cannot use multiple SELECT statements in a subquery + +InfluxQL does not support multiple +[`SELECT` statements](/influxdb/clustered/reference/influxql/select/) +per subquery: + +```sql +SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] +``` + +However, InfluxQL does support multiple nested subqueries per outer query: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] + ------------------ ---------------- + Subquery 1 Subquery 2 +```