Merge branch 'master' into jstirnaman/issue5463

assets/styles/layouts/_article.scss

@@ -70,14 +70,19 @@
       vertical-align: middle;
     }
 
-    &[date]::after {
+    &[date]::after,
-      content: attr(date);
+    &[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 {

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.
 
 <!-- **Tracking issue**: [influxdb_iox#6933](https://github.com/influxdata/influxdb_iox/issues/6933) -->
 
-### Subqueries
-
-InfluxQL in {{< product-name >}} does not currently support subqueries, which
-let you query data from the results of another InfluxQL query.
-
-<!-- **Tracking issue**: [influxdb_iox#6897](https://github.com/influxdata/influxdb_iox/issues/6897) -->
-
 ### SLIMIT clause
 
 InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause,

content/influxdb/cloud-dedicated/reference/influxql/select.md

@@ -66,22 +66,28 @@ 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.
+[measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) or
-It requires one or more comma-delimited **measurement expressions**.
+[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.
+A measurement expression identifies a measurement to query.
-  Can be a measurement name, fully-qualified measurement, constant, or
+It can be a measurement name, fully-qualified measurement, constant, or
-  [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/).
+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
   ```
 
-  - ##### 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
@@ -91,10 +97,10 @@ It requires one or more comma-delimited **measurement expressions**.
 ```
 
 {{% note %}}
-#### InfluxDB retention policies
+#### InfluxQL retention policies
 
-In {{< product-name >}}, **retention policies** are not part of the data model like
+In {{< product-name >}}, **retention policies** are not part of the data model
-they are in InfluxDB 1.x.
+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
@@ -105,6 +111,13 @@ database_name/retention_policy
 ```
 {{% /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
 
 - [Must query at least one field](#must-query-at-least-one-field)

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
+```

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.
 
 <!-- **Tracking issue**: [influxdb_iox#6933](https://github.com/influxdata/influxdb_iox/issues/6933) -->
 
-### Subqueries
-
-InfluxQL in {{< product-name >}} does not currently support subqueries, which
-let you query data from the results of another InfluxQL query.
-
-<!-- **Tracking issue**: [influxdb_iox#6897](https://github.com/influxdata/influxdb_iox/issues/6897) -->
-
 ### SLIMIT clause
 
 InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause,

content/influxdb/cloud-serverless/reference/influxql/select.md

@@ -66,22 +66,28 @@ 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.
+[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) or
-It requires one or more comma-delimited [measurement_expressions](#measurement_expression).
+[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.
+A measurement expression identifies a measurement to query.
-  Can be a measurement name, fully-qualified measurement, constant, or
+It can be a measurement name, fully-qualified measurement, constant, or
-  [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/).
+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
   ```
 
-  - ##### 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
@@ -91,20 +97,27 @@ It requires one or more comma-delimited [measurement_expressions](#measurement_e
 ```
 
 {{% note %}}
-#### InfluxDB retention policies
+#### InfluxQL retention policies
 
-In {{< product-name >}}, **retention policies** are not part of the data model like
+In {{< product-name >}}, **retention policies** are not part of the data model
-they are in InfluxDB 1.x.
+like they are in InfluxDB 1.x.
-Each {{< product-name >}} bucket has a **retention period** which defines the
+Each {{< product-name >}} database has a **retention period** which defines the
-maximum age of data to retain in the bucket. To use fully-qualified
+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 %}}
 
+#### 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
 
 - [Must query at least one field](#must-query-at-least-one-field)

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
+```

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.
 
 <!-- **Tracking issue**: [influxdb_iox#6933](https://github.com/influxdata/influxdb_iox/issues/6933) -->
 
-### Subqueries
-
-InfluxQL in {{< product-name >}} does not currently support subqueries, which
-let you query data from the results of another InfluxQL query.
-
-<!-- **Tracking issue**: [influxdb_iox#6897](https://github.com/influxdata/influxdb_iox/issues/6897) -->
-
 ### SLIMIT clause
 
 InfluxQL in {{< product-name >}} does not currently support the `SLIMIT` clause,

content/influxdb/clustered/reference/influxql/select.md

@@ -66,22 +66,28 @@ 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.
+[measurement](/influxdb/clustered/reference/glossary/#measurement) or
-It requires one or more comma-delimited **measurement expressions**.
+[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.
+A measurement expression identifies a measurement to query.
-  Can be a measurement name, fully-qualified measurement, constant, or
+It can be a measurement name, fully-qualified measurement, constant, or
-  [regular expression](/influxdb/clustered/reference/influxql/regular-expressions/).
+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
   ```
 
-  - ##### 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
@@ -91,10 +97,10 @@ It requires one or more comma-delimited **measurement expressions**.
 ```
 
 {{% note %}}
-#### InfluxDB retention policies
+#### InfluxQL retention policies
 
-In {{< product-name >}}, **retention policies** are not part of the data model like
+In {{< product-name >}}, **retention policies** are not part of the data model
-they are in InfluxDB 1.x.
+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
@@ -105,6 +111,13 @@ database_name/retention_policy
 ```
 {{% /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
 
 - [Must query at least one field](#must-query-at-least-one-field)

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
+```