From d74b856bc0ba0a2ac4a20f93dfaec31847c31611 Mon Sep 17 00:00:00 2001 From: lwandzura <51929958+lwandzura@users.noreply.github.com> Date: Wed, 16 Nov 2022 15:10:11 -0600 Subject: [PATCH] port influxql docs into 2.5 (#4621) * moved InfluxQL to 2.4 * delete _index file in influxql 2.1 * Revert "delete _index file in influxql 2.1" This reverts commit cf506408b758267000793b7f02b4bcf846bc5366. * Add InfluxQL functions (#4553) * delete old functions file * Link Fixes (#4554) * 2.1 to 2.4 * 2.1 to 2.4 * update front matter * add overview links on landing functions page * updated _index.md page * removed into clause in a few docs * fix params formatting * update intro and overview list * updates to links, changed CLI to influxql shell * edits * fixed links * update links (#4567) * update links * add missing note shortcode * fixed links, made updates * edits to examples * remove into clause and edits * fix dates/upd egs * edits * added dbrp doc, edited manage data doc * Update Selectors * updates to language and examples * added another DELETE FROM example * updates to functions * updates * updated 2.4 faq doc * edits to manage-data * misc edits manage-data * InfluxQL syntax updates * update glossary definitions * upd glossary * edits * updated index for influxql syntax * fixed index file * made edits * Edits to explore data * edit * Explore data edits * SELECT statement edits * SELECT statement edits * moved influxql 2.4 into 2.5 * fix typo * Delete FETCH_HEAD * added updated faq doc * updated frontmatter to and link to 2.5 * edits to query data with influxQL * fix typo * misc edits * Edits to InfluxQL Explore data clauses * misc edits * InfluxQL Clause Edits-2 * Update content/influxdb/v2.4/query-data/influxql/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-schema.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-schema.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-schema.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-schema.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * PR edits * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * PR review * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * PR edits * revert influxql 2.1 upd * Update content/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset.md Co-authored-by: Scott Anderson * updated dates and mention InfluxQL in sample data * update sample data query * misc PR edits * Update content/influxdb/v2.4/query-data/influxql/explore-data/_index.md Co-authored-by: Scott Anderson * clarify group by requires an aggregate or selector * Update content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * Update content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md Co-authored-by: Scott Anderson * PR edits * Update content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md Co-authored-by: Scott Anderson * PR edits Influxql 2.4 (#4634) * returned per query * PR edits * Update content/influxdb/v2.4/query-data/influxql/_index.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * Timezone edits * Update content/influxdb/v2.4/query-data/influxql/explore-schema.md Co-authored-by: Scott Anderson * added identifier to regex doc * added identifier to menu * fixed typo * made edits requested in PR * missed a word * Apply suggestions from code review * updated explore schema * updated manage data and added insert * updated influxql math operators * fixed influxql math TOC order * added warning about DROP MESSURMENT * reformatted influxql functions pages * link audit for influxql docs * reorder influxql nav * ported influxql and other changes into 2.5 * fix 2.4 links in 2.5 Co-authored-by: Kelly Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> Co-authored-by: peterreg Co-authored-by: Scott Anderson Co-authored-by: Scott Anderson --- assets/styles/layouts/_article.scss | 1 + assets/styles/layouts/article/_influxql.scss | 9 + .../{influxql.md => influxql/_index.md} | 10 +- .../v2.4/query-data/influxql/_index.md | 120 +- .../influxdb/v2.4/query-data/influxql/dbrp.md | 6 +- .../influxql/explore-data/_index.md | 73 + .../influxql/explore-data/group-by.md | 1193 +++++ .../influxql/explore-data/limit-and-slimit.md | 241 + .../explore-data/offset-and-soffset.md | 206 + .../influxql/explore-data/order-by.md | 119 + .../explore-data/regular-expressions.md | 216 + .../influxql/explore-data/select.md | 681 +++ .../influxql/explore-data/subqueries.md | 294 ++ .../explore-data/time-and-timezone.md | 441 ++ .../query-data/influxql/explore-data/where.md | 314 ++ .../query-data/influxql/explore-schema.md | 592 +++ .../query-data/influxql/functions/_index.md | 75 + .../influxql/functions/aggregates.md | 1025 ++++ .../influxql/functions/selectors.md | 1301 +++++ .../influxql/functions/technical-analysis.md | 659 +++ .../influxql/functions/transformations.md | 4265 +++++++++++++++++ .../v2.4/query-data/influxql/manage-data.md | 149 + .../query-data/influxql/math-operators.md | 318 ++ content/influxdb/v2.4/reference/faq.md | 76 + content/influxdb/v2.4/reference/glossary.md | 6 +- .../influxdb/v2.4/reference/sample-data.md | 2 +- .../v2.4/reference/syntax/influxql/_index.md | 14 + .../reference/syntax/influxql/internals.md | 163 + .../v2.4/reference/syntax/influxql/spec.md | 761 +++ content/influxdb/v2.4/users/create-user.md | 6 +- .../v2.5/query-data/influxql/_index.md | 122 +- .../influxdb/v2.5/query-data/influxql/dbrp.md | 6 +- .../influxql/explore-data/_index.md | 73 + .../influxql/explore-data/group-by.md | 1193 +++++ .../influxql/explore-data/limit-and-slimit.md | 241 + .../explore-data/offset-and-soffset.md | 206 + .../influxql/explore-data/order-by.md | 119 + .../explore-data/regular-expressions.md | 216 + .../influxql/explore-data/select.md | 681 +++ .../influxql/explore-data/subqueries.md | 294 ++ .../explore-data/time-and-timezone.md | 441 ++ .../query-data/influxql/explore-data/where.md | 314 ++ .../query-data/influxql/explore-schema.md | 592 +++ .../query-data/influxql/functions/_index.md | 75 + .../influxql/functions/aggregates.md | 1025 ++++ .../influxql/functions/selectors.md | 1301 +++++ .../influxql/functions/technical-analysis.md | 659 +++ .../influxql/functions/transformations.md | 4265 +++++++++++++++++ .../v2.5/query-data/influxql/manage-data.md | 149 + .../query-data/influxql/math-operators.md | 318 ++ content/influxdb/v2.5/reference/faq.md | 78 +- content/influxdb/v2.5/reference/glossary.md | 8 +- .../v2.5/reference/syntax/influxql/_index.md | 14 + .../reference/syntax/influxql/internals.md | 163 + .../v2.5/reference/syntax/influxql/spec.md | 761 +++ content/influxdb/v2.5/users/create-user.md | 9 +- layouts/shortcodes/influxql/table-meta.html | 3 + .../influxdb/2-4-influxql-holtwinters-1.png | Bin 0 -> 38373 bytes .../influxdb/2-4-influxql-holtwinters-2.png | Bin 0 -> 48583 bytes .../influxdb/2-4-influxql-holtwinters-3.png | Bin 0 -> 50711 bytes 60 files changed, 26519 insertions(+), 143 deletions(-) create mode 100644 assets/styles/layouts/article/_influxql.scss rename content/influxdb/v2.1/query-data/{influxql.md => influxql/_index.md} (97%) create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/_index.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/order-by.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/select.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/subqueries.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-data/where.md create mode 100644 content/influxdb/v2.4/query-data/influxql/explore-schema.md create mode 100644 content/influxdb/v2.4/query-data/influxql/functions/_index.md create mode 100644 content/influxdb/v2.4/query-data/influxql/functions/aggregates.md create mode 100644 content/influxdb/v2.4/query-data/influxql/functions/selectors.md create mode 100644 content/influxdb/v2.4/query-data/influxql/functions/technical-analysis.md create mode 100644 content/influxdb/v2.4/query-data/influxql/functions/transformations.md create mode 100644 content/influxdb/v2.4/query-data/influxql/manage-data.md create mode 100644 content/influxdb/v2.4/query-data/influxql/math-operators.md create mode 100644 content/influxdb/v2.4/reference/syntax/influxql/_index.md create mode 100644 content/influxdb/v2.4/reference/syntax/influxql/internals.md create mode 100644 content/influxdb/v2.4/reference/syntax/influxql/spec.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/_index.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/group-by.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/limit-and-slimit.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/offset-and-soffset.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/order-by.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/regular-expressions.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/select.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/subqueries.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/time-and-timezone.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-data/where.md create mode 100644 content/influxdb/v2.5/query-data/influxql/explore-schema.md create mode 100644 content/influxdb/v2.5/query-data/influxql/functions/_index.md create mode 100644 content/influxdb/v2.5/query-data/influxql/functions/aggregates.md create mode 100644 content/influxdb/v2.5/query-data/influxql/functions/selectors.md create mode 100644 content/influxdb/v2.5/query-data/influxql/functions/technical-analysis.md create mode 100644 content/influxdb/v2.5/query-data/influxql/functions/transformations.md create mode 100644 content/influxdb/v2.5/query-data/influxql/manage-data.md create mode 100644 content/influxdb/v2.5/query-data/influxql/math-operators.md create mode 100644 content/influxdb/v2.5/reference/syntax/influxql/_index.md create mode 100644 content/influxdb/v2.5/reference/syntax/influxql/internals.md create mode 100644 content/influxdb/v2.5/reference/syntax/influxql/spec.md create mode 100644 layouts/shortcodes/influxql/table-meta.html create mode 100644 static/img/influxdb/2-4-influxql-holtwinters-1.png create mode 100644 static/img/influxdb/2-4-influxql-holtwinters-2.png create mode 100644 static/img/influxdb/2-4-influxql-holtwinters-3.png diff --git a/assets/styles/layouts/_article.scss b/assets/styles/layouts/_article.scss index 62711ad03f..f67a477519 100644 --- a/assets/styles/layouts/_article.scss +++ b/assets/styles/layouts/_article.scss @@ -124,6 +124,7 @@ "article/flux", "article/html-diagrams", "article/influxdbu", + "article/influxql", "article/keybinding", "article/list-filters", "article/lists", diff --git a/assets/styles/layouts/article/_influxql.scss b/assets/styles/layouts/article/_influxql.scss new file mode 100644 index 0000000000..f1d61ac456 --- /dev/null +++ b/assets/styles/layouts/article/_influxql.scss @@ -0,0 +1,9 @@ +.influxql-table-meta p { + font-size: .9rem; + line-height: 1.25rem; + &:last-child {margin-bottom: 0rem} +} + +table + .influxql-table-meta { + margin-top:-1.5rem; +} \ No newline at end of file diff --git a/content/influxdb/v2.1/query-data/influxql.md b/content/influxdb/v2.1/query-data/influxql/_index.md similarity index 97% rename from content/influxdb/v2.1/query-data/influxql.md rename to content/influxdb/v2.1/query-data/influxql/_index.md index b0c37a0786..072c3bbc2a 100644 --- a/content/influxdb/v2.1/query-data/influxql.md +++ b/content/influxdb/v2.1/query-data/influxql/_index.md @@ -22,6 +22,7 @@ Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database {{% note %}} #### InfluxQL reference documentation + For complete InfluxQL reference documentation, see [Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/). {{% /note %}} @@ -41,8 +42,7 @@ For more information, see [Database and retention policy mapping](/influxdb/v2.1 If you're not sure how data was written into a bucket, verify the bucket has a mapping. {{% /note %}} -Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) -to verify the buckets you want to query are mapped to a database and retention policy. +Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) to verify the buckets you want to query are mapped to a database and retention policy. {{< tabs-wrapper >}} {{% tabs %}} @@ -116,13 +116,14 @@ If you **do not find a DBRP mapping for a bucket**, complete the next procedure _For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/v2.1/api/#tag/DBRPs)._ ## Map unmapped buckets -Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) -to manually create DBRP mappings for unmapped buckets. + +Use the [`influx` CLI](/influxdb/v2.1/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.1/reference/api/) to manually create DBRP mappings for unmapped buckets. {{< tabs-wrapper >}} {{% tabs %}} [influx CLI](#) [InfluxDB API](#) + {{% /tabs %}} {{% tab-content %}} @@ -245,6 +246,7 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest - `GRANT` - `KILL` - `REVOKE` +- `SHOW SERIES CARDINALITY` {{% /warn %}} {{< /flex-content >}} {{< /flex >}} diff --git a/content/influxdb/v2.4/query-data/influxql/_index.md b/content/influxdb/v2.4/query-data/influxql/_index.md index 1fa89ad209..cd0d7676d0 100644 --- a/content/influxdb/v2.4/query-data/influxql/_index.md +++ b/content/influxdb/v2.4/query-data/influxql/_index.md @@ -9,44 +9,45 @@ menu: influxdb_2_4: name: Query with InfluxQL parent: Query data -cascade: - related: - - /influxdb/v2.4/reference/api/influxdb-1x/ - - /influxdb/v2.4/reference/api/influxdb-1x/query - - /influxdb/v2.4/reference/api/influxdb-1x/dbrp - - /influxdb/v2.4/tools/influxql-shell/ +related: + - /influxdb/v2.4/reference/api/influxdb-1x/ + - /influxdb/v2.4/reference/api/influxdb-1x/query + - /influxdb/v2.4/reference/api/influxdb-1x/dbrp + - /influxdb/v2.4/tools/influxql-shell/ --- +Use InfluxQL (an SQL-like query language) to interact with InfluxDB, and query and analyze your times series data. + In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database) and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp). -InfluxDB {{< current-version >}} combines and replaces database and retention -policies with [buckets](/influxdb/v2.4/reference/glossary/#bucket). -Because InfluxQL uses the 1.x data model, a database and retention policy combination -(DBRP) must be mapped to a bucket before it can be queried using InfluxQL. - -{{% note %}} -#### InfluxQL reference documentation -For complete InfluxQL reference documentation, see -[Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/). -{{% /note %}} +In InfluxDB OSS {{< current-version >}}, data is stored in [buckets](/influxdb/v2.4/reference/glossary/#bucket). +Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL. -**To use InfluxQL to query bucket data, complete the following steps:** +**To query data with InfluxQL, complete the following steps:** 1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping). 2. [Create DBRP mappings for unmapped buckets](#create-dbrp-mappings-for-unmapped-buckets). 3. [Query a mapped bucket with InfluxQL](#query-a-mapped-bucket-with-influxql). +{{% note %}} + +#### InfluxQL reference documentation + +For complete InfluxQL reference documentation, see the +[InfluxQL specification for InfluxDB 2.x](/influxdb/v2.4/reference/syntax/influxql/spec/). +{{% /note %}} + ## Verify buckets have a mapping -Use the [`influx` CLI](/influxdb/v2.4/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.4/reference/api/) -to verify the buckets you want to query are mapped to a database and retention policy. +1. To verify the buckets you want to query are mapped to a database and retention policy, use the [`influx` CLI](/influxdb/v2.4/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.4/reference/api/). _For examples, see [List DBRP mappings](/influxdb/v2.4/query-data/influxql/dbrp/#list-dbrp-mappings)._ -If you **do not find a DBRP mapping for a bucket**, [create a new DBRP mapping]() to +2. If you **do not find a DBRP mapping for a bucket**, [create a new DBRP mapping](/influxdb/v2.4/query-data/influxql/dbrp/#create-dbrp-mappings) to map the unmapped bucket. ## Create DBRP mappings for unmapped buckets -Use the [`influx` CLI](/influxdb/v2.4/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.4/reference/api/) + +- Use the [`influx` CLI](/influxdb/v2.4/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2.4/reference/api/) to manually create DBRP mappings for unmapped buckets. _For examples, see [Create DBRP mappings](/influxdb/v2.4/query-data/influxql/dbrp/#create-dbrp-mappings)._ @@ -54,36 +55,32 @@ _For examples, see [Create DBRP mappings](/influxdb/v2.4/query-data/influxql/dbr {{< tabs-wrapper >}} {{% tabs %}} -[InfluxQL Shell](#) +[InfluxQL shell](#) [InfluxDB API](#) {{% /tabs %}} {{% tab-content %}} -The [`influx` CLI](/influxdb/v2.4/tools/influx-cli/) provides an InfluxQL shell -where you can execute InfluxQL queries in an interactive Read-Eval-Print-Loop (REPL). +The [`influx` CLI](/influxdb/v2.4/reference/cli/influx/) provides an [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/) where you can execute InfluxQL queries in an interactive Read-Eval-Print-Loop (REPL). -{{% note %}} -If you haven't already, be sure to do the following: +1. If you haven't already, do the following: -- [Download and install the `influx` CLI](/influxdb/v2.4/tools/influx-cli/#install-the-influx-cli) -- [Configure your authentication credentials](/influxdb/v2.4/tools/influx-cli/#provide-required-authentication-credentials) -{{% /note %}} + - [Download and install the `influx` CLI](/influxdb/v2.4/tools/influx-cli/#install-the-influx-cli) + - [Configure your authentication credentials](/influxdb/v2.4/tools/influx-cli/#provide-required-authentication-credentials) -Use the following command to start an InfluxQL shell: +2. Use the following command to start an InfluxQL shell: -```sh -influx v1 shell -``` + ```sh + influx v1 shell + ``` -Execute an InfluxQL query inside the InfluxQL shell. +3. Execute an InfluxQL query inside the InfluxQL shell. -```sql -> SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1 -``` + ```sql + SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1 + ``` -For more information about using the InfluxQL shell, see -[Use the InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/). + For more information, see how to [use the InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/). For more information about DBRP mappings, see [Manage DBRP mappings](/influxdb/v2.4/query-data/influxql/dbrp/). {{% /tab-content %}} @@ -93,37 +90,36 @@ For more information about using the InfluxQL shell, see The [InfluxDB 1.x compatibility API](/influxdb/v2.4/reference/api/influxdb-1x/) supports all InfluxDB 1.x client libraries and integrations in InfluxDB {{< current-version >}}. -To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/v2.4/reference/api/influxdb-1x/query/). -Include the following in your request: +1. To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/v2.4/reference/api/influxdb-1x/query/), and include the following in your request: + + - **Request method:** `GET` + - **Headers:** + - **Authorization:** _See [compatibility API authentication](/influxdb/v2.4/reference/api/influxdb-1x/#authentication)_ + - **Query parameters:** + - **db**: 1.x database to query + - **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_ + - **q**: URL-encoded InfluxQL query -- **Request method:** `GET` -- **Headers:** - - **Authorization:** _See [compatibility API authentication](/influxdb/v2.4/reference/api/influxdb-1x/#authentication)_ -- **Query parameters:** - - **db**: 1.x database to query - - **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_ - - **q**: URL-encoded InfluxQL query + {{% api/url-encode-note %}} -{{% api/url-encode-note %}} + ```sh + curl --get http://localhost:8086/query?db=example-db \ + --header "Authorization: Token YourAuthToken" \ + --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" + ``` -```sh -curl --get http://localhost:8086/query?db=example-db \ - --header "Authorization: Token YourAuthToken" \ - --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1" -``` + By default, the `/query` compatibility endpoint returns results in **JSON**. -By default, the `/query` compatibility endpoint returns results in **JSON**. -To return results as **CSV**, include the `Accept: application/csv` header. +2. (Optional) To return results as **CSV**, include the `Accept: application/csv` header. +For more information about DBRP mappings, see [Manage DBRP mappings](/influxdb/v2.4/query-data/influxql/dbrp/). {{% /tab-content %}} {{< /tabs-wrapper >}} ## InfluxQL support -InfluxDB {{< current-version >}} supports InfluxQL queries. -See supported and unsupported queries below. -To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest "influxdb" "v1" >}}/query_language/). +InfluxDB OSS 2.x supports the following InfluxQL statements and clauses. See supported and unsupported queries below. {{< flex >}} {{< flex-content >}} @@ -135,10 +131,13 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest - `EXPLAIN ANALYZE` - `SELECT` _(read-only)_ - `SHOW DATABASES` +- `SHOW SERIES` - `SHOW MEASUREMENTS` - `SHOW TAG KEYS` -- `SHOW TAG VALUES` - `SHOW FIELD KEYS` +- `SHOW SERIES EXACT CARDINALITY` +- `SHOW TAG KEY CARDINALITY` +- `SHOW FIELD KEY CARDINALITY` \* These commands delete data. {{% /note %}} @@ -155,6 +154,7 @@ To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest - `GRANT` - `KILL` - `REVOKE` +- `SHOW SERIES CARDINALITY` {{% /warn %}} {{< /flex-content >}} {{< /flex >}} diff --git a/content/influxdb/v2.4/query-data/influxql/dbrp.md b/content/influxdb/v2.4/query-data/influxql/dbrp.md index 8940bca6ae..f6ef47a4ca 100644 --- a/content/influxdb/v2.4/query-data/influxql/dbrp.md +++ b/content/influxdb/v2.4/query-data/influxql/dbrp.md @@ -7,14 +7,14 @@ description: > menu: influxdb_2_4: parent: Query with InfluxQL -weight: 202 +weight: 201 influxdb/v2.4/tags: [influxql, dbrp] --- -InfluxQL requires a database and retention policy (DBRP) combination to query data from. +InfluxQL requires a database and retention policy (DBRP) combination in order to query data. In InfluxDB {{< current-version >}}, databases and retention policies have been combined and replaced by InfluxDB [buckets](/influxdb/v2.4/reference/glossary/#bucket). -To query an InfluxDB {{< current-version >}} with InfluxQL, the specified DBRP +To query InfluxDB {{< current-version >}} with InfluxQL, the specified DBRP combination must be mapped to a bucket. - [Automatic DBRP mapping](#automatic-dbrp-mapping) diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/_index.md b/content/influxdb/v2.4/query-data/influxql/explore-data/_index.md new file mode 100644 index 0000000000..c14073fc3f --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/_index.md @@ -0,0 +1,73 @@ +--- +title: Explore data using InfluxQL +description: > + Explore time series data using InfluxQL, InfluxData's SQL-like query language. + Use the `SELECT` statement to query data from measurements, tags, and fields. +menu: + influxdb_2_4: + name: Explore data + parent: Query with InfluxQL +weight: 202 +--- + +To start exploring data with InfluxQL, do the following: + +1. Verify your bucket has a database and retention policy (DBRP) mapping by [listing DBRP mappings for your bucket](/influxdb/v2.4/query-data/influxql/dbrp/#list-dbrp-mappings). If not, [create a new DBRP mapping](/influxdb/v2.4/query-data/influxql/dbrp/#create-dbrp-mappings). + +2. [Configure timestamps in the InfluxQL shell](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/). + +3. _(Optional)_ If you would like to use the data used in the examples below, [download the NOAA sample data](#download-sample-data). + +4. Use the InfluxQL `SELECT` statement with other key clauses to explore your data. + +{{< children type="anchored-list" >}} + +{{< children readmore=true hr=true >}} + +## Download sample data + +The example InfluxQL queries in this documentation use publicly available [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov/) data. + +To download a subset of NOAA data used in examples, run the script under [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data) (for example, copy and paste the script into your Data Explorer - Script Editor), and replace "example-org" in the script with the name of your InfluxDB organization. + +Let's get acquainted with this subsample of the data in the `h2o_feet` measurement: + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | level description | location | water_level | +| :------------------- | :------------------ | :----------------------- |----------------------:| +| 2019-08-18T00:00:00Z | between 6 and 9 feet |coyote_creek | 8.1200000000 | +| 2019-08-18T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | +| 2019-08-18T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.0050000000 | +| 2019-08-18T00:06:00Z | below 3 feet| santa_monica | 2.1160000000 | +| 2019-08-18T00:12:00Z | between 6 and 9 feet| coyote_creek | 7.8870000000 | +| 2019-08-18T00:12:00Z | below 3 feet | santa_monica | 2.0280000000 | + +The data in the `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement) +occurs at six-minute time intervals. +This measurement has one [tag key](/influxdb/v2.4/reference/glossary/#tag-key) +(`location`) which has two [tag values](/influxdb/v2.4/reference/glossary/#tag-value): +`coyote_creek` and `santa_monica`. +The measurement also has two [fields](/influxdb/v2.4/reference/glossary/#field): +`level description` stores string [field values](/influxdb/v2.4/reference/glossary/#field-value) +and `water_level` stores float field values. + + +### Configure timestamps in the InfluxQL shell + +By default, the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/) returns timestamps in +nanosecond UNIX epoch format by default. +To return human-readable RFC3339 timestamps instead of Unix nanosecond timestamps, +use the [precision helper command](/influxdb/v2.4/tools/influxql-shell/#precision) ` to configure +the timestamp format: + +```sql +precision rfc3339 +``` + +The [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) returns timestamps +in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. +Specify alternative formats with the [`epoch` query string parameter](/influxdb/v2.4/reference/api/influxdb-1x/). diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md b/content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md new file mode 100644 index 0000000000..ad50bb2709 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/group-by.md @@ -0,0 +1,1193 @@ +--- +title: GROUP BY clause +description: > + Use the `GROUP BY` clause to group query results by one or more specified [tags](/influxdb/v2.4/reference/glossary/#tag) and/or a specified time interval. +menu: + influxdb_2_4: + name: GROUP BY clause + parent: Explore data +weight: 303 +list_code_example: | + ```sql + SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [,` groups query results by one or more specified [tags](/influxdb/v2.4/reference/glossary/#tag). + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [,]] +``` + + - `GROUP BY *` - Groups results by all [tags](/influxdb/v2.4/reference/glossary/#tag) + - `GROUP BY ` - Groups results by a specific tag + - `GROUP BY ,` - Groups results by more than one tag. The order of the [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) is irrelevant. + - `GROUP BY \regex\` - Groups results by tags that match the regular expression. + +If the query includes a `WHERE` clause, the `GROUP BY` clause must appear after the `WHERE` clause. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Group query results by a single tag" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 5.3591424203 | + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 3.5307120942 | + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/) +to calculate the average `water_level` for each +[tag value](/influxdb/v2.4/reference/glossary/#tag-value) of `location` in +the `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). +InfluxDB returns results in two [series](/influxdb/v2.4/reference/glossary/#series): one for each tag value of `location`. + +{{% note %}} +**Note:** In InfluxDB, [epoch 0](https://en.wikipedia.org/wiki/Unix_time) (`1970-01-01T00:00:00Z`) is often used as a null timestamp equivalent. +If you request a query that has no timestamp to return, such as an [aggregation function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. +{{% /note %}} + +{{% /expand %}} + +{{% expand "Group query results by more than one tag" %}} + +```sql +SELECT MEAN("index") FROM "h2o_quality" GROUP BY "location","randtag" +``` +Output: +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=1 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 50.6903376019 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=2 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.6618675442 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=3 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.3609399076 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=1 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.1327124563 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=2 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 50.2937984496 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=3 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.9991990388 | + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `index` for +each combination of the `location` tag and the `randtag` tag in the +`h2o_quality` measurement. +Separate multiple tags with a comma in the `GROUP BY` clause. + +{{% /expand %}} + +{{% expand "Group query results by all tags" %}} + +```sql +SELECT MEAN("index") FROM "h2o_quality" GROUP BY * +``` +Output: +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=1 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 50.6903376019 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=2 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.6618675442 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek, randtag=3 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.3609399076 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=1 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.1327124563 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=2 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 50.2937984496 | + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica, randtag=3 +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 49.9991990388 | + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `index` for every possible +[tag](/influxdb/v2.4/reference/glossary/#tag) combination in the `h2o_quality` +measurement. + +{{% /expand %}} + +{{% expand "Group query results by tags that start with `l`" %}} + +```sql +SELECT "water_level",location FROM "h2o_feet" GROUP BY /l/ +``` + +This query uses a regular expression to group by tags that start with `l`. With the sample NOAA water dataset, results are grouped by the `location` tag. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## GROUP BY time intervals + +`GROUP BY time()` group query results by a user-specified time interval. +When using aggregate or selector functions in the `SELECT` clause, the operation is applied to each interval. + +### Basic GROUP BY time() syntax + +#### Syntax + +```sql +SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] +``` + +Basic `GROUP BY time()` queries require an InfluxQL [function](/influxdb/v2.4/query-data/influxql/functions) +in the `SELECT` clause and a time range in the `WHERE` clause. +Note that the `GROUP BY` clause must come **after** the `WHERE` clause. + +##### `time(time_interval)` + +The `time_interval` in the `GROUP BY time()` clause is a +[duration literal](/influxdb/v2.4/reference/glossary/#duration). +It determines how InfluxDB groups query results over time. +For example, a `time_interval` of `5m` groups query results into five-minute +time groups across the time range specified in the `WHERE` clause. + +##### `fill()` + +`fill()` is optional. +It changes the value reported for time intervals with no data. +See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) +for more information. + +**Coverage:** + +Basic `GROUP BY time()` queries rely on the `time_interval` and InfluxDB's +preset time boundaries to determine the raw data included in each time interval +and the timestamps returned by the query. + +### Examples of basic syntax + +The examples below use the following subsample of the sample data: + +```sql +SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | location | +| :------------------- | -----------: | :----------- | +| 2019-08-18T00:00:00Z | 8.5040000000 | coyote_creek | +| 2019-08-18T00:00:00Z | 2.3520000000 | santa_monica | +| 2019-08-18T00:06:00Z | 8.4190000000 | coyote_creek | +| 2019-08-18T00:06:00Z | 2.3790000000 | santa_monica | +| 2019-08-18T00:12:00Z | 8.3200000000 | coyote_creek | +| 2019-08-18T00:12:00Z | 2.3430000000 | santa_monica | +| 2019-08-18T00:18:00Z | 8.2250000000 | coyote_creek | +| 2019-08-18T00:18:00Z | 2.3290000000 | santa_monica | +| 2019-08-18T00:24:00Z | 8.1300000000 | coyote_creek | +| 2019-08-18T00:24:00Z | 2.2640000000 | santa_monica | +| 2019-08-18T00:30:00Z | 8.0120000000 | coyote_creek | +| 2019-08-18T00:30:00Z | 2.2670000000 | santa_monica | + +{{< expand-wrapper >}} + +{{% expand "Group query results into 12 minute intervals" %}} + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | :----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | + +The query uses the InfluxQL [COUNT() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count) to count the number of `water_level` points per location, per 12-minute interval. + +Each output row represents a single 12 minute interval. +The count for the first timestamp covers the raw data between `2019-08-18T00:00:00Z` +and up to, but not including, `2019-08-18T00:12:00Z`. +The count for the second timestamp covers the raw data between `2019-08-18T00:12:00Z` +and up to, but not including, `2019-08-18T00:24:00Z.` + +{{% /expand %}} + +{{% expand "Group query results into 12 minute intervals and by a tag key" %}} + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location" +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | + + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | + +The query uses the InfluxQL [COUNT() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count) +to count the number of `water_level` points per location, per 12 minute interval. +Note that the time interval and the tag key are separated by a comma in the +`GROUP BY` clause. + +The query returns two [series](/influxdb/v2.4/reference/glossary/#series) of results: one for each +[tag value](/influxdb/v2.4/reference/glossary/#tag-value) of the `location` tag. +The result for each timestamp represents a single 12 minute interval. +Each output row represents a single 12 minute interval. +and up to, but not including, `2019-08-18T00:12:00Z`. +The count for the second timestamp covers the raw data between `2019-08-18T00:12:00Z` +and up to, but not including, `2019-08-18T00:24:00Z.` + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with basic syntax + +##### Unexpected timestamps and values in query results + +With the basic syntax, InfluxDB relies on the `GROUP BY time()` interval +and on the system's preset time boundaries to determine the raw data included +in each time interval and the timestamps returned by the query. +In some cases, this can lead to unexpected results. + +**Example** + +Raw data: + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:18:00Z' +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.5040000000 | +| 2019-08-18T00:06:00Z | 8.4190000000 | +| 2019-08-18T00:12:00Z | 8.3200000000 | +| 2019-08-18T00:18:00Z | 8.2250000000 | + +Query and results: + +The following example queries a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m) +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.0000000000 | +| 2019-08-18T00:12:00Z | 1.0000000000 | + +{{% note %}} +**Note:** The timestamp in the first row of data occurs before the start of the queried time range. +{{% /note %}} + +Explanation: + +InfluxDB uses preset round-number time boundaries for `GROUP BY` intervals that are +independent of any time conditions in the `WHERE` clause. +When it calculates the results, all returned data must occur within the query's +explicit time range but the `GROUP BY` intervals will be based on the preset +time boundaries. + +The table below shows the preset time boundary, the relevant `GROUP BY time()` interval, the +points included, and the returned timestamp for each `GROUP BY time()` +interval in the results. + +| Time Interval Number | Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------- | :-------------- | :--------------------- | +| 1 | `time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z` | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z` | `8.005` | `2019-08-18T00:00:00Z` | +| 2 | `time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z` | `time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z` | `7.887` | `2019-08-18T00:12:00Z` | + +The first preset 12-minute time boundary begins at `00:00` and ends just before +`00:12`. +Only one raw point (`8.005`) falls both within the query's first `GROUP BY time()` interval and in that +first time boundary. +Note that while the returned timestamp occurs before the start of the queried time range, +the query result excludes data that occur before the queried time range. + +The second preset 12-minute time boundary begins at `00:12` and ends just before +`00:24`. +Only one raw point (`7.887`) falls both within the query's second `GROUP BY time()` interval and in that +second time boundary. + +The [advanced `GROUP BY time()` syntax](#advanced-group-by-time-syntax) allows users to shift +the start time of the InfluxDB database's preset time boundaries. It shifts forward the preset time boundaries by six minutes such that +InfluxDB returns: + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | ----: | +| 2019-08-18T00:06:00Z | 2 | + +### Advanced GROUP BY time() syntax + +#### Syntax + +```sql +SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] +``` + +Advanced `GROUP BY time()` queries require an InfluxQL [function](/influxdb/v2.4/query-data/influxql/functions/) +in the `SELECT` clause and a time range in the +`WHERE` clause). Note that the `GROUP BY` clause must come after the `WHERE` clause. + +##### `time(time_interval,offset_interval)` + +See the [Basic GROUP BY time() Syntax](#basic-group-by-time-syntax) +for details on the `time_interval`. + +The `offset_interval` is a [duration literal](/influxdb/v2.4/reference/glossary/#duration). +It shifts forward or back the InfluxDB database's preset time boundaries. +The `offset_interval` can be positive or negative. + +##### `fill()` + +`fill()` is optional. +It changes the value reported for time intervals with no data. +See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) +for more information. + +**Coverage:** + +Advanced `GROUP BY time()` queries rely on the `time_interval`, the `offset_interval` +, and on the InfluxDB database's preset time boundaries to determine the raw data included in each time interval +and the timestamps returned by the query. + +### Examples of advanced syntax + +The examples below use the following subsample of the sample data: + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.5040000000 | +| 2019-08-18T00:06:00Z | 8.4190000000 | +| 2019-08-18T00:12:00Z | 8.3200000000 | +| 2019-08-18T00:18:00Z | 8.2250000000 | +| 2019-08-18T00:24:00Z | 8.1300000000 | +| 2019-08-18T00:30:00Z | 8.0120000000 | +| 2019-08-18T00:36:00Z | 7.8940000000 | +| 2019-08-18T00:42:00Z | 7.7720000000 | +| 2019-08-18T00:48:00Z | 7.6380000000 | +| 2019-08-18T00:54:00Z | 7.5100000000 | + +{{< expand-wrapper >}} + +{{% expand "Group query results into 18 minute intervals and shift the preset time boundaries forward" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m,6m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 2019-08-18T00:06:00Z | 8.3213333333 | +| 2019-08-18T00:24:00Z | 8.0120000000 | +| 2019-08-18T00:42:00Z | 7.6400000000 | + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) +to calculate the average `water_level`, grouping results into 18 minute time intervals, and offsetting the preset time boundaries by 6 minutes. + +The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to the InfluxDB database's preset time boundaries. Let's first examine the results without the offset: + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.3695000000 | +| 2019-08-18T00:18:00Z | 8.1223333333 | +| 2019-08-18T00:36:00Z | 7.7680000000 | +| 2019-08-18T00:54:00Z | 7.5100000000 | + +The time boundaries and returned timestamps for the query **without** the +`offset_interval` adhere to the InfluxDB database's preset time boundaries: + +| Time Interval Number | Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------- | :--------------------- | :--------------------- | +| 1 | `time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z` | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z` | `8.005`,`7.887` | `2019-08-18T00:00:00Z` | +| 2 | `time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z` | <--- same | `7.762`,`7.635`,`7.5` | `2019-08-18T00:18:00Z` | +| 3 | `time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z` | <--- same | `7.372`,`7.234`,`7.11` | `2019-08-18T00:36:00Z` | +| 4 | `time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z` | `time = 2019-08-18T00:54:00Z` | `6.982` | `2019-08-18T00:54:00Z` | + +The first preset 18-minute time boundary begins at `00:00` and ends just before +`00:18`. Two raw points (`8.005` and `7.887`) fall both within the first `GROUP BY time()` interval and in that +first time boundary. While the returned timestamp occurs before the start of the queried time range, +the query result excludes data that occur before the queried time range. + +The second preset 18-minute time boundary begins at `00:18` and ends just before +`00:36`. Three raw points (`7.762` and `7.635` and `7.5`) fall both within the second `GROUP BY time()` interval and in that +second time boundary. In this case, the boundary time range and the interval's time range are the same. + +The fourth preset 18-minute time boundary begins at `00:54` and ends just before +`1:12:00`. One raw point (`6.982`) falls both within the fourth `GROUP BY time()` interval and in that +fourth time boundary. + +The time boundaries and returned timestamps for the query **with** the `offset_interval` adhere to the offset time boundaries: + +| Time Interval Number | Offset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------- | :---------------------- | ---------------------- | +| 1 | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z` | <--- same | `8.005`,`7.887`,`7.762` | `2019-08-18T00:06:00Z` | +| 2 | `time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z` | <--- same | `7.635`,`7.5`,`7.372` | `2019-08-18T00:24:00Z` | +| 3 | `time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z` | <--- same | `7.234`,`7.11`,`6.982` | `2019-08-18T00:42:00Z` | +| 4 | `time >= 2019-08-18T01:00:00Z AND time < 2019-08-18T01:18:00Z` | NA | NA | NA | + +The six-minute offset interval shifts forward the preset boundary's time range +such that the boundary time ranges and the relevant `GROUP BY time()` interval time ranges are +always the same. +With the offset, each interval performs the calculation on three points, and +the timestamp returned matches both the start of the boundary time range and the +start of the `GROUP BY time()` interval time range. + +Note that `offset_interval` forces the fourth time boundary to be outside +the queried time range so the query returns no results for that last interval. + +{{% /expand %}} + +{{% expand "Group query results into 12 minute intervals and shift the preset time boundaries back" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m,-12m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 2019-08-18T00:06:00Z | 8.3213333333 | +| 2019-08-18T00:24:00Z | 8.0120000000 | +| 2019-08-18T00:42:00Z | 7.6400000000 | + + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level`, grouping results into 18 minute +time intervals, and offsetting the preset time boundaries by -12 minutes. + +{{% note %}} +**Note:** The query in Example 2 returns the same results as the query in Example 1, but +the query in Example 2 uses a negative `offset_interval` instead of a positive +`offset_interval`. +There are no performance differences between the two queries; feel free to choose the most +intuitive option when deciding between a positive and negative `offset_interval`. +{{% /note %}} + +The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database's preset time boundaries. Let's first examine the results without the offset: + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(18m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.3695000000 | +| 2019-08-18T00:18:00Z | 8.1223333333 | +| 2019-08-18T00:36:00Z | 7.7680000000 | +| 2019-08-18T00:54:00Z | 7.5100000000 | + +The time boundaries and returned timestamps for the query **without** the +`offset_interval` adhere to the InfluxDB database's preset time boundaries: + +| Time Interval Number | Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------- | :--------------------- | :--------------------- | +| 1 | `time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:18:00Z` | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z` | `8.005`,`7.887` | `2019-08-18T00:00:00Z` | +| 2 | `time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:36:00Z` | <--- same | `7.762`,`7.635`,`7.5` | `2019-08-18T00:18:00Z` | +| 3 | `time >= 2019-08-18T00:36:00Z AND time < 2019-08-18T00:54:00Z` | <--- same | `7.372`,`7.234`,`7.11` | `2019-08-18T00:36:00Z` | +| 4 | `time >= 2019-08-18T00:54:00Z AND time < 2019-08-18T01:12:00Z` | `time = 2019-08-18T00:54:00Z` | `6.982` | `2019-08-18T00:54:00Z` | + +The first preset 18-minute time boundary begins at `00:00` and ends just before +`00:18`. +Two raw points (`8.005` and `7.887`) fall both within the first `GROUP BY time()` interval and in that +first time boundary. +Note that while the returned timestamp occurs before the start of the queried time range, +the query result excludes data that occur before the queried time range. + +The second preset 18-minute time boundary begins at `00:18` and ends just before +`00:36`. +Three raw points (`7.762` and `7.635` and `7.5`) fall both within the second `GROUP BY time()` interval and in that +second time boundary. In this case, the boundary time range and the interval's time range are the same. + +The fourth preset 18-minute time boundary begins at `00:54` and ends just before +`1:12:00`. +One raw point (`6.982`) falls both within the fourth `GROUP BY time()` interval and in that +fourth time boundary. + +The time boundaries and returned timestamps for the query **with** the +`offset_interval` adhere to the offset time boundaries: + +| Time Interval Number | Offset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------- | :---------------------- | ---------------------- | +| 1 | `time >= 2019-08-17T23:48:00Z AND time < 2019-08-18T00:06:00Z` | NA | NA | NA | +| 2 | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:24:00Z` | <--- same | `8.005`,`7.887`,`7.762` | `2019-08-18T00:06:00Z` | +| 3 | `time >= 2019-08-18T00:24:00Z AND time < 2019-08-18T00:42:00Z` | <--- same | `7.635`,`7.5`,`7.372` | `2019-08-18T00:24:00Z` | +| 4 | `time >= 2019-08-18T00:42:00Z AND time < 2019-08-18T01:00:00Z` | <--- same | `7.234`,`7.11`,`6.982` | `2019-08-18T00:42:00Z` | + +The negative 12-minute offset interval shifts back the preset boundary's time range +such that the boundary time ranges and the relevant `GROUP BY time()` interval time ranges are always the +same. +With the offset, each interval performs the calculation on three points, and +the timestamp returned matches both the start of the boundary time range and the +start of the `GROUP BY time()` interval time range. + +Note that `offset_interval` forces the first time boundary to be outside +the queried time range so the query returns no results for that first interval. + +{{% /expand %}} + +{{% expand "Group query results into 12 minute intervals and shift the preset time boundaries forward" %}} + +This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m,6m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 2019-08-18T00:06:00Z | 2.0000000000 | + +The query uses the InfluxQL [COUNT() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count) to count the number of `water_level` points per location, per 12-minute interval, and offset the preset time boundaries by six minutes. + +The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database's preset time boundaries. Let's first examine the results without the offset: + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2019-08-18T00:06:00Z' AND time < '2019-08-18T00:18:00Z' GROUP BY time(12m) +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.0000000000 | +| 2019-08-18T00:12:00Z | 1.0000000000 | + +The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB database's preset time boundaries: + +| Time Interval Number | Preset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------- | :-------------- | :--------------------- | +| 1 | `time >= 2019-08-18T00:00:00Z AND time < 2019-08-18T00:12:00Z` | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:12:00Z` | `8.005` | `2019-08-18T00:00:00Z` | +| 2 | `time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:24:00Z` | `time >= 2019-08-12T00:12:00Z AND time < 2019-08-18T00:18:00Z` | `7.887` | `2019-08-18T00:12:00Z` | + +The first preset 12-minute time boundary begins at `00:00` and ends just before +`00:12`. +Only one raw point (`8.005`) falls both within the query's first `GROUP BY time()` interval and in that +first time boundary. +Note that while the returned timestamp occurs before the start of the queried time range, +the query result excludes data that occur before the queried time range. + +The second preset 12-minute time boundary begins at `00:12` and ends just before +`00:24`. +Only one raw point (`7.887`) falls both within the query's second `GROUP BY time()` interval and in that +second time boundary. + +The time boundaries and returned timestamps for the query **with** the +`offset_interval` adhere to the offset time boundaries: + +| Time Interval Number | Offset Time Boundary | `GROUP BY time()` Interval | Points Included | Returned Timestamp | +| :------------------- | :------------------------------------------------------------- | :------------------------- | :-------------- | :--------------------- | +| 1 | `time >= 2019-08-18T00:06:00Z AND time < 2019-08-18T00:18:00Z` | <--- same | `8.005`,`7.887` | `2019-08-18T00:06:00Z` | +| 2 | `time >= 2019-08-18T00:18:00Z AND time < 2019-08-18T00:30:00Z` | NA | NA | NA | + +The six-minute offset interval shifts forward the preset boundary's time range +such that the preset boundary time range and the relevant `GROUP BY time()` interval time range are the +same. With the offset, the query returns a single result, and the timestamp returned +matches both the start of the boundary time range and the start of the `GROUP BY time()` interval +time range. + +Note that `offset_interval` forces the second time boundary to be outside +the queried time range so the query returns no results for that second interval. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## `GROUP BY` time intervals and `fill()` + +`fill()` changes the value reported for time intervals with no data. + +#### Syntax + +```sql +SELECT () FROM_clause WHERE GROUP BY time(time_interval,[])[,tag_key] [fill()] +``` + +By default, a `GROUP BY time()` interval with no data reports `null` as its +value in the output column. +`fill()` changes the value reported for time intervals with no data. +Note that `fill()` must go at the end of the `GROUP BY` clause if you're +`GROUP(ing) BY` several things (for example, both [tags](/influxdb/v2.4/reference/glossary/#tag) and a time interval). + +##### fill_option + + - Any numerical value - Reports the given numerical value for time intervals with no data. + - `linear` - Reports the results of [linear interpolation](https://en.wikipedia.org/wiki/Linear_interpolation) for time intervals with no data. + - `none` - Reports no timestamp and no value for time intervals with no data. + - `null` - Reports null for time intervals with no data but returns a timestamp. This is the same as the default behavior. + - `previous` - Reports the value from the previous time interval for time intervals with no data. + +### Examples + +{{< tabs-wrapper >}} +{{% tabs "even-wrap" %}} +[fill(100)](#) +[fill(linear)](#) +[fill(none)](#) +[fill(null)](#) +[fill(previous)](#) +{{% /tabs %}} +{{% tab-content %}} + +Without `fill(100)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 2019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | | +| 2019-08-19T09:30:00Z | 6.0000000000 | + +With `fill(100)`: +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(100) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 2019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | 100.0000000000 | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | 100.0000000000 | +| 2019-08-19T09:30:00Z | 6.0000000000 | + +`fill(100)` changes the value reported for the time interval with no data to `100`. + +{{% /tab-content %}} + +{{% tab-content %}} + +Without `fill(linear)`: + +```sql +SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:00:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) +``` +Output: +{{% influxql/table-meta %}} +Name: pond +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---: | +| 2019-11-11T21:00:00Z | 1 | +| 2019-11-11T21:12:00Z | | +| 2019-11-11T21:24:00Z | 3 | +| 2019-11-11T21:36:00Z | | +| 2019-11-11T21:48:00Z | | +| 2019-11-11T22:00:00Z | 6 | + +With `fill(linear)`: + +```sql +SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:00:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) +``` + +Output: +{{% influxql/table-meta %}} +Name: pond +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---: | +| 2019-11-11T21:00:00Z | 1 | +| 2019-11-11T21:12:00Z | 2 | +| 2019-11-11T21:24:00Z | 3 | +| 2019-11-11T21:36:00Z | 4 | +| 2019-11-11T21:48:00Z | 5 | +| 2019-11-11T22:00:00Z | 6 | + +`fill(linear)` changes the value reported for the time interval with no data +to the results of [linear interpolation](https://en.wikipedia.org/wiki/Linear_interpolation). + +{{% note %}} +**Note:** The data in this example is not in the `noaa` database. +{{% /note %}} + +{{% /tab-content %}} + +{{% tab-content %}} + +Without `fill(none)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | | +| 2019-08-19T09:30:00Z | 6.0000000000 | + +With `fill(none)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(none) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 2019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:30:00Z | 6.0000000000 | +``` + +`fill(none)` reports no value and no timestamp for the time interval with no data. + +{{% /tab-content %}} + +{{% tab-content %}} + +Without `fill(null)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | | +| 2019-08-19T09:30:00Z | 6.0000000000 | + +With `fill(null)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(null) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | null | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | null | +| 2019-08-19T09:30:00Z | 6.0000000000 | + +`fill(null)` reports `null` as the value for the time interval with no data. +That result matches the result of the query without `fill(null)`. + +{{% /tab-content %}} + +{{% tab-content %}} + +Without `fill(previous)`: + +```sql + SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) + ``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | | + +With `fill(previous)`: + +```sql +SELECT MEAN("index") FROM "h2o_quality" WHERE "location"='santa_monica' AND time >= '2019-08-19T08:42:00Z' AND time <= '2019-08-19T09:30:00Z' GROUP BY time(5m) fill(previous) + ``` +Output: +{{% influxql/table-meta %}} +Name: h2o_quality +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ------------: | +| 2019-08-19T08:40:00Z | 68.0000000000 | +| 019-08-19T08:45:00Z | 29.0000000000 | +| 2019-08-19T08:50:00Z | 47.0000000000 | +| 2019-08-19T08:55:00Z | 47.0000000000 | +| 2019-08-19T09:00:00Z | 84.0000000000 | +| 2019-08-19T09:05:00Z | 0.0000000000 | +| 2019-08-19T09:10:00Z | 41.0000000000 | +| 2019-08-19T09:15:00Z | 13.0000000000 | +| 2019-08-19T09:20:00Z | 9.0000000000 | +| 2019-08-19T09:25:00Z | 9.0000000000 | + +`fill(previous)` changes the value reported for the time interval with no data to `3.235`, +the value from the previous time interval. + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +### Common issues with `fill()` + +##### Queries with no data in the queried time range + +Currently, queries ignore `fill()` if no data exists in the queried time range. +This is the expected behavior. An open +[feature request](https://github.com/influxdata/influxdb/issues/6967) on GitHub +proposes that `fill()` should force a return of values even if the queried time +range covers no data. + +**Example** + +The following query returns no data because `water_level` has no points within +the queried time range. +Note that `fill(800)` has no effect on the query results. + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2019-09-18T22:00:00Z' AND time <= '2019-09-18T22:18:00Z' GROUP BY time(12m) fill(800) +> no results +``` + +##### Queries with `fill(previous)` when the previous result is outside the queried time range + +`fill(previous)` doesn’t fill the result for a time interval if the previous +value is outside the query’s time range. + +**Example** + +The following example queries the time range between `2019-09-18T16:24:00Z` and `2019-09-18T16:54:00Z`. +Note that `fill(previous)` fills the result for `2019-09-18T16:36:00Z` with the +result from `2019-09-18T16:24:00Z`. + +```sql +SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2019-09-18T16:24:00Z' AND time <= '2019-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ----: | +| 2019-09-18T16:24:00Z | 3.235 | +| 2019-09-18T16:36:00Z | 3.235 | +| 2019-09-18T16:48:00Z | 4 | + + +The next example queries the time range between `2019-09-18T16:36:00Z` and `2019-09-18T16:54:00Z`. +Note that `fill(previous)` doesn't fill the result for `2019-09-18T16:36:00Z` with the +result from `2019-09-18T16:24:00Z`; the result for `2019-09-18T16:24:00Z` is outside the query's +shorter time range. + +```sql +SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2019-09-18T16:36:00Z' AND time <= '2019-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | --: | +| 2019-09-18T16:36:00Z | | +| 2019-09-18T16:48:00Z | 4 | + +##### `fill(linear)` when the previous or following result is outside the queried time range + +`fill(linear)` doesn't fill the result for a time interval with no data if the +previous result or the following result is outside the queried time range. + +**Example** + +The following example queries the time range between `2019-11-11T21:24:00Z` and +`2019-11-11T22:06:00Z`. Note that `fill(linear)` fills the results for the +`2019-11-11T21:36:00Z` time interval and the `2019-11-11T21:48:00Z` time interval +using the values from the `2019-11-11T21:24:00Z` time interval and the +`2019-11-11T22:00:00Z` time interval. + +```sql +SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2019-11-11T21:24:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) +``` +Output: +{{% influxql/table-meta %}} +Name: pond +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---: | +| 2019-11-11T21:24:00Z | 3 | +| 2019-11-11T21:36:00Z | 4 | +| 2019-11-11T21:48:00Z | 5 | +| 2019-11-11T22:00:00Z | 6 | + +The next query shortens the time range in the previous query. +It now covers the time between `2019-11-11T21:36:00Z` and `2019-11-11T22:06:00Z`. +Note that `fill()` previous doesn't fill the results for the `2019-11-11T21:36:00Z` +time interval and the `2019-11-11T21:48:00Z` time interval; the result for +`2019-11-11T21:24:00Z` is outside the query's shorter time range and InfluxDB +cannot perform the linear interpolation. + +```sql +SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2019-11-11T21:36:00Z' AND time <= '2019-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) +``` +Output: +{{% influxql/table-meta %}} +Name: pond +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | ---: | +| 2019-11-11T21:36:00Z | | +| 2019-11-11T21:48:00Z | | +| 2019-11-11T22:00:00Z | 6 | + +{{% note %}} +**Note:** The data in Issue 3 are not in `NOAA` database. We had to create a dataset with less regular data to work with `fill(linear)`. +{{% /note %}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md b/content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md new file mode 100644 index 0000000000..70d40aea21 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit.md @@ -0,0 +1,241 @@ +--- +title: LIMIT and SLIMIT clauses +description: > + Use the `LIMIT` and `SLIMIT` clauses to limit the number of [points](/influxdb/v2.4/reference/glossary/#point) and [series](/influxdb/v2.4/reference/glossary/#series) returned in queries. +menu: + influxdb_2_4: + name: LIMIT and SLIMIT clauses + parent: Explore data +weight: 305 +list_code_example: | + ```sql + SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT + ``` +--- + +Use `LIMIT` and `SLIMIT` to limit the number of [points](/influxdb/v2.4/reference/glossary/#point) and [series](/influxdb/v2.4/reference/glossary/#series) returned per query. + +- [LIMIT clause](#limit-clause) + - [Syntax](#syntax) + - [Examples](#examples) +- [SLIMIT clause](#slimit-clause) + - [Syntax](#syntax-1) + - [Examples](#examples-2) +- [Use LIMIT and SLIMIT together](#use-limit-and-slimit-together) + +## LIMIT clause + +`LIMIT ` returns the first `N` points from the specified [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT +``` + +`N` specifies the number of points to return from the specified measurement . If `N` is greater than the number of points in a measurement, InfluxDB returns all points from the measurement. + +{{% note %}} +**IMPORTANT:** The `LIMIT` clause must appear in the order outlined in the syntax above. +{{% /note %}} + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Limit the number of points returned" %}} + +```sql +SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | location | +| :-------------- | :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000 | coyote_creek| +| 2019-08-17T00:00:00Z | 2.0640000000 |santa_monica | +| 2019-08-17T00:06:00Z | 8.0050000000 |coyote_creek | + +The query returns the three oldest points, determined by timestamp, from the `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +{{% /expand %}} + +{{% expand "Limit the number of points returned and include a `GROUP BY` clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | :-------------------------- | +| 2019-08-18T00:00:00Z | 8.4615000000 | +| 2019-08-18T00:12:00Z | 8.2725000000 | + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | :-------------------------- | +| 2019-08-18T00:00:00Z | 2.3655000000 | +| 2019-08-18T00:12:00Z | 2.3360000000 | + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) and a `GROUP BY` clause to calculate the average `water_level` for each [tag](/influxdb/v2.4/reference/glossary/#tag) and for each 12-minute interval in the queried time range. `LIMIT 2` requests the two oldest 12-minute averages (determined by timestamp). + +Note that without `LIMIT 2`, the query would return four points per series; one for each 12-minute interval in the queried time range. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## SLIMIT clause + +`SLIMIT ` returns every [point](/influxdb/v2.4/reference/glossary/#point) from `N` [series](//influxdb/v2.4/reference/glossary/#series) in the specified [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT +``` + +`N` specifies the number of series to return from the specified measurement. If `N` is greater than the number of series in a measurement, InfluxDB returns all series from that measurement. + +`SLIMIT` queries must include `GROUP BY *`. Note that the `SLIMIT` clause must appear in the order outlined in the syntax above. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Limit the number of series returned" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ---------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000| +| 2019-08-17T00:06:00Z | 8.0050000000| +| 2019-08-17T00:12:00Z | 7.8870000000| +| 2019-08-17T00:18:00Z | 7.7620000000| +| 2019-08-17T00:24:00Z | 7.6350000000| +| 2019-08-17T00:30:00Z | 7.5000000000| +| 2019-08-17T00:36:00Z | 7.3720000000| + +The results above include only the first few rows, as the data set is quite large. The query returns all `water_level` [points](/influxdb/v2.4/reference/glossary/#point) from one of the [series](/influxdb/v2.4/reference/glossary/#series) associated with the `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +{{% /expand %}} + +{{% expand "Limit the number of series returned and include a `GROUP BY time()` clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:00:00Z | 8.4615000000| +| 2019-08-18T00:12:00Z | 8.2725000000| +| 2019-08-18T00:24:00Z | 8.0710000000| +| 2019-08-18T00:36:00Z | 7.8330000000| + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) +and a time interval in the [GROUP BY clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +to calculate the average `water_level` for each 12-minute +interval in the queried time range. + +`SLIMIT 1` requests a single series associated with the `h2o_feet` measurement. + +Note that without `SLIMIT 1`, the query would return results for the two series +associated with the `h2o_feet` measurement: `location=coyote_creek` and +`location=santa_monica`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Use LIMIT and SLIMIT together + +`LIMIT ` followed by `SLIMIT <2>` returns the first `N1` [points](/influxdb/v2.4/reference/glossary/#point) from `N2` series in the specified measurement. + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT +``` + +`N1` specifies the number of points to return per measurement. If `N1` is greater than the number of points in a measurement, InfluxDB returns all points from that measurement. + +`N2` specifies the number of series to return from the specified measurement. If `N2` is greater than the number of series in a measurement, InfluxDB returns all series from that measurement. + +`SLIMIT` queries must include `GROUP BY *`. Note that the `SLIMIT` clause must appear in the order outlined in the syntax above. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Limit the number of points and series returned" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +Tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ---------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000| +| 2019-08-17T00:06:00Z | 8.0050000000| +| 2019-08-17T00:12:00Z | 7.8870000000| + +The query returns the three oldest points, determined by timestamp, from one of the series associated with the measurement `h2o_feet`. + +{{% /expand %}} + +{{% expand "Limit the number of points and series returned and include a `GROUP BY time()` clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +Tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:00:00Z | 8.4615000000| +| 2019-08-18T00:12:00Z | 8.2725000000| + +The query uses the InfluxQL function MEAN() and a time interval in the GROUP BY clause to calculate the average `water_level` for each 12-minute interval in the queried time range. `LIMIT 2` requests the two oldest 12-minute averages (determined by +timestamp) and `SLIMIT 1` requests a single series associated with the `h2o_feet` measurement. + +Note that without `LIMIT 2 SLIMIT 1`, the query would return four points for each of the two series associated with the `h2o_feet` measurement. + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset.md b/content/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset.md new file mode 100644 index 0000000000..a4c0425d92 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset.md @@ -0,0 +1,206 @@ +--- +title: OFFSET and SOFFSET clauses +description: > + Use the `OFFSET` and `SOFFSET` clauses to paginate [points](/influxdb/v2.4/reference/glossary/#point) and [series](/influxdb/v2.4/reference/glossary/#series). +menu: + influxdb_2_4: + name: OFFSET and SOFFSET clauses + parent: Explore data +weight: 306 +list_code_example: | + ```sql + SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] + ``` +--- + +Use `OFFSET` and `SOFFSET` to paginate [points](/influxdb/v2.4/reference/glossary/#point) and [series](/influxdb/v2.4/reference/glossary/#series) returned. + + - [OFFSET clause](#offset-clause) + - [Syntax](#syntax) + - [Examples](#examples) + - [The SOFFSET clause](#soffset-clause) + - [Syntax](#syntax-1) + - [Examples](#examples-1) + +## `OFFSET` clause + +`OFFSET ` paginates `N` [points](/influxdb/v2.4/reference/glossary/#point) in the query results. + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] +``` + +`N` specifies the number of points to paginate. The `OFFSET` clause requires a [`LIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/#limit-clause). + +{{% note %}} +**Note:** InfluxDB returns no results if the `WHERE clause` includes a time range and the `OFFSET clause` would cause InfluxDB to return points with timestamps outside of that time range. +{{% /note %}} + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Paginate points" %}} + +```sql +SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | location | +| :-------------- | -------------------:| :------------------| +| 2019-08-17T00:06:00Z | 2.1160000000 | santa_monica| +| 2019-08-17T00:12:00Z | 7.8870000000 | coyote_creek| +| 2019-08-17T00:12:00Z | 2.0280000000 | santa_monica| + +The query returns the fourth, fifth, and sixth points from the `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). If the query did not include `OFFSET 3`, it would return the first, second, +and third points from that measurement. + +{{% /expand %}} + +{{% expand "Paginate points and include several clauses" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:12:00Z | 8.2725000000 | +| 2019-08-18T00:00:00Z | 8.4615000000 | + +In this example: + + - The [`SELECT clause`](/influxdb/v2.4/query-data/influxql/explore-data/select/) specifies the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean). + - The [`FROM clause`] (/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. + - The [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/) specifies the time range for the query. + - The [`GROUP BY` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. + - The [`ORDER BY time DESC` clause](/influxdb/v2.4/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. + - The [`LIMIT 2` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) limits the number of points returned to two. + - The `OFFSET 2` clause excludes the first two averages from the query results. + - The [`SLIMIT 1` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) limits the number of series returned to one. + +Without `OFFSET 2`, the query would return the first two averages of the query results: + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:36:00Z | 7.8330000000 | +| 2019-08-18T00:24:00Z | 8.0710000000 | + +{{< /expand >}} + +{{< /expand-wrapper >}} + +## `SOFFSET` clause + +`SOFFSET ` paginates `N` [series](/influxdb/v2.4/reference/glossary/#series) in the query results. + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET +``` + +`N` specifies the number of [series](/influxdb/v2.4/reference/glossary/#series) to paginate. +The `SOFFSET` clause requires an [`SLIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/. +Using the `SOFFSET` clause without an `SLIMIT` clause can cause [inconsistent +query results](https://github.com/influxdata/influxdb/issues/7578). +`SLIMIT` queries must include `GROUP BY *`. +{{% note %}} +**Note:** InfluxDB returns no results if the `SOFFSET` clause paginates through more than the total number of series. +{{% /note %}} + +### Examples + +{{% expand-wrapper %}} + +{{% expand "Paginate series" %}} + +#### Paginate series + +```sql +SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ---------------------:| +| 2019-08-17T00:00:00Z | 2.0640000000| +| 2019-08-17T00:06:00Z | 2.1160000000| +| 2019-08-17T00:12:00Z | 2.0280000000| +| 2019-08-17T00:18:00Z | 2.1260000000| +| 2019-08-17T00:24:00Z | 2.0410000000| +| 2019-08-17T00:30:00Z | 2.0510000000| +| 2019-08-17T00:36:00Z | 2.0670000000| +| 2019-08-17T00:42:00Z | 2.0570000000| + +The results above are partial, as the data set is quite large. The query returns data for the series associated with the `h2o_feet` +measurement and the `location = santa_monica` tag. Without `SOFFSET 1`, the query returns data for the series associated with the `h2o_feet` measurement and the `location = coyote_creek` tag. + +{{% /expand %}} + +{{% expand "Paginate points and include several clauses" %}} + +#### Paginate series and include all clauses + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:12:00Z | 2.3360000000| +| 2019-08-18T00:00:00Z | 2.3655000000| + +In this example: + + - The [`SELECT` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/) specifies an InfluxQL [function](/influxdb/v2.4/query-data/influxql/functions/). + - The [`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause) specifies a single measurement. + - The [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/) specifies the time range for the query. + - The [`GROUP BY` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) groups results by all tags (`*`) and into 12-minute intervals. + - The [`ORDER BY time DESC` clause](/influxdb/v2.4/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns results in descending timestamp order. + - The [`LIMIT 2` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) limits the number of points returned to two. + - The [`OFFSET 2` clause](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) excludes the first two averages from the query results. + - The [`SLIMIT 1` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) limits the number of series returned to one. + - The [`SOFFSET 1`](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) clause paginates the series returned. + +Without `SOFFSET 1`, the query would return the results for a different series: + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek + +| time | mean | +| :------------------ | ---------------------:| +| 2019-08-18T00:12:00Z | 8.2725000000 | +| 2019-08-18T00:00:00Z | 8.4615000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/order-by.md b/content/influxdb/v2.4/query-data/influxql/explore-data/order-by.md new file mode 100644 index 0000000000..77d2bb1721 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/order-by.md @@ -0,0 +1,119 @@ +--- +title: ORDER BY clause +list_title: ORDER BY clause +description: > + Use the `ORDER BY` clause to sort data in ascending or descending order. +menu: + influxdb_2_4: + name: ORDER BY clause + parent: Explore data +weight: 304 +list_code_example: | + ```sql + SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC + ``` +--- + +Use the `ORDER BY` clause to sort data. + +- [Syntax](#syntax) +- [Examples](#examples) + +## ORDER BY time DESC + +By default, InfluxDB returns results in ascending time order; the first [point](/influxdb/v2.4/reference/glossary/#point) +returned has the oldest [timestamp](/influxdb/v2.4/reference/glossary/#timestamp) and +the last point returned has the most recent timestamp. +`ORDER BY time DESC` reverses that order such that InfluxDB returns the points +with the most recent timestamps first. + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC +``` + +If the query includes a `GROUP BY` clause, `ORDER by time DESC` must appear **after** the `GROUP BY` clause. +If the query includes a `WHERE` clause and no `GROUP BY` clause, `ORDER by time DESC` must appear **after** the `WHERE` clause. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Return the newest points first" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :-------------- | ------------------:| +| 2019-09-17T21:42:00Z | 4.9380000000| +| 2019-09-17T21:36:00Z | 5.0660000000| +| 2019-09-17T21:30:00Z | 5.0100000000| +| 2019-09-17T21:24:00Z | 5.0130000000| +| 2019-09-17T21:18:00Z | 5.0720000000| + +The query returns the points with the most recent timestamps from the +`h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement) first. +Without `ORDER by time DESC`, the query would return the following output: + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :-------------- | ------------------:| +| 2019-08-17T00:00:00Z | 2.0640000000| +| 2019-08-17T00:06:00Z | 2.1160000000| +| 2019-08-17T00:12:00Z | 2.0280000000| +| 2019-08-17T00:18:00Z | 2.1260000000| + +{{% /expand %}} + +{{% expand "Return the newest points first and include a `GROUP BY time()` clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :-------------- | ------------------:| +| 2019-08-18T00:36:00Z | 4.9712860355| +| 2019-08-18T00:24:00Z | 5.1682500000| +| 2019-08-18T00:12:00Z | 5.3042500000| +| 2019-08-18T00:00:00Z | 5.4135000000| + +The query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) +and a time interval in the [GROUP BY clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +to calculate the average `water_level` for each 12-minute +interval in the queried time range. +[`ORDER BY time DESC`](/influxdb/v2.4/query-data/influxql/explore-data/order-by/#order-by-time-desc) returns the most recent 12-minute time intervals +first. + +Without `ORDER BY time DESC`, the query would return the following output: + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :-------------- | ------------------:| +| 2019-08-18T00:00:00Z | 5.4135000000| +| 2019-08-18T00:12:00Z | 5.3042500000| +| 2019-08-18T00:24:00Z | 5.1682500000| +| 2019-08-18T00:36:00Z | 4.9712860355| + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions.md b/content/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions.md new file mode 100644 index 0000000000..5582ae2ee1 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions.md @@ -0,0 +1,216 @@ +--- +title: Regular expressions +list_title: Regular expressions +description: > + Use `regular expressions` to match patterns in your data. +menu: + influxdb_2_4: + name: Regular expressions + identifier: influxql-regular-expressions + parent: Explore data +weight: 313 +list_code_example: | + ```sql + SELECT // FROM // WHERE [ // | //] GROUP BY // + ``` +--- + +InfluxQL supports using regular expressions when specifying: + +- [field keys](/influxdb/v2.4/reference/glossary/#field-key) and [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/). +- [measurements](/influxdb/v2.4/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause). +- [tag values](/influxdb/v2.4/reference/glossary/#tag-value) and string [field values](/influxdb/v2.4/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/). +- [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) + +Regular expressions in InfluxQL only support string comparisons and can only evaluate [fields](/influxdb/v2.4/reference/glossary/#field) with string values. + +{{% note %}} +**Note:** Regular expression comparisons are more computationally intensive than exact +string comparisons. Queries with regular expressions are not as performant +as those without. +{{% /note %}} + +- [Syntax](#syntax) +- [Examples](#examples) + +## Syntax + +```sql +SELECT // FROM // WHERE [ // | //] GROUP BY // +``` + +Regular expressions are surrounded by `/` characters and use +[Golang's regular expression syntax](http://golang.org/pkg/regexp/syntax/). + +## Supported operators + +`=~`: matches against +`!~`: doesn't match against + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT clause" %}} + +```sql +SELECT /l/ FROM "h2o_feet" LIMIT 1 +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level| +| :------------ | :----------------| :--------------| --------------:| +| 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000| + +The query selects all field keys and tag keys that include an `l`. +Note that the regular expression in the `SELECT` clause must match at least one +field key in order to return results for a tag key that matches the regular +expression. + +Currently, there is no syntax to distinguish between regular expressions for +field keys and regular expressions for tag keys in the `SELECT` clause. +The syntax `//::[field | tag]` is not supported. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} + +```sql +SELECT MEAN("degrees") FROM /temperature/ +``` + +Output: + +{{% influxql/table-meta %}} +Name: average_temperature +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 1970-01-01T00:00:00Z | 79.9847293223 | + +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 1970-01-01T00:00:00Z | 64.9980273540 | + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `degrees` for every [measurement](/influxdb/v2.4/reference/glossary/#measurement) in the [NOAA sample data] that contains the word `temperature`. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify tag values in the WHERE clause" %}} + +```sql +SELECT MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 1970-01-01T00:00:00Z | 4.4710766395| + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level` where the [tag value](/influxdb/v2.4/reference/glossary/#measurement) of `location` includes an `m` and `water_level` is greater than three. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify a tag with no value in the WHERE clause" %}} + +```sql +SELECT * FROM "h2o_feet" WHERE "location" !~ /./ +> +``` + +The query selects all data from the `h2o_feet` measurement where the `location` +[tag](/influxdb/v2.4/reference/glossary/#tag) has no value. +Every data [point](/influxdb/v2.4/reference/glossary/#point) in the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data) has a tag value for `location`. +It's possible to perform this same query without a regular expression. +See the [Frequently Asked Questions](/influxdb/v2.4/reference/faq/#how-do-i-query-data-by-a-tag-with-a-null-value) +document for more information. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify a tag with a value in the WHERE clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 1970-01-01T00:00:00Z | 4.4418434585| + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `water_level` across all data with a tag value for `location`. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify a field value in the WHERE clause" %}} + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ | ---------------------:| +| 1970-01-01T00:00:00Z | 4.4713666916 + + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) +to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify tag keys in the GROUP BY clause" %}} + +```sql +SELECT FIRST("index") FROM "h2o_quality" GROUP BY /l/ +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ |-------------------:| +| 2019-08-17T00:00:00Z | 41.0000000000 | + + +{{% influxql/table-meta %}} +name: h2o_quality +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ |-------------------:| +| 2019-08-17T00:00:00Z | 99.0000000000 | + +This query uses the InfluxQL [FIRST() function](/influxdb/v2.4/query-data/influxql/functions/selectors/#first) + +to select the first value of `index` for every tag that includes the letter `l` +in its tag key. + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/select.md b/content/influxdb/v2.4/query-data/influxql/explore-data/select.md new file mode 100644 index 0000000000..980cfb701d --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/select.md @@ -0,0 +1,681 @@ +--- +title: SELECT statement +list_title: SELECT statement +description: > + Use the `SELECT` statement to query data from a particular [measurement](/influxdb/v2.4/reference/glossary/#measurement) or measurements. +menu: + influxdb_2_4: + name: SELECT statement + parent: Explore data +weight: 301 +list_code_example: | + ```sql + SELECT [,,] FROM [,] + ``` +--- + +Use the `SELECT` statement to query data from a particular [measurement](/influxdb/v2.4/reference/glossary/#measurement) or measurements. + +- [Syntax](#syntax) +- [Examples](#examples) +- [Common issues](#common-issues-with-the-select-statement) +- [Regular expressions](#regular-expressions) +- [Data types and cast operations](#data-types-and-cast-operations) +- [Merge behavior](#merge-behavior) +- [Multiple statements](#multiple-statements) + +## Syntax + +```sql +SELECT [,,] FROM [,] +``` +{{% note %}} +**Note:** The `SELECT` statement **requires** a `SELECT` clause and a `FROM` clause. +{{% /note %}} + +### `SELECT` clause + +The `SELECT` clause supports several formats for specifying data: + +- `SELECT *` - Returns all [fields](/influxdb/v2.4/reference/glossary/#field) and [tags](/influxdb/v2.4/reference/glossary/#tag). +- `SELECT ""` - Returns a specific field. +- `SELECT "",""` - Returns more than one field. +- `SELECT "",""` - Returns a specific field and tag. The `SELECT` clause must specify at least one field when it includes a tag. +- `SELECT ""::field,""::tag` - Returns a specific field and tag. +The `::[field | tag]` syntax specifies the [identifier's](/influxdb/v2.4/reference/syntax/influxql/spec/#identifiers) type. +Use this syntax to differentiate between field keys and tag keys with the same name. + +Other supported features include: + +- [Functions](/influxdb/v2.4/query-data/influxql/functions/) +- [Basic cast operations](#data-types-and-cast-operations) +- [Regular expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) + +{{% note %}} +**Note:** The SELECT statement cannot include an aggregate function **and** a non-aggregate function, field key, or tag key. For more information, see [error about mixing aggregate and non-aggregate queries](/enterprise_influxdb/v1.9/troubleshooting/errors/#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported). +{{% /note %}} + +### `FROM` clause + +The `SELECT` clause specifies the measurement to query. +This clause supports several formats for specifying a [measurement(s)](/influxdb/v2.4/reference/glossary/#measurement): + +- `FROM ` - Returns data from a measurement. +- `FROM ,` - Returns data from more than one measurement. +- `FROM ..` - Returns data from a fully qualified measurement. +- `FROM ..` - Returns data from a measurement. + +#### Quoting + +[Identifiers](/influxdb/v2.4/reference/syntax/influxql/spec/#identifiers) **must** be double quoted if they contain characters other than `[A-z,0-9,_]`, +begin with a digit, or are an [InfluxQL keyword](https://github.com/influxdata/influxql/blob/master/README.md#keywords). +While not always necessary, we recommend that you double quote identifiers. + +{{% note %}} +**Note:** InfluxQL quoting guidelines differ from [line protocol quoting guidelines](/influxdb/v2.4/reference/syntax/line-protocol/#quotes). +Please review the [rules for single and double-quoting](/influxdb/v2.4/reference/syntax/line-protocol/#quotes) in queries. +{{% /note %}} + +### Examples + +{{< expand-wrapper >}} +{{% expand "Select all fields and tags from a measurement" %}} + +```sql +SELECT * FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- |:----------------------| :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | below 3 feet |santa_monica | 2.0640000000| +| 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000| +| 2019-08-17T00:06:00Z | below 3 feet| santa_monica | 2.1160000000| +| 2019- 08-17T00:06:00Z | between 6 and 9 feet |coyote_creek |8.0050000000| +| 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000| +| 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.8870000000| +| 2019-08-17T00:18:00Z | below 3 feet |santa_monica | 2.1260000000| + +The data above is a partial listing of the query output, as the result set is quite large. The query selects all [fields](/influxdb/v2.4/reference/glossary/#field) and +[tags](/influxdb/v2.4/reference/glossary/#tag) from the `h2o_feet` +[measurement](/influxdb/v2.4/reference/glossary/#measurement). + +{{% /expand %}} + +{{% expand "Select specific tags and fields from a measurement" %}} + +```sql +SELECT "level description","location","water_level" FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- |:----------------------| :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | below 3 feet |santa_monica | 2.0640000000| +| 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000| + +The query selects the `level description` field, the `location` tag, and the +`water_level` field. + +{{% note %}} +**Note:** The `SELECT` clause must specify at least one field when it includes +a tag. +{{% /note %}} + +{{% /expand %}} + +{{% expand "Select specific tags and fields from a measurement and provide their identifier type" %}} + +```sql +SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- |:----------------------| :-------------------| ------------------:| +| 2019-08-17T00:24:00Z | between 6 and 9 feet | coyote_creek | 7.6350000000| +| 2019-08-17T00:30:00Z | below 3 feet | santa_monica | 2.0510000000| +| 2019-08-17T00:30:00Z | between 6 and 9 feet | coyote_creek | 7.5000000000| +| 2019-08-17T00:36:00Z | below 3 feet | santa_monica | 2.0670000000 | +| 2019-08-17T00:36:00Z | between 6 and 9 feet | coyote_creek | 7.3720000000 | +| 2019-08-17T00:42:00Z | below 3 feet | santa_monica | 2.0570000000 | + +The query selects the `level description` field, the `location` tag, and the +`water_level` field from the `h2o_feet` measurement. +The `::[field | tag]` syntax specifies if the +[identifier](/influxdb/v2.4/reference/syntax/influxql/spec/#identifiers) is a field or tag. +Use `::[field | tag]` to differentiate between [an identical field key and tag key ](/v2.4/reference/faq/#how-do-i-query-data-with-an-identical-tag-key-and-field-key). +That syntax is not required for most use cases. + +{{% /expand %}} + +{{% expand "Select all fields from a measurement" %}} + +```sql +SELECT *::field FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description| water_level | +| :-------------- | :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | below 3 feet | 2.0640000000 | +| 2019-08-17T00:00:00Z | between 6 and 9 feet | 8.1200000000| +| 2019-08-17T00:06:00Z | below 3 feet | 2.1160000000| +| 2019-08-17T00:06:00Z | between 6 and 9 feet | 8.0050000000| +| 2019-08-17T00:12:00Z | below 3 feet | 2.0280000000| +| 2019-08-17T00:12:00Z | between 6 and 9 feet | 7.8870000000| + +The query selects all fields from the `h2o_feet` measurement. +The `SELECT` clause supports combining the `*` syntax with the `::` syntax. + +{{% /expand %}} + +{{% expand "Select a specific field from a measurement and perform basic arithmetic" %}} + +```sql +SELECT ("water_level" * 2) + 4 FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :-------------- | ------------------:| +| 2019-08-17T00:00:00Z | 20.2400000000 | +| 2019-08-17T00:00:00Z | 8.1280000000 | +| 2019-08-17T00:06:00Z | 20.0100000000 | +| 2019-08-17T00:06:00Z | 8.2320000000 | +| 2019-08-17T00:12:00Z | 19.7740000000 | +| 2019-08-17T00:12:00Z | 8.0560000000 | + +The query multiplies `water_level`'s field values by two and adds four to those +values. + +{{% note %}} +**Note:** InfluxDB follows the standard order of operations. +See [InfluxQL mathematical operators](/influxdb/v2.4/query-data/influxql/math-operators/) +for more on supported operators. +{{% /note %}} + +{{% /expand %}} + +{{% expand "Select all data from more than one measurement" %}} + +```sql +SELECT * FROM "h2o_feet","h2o_pH" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | pH | water_level | +| :-------------- |:-------------| :----------------| :-------------| --------------:| +| 2019-08-17T00:00:00Z | below 3 feet | santa_monica | | 2.0640000000| +| 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | | 8.1200000000| +| 2019-08-17T00:06:00Z | below 3 feet | santa_monica | | 2.1160000000| +| 2019-08-17T00:06:00Z | between 6 and 9 feet | coyote_creek | | 8.0050000000| +| 2019-08-17T00:12:00Z | below 3 feet | santa_monica | | 2.0280000000 | +| 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | | 7.8870000000| +| 2019-08-17T00:18:00Z | below 3 feet | santa_monica | | 2.1260000000| +| 2019-08-17T00:18:00Z | between 6 and 9 feet | coyote_creek | | 7.7620000000| + +{{% influxql/table-meta %}} +Name: h2o_pH +{{% /influxql/table-meta %}} + +| time | level description | location | pH | water_level | +| :-------------- |:-------------| :----------------| :-------------| --------------:| +| 2019-08-17T00:00:00Z | | coyote_creek | 7.00| | +| 2019-08-17T00:06:00Z | |coyote_creek | 8.00 | | +| 2019-08-17T00:06:00Z | |santa_monica | 6.00 | | +| 2019-08-17T00:12:00Z | |coyote_creek |8.00 | | + + +The query selects all fields and tags from two measurements: `h2o_feet` and +`h2o_pH`. +Separate multiple measurements with a comma (`,`). + +{{% /expand %}} + +{{% expand "Select all data from a measurement in a particular database" %}} + +```sql +SELECT * FROM noaa.."h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- |:----------------------| :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | below 3 feet |santa_monica | 2.0640000000| +| 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.1200000000| +| 2019-08-17T00:06:00Z | below 3 feet| santa_monica | 2.1160000000| +| 2019- 08-17T00:06:00Z | between 6 and 9 feet |coyote_creek |8.0050000000| +| 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000| +| 2019-08-17T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.8870000000| + +The query selects data from the `h2o_feet` measurement in the `noaa` database. +The `..` indicates the `DEFAULT` retention policy for the specified database. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Common issues with the SELECT statement + +### Selecting tag keys in the SELECT statement + +A query requires at least one [field key](/influxdb/v2.4/reference/glossary/#field-key) +in the `SELECT` clause to return data. +If the `SELECT` clause only includes a single [tag key](/influxdb/v2.4/reference/glossary/#tag-key) or several tag keys, the +query returns an empty response. + +#### Example + +The following query returns no data because it specifies a single tag key (`location`) in +the `SELECT` clause: + +```sql +SELECT "location" FROM "h2o_feet" +> No results +``` +To return any data associated with the `location` tag key, the query's `SELECT` +clause must include at least one field key (`water_level`): + +```sql +SELECT "water_level","location" FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | location | +| :-------------- | :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000 | coyote_creek | +| 2019-08-17T00:00:00Z | 2.0640000000 | santa_monica | +| 2019-08-17T 00:06:00Z | 8.0050000000 | coyote_creek | +| 2019-08-17T00:06:00Z | 2.1160000000 | santa_monica | +| 2019-08-17T00:12:00Z | 7.8870000000 | coyote_creek | +| 2019-08-17T00:12:00Z | 2.0280000000 | santa_monica | +| 2019-08-17T00:18:00Z | 7.7620000000 | coyote_creek | +| 2019-08-17T00:18:00Z | 2.1260000000 | santa_monica | + +## Regular expressions + +InfluxQL supports using regular expressions when specifying: +- [field keys](/influxdb/v2.4/reference/glossary/#field-key) and [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) in the [`SELECT` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/) +- [measurements](/influxdb/v2.4/reference/glossary/#measurement) in the [`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause) +- [tag values](/influxdb/v2.4/reference/glossary/#tag-value) and string [field values](/influxdb/v2.4/reference/glossary/#field-value) in the [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/). +- [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) in the [`GROUP BY` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) + +Currently, InfluxQL does not support using regular expressions to match +non-string field values in the +`WHERE` clause, +[databases](/influxdb/v2.4/reference/glossary/#database), and +[retention policies](/influxdb/v2.4/reference/glossary/#retention-policy-rp). + +{{% note %}} +**Note:** Regular expression comparisons are more computationally intensive than exact +string comparisons. Queries with regular expressions are not as performant +as those without. +{{% /note %}} + +## Syntax + +```sql +SELECT // FROM // WHERE [ // | //] GROUP BY // +``` + +Regular expressions are surrounded by `/` characters and use +[Golang's regular expression syntax](http://golang.org/pkg/regexp/syntax/). + +## Supported operators + +`=~`: matches against +`!~`: doesn't match against + +## Examples + +{{< expand-wrapper >}} +{{% expand "Use a regular expression to specify field keys and tag keys in the SELECT statement" %}} +#### Use a regular expression to specify field keys and tag keys in the SELECT statement + +```sql +SELECT /l/ FROM "h2o_feet" LIMIT 1 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- |:----------------------| :-------------------| ------------------:| +| 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000 | + +The query selects all [field keys](/influxdb/v2.4/reference/glossary/#field-key) +and [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) that include an `l`. +Note that the regular expression in the `SELECT` clause must match at least one +field key in order to return results for a tag key that matches the regular +expression. + +Currently, there is no syntax to distinguish between regular expressions for +field keys and regular expressions for tag keys in the `SELECT` clause. +The syntax `//::[field | tag]` is not supported. + +{{% /expand %}} + +{{% expand "Use a regular expression to specify measurements in the FROM clause" %}} + +```sql +SELECT MEAN("degrees") FROM /temperature/ +``` +Output: +{{% influxql/table-meta %}} +Name: average_temperature +{{% /influxql/table-meta %}} + +| time | mean| +| :-------------- |----------------------:| +| 1970-01-01T00:00:00Z | 79.9847293223 + + +{{% influxql/table-meta %}} +Name: h2o_temperature +{{% /influxql/table-meta %}} + +| time | mean| +| :-------------- |----------------------:| +| 1970-01-01T00:00:00Z | 64.9980273540 | + + +This query uses the InfluxQL [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) to calculate the average `degrees` for every [measurement](/influxdb/v2.4/reference/glossary/#measurement) in the `noaa` database that contains the word `temperature`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Data types and cast operations + +The [`SELECT` clause](#select-clause) supports specifying a [field's](/influxdb/v2.4/reference/glossary/#field) type and basic cast operations with the `::` syntax. + + - [Data types](#data-types) + - [Cast operations](#cast-operations) + +### Data types + +[Field values](/influxdb/v2.4/reference/glossary/#field-value) can be floats, integers, strings, or booleans. +The `::` syntax allows users to specify the field's type in a query. + +{{% note %}} +**Note:** Generally, it is not necessary to specify the field value type in the [`SELECT` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/). In most cases, InfluxDB rejects any writes that attempt to write a [field value](/influxdb/v2.4/reference/glossary/#field-value) to a field that previously accepted field values of a different type. +{{% /note %}} + +It is possible for field value types to differ across [shard groups](/influxdb/v2.4/reference/glossary/#shard-group). +In these cases, it may be necessary to specify the field value type in the +`SELECT` clause. +Please see the +[Frequently Asked Questions](/influxdb/v2.4/reference/faq/#how-does-influxdb-handle-field-type-discrepancies-across-shards) +document for more information on how InfluxDB handles field value type discrepancies. + +### Syntax + +```sql +SELECT_clause :: FROM_clause +``` + +`type` can be `float`, `integer`, `string`, or `boolean`. +In most cases, InfluxDB returns no data if the `field_key` does not store data of the specified +`type`. See [Cast Operations](#cast-operations) for more information. + +### Example + +```sql +SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | water_level | +| :------------------ |-------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000 | +| 2019-08-17T00:00:00Z | 2.0640000000 | +| 2019-08-17T00:06:00Z | 8.0050000000 | +| 2019-08-17T00:06:00Z | 2.1160000000 | + +The query returns values of the `water_level` field key that are floats. + +## Cast operations + +The `::` syntax allows users to perform basic cast operations in queries. +Currently, InfluxDB supports casting [field values](/influxdb/v2.4/reference/glossary/#field-value) from integers to +floats or from floats to integers. + +### Syntax + +```sql +SELECT_clause :: FROM_clause +``` + +`type` can be `float` or `integer`. + +InfluxDB returns no data if the query attempts to cast an integer or float to a string or boolean. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Cast float field values to integers" %}} + +```sql +SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | water_level | +| :------------------ |-------------------:| +| 2019-08-17T00:00:00Z | 8.0000000000 | +| 2019-08-17T00:00:00Z | 2.0000000000 | +| 2019-08-17T00:06:00Z | 8.0000000000 | +| 2019-08-17T00:06:00Z | 2.0000000000 | + +The query returns the integer form of `water_level`'s float [field values](/influxdb/v2.4/reference/glossary/#field-value). + +{{% /expand %}} + +{{% expand "Cast float field values to strings (this functionality is not supported)" %}} + +```sql +SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 +> No results +``` + +The query returns no data as casting a float field value to a string is not yet supported. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Merge behavior + +InfluxQL merges [series](/influxdb/v2.4/reference/glossary/#series) automatically. + +### Example + +{{< expand-wrapper >}} + +{{% expand "Merge behavior" %}} + +The `h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement) in the `noaa` is part of two [series](/influxdb/v2.4/reference/glossary/#series). +The first series is made up of the `h2o_feet` measurement and the `location = coyote_creek` [tag](/influxdb/v2.4/reference/glossary/#tag). The second series is made of up the `h2o_feet` measurement and the `location = santa_monica` tag. + +The following query automatically merges those two series when it calculates the average `water_level` using the [MEAN() function](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean): + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | mean | +| :------------------ |-------------------:| +| 1970-01-01T00:00:00Z | 4.4419314021 | + +If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/): + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | mean | +| :------------------ |-------------------:| +| 1970-01-01T00:00:00Z | 5.3591424203 | + +If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/): + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ |-------------------:| + | 1970-01-01T00:00:00Z | 5.3591424203 | + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------ |-------------------:| +| 1970-01-01T00:00:00Z | 3.5307120942 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Multiple statements + +Separate multiple `SELECT` statements in a query with a semicolon (`;`). + +### Examples + +{{< tabs-wrapper >}} +{{% tabs %}} +[InfluxQL shell](#) +[InfluxDB API](#) +{{% /tabs %}} + +{{% tab-content %}} + +In the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/): + +```sql +SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | mean | +| :------------------ |-------------------:| +| 1970-01-01T00:00:00Z | 4.4419314021 | + + +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +|time | water_level | +| :------------------ |-------------------:| +| 2019-08-17T00:00:00Z | 8.12 | +| 2015-08-18T00:00:00Z | 2.064 | + +{{% /tab-content %}} + +{{% tab-content %}} + +With the [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/): + +```json +{ + "results": [ + { + "statement_id": 0, + "series": [ + { + "name": "h2o_feet", + "columns": [ + "time", + "mean" + ], + "values": [ + [ + "1970-01-01T00:00:00Z", + 4.442107025822522 + ] + ] + } + ] + }, + { + "statement_id": 1, + "series": [ + { + "name": "h2o_feet", + "columns": [ + "time", + "water_level" + ], + "values": [ + [ + "2015-08-18T00:00:00Z", + 8.12 + ], + [ + "2015-08-18T00:00:00Z", + 2.064 + ] + ] + } + ] + } + ] +} +``` + +{{% /tab-content %}} +{{< /tabs-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/subqueries.md b/content/influxdb/v2.4/query-data/influxql/explore-data/subqueries.md new file mode 100644 index 0000000000..452f410bd4 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/subqueries.md @@ -0,0 +1,294 @@ +--- +title: Subqueries +description: > + Use a `subquery` to apply a query as a condition in the enclosing query. +menu: + influxdb_2_4: + name: Subqueries + parent: Explore data +weight: 310 +list_code_example: | + ```sql + SELECT_clause FROM ( SELECT_statement ) [...] + ``` +--- + +A subquery is a query that is nested in the `FROM` clause of another query. Use a subquery to apply a query as a condition in the enclosing query. Subqueries offer functionality similar to nested functions and the SQL [`HAVING` clause](https://en.wikipedia.org/wiki/Having_%28SQL%29). + +{{% note %}} +**Note:** InfluxQL does not support a `HAVING` clause. +{{% /note %}} + +- [Syntax](#syntax) +- [Examples](#examples) +- [Common Issues](#common-issues-with-subqueries) + +### Syntax + +```sql +SELECT_clause FROM ( SELECT_statement ) [...] +``` + +InfluxDB **performs the subquery first** and the main query second. + +The main query surrounds the subquery and requires at least the [`SELECT` clause](/influxdb//v2.4/query-data/influxql/explore-data/select/) and the [`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause). +The main query supports all clauses listed in InfluxQL 2.x documentation. + +The subquery appears in the main query's `FROM` clause, and it requires surrounding parentheses. +The subquery also supports all clauses listed in InfluxQL 2.x documentation. + +InfluxQL supports multiple nested subqueries per main query. +Sample syntax for multiple subqueries: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] +``` + +{{% note %}} +**Note:** #### Improve performance of time-bound subqueries +To improve the performance of InfluxQL queries with time-bound subqueries, +apply the `WHERE time` clause to the outer query instead of the inner query. +For example, the following queries return the same results, but **the query with +time bounds on the outer query is more performant than the query with time +bounds on the inner query**: + +##### Time bounds on the outer query (recommended) +```sql +SELECT inner_value AS value FROM (SELECT raw_value as inner_value) +WHERE time >= '2022-07-19T21:00:00Z' +AND time <= '2022-07-20T22: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-19T21:00:00Z' + AND time <= '2022-07-20T22:00:00Z' +) +``` +{{% /note %}} + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the SUM() of several MAX() values" %}} + +```sql +SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sum | +| :--------------| ------------------:| +|1970-01-01T00:00:00Z | 17.169 | + + +The query returns the sum of the maximum `water_level` values across every tag value of `location`. + +InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: + +```sql +SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | max | +| :--------------------------- | ------------------: | +| 2015-08-29T07:24:00Z | 9.9640000000 | + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | max | +| :--------------------------- | ------------------: | +| 2015-08-29T03:54:00Z | 7.2050000000 | + +Next, InfluxDB performs the main query and calculates the sum of those maximum values: `9.9640000000` + `7.2050000000` = `17.169`. +Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. + +{{% /expand %}} + +{{% expand "Calculate the MEAN() difference between two fields" %}} + +```sql +SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") +``` + +Output: +{{% influxql/table-meta %}} +Name: pet_daycare +{{% /influxql/table-meta %}} + +| time | max | +| :--------------------------- | ------------------: | +| 1970-01-01T00:00:00Z | 1.75 | + + +The query returns the average of the differences between the number of `cats` and `dogs` in the `pet_daycare` measurement. + +InfluxDB first performs the subquery. +The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, +and it names the output column `difference`: + +```sql +SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" +``` +Output: +{{% influxql/table-meta %}} +Name: pet_daycare +{{% /influxql/table-meta %}} + +| time | difference | +| :--------------------------- | ------------------: | +| 2017-01-20T00:55:56Z | -1 | +2017-01-21T00:55:56Z | -49 | +2017-01-22T00:55:56Z | 66 | +2017-01-23T00:55:56Z | -9 | + + +Next, InfluxDB performs the main query and calculates the average of those differences. +Notice that the main query specifies `difference` as the field key in the [`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) function. + +{{% /expand %}} + +{{% expand "Calculate several MEAN() values and place a condition on those mean values" %}} + +```sql +SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | all_the_means | +| :--------------------------- | ------------------: | +| 2019-08-18T00:00:00Z | 5.4135000000 | +| 2019-08-18T00:12:00Z | 5.3042500000 | +| 2019-08-18T00:24:00Z | 5.1682500000 | + + +The query returns all mean values of the `water_level` field that are greater than five. + +InfluxDB first performs the subquery. +The subquery calculates `MEAN()` values of `water_level` from `2019-08-18T00:00:00Z` through `2019-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: + +```sql +SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | all_the_means | +| :--------------------------- | ------------------: | +| 2019-08-18T00:00:00Z | 5.4135000000 | +| 2019-08-18T00:12:00Z | 5.3042500000 | +| 2019-08-18T00:24:00Z | 5.1682500000 | + +Next, InfluxDB performs the main query and returns only those mean values that are greater than five. +Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. + +{{% /expand %}} + +{{% expand "Calculate the SUM() of several DERIVATIVE() values" %}} + +```sql +SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" +``` + +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | sum_derivative | +| :--------------------------- | ------------------: | +| 1970-01-01T00:00:00Z | -0.5315000000 | + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | sum_derivative | +| :--------------------------- | ------------------: | +| 1970-01-01T00:00:00Z | -0.2375000000 | + +The query returns the sum of the derivative of average `water_level` values for each tag value of `location`. + +InfluxDB first performs the subquery. +The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. +It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: + +```sql +SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),"location" +``` +Output: +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | water_level_derivative | +| :--------------------------- | ------------------: | +| 2019-08-18T00:00:00Z | -0.1410000000 | +| 2019-08-18T00:12:00Z | -0.1890000000 | +| 2019-08-18T00:24:00Z | -0.2015000000 | + + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | water_level_derivative | +| :--------------------------- | ------------------: | +| 2019-08-18T00:00:00Z | -0.1375000000 | +| 2019-08-18T00:12:00Z | -0.0295000000 | +| 2019-08-18T00:24:00Z | -0.0705000000 | + + +Next, InfluxDB performs the main query and calculates the sum of the `water_level_derivative` values for each tag value of `location`. +Notice that the main query specifies `water_level_derivative`, not `water_level` or `derivative`, as the field key in the [`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum) function. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with subqueries + +#### Multiple statements in a subquery + +InfluxQL supports multiple nested subqueries per main query: + +```sql +SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] + ------------------ ---------------- + Subquery 1 Subquery 2 +``` + +InfluxQL does not support multiple [`SELECT` statements](/influxdb/v2.4/query-data/influxql/explore-data/select/) per subquery: + +```sql +SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] +``` + +The system returns a parsing error if a subquery includes multiple `SELECT` statements. diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone.md b/content/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone.md new file mode 100644 index 0000000000..813e5f1e6c --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone.md @@ -0,0 +1,441 @@ +--- +title: Time and timezone queries +list_title: Time and timezone queries +description: > + Explore InfluxQL features used specifically for working with time. Use the `tz` (timezone) clause to return the UTC offset for the specified timezone. +menu: + influxdb_2_4: + name: Time and timezone + parent: Explore data +weight: 308 +list_code_example: | + ```sql + SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') + ``` +--- + +InfluxQL is designed for working with time series data and includes features specifically for working with time. +You can review the following ways to work with time and timestamps in your InfluxQL queries: + +- [Configuring returned timestamps](#configuring-returned-timestamps) +- [Time syntax](#time-syntax) +- [Absolute time](#absolute-time) +- [Relative time](#relative-time) +- [The Time Zone clause](#the-time-zone-clause) +- [Common issues with time syntax](#common-issues-with-time-syntax) + +## Configuring returned timestamps + +The [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/) returns timestamps in +nanosecond UNIX epoch format by default. +Specify alternative formats with the +[`precision ` command](/influxdb/v2.4/tools/influxql-shell/#precision). + +If you are using the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/), use the precision helper command `precision rfc3339` to view results in human readable format. + +The [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) returns timestamps +in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. +Specify alternative formats with the +[`epoch` query string parameter](/influxdb/v2.4/reference/api/influxdb-1x/). + +## Time syntax + +For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2.4/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). +For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/), +the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2.4/reference/glossary/#now). +The following sections detail how to specify alternative time ranges in the `SELECT` +statement's [`WHERE` clause](/influxdb/v2.4/query-data/influxql/explore-data/where/). + +Other supported features include: +[Absolute time](#absolute-time) +[Relative time](#relative-time) + +## Absolute time + +Specify absolute time with date-time strings and epoch time. + +### Syntax + +```sql +SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] +``` + +#### Supported operators + +| Operator | Meaning | +|:--------:|:------- | +| `=` | equal to | +| `<>` | not equal to | +| `!=` | not equal to | +| `>` | greater than | +| `>=` | greater than or equal to | +| `<` | less than | +| `<=` | less than or equal to | + +Currently, InfluxDB does not support using `OR` with absolute time in the `WHERE` +clause. See the [Frequently Asked Questions](/influxdb/v2.4/reference/faq/#why-is-my-query-with-a-where-or-time-clause-returning-empty-results) +document and the [GitHub Issue](https://github.com/influxdata/influxdb/issues/7530) +for more information. + +#### `rfc3339_date_time_string` + +```sql +'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' +``` + +`.nnnnnnnnn` is optional and is set to `.000000000` if not included. +The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires single quotes. + +#### `rfc3339_like_date_time_string` + +```sql +'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' +``` + +`HH:MM:SS.nnnnnnnnn.nnnnnnnnn` is optional and is set to `00:00:00.000000000` if not included. +The RFC3339-like date-time string requires single quotes. + +#### `epoch_time` + +Epoch time is the amount of time that has elapsed since 00:00:00 +Coordinated Universal Time (UTC), Thursday, 1 January 1970. + +By default, InfluxDB assumes that all epoch timestamps are in **nanoseconds**. Include a [duration literal](/influxdb/v2.4/reference/glossary/#duration) at the end of the epoch timestamp to indicate a precision other than nanoseconds. + +#### Basic arithmetic + +All timestamp formats support basic arithmetic. +Add (`+`) or subtract (`-`) a time from a timestamp with a [duration literal](/influxdb/v2.4/reference/glossary/#duration). +Note that InfluxQL requires a whitespace between the `+` or `-` and the +duration literal. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Specify a time range with RFC3339 date-time strings" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00.000000000Z' AND time <= '2019-08-18T00:12:00Z' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ------------------:| +| 2019-08-18T00:00:00Z | 2.3520000000| +| 2019-08-18T00:06:00Z | 2.3790000000| +| 2019-08-18T00:12:00Z | 2.3430000000| + +The query returns data with timestamps between August 18, 2019 at 00:00:00.000000000 and +August 18, 2019 at 00:12:00. + +Note that the single quotes around the RFC3339 date-time strings are required. + +{{% /expand %}} + +{{% expand "Specify a time range with RFC3339-like date-time strings" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18' AND time <= '2019-08-18 00:12:00' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ------------------:| +| 2019-08-18T00:00:00Z | 2.3520000000| +| 2019-08-18T00:06:00Z | 2.3790000000| +| 2019-08-18T00:12:00Z | 2.3430000000| + +The query returns data with timestamps between August 18, 2019 at 00:00:00 and August 18, 2019 +at 00:12:00. +The first date-time string does not include a time; InfluxDB assumes the time +is 00:00:00. + +Note that the single quotes around the RFC3339-like date-time strings are +required. + +{{% /expand %}} + +{{% expand "Specify a time range with epock timestamps" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1564635600000000000 AND time <= 1566190800000000000 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ------------------:| +| 2019-08-17T00:00:00Z | 2.0640000000| +| 2019-08-17T00:06:00Z | 2.1160000000| +| 2019-08-17T00:12:00Z | 2.0280000000| +| 2019-08-17T00:18:00Z | 2.1260000000| +| 2019-08-17T00:24:00Z | 2.0410000000| +| 2019-08-17T00:30:00Z | 2.0510000000| +| 2019-08-17T00:36:00Z | 2.0670000000| +| 2019-08-17T00:42:00Z | 2.0570000000| +| 2019-08-17T00:48:00Z | 1.9910000000| +| 2019-08-17T00:54:00Z | 2.0540000000| +| 2019-08-17T01:00:00Z | 2.0180000000| +| 2019-08-17T01:06:00Z | 2.0960000000| +| 2019-08-17T01:12:00Z | 2.1000000000| +| 2019-08-17T01:18:00Z | 2.1060000000| +| 2019-08-17T01:24:00Z | 2.1261441460| + +The query returns data with timestamps that occur between August 1, 2019 +at 00:00:00 and August 19, 2019 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. + +{{% /expand %}} + +{{% expand "Specify a time range with second-precision epoch timestamps" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1566190800s AND time <= 1566191520s +``` +Output: +| time | water_level | +| :------------------ | ------------------:| +| 2019-08-19T05:00:00Z | 3.2320000000| +| 2019-08-19T05:06:00Z | 3.2320000000| +| 2019-08-19T05:12:00Z | 3.2910000000| + +The query returns data with timestamps that occur between August 19, 2019 +at 00:00:00 and August 19, 2019 at 00:12:00. +The `s` duration literal at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. + +{{% /expand %}} + +{{% expand "Perform basic arithmetic on an RFC3339-like date-time string" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time > '2019-09-17T21:24:00Z' + 6m +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ------------------:| +| 2019-09-17T21:36:00Z | 5.0660000000| +| 2019-09-17T21:42:00Z | 4.9380000000| + +The query returns data with timestamps that occur at least six minutes after +September 17, 2019 at 21:24:00. +Note that the whitespace between the `+` and `6m` is required. + +{{% /expand %}} + +{{% expand "Perform basic arithmetic on an epock timestamp" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------ | ------------------:| +| 2019-08-17T00:00:00Z | 8.1200000000| +| 2019-08-17T00:00:00Z | 2.0640000000| +| 2019-08-17T00:06:00Z | 8.0050000000| +| 2019-08-17T00:06:00Z | 2.1160000000| +| 2019-08-17T00:12:00Z | 7.8870000000| +| 2019-08-17T00:12:00Z | 2.0280000000| +| 2019-08-17T00:18:00Z | 7.7620000000| +| 2019-08-17T00:18:00Z | 2.1260000000| + +The query returns data with timestamps that occur at least six minutes before +September 18, 2019 at 21:24:00. Note that the whitespace between the `-` and `6m` is required. Note that the results above are partial as the dataset is large. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Relative time + +Use [`now()`](/influxdb/v2.4/reference/glossary/#now) to query data with [timestamps](/influxdb/v2.4/reference/glossary/#timestamp) relative to the server's current timestamp. + +### Syntax + +```sql +SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] +``` + +`now()` is the Unix time of the server at the time the query is executed on that server. +The whitespace between `-` or `+` and the [duration literal](/influxdb/v2.4/reference/glossary/#duration) is required. + +#### Supported operators +| Operator | Meaning | +|:--------:|:------- | +| `=` | equal to | +| `<>` | not equal to | +| `!=` | not equal to | +| `>` | greater than | +| `>=` | greater than or equal to | +| `<` | less than | +| `<=` | less than or equal to | + +#### `duration_literal` + +- microseconds: `u` or `µ` +- milliseconds: `ms` +- seconds`s` +- minutes`m` +- hours:`h` +- days:`d` +- weeks:`w` + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Specify a time range with relative time" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h +``` + +The query returns data with timestamps that occur within the past hour. +The whitespace between `-` and `1h` is required. + +{{% /expand %}} + +{{% expand "Specify a time range with absolute time and relative time" %}} + +#### Specify a time range with absolute time and relative time + +```sql +SELECT "level description" FROM "h2o_feet" WHERE time > '2019-09-17T21:18:00Z' AND time < now() + 1000d +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | +| :------------------ |--------------------:| +|2019-09-17T21:24:00Z | between 3 and 6 feet | +|2019-09-17T21:30:00Z | between 3 and 6 feet | +|2019-09-17T21:36:00Z | between 3 and 6 feet | +|2019-09-17T21:42:00Z | between 3 and 6 feet | + +The query returns data with timestamps that occur between September 17, 2019 at 21:18:00 and 1000 days from `now()`. The whitespace between `+` and `1000d` is required. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## The Time Zone clause + +Use the `tz()` clause to return the UTC offset for the specified timezone. + +### Syntax + +```sql +SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') +``` + +By default, InfluxDB stores and returns timestamps in UTC. +The `tz()` clause includes the UTC offset or, if applicable, the UTC Daylight Savings Time (DST) offset to the query's returned timestamps. The returned timestamps must be in `RFC3339` format for the UTC offset or UTC DST to appear. +The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Numbers Authority time zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) and it requires single quotes. + +### Examples + +{{< expand-wrapper >}} + +{{% expand "Return the UTC offset for Chicago's time zone" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:18:00Z' tz('America/Chicago') +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :-------------- | -------------------:| +| 2019-08-17T19:00:00-05:00 | 2.3520000000| +| 2019-08-17T19:06:00-05:00 | 2.3790000000| +| 2019-08-17T19:12:00-05:00 | 2.3430000000| +| 2019-08-17T19:18:00-05:00 | 2.3290000000| + +The query results include the UTC offset (`-05:00`) for the `America/Chicago` time zone in the timestamps. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## Common issues with time syntax + +### Using `OR` to select time multiple time intervals + +InfluxDB does not support using the `OR` operator in the `WHERE` clause to specify multiple time intervals. + +For more information, see [Frequently asked questions](/influxdb/v2.4/reference/faq/#why-is-my-query-with-a-where-or-time-clause-returning-empty-results). + +### Querying data that occur after `now()` with a `GROUP BY time()` clause + +Most `SELECT` statements have a default time range between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2.4/reference/faq/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). +For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals), +the default time range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2.4/reference/glossary/#now). + +To query data with timestamps that occur after `now()`, `SELECT` statements with +a `GROUP BY time()` clause must provide an alternative upper bound in the +`WHERE` clause. + + diff --git a/content/influxdb/v2.4/query-data/influxql/explore-data/where.md b/content/influxdb/v2.4/query-data/influxql/explore-data/where.md new file mode 100644 index 0000000000..115c4917ef --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-data/where.md @@ -0,0 +1,314 @@ +--- +title: The WHERE clause +list_title: WHERE clause +description: > + Use the `WHERE` clause to filter data based on [fields](/influxdb/v2.4/reference/glossary/#field), [tags](/influxdb/v2.4/reference/glossary/#tag), and/or [timestamps](/influxdb/v2.4/reference/glossary/#timestamp). +menu: + influxdb_2_4: + name: WHERE clause + parent: Explore data +weight: 302 +list_code_example: | + ```sql + SELECT_clause FROM_clause WHERE [(AND|OR) [...]] + ``` +--- + +Use the `WHERE` clause to filter data based on +[fields](/influxdb/v2.4/reference/glossary/#field), +[tags](/influxdb/v2.4/reference/glossary/#tag), and/or +[timestamps](/influxdb/v2.4/reference/glossary/#timestamp). + +- [Syntax](#syntax) +- [Examples](#examples) +- [Common issues](#common-issues-with-the-where-clause) + +### Syntax + +```sql +SELECT_clause FROM_clause WHERE [(AND|OR) [...]] +``` + +The `WHERE` clause supports `conditional_expressions` on fields, tags, and timestamps. + +{{% note %}} +**Note:** InfluxDB does not support using OR in the WHERE clause to specify multiple time ranges. For example, InfluxDB returns an empty response for the following query: + +```sql +SELECT * FROM "mydb" WHERE time = '2020-07-31T20:07:00Z' OR time = '2020-07-31T23:07:17Z'` +``` +{{% /note %}} + +#### Fields + +``` +field_key ['string' | boolean | float | integer] +``` + +The `WHERE` clause supports comparisons against string, boolean, float, and integer [field values](/influxdb/v2.4/reference/glossary/#field-value). + +Single quote string field values in the `WHERE` clause. +Queries with unquoted string field values or double quoted string field values will not return any data and, in most cases, +[will not return an error](#common-issues-with-the-where-clause). + +#### Supported operators + +| Operator | Meaning | +|:--------:|:-------- | +| `=` | equal to | +| `<>` | not equal to | +| `!=` | not equal to | +| `>` | greater than | +| `>=` | greater than or equal to | +| `<` | less than | +| `<=` | less than or equal to | + +InfluxQL also supports [Regular Expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +#### Tags + +```sql +tag_key ['tag_value'] +``` + +Single quote [tag values](/influxdb/v2.4/reference/glossary/#tag-value) in +the `WHERE` clause. +Queries with unquoted tag values or double quoted tag values will not return +any data and, in most cases, +[will not return an error](#common-issues-with-the-where-clause). + +#### Supported operators + +| Operator | Meaning | +|:--------:|:------- | +| `=` | equal to | +| `<>` | not equal to | +| `!=` | not equal to | + +#### Timestamps + +For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v2.4/reference/faq/#what-are-the-minimum-and-maximum-integers-that-influxdb-can-store). +For `SELECT` statements with a [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/), the default time +range is between `1677-09-21 00:12:43.145224194` UTC and [`now()`](/influxdb/v2.4/reference/glossary/#now). + +See [Time Syntax](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) for information on how to specify alternative time ranges in the `WHERE` clause. + +### Examples + +{{< expand-wrapper >}} +{{% expand "Select data with specific field key-values" %}} + + +```sql +SELECT * FROM "h2o_feet" WHERE "water_level" > 9 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- | :-------------------| :------------------| -------: | +| 2019-08-25T04:00:00Z | at or greater than 9 feet | coyote_creek | 9.0320000000| +| 2019-08-25T04:06:00Z | at or greater than 9 feet | coyote_creek | 9.0780000000| +| 2019-08-25T04:12:00Z | at or greater than 9 feet | coyote_creek | 9.1110000000| +| 2019-08-25T04:18:00Z | at or greater than 9 feet | coyote_creek | 9.1500000000| +| 2019-08-25T04:24:00Z | at or greater than 9 feet | coyote_creek | 9.1800000000| + +The query returns data from the `h2o_feet` measurement with field values of `water_level` that are greater than nine. +This is a partial data set. + +{{% /expand %}} + +{{% expand "Select data with a specific string field key-value" %}} + +```sql +SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- | :-------------------| :------------------| :------------------ | +| 2019-08-17T00:00:00Z | below 3 feet | santa_monica | 2.0640000000| +| 2019-08-17T00:06:00Z | below 3 feet | santa_monica | 2.1160000000| +| 2019-08-17T00:12:00Z | below 3 feet | santa_monica | 2.0280000000| +| 2019-08-17T00:18:00Z | below 3 feet | santa_monica | 2.1260000000| +| 2019-08-17T00:24:00Z | below 3 feet | santa_monica | 2.0410000000| +| 2019-08-17T00:30:00Z | below 3 feet | santa_monica | 2.0510000000| + +The query returns data from the `h2o_feet` measurement with field values of `level description` that equal the `below 3 feet` string. InfluxQL requires single quotes around string field values in the `WHERE` clause. + +{{% /expand %}} + +{{% expand "Select data with a specific field key-value and perform basic arithmetic" %}} + +```sql +SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level description | location | water_level | +| :-------------- | :-------------------| :------------------|---------------: | +| 2019-08-28T07:06:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000| +| 2019-08-28T07:12:00Z | at or greater than 9 feet | coyote_creek | 9.9380000000| +| 2019-08-28T07:18:00Z | at or greater than 9 feet | coyote_creek | 9.9570000000| +| 2019-08-28T07:24:00Z | at or greater than 9 feet | coyote_creek | 9.9640000000| +| 2019-08-28T07:30:00Z | at or greater than 9 feet | coyote_creek | 9.9540000000| +| 2019-08-28T07:36:00Z | at or greater than 9 feet | coyote_creek | 9.9410000000| +| 2019-08-28T07:42:00Z | at or greater than 9 feet | coyote_creek | 9.9250000000| +| 2019-08-28T07:48:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000| +| 2019-09-01T23:30:00Z | at or greater than 9 feet | coyote_creek | 9.9020000000| + +The query returns data from the `h2o_feet` measurement with field values of +`water_level` plus two that are greater than 11.9. Note that InfluxDB follows the standard order of operations. + +See [Mathematical operators](/influxdb/v2.4/query-data/influxql/math-operators/) +for more on supported operators. + +{{% /expand %}} + +{{% expand "Select data with a specific tag key-value" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :-------------- | -------------------:| +| 2019-08-17T00:00:00Z | 2.0640000000| +| 2019-08-17T00:06:00Z | 2.1160000000| +| 2019-08-17T00:12:00Z | 2.0280000000| +| 2019-08-17T00:18:00Z | 2.1260000000| +| 2019-08-17T00:24:00Z | 2.0410000000| + + + +The query returns data from the `h2o_feet` measurement where the +[tag key](/influxdb/v2.4/reference/glossary/#tag-key) `location` is set to `santa_monica`. +InfluxQL requires single quotes around tag values in the `WHERE` clause. + +{{% /expand %}} + +{{% expand "Select data with specific field key-values and tag key-valuest" %}} + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-28T07:18:00Z | 9.9570000000| +| 2019-08-28T07:24:00Z | 9.9640000000| +| 2019-08-28T07:30:00Z | 9.9540000000| +| 2019-08-28T14:30:00Z | -0.6100000000| +| 2019-08-28T14:36:00Z | -0.5910000000| +| 2019-08-29T15:18:00Z | -0.5940000000| + +The query returns data from the `h2o_feet` measurement where the tag key +`location` is not set to `santa_monica` and where the field values of +`water_level` are either less than -0.59 or greater than 9.95. +The `WHERE` clause supports the operators `AND` and `OR`, and supports +separating logic with parentheses. + +{{% /expand %}} + + +{{< /expand-wrapper >}} + +```sql +SELECT * FROM "h2o_feet" WHERE time > now() - 7d +``` + +The query returns data from the `h2o_feet` measurement with [timestamps](/influxdb/v2.4/reference/glossary/#timestamp) +within the past seven days. See [Time Syntax](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) for more in-depth information on supported time syntax in the `WHERE` clause. + +### Common issues with the `WHERE` clause + +#### A `WHERE` clause query unexpectedly returns no data + +In most cases, this issue is the result of missing single quotes around +tag values or string field values. +Queries with unquoted or double quoted tag values or string field values will +not return any data and, in most cases, will not return an error. + +The first two queries in the code block below attempt to specify the tag value +`santa_monica` without any quotes and with double quotes. +Those queries return no results. +The third query single quotes `santa_monica` (this is the supported syntax) +and returns the expected results. + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica +No results + +SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" +No results + +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' +``` +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-17T00:00:00Z | 2.0640000000 | +| 2019-08-17T00:06:00Z | 2.1160000000 | +| 2019-08-17T00:12:00Z | 2.0280000000 | +| 2019-08-17T00:18:00Z | 2.1260000000 | +| 2019-08-17T00:24:00Z | 2.0410000000 | +| 2019-08-17T00:30:00Z | 2.0510000000 | + +The first two queries in the code block below attempt to specify the string +field value `at or greater than 9 feet` without any quotes and with double +quotes. +The first query returns an error because the string field value includes +white spaces. +The second query returns no results. +The third query single quotes `at or greater than 9 feet` (this is the +supported syntax) and returns the expected results. + +```sql +SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet +ERR: 400 Bad Request: failed to parse query: found than, expected ; at line 1, char 86 + +SELECT "level description" FROM "h2o_feet" WHERE "level description" = "at or greater than 9 feet" +No results + +SELECT "level description" FROM "h2o_feet" WHERE "level description" = 'at or greater than 9 feet' +``` + +Output: +{{% influxql/table-meta %}} +Name: h2o_feet +{{% /influxql/table-meta %}} + +| time | level_description | +| :---------------------------| ------: | +| 2019-08-25T04:00:00Z | at or greater than 9 feet | +| 2019-08-25T04:06:00Z | at or greater than 9 feet | +| 019-08-25T04:12:00Z | at or greater than 9 feet | +| 2019-08-25T04:18:00Z | at or greater than 9 feet | +| 2019-08-25T04:24:00Z | at or greater than 9 feet | \ No newline at end of file diff --git a/content/influxdb/v2.4/query-data/influxql/explore-schema.md b/content/influxdb/v2.4/query-data/influxql/explore-schema.md new file mode 100644 index 0000000000..768bd092a2 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/explore-schema.md @@ -0,0 +1,592 @@ +--- +title: Explore your schema using InfluxQL +description: > + Learn to use InfluxQL to explore the schema of your time series data. +menu: + influxdb_2_4: + name: Explore your schema + parent: Query with InfluxQL + identifier: explore-schema-influxql +weight: 202 +--- + +Use InfluxQL to explore the schema of your time series data. +Use the following InfluxQL commands to explore your schema: + +- [SHOW SERIES](#show-series) +- [SHOW MEASUREMENTS](#show-measurements) +- [SHOW TAG KEYS](#show-tag-keys) +- [SHOW TAG VALUES](#show-tag-values) +- [SHOW FIELD KEYS](#show-field-keys) +- [SHOW FIELD KEY CARDINALITY](#show-field-key-cardinality) +- [SHOW TAG KEY CARDINALITY](#show-tag-key-cardinality) + +{{% note %}} +Command examples use the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data). +{{% /note %}} + +## SHOW SERIES + +Return a list of [series](/influxdb/v2.4/reference/glossary/#series) for +the specified [database](/influxdb/v2.4/reference/glossary/#database). + +### Syntax + +```sql +SHOW SERIES [ON ] [FROM_clause] [WHERE [ '' | ]] [LIMIT_clause] [OFFSET_clause] +``` + +- `ON ` is optional. + If the query does not include `ON `, you must specify the + database with the `db` query string parameter in the + [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) request. +- `FROM`, `WHERE`, `LIMIT`, and `OFFSET` clauses are optional. +- The `WHERE` clause in `SHOW SERIES` supports tag comparisons but not field comparisons. + + **Supported operators in the `WHERE` clause**: + + - `=`: equal to + - `<>`: not equal to + - `!=`: not equal to + - `=~`: matches against + - `!~`: doesn't match against + +See [Explore data using InfluxQL](/influxdb/v2.4/query-data/influxql/explore-data/) for documentation on the +[`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause), +[`LIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/), +[`OFFSET` clause](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/), +and [Regular Expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +### Examples + +#### Run SHOW SERIES with the ON clause + +```sql +SHOW SERIES ON noaa +``` + +**Output:** + +The query returns all series in the `noaa` database. +The query's output is similar to the [line protocol](/influxdb/v2.4/reference/syntax/line-protocol/) format. +Everything before the first comma is the [measurement](/influxdb/v2.4/reference/glossary/#measurement) name. +Everything after the first comma is either a [tag key](/influxdb/v2.4/reference/glossary/#tag-key) or a [tag value](/influxdb/v2.4/reference/glossary/#tag-value). +The `noaa` database has 5 different measurements and 13 different series. + +| key | +| :------------------------------------------ | +| average_temperature,location=coyote_creek | +| average_temperature,location=santa_monica | +| h2o_feet,location=coyote_creek | +| h2o_feet,location=santa_monica | +| h2o_pH,location=coyote_creek | +| h2o_pH,location=santa_monica | +| h2o_quality,location=coyote_creek,randtag=1 | +| h2o_quality,location=coyote_creek,randtag=2 | +| h2o_quality,location=coyote_creek,randtag=3 | +| h2o_quality,location=santa_monica,randtag=1 | +| h2o_quality,location=santa_monica,randtag=2 | +| h2o_quality,location=santa_monica,randtag=3 | +| h2o_temperature,location=coyote_creek | + +#### Run SHOW SERIES with several clauses + +```sql +SHOW SERIES ON noaa FROM "h2o_quality" WHERE "location" = 'coyote_creek' LIMIT 2 +``` + +**Output:** + +The query returns all series in the `noaa` database that are +associated with the `h2o_quality` measurement and the tag `location = coyote_creek`. +The `LIMIT` clause limits the number of series returned to two. + +| key | +| :------------------------------------------ | +|h2o_quality,location=coyote_creek,randtag=1 | +|h2o_quality,location=coyote_creek,randtag=2 | + +## SHOW MEASUREMENTS + +Returns a list of [measurements](/influxdb/v2.4/reference/glossary/#measurement) +for the specified [database](/influxdb/v2.4/reference/glossary/#database). + +### Syntax + +```sql +SHOW MEASUREMENTS [ON ] [WITH MEASUREMENT ['' | ]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] +``` + +- `ON ` is optional. + If the query does not include `ON `, you must specify the + database with the `db` query string parameter in the + [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) request. + +- The `WITH`, `WHERE`, `LIMIT` and `OFFSET` clauses are optional. +- The `WHERE` in `SHOW MEASURMENTS` supports tag comparisons, but not field comparisons. + + **Supported operators in the `WHERE` clause:** + + - `=` : equal to + - `<>`: not equal to + - `!=`: not equal to + - `=~`: matches against + - `!~`: doesn't match against + +See [Explore data using InfluxQL](/influxdb/v2.4/query-data/influxql/explore-data/) for documentation on the +[`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause), +[`LIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/), +[`OFFSET` clause](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/), +and [Regular Expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +### Examples + +#### Run SHOW MEASUREMENTS with the ON clause + +```sql +SHOW MEASUREMENTS ON noaa +``` + +**Output:** + +The query returns the list of measurements in the `noaa` database. +The database has five measurements: `average_temperature`, `h2o_feet`, `h2o_pH`, +`h2o_quality`, and `h2o_temperature`. + +| name | +| :------------------ | +| average_temperature | +| h2o_feet | +| h2o_pH | +| h2o_quality | +| h2o_temperature | + + +#### Run SHOW MEASUREMENTS with several clauses (i) + +```sql +SHOW MEASUREMENTS ON noaa WITH MEASUREMENT =~ /h2o.*/ LIMIT 2 OFFSET 1 +``` + +**Output:** + +The query returns the measurements in the `noaa` database that start with `h2o`. +The `LIMIT` and `OFFSET` clauses limit the number of measurement names returned to +two and offset the results by one, skipping the `h2o_feet` measurement. + +| name | +| :---------- | +| h2o_pH | +| h2o_quality | + +#### Run SHOW MEASUREMENTS with several clauses (ii) + +```sql +SHOW MEASUREMENTS ON noaa WITH MEASUREMENT =~ /h2o.*/ WHERE "randtag" =~ /\d/ +``` + +The query returns all measurements in the `noaa` that start with `h2o` and have +values for the tag key `randtag` that include an integer. + +| name | +| :---------- | +| h2o_quality | + +## SHOW TAG KEYS + +Returns a list of [tag keys](/influxdb/v2.4/reference/glossary/#tag-key) +associated with the specified [database](/influxdb/v2.4/reference/glossary/#database). + +### Syntax + +```sql +SHOW TAG KEYS [ON ] [FROM_clause] WITH KEY [ [ "" | ] | [IN ("","")]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] +``` + +- `ON ` is optional. + If the query does not include `ON `, you must specify the + database with `db` query string parameter in the [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) request. +- The `FROM` clause and the `WHERE` clause are optional. +- The `WHERE` clause in `SHOW TAG KEYS` supports tag comparisons, but not field comparisons. + + **Supported operators in the `WHERE` clause:** + + - `=` : equal to + - `<>`: not equal to + - `!=`: not equal to + - `=~`: matches against + - `!~`: doesn't match against + +See [Explore data using InfluxQL](/influxdb/v2.4/query-data/influxql/explore-data/) for documentation on the +[`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause), +[`LIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/), +[`OFFSET` clause](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/), +and [Regular Expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +### Examples + +#### Run SHOW TAG KEYS with the ON clause + +```sql +SHOW TAG KEYS ON noaa +``` + +**Output:** + +The query returns the list of tag keys in the `noaa` database. +The output groups tag keys by measurement name; +it shows that every measurement has the `location` tag key and that the +`h2o_quality` measurement has an additional `randtag` tag key. + +| name | tagKey | +| :------------------ | :------- | +| average_temperature | location | +| h2o_feet | location | +| h2o_pH | location | +| h2o_quality | location | +| h2o_quality | randtag | +| h2o_temperature | location | + + +#### Run SHOW TAG KEYS with several clauses + +```sql +SHOW TAG KEYS ON noaa FROM "h2o_quality" LIMIT 1 OFFSET 1 +``` + +**Output:** + +The query returns tag keys from the `h2o_quality` measurement in the `noaa` database. +The `LIMIT` and `OFFSET` clauses limit the number of tag keys returned to one +and offsets the results by one. + +| name | tagKey | +| :---------- | :------ | +| h2o_quality | randtag | + +#### Run SHOW TAG KEYS with a WITH KEY IN clause + +```sql +SHOW TAG KEYS ON noaa WITH KEY IN ("location") +``` + +**Output:** + +| measurement | tagKey | +| :------------------ | :------- | +| average_temperature | location | +| h2o_feet | location | +| h2o_pH | location | +| h2o_quality | location | +| h2o_quality | randtag | +| h2o_temperature | location | + + +## SHOW TAG VALUES + +Returns the list of [tag values](/influxdb/v2.4/reference/glossary/#tag-value) +for the specified [tag key(s)](/influxdb/v2.4/reference/glossary/#tag-key) in the database. + +### Syntax + +```sql +SHOW TAG VALUES [ON ][FROM_clause] WITH KEY [ [ "" | ] | [IN ("","")]] [WHERE ['' | ]] [LIMIT_clause] [OFFSET_clause] +``` + +- `ON ` is optional. + If the query does not include `ON `, you must specify the + database with the `db` query string parameter in the [InfluxDB API](/influxdb/v2.4/reference/api/influxdb-1x/) request. +- The `WITH` clause is required. + It supports specifying a single tag key, a regular expression, and multiple tag keys. +- The `FROM`, `WHERE`, `LIMIT`, and `OFFSET` clauses are optional. +- The `WHERE` clause in `SHOW TAG KEYS` supports tag comparisons, but not field comparisons. + + **Supported operators in the `WITH` and `WHERE` clauses:** + + - `=` : equal to + - `<>`: not equal to + - `!=`: not equal to + - `=~`: matches against + - `!~`: doesn't match against + +See [Explore data using InfluxQL](/influxdb/v2.4/query-data/influxql/explore-data/) for documentation on the +[`FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause), +[`LIMIT` clause](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/), +[`OFFSET` clause](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/), +and [Regular Expressions](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +### Examples + +#### Run SHOW TAG VALUES with the ON clause + +```sql +SHOW TAG VALUES ON noaa WITH KEY = "randtag" +``` + +**Output:** + +The query returns all tag values of the `randtag` tag key in the `noaa` database. +`SHOW TAG VALUES` groups query results by measurement name. + +{{% influxql/table-meta %}} +name: h2o_quality +{{% /influxql/table-meta %}} + +| key | value | +| :------ | ----: | +| randtag | 1 | +| randtag | 2 | +| randtag | 3 | + +#### Run a `SHOW TAG VALUES` query with several clauses + +```sql +SHOW TAG VALUES ON noaa WITH KEY IN ("location","randtag") WHERE "randtag" =~ /./ LIMIT 3 +``` + +**Output:** + +The query returns the tag values of the tag keys `location` and `randtag` for +all measurements in the `noaa` database where `randtag` has tag values. +The `LIMIT` clause limits the number of tag values returned to three. + +{{% influxql/table-meta %}} +name: h2o_quality +{{% /influxql/table-meta %}} + +| key | value | +| :------- | -----------: | +| location | coyote_creek | +| location | santa_monica | +| randtag | 1 | + +## SHOW FIELD KEYS + +Returns the [field keys](/influxdb/v2.4/reference/glossary/#field-key) and the +[data type](/influxdb/v2.4/reference/glossary/#data-type) of their +[field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SHOW FIELD KEYS [ON ] [FROM ] +``` + +- `ON ` is optional. + If the query does not include `ON `, you must specify the + database with `USE ` when using the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/) + or with the `db` query string parameter in the + [InfluxDB 1.x compatibility API](/influxdb/v2.4/reference/api/influxdb-1x/) request. +- The `FROM` clause is optional. + See the Data Exploration page for documentation on the +[` FROM` clause](/influxdb/v2.4/query-data/influxql/explore-data/select/#from-clause). + +{{% note %}} +**Note:** A field's data type [can differ](/influxdb/v2.4/reference/faq/#how-does-influxdb-handle-field-type-discrepancies-across-shards) across +[shards](/influxdb/v2.4/reference/glossary/#shard). +If your field has more than one type, `SHOW FIELD KEYS` returns the type that +occurs first in the following list: float, integer, string, boolean. +{{% /note %}} + +### Examples + +#### Run SHOW FIELD KEYS with the ON clause + +```sql +SHOW FIELD KEYS ON noaa +``` + +**Output:** + +The query returns the field keys and field value data types for each +measurement in the `noaa` database. + +| name | fieldKey | fieldType | +| :------------------ | :---------------- | :-------- | +| average_temperature | degrees | float | +| h2o_feet | level description | string | +| h2o_feet | water_level | float | +| h2o_pH | pH | float | +| h2o_quality | index | float | +| hh2o_temperature | degrees | float | + +#### Run SHOW FIELD KEYS with the FROM clause + +```sql +SHOW FIELD KEYS ON noaa FROM h2o_feet +``` + +**Output:** + +The query returns the fields keys and field value data types for the `h2o_feet` +measurement in the `noaa` database. + +| name | fieldKey | fieldType | +| :------- | :---------------- | :-------- | +| h2o_feet | level description | string | +| h2o_feet | water_level | float | + +### Common Issues with SHOW FIELD KEYS + +#### SHOW FIELD KEYS and field type discrepancies + +Field value [data types](/influxdb/v2.4/reference/glossary/#data-type) +cannot differ within a [shard](/influxdb/v2.4/reference/glossary/#shard) but they +can differ across shards. +`SHOW FIELD KEYS` returns every data type, across every shard, associated with +the field key. + +##### Example + +The `all_the_types` field stores four different data types: + +```sql +SHOW FIELD KEYS +``` + +{{% influxql/table-meta %}} +name: mymeas +{{% /influxql/table-meta %}} + +| fieldKey | fieldType | +| :------------ | :-------- | +| all_the_types | integer | +| all_the_types | float | +| all_the_types | string | +| all_the_types | boolean | + +Note that `SHOW FIELD KEYS` handles field type discrepancies differently from +`SELECT` statements. +For more information, see the +[How does InfluxDB handle field type discrepancies across shards?](/enterprise_influxdb/v1.9/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-field-type-discrepancies-across-shards). + +## SHOW FIELD KEY CARDINALITY + +Cardinality is the product of all unique databases, retention policies, measurements, field keys and tag values in your Influx instance. Managing cardinality is important, as high cardinality leads to greater resource usage. + +```sql +-- show estimated cardinality of the field key set of current database +SHOW FIELD KEY CARDINALITY +-- show exact cardinality on field key set of specified database +SHOW FIELD KEY EXACT CARDINALITY ON noaa +``` + +## SHOW TAG KEY CARDINALITY + +```sql +-- show estimated tag key cardinality +SHOW TAG KEY CARDINALITY +-- show exact tag key cardinality +SHOW TAG KEY EXACT CARDINALITY +``` + + + + diff --git a/content/influxdb/v2.4/query-data/influxql/functions/_index.md b/content/influxdb/v2.4/query-data/influxql/functions/_index.md new file mode 100644 index 0000000000..6f9ff4069b --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/functions/_index.md @@ -0,0 +1,75 @@ +--- +title: View InfluxQL functions +description: > + Aggregate, select, transform, and predict data with InfluxQL functions. +menu: + influxdb_2_4: + name: InfluxQL functions + parent: Query with InfluxQL +weight: 203 +--- + +Use InfluxQL functions to aggregate, select, transform, analyze, and predict data. + +{{% note %}} +To query with InfluxQL, the bucket you query must be mapped to a database and retention policy (DBRP). For more information, see how to [Query data with InfluxQL](/influxdb/v2.4/query-data/influxql/). +{{%/ note %}} + +## InfluxQL functions (by type) + +- [Aggregates](/influxdb/v2.4/query-data/influxql/functions/aggregates/) + - [COUNT()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count) + - [DISTINCT()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#distinct) + - [INTEGRAL()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#integral) + - [MEAN()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) + - [MEDIAN()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median) + - [MODE()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode) + - [SPREAD()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#spread) + - [STDDEV()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#stddev) + - [SUM()](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum) +- [Selectors](/influxdb/v2.4/query-data/influxql/functions/selectors/) + - [BOTTOM()](/influxdb/v2.4/query-data/influxql/functions/selectors/#bottom) + - [FIRST()](/influxdb/v2.4/query-data/influxql/functions/selectors/#first) + - [LAST()](/influxdb/v2.4/query-data/influxql/functions/selectors/#last) + - [MAX()](/influxdb/v2.4/query-data/influxql/functions/selectors/#max) + - [MIN()](/influxdb/v2.4/query-data/influxql/functions/selectors/#min) + - [PERCENTILE()](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile) + - [SAMPLE()](/influxdb/v2.4/query-data/influxql/functions/selectors/#sample) + - [TOP()](/influxdb/v2.4/query-data/influxql/functions/selectors/#top) +- [Transformations](/influxdb/v2.4/query-data/influxql/functions/transformations/) + - [ABS()](/influxdb/v2.4/query-data/influxql/functions/transformations/#abs) + - [ACOS()](/influxdb/v2.4/query-data/influxql/functions/transformations/#acos) + - [ASIN()](/influxdb/v2.4/query-data/influxql/functions/transformations/#asin) + - [ATAN()](/influxdb/v2.4/query-data/influxql/functions/transformations/#atan) + - [ATAN2()](/influxdb/v2.4/query-data/influxql/functions/transformations/#atan2) + - [CEIL()](/influxdb/v2.4/query-data/influxql/functions/transformations/#ceil) + - [COS()](/influxdb/v2.4/query-data/influxql/functions/transformations/#cos) + - [CUMULATIVE_SUM()](/influxdb/v2.4/query-data/influxql/functions/transformations/#cumulative_sum) + - [DERIVATIVE()](/influxdb/v2.4/query-data/influxql/functions/transformations/#derivative) + - [DIFFERENCE()](/influxdb/v2.4/query-data/influxql/functions/transformations/#difference) + - [ELAPSED()](/influxdb/v2.4/query-data/influxql/functions/transformations/#elapsed) + - [EXP()](/influxdb/v2.4/query-data/influxql/functions/transformations/#exp) + - [FLOOR()](/influxdb/v2.4/query-data/influxql/functions/transformations/#floor) + - [HISTOGRAM()](/influxdb/v2.4/query-data/influxql/functions/transformations/#histogram) + - [LN()](/influxdb/v2.4/query-data/influxql/functions/transformations/#ln) + - [LOG()](/influxdb/v2.4/query-data/influxql/functions/transformations/#log) + - [LOG2()](/influxdb/v2.4/query-data/influxql/functions/transformations/#log2) + - [LOG10()](/influxdb/v2.4/query-data/influxql/functions/transformations/#log10) + - [MOVING_AVERAGE()](/influxdb/v2.4/query-data/influxql/functions/transformations/#moving_average) + - [NON_NEGATIVE_DERIVATIVE()](/influxdb/v2.4/query-data/influxql/functions/transformations/#non_negative_derivative) + - [NON_NEGATIVE_DIFFERENCE()](/influxdb/v2.4/query-data/influxql/functions/transformations/#non_negative_difference) + - [POW()](/influxdb/v2.4/query-data/influxql/functions/transformations/#pow) + - [ROUND()](/influxdb/v2.4/query-data/influxql/functions/transformations/#round) + - [SIN()](/influxdb/v2.4/query-data/influxql/functions/transformations/#sin) + - [SQRT()](/influxdb/v2.4/query-data/influxql/functions/transformations/#sqrt) + - [TAN()](/influxdb/v2.4/query-data/influxql/functions/transformations/#tan) +- [Technical analysis](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/) + - (Predictive analysis) [HOLT_WINTERS()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#holt_winters) + - [CHANDE_MOMENTUM_OSCILLATOR()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#chande_momentum_oscillator) + - [EXPONENTIAL_MOVING_AVERAGE()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#exponential_moving_average) + - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#double_exponential_moving_average) + - [KAUFMANS_EFFICIENCY_RATIO()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) + - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#kaufmans_adaptive_moving_average) + - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#triple_exponential_moving_average) + - [TRIPLE_EXPONENTIAL_DERIVATIVE()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#triple_exponential_derivative) + - [RELATIVE_STRENGTH_INDEX()](/influxdb/v2.4/query-data/influxql/functions/technical-analysis/#relative_strength_index) diff --git a/content/influxdb/v2.4/query-data/influxql/functions/aggregates.md b/content/influxdb/v2.4/query-data/influxql/functions/aggregates.md new file mode 100644 index 0000000000..065f2cb9ae --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/functions/aggregates.md @@ -0,0 +1,1025 @@ +--- +title: InfluxQL aggregate functions +list_title: Aggregate functions +description: > + Aggregate data with InfluxQL aggregate functions. +menu: + influxdb_2_4: + name: Aggregates + parent: InfluxQL functions +weight: 205 +--- + +Use aggregate functions to assess, aggregate, and return values in your data. +Aggregate functions return one row containing the aggregate values from each InfluxQL group. + +Each aggregate function below covers **syntax** including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data). + +- [COUNT()](#count) +- [DISTINCT()](#distinct) +- [INTEGRAL()](#integral) +- [MEAN()](#mean) +- [MEDIAN()](#median) +- [MODE()](#mode) +- [SPREAD()](#spread) +- [STDDEV()](#stddev) +- [SUM()](#sum) + +## COUNT() + +Returns the number of non-null [field values](/influxdb/v2.4/reference/glossary/#field-value). Supports all field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +### Syntax + +```sql +SELECT COUNT( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`COUNT(*)` + +Returns the number of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`COUNT(field_key)` + +Returns the number of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`COUNT(/regular_expression/)` + +Returns the number of field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Count values for a field" %}} + +Return the number of non-null field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT COUNT("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | ---------------: | +| 1970-01-01T00:00:00Z | 61026.0000000000 | + +{{% /expand %}} + +{{% expand "Count values for each field in a measurement" %}} + +Return the number of non-null field values for each field key associated with the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT COUNT(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count_level description | count_water_level | +| :------------------- | ----------------------: | ----------------: | +| 1970-01-01T00:00:00Z | 61026.0000000000 | 61026.0000000000 | + +{{% /expand %}} + +{{% expand "Count the values that match a regular expression" %}} + +Return the number of non-null field values for every field key that contains the +word `water` in the `h2o_feet` measurement. + +```sql +SELECT COUNT(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count_water_level | +| :------------------- | ----------------: | +| 1970-01-01T00:00:00Z | 61026.0000000000 | + +{{% /expand %}} + +{{% expand "Count distinct values for a field" %}} + +Return the number of unique field values for the `level description` field key +and the `h2o_feet` measurement. +InfluxQL supports nesting [DISTINCT()](#distinct) in `COUNT()`. + +```sql +SELECT COUNT(DISTINCT("level description")) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | count | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 4.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## DISTINCT() + +Returns the list of unique [field values](/influxdb/v2.4/reference/glossary/#field-value). +Supports all field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +InfluxQL supports nesting `DISTINCT()` with [`COUNT()`](#count). + +### Syntax + +```sql +SELECT DISTINCT( [ | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`DISTINCT(field_key)` + +Returns the unique field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "List the distinct field values associated with a field key" %}} + +Return a tabular list of the unique field values in the `level description` +field key in the `h2o_feet` measurement. + +```sql +SELECT DISTINCT("level description") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | distinct | +| :------------------- | :------------------------ | +| 1970-01-01T00:00:00Z | between 6 and 9 feet | +| 1970-01-01T00:00:00Z | below 3 feet | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | +| 1970-01-01T00:00:00Z | at or greater than 9 feet | + +{{% /expand %}} + + +{{% expand "List the distinct field values associated with each field key in a measurement" %}} + +Return a tabular list of the unique field values for each field key in the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT DISTINCT(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | distinct_level description | distinct_water_level | +| :------------------- | :------------------------- | -------------------: | +| 1970-01-01T00:00:00Z | between 6 and 9 feet | 8.12 | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | 8.005 | +| 1970-01-01T00:00:00Z | at or greater than 9 feet | 7.887 | +| 1970-01-01T00:00:00Z | below 3 feet | 7.762 | + +{{% /expand %}} +--> + +{{< /expand-wrapper >}} + +## INTEGRAL() + +Returns the area under the curve for subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). + +{{% note %}} +`INTEGRAL()` does not support [`fill()`](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill). `INTEGRAL()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). +{{% /note %}} + +### Syntax + +```sql +SELECT INTEGRAL( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +InfluxDB calculates the area under the curve for subsequent field values and converts those results into the summed area per `unit`. +The `unit` argument is an integer followed by an optional [duration literal](/influxdb/v2.4/reference/syntax/spec/#literals). +If the query does not specify the `unit`, the unit defaults to one second (`1s`). + +`INTEGRAL(field_key)` + +Returns the area under the curve for subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`INTEGRAL(/regular_expression/)` + +Returns the area under the curve for subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`INTEGRAL(*)` + +Returns the average field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +The following examples use a subset of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data) data: + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} +{{% expand "Calculate the integral for the field values associated with a field key" %}} + +Return the area under the curve (in seconds) for the field values associated +with the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT INTEGRAL("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | integral | +| :------------------- | --------------: | +| 1970-01-01T00:00:00Z | 4184.8200000000 | + +{{% /expand %}} + +{{% expand "Calculate the integral for the field values associated with a field key and specify the unit option" %}} + +Return the area under the curve (in minutes) for the field values associated +with the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT INTEGRAL("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | integral | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 69.7470000000 | + +{{% /expand %}} + +{{% expand "Calculate the integral for the field values associated with each field key in a measurement and specify the unit option" %}} + +Return the area under the curve (in minutes) for the field values associated +with each field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has on numeric field: `water_level`. + +```sql +SELECT INTEGRAL(*,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | integral_water_level | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | 69.7470000000 | + +{{% /expand %}} + +{{% expand "Calculate the integral for the field values associated with each field key that matches a regular expression and specify the unit option" %}} + +Return the area under the curve (in minutes) for the field values associated +with each field key that stores numeric values includes the word `water` in +the `h2o_feet` measurement. + +```sql +SELECT INTEGRAL(/water/,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | integral_water_level | +| :------------------- | -------------------: | +| 1970-01-01T00:00:00Z | 69.7470000000 | + +{{% /expand %}} + +{{% expand "Calculate the integral for the field values associated with a field key and include several clauses" %}} + +Return the area under the curve (in minutes) for the field values associated +with the `water_level` field key and in the `h2o_feet` measurement in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) between +`2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z`, [grouped](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 12-minute intervals, and +[limit](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of results returned to one. + +```sql +SELECT INTEGRAL("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) LIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | integral | +| :------------------- | -------------: | +| 2019-08-18T00:00:00Z | 28.3590000000 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MEAN() + +Returns the arithmetic mean (average) of [field values](/influxdb/v2.4/reference/glossary/#field-value). `MEAN()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +### Syntax + +```sql +SELECT MEAN( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MEAN(field_key)` +Returns the average field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MEAN(/regular_expression/) + +Returns the average field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`MEAN(*)` +Returns the average field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the mean field value associated with a field key" %}} + +Return the average field value in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 4.4418674882 | + +{{% /expand %}} + +{{% expand "Calculate the mean field value associated with each field key in a measurement" %}} + +Return the average field value for every field key that stores numeric values +in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT MEAN(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean_water_level | +| :------------------- | ---------------: | +| 1970-01-01T00:00:00Z | 4.4418674882 | + +{{% /expand %}} + +{{% expand "Calculate the mean field value associated with each field key that matches a regular expression" %}} + +Return the average field value for each field key that stores numeric values and +includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT MEAN(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mean_water_level | +| :------------------- | ---------------: | +| 1970-01-01T00:00:00Z | 4.4418674882 | + +{{% /expand %}} + +{{% expand "Calculate the mean field value associated with a field key and include several clauses" %}} + +Return the average of the values in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `9.01` and +[limit](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to seven and one. + +```sql +SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 7 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | mean | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.4615000000 | +| 2019-08-18T00:12:00Z | 8.2725000000 | +| 2019-08-18T00:24:00Z | 8.0710000000 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MEDIAN() + +Returns the middle value from a sorted list of [field values](/influxdb/v2.4/reference/glossary/#field-value). `MEDIAN()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +{{% note %}} +**Note:** `MEDIAN()` is nearly equivalent to [`PERCENTILE(field_key, 50)`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile), except `MEDIAN()` returns the average of the two middle field values if the field contains an even number of values. +{{% /note %}} + +### Syntax + +```sql +SELECT MEDIAN( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MEDIAN(field_key)` + +Returns the middle field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MEDIAN(/regular_expression/)` + +Returns the middle field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`MEDIAN(*)` + +Returns the middle field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the median field value associated with a field key" %}} + +Return the middle field value in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT MEDIAN("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | median | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 4.1240000000 | + +{{% /expand %}} + +{{% expand "Calculate the median field value associated with each field key in a measurement" %}} + +Return the middle field value for every field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT MEDIAN(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | median_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 4.1240000000 | + +{{% /expand %}} + +{{% expand "Calculate the median field value associated with each field key that matches a regular expression" %}} + +Return the middle field value for every field key that stores numeric values and +includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT MEDIAN(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | median_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 4.1240000000 | + +{{% /expand %}} + +{{% expand "Calculate the median field value associated with a field key and include several clauses" %}} + +Return the middle field value in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `700 `, [limit](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to seven and one, and [offset](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. + +```sql +SELECT MEDIAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(700) LIMIT 7 SLIMIT 1 SOFFSET 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | median | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3655000000 | +| 2019-08-18T00:12:00Z | 2.3360000000 | +| 2019-08-18T00:24:00Z | 2.2655000000 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## MODE() + +Returns the most frequent value in a list of [field values](/influxdb/v2.4/reference/glossary/#field-value). `MODE()` supports all field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +{{% note %}} +**Note:** `MODE()` returns the field value with the earliest [timestamp](/influxdb/v2.4/reference/glossary/#timestamp) if there's a tie between two or more values for the maximum number of occurrences. +{{% /note %}} + +### Syntax + +```sql +SELECT MODE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MODE(field_key)` + +Returns the most frequent field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MODE(/regular_expression/)` + +Returns the most frequent field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`MODE(*)` + +Returns the most frequent field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the mode field value associated with a field key" %}} + +Return the most frequent field value in the `level description` field key and in +the `h2o_feet` measurement. + +```sql +SELECT MODE("level description") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mode | +| :------------------- | :------------------- | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | + +{{% /expand %}} + +{{% expand "Calculate the mode field value associated with each field key in a measurement" %}} + +Return the most frequent field value for every field key in the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT MODE(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mode_level description | mode_water_level | +| :------------------- | :--------------------- | ---------------: | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | 2.6900000000 | + +{{% /expand %}} + +{{% expand "Calculate the mode field value associated with each field key that matches a regular expression" %}} + +Return the most frequent field value for every field key that includes the word +`/water/` in the `h2o_feet` measurement. + +```sql +SELECT MODE(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | mode_water_level | +| :------------------- | ---------------: | +| 1970-01-01T00:00:00Z | 2.6900000000 | + +{{% /expand %}} + +{{% expand "Calculate the mode field value associated with a field key and include several clauses" %}} + +Return the mode of the values associated with the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [limis](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series retu +ned tothree and one, and it [offsets](/influxdb/v2.4/query-data/influxql/explore-data +#the-offset-and-soffset-clauses) the series returned by one. + +```sql +SELECT MODE("level description") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* LIMIT 3 SLIMIT 1 SOFFSET 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | mode | +| :------------------- | :----------- | +| 2019-08-18T00:00:00Z | below 3 feet | +| 2019-08-18T00:12:00Z | below 3 feet | +| 2019-08-18T00:24:00Z | below 3 feet | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SPREAD() + +Returns the difference between the minimum and maximum [field values](/influxdb/v2.4/reference/glossary/#field-value). `SPREAD()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +### Syntax + +```sql +SELECT SPREAD( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`SPREAD(field_key)` + +Returns the difference between the minimum and maximum field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`SPREAD(/regular_expression/)` + +Returns the difference between the minimum and maximum field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`SPREAD(*)` + +Returns the difference between the minimum and maximum field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the spread for the field values associated with a field key" %}} + +Return the difference between the minimum and maximum field values in the +`water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT SPREAD("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | spread | +| :------------------- | ------------: | +| 1970-01-01T00:00:00Z | 10.5740000000 | + +{{% /expand %}} + +{{% expand "Calculate the spread for the field values associated with each field key in a measurement" %}} + +Return the difference between the minimum and maximum field values for every +field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT SPREAD(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | spread_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 10.5740000000 | + +{{% /expand %}} + +{{% expand "Calculate the spread for the field values associated with each field key that matches a regular expression" %}} + +Return the difference between the minimum and maximum field values for every +field key that stores numeric values and includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT SPREAD(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | spread_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 10.5740000000 | + +{{% /expand %}} + +{{% expand "Calculate the spread for the field values associated with a field key and include several clauses" %}} + +Return the difference between the minimum and maximum field values in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `18`, [lim +ts](/ifluxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to three and one, and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. + +```sql +SELECT SPREAD("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18) LIMIT 3 SLIMIT 1 SOFFSET 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | spread | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.0270000000 | +| 2019-08-18T00:12:00Z | 0.0140000000 | +| 2019-08-18T00:24:00Z | 0.0030000000 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## STDDEV() + +Returns the standard deviation of [field values](/influxdb/v2.4/reference/glossary/#field-value). `STDDEV()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +### Syntax + +```sql +SELECT STDDEV( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`STDDEV(field_key)` + +Returns the standard deviation of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`STDDEV(/regular_expression/)` + +Returns the standard deviation of field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`STDDEV(*)` + +Returns the standard deviation of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the standard deviation for the field values associated with a field key" %}} + +Return the standard deviation of the field values in the `water_level` field key +and in the `h2o_feet` measurement. + +```sql +SELECT STDDEV("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | stddev | +| :------------------- | -----------: | +| 1970-01-01T00:00:00Z | 2.2789744110 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation for the field values associated with each field key in a measurement" %}} + +Return the standard deviation of numeric fields in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT STDDEV(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | stddev_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 2.2789744110 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation for the field values associated with each field key that matches a regular expression" %}} + +Return the standard deviation of numeric fields with `water` in the field key in the `h2o_feet` measurement. + +```sql +SELECT STDDEV(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | stddev_water_level | +| :------------------- | -----------------: | +| 1970-01-01T00:00:00Z | 2.2789744110 | + +{{% /expand %}} + +{{% expand "Calculate the standard deviation for the field values associated with a field key and include several clauses" %}} + +Return the standard deviation of the field values in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `18000`, [limit](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to two and one, and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) the series returned by one. + +```sql +SELECT STDDEV("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18000) LIMIT 2 SLIMIT 1 SOFFSET 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=santa_monica +{{% /influxql/table-meta %}} + +| time | stddev | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.0190918831 | +| 2019-08-18T00:12:00Z | 0.0098994949 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## SUM() + +Returns the sum of [field values](/influxdb/v2.4/reference/glossary/#field-value). `SUM()` supports int64 and float64 field value [data types](/influxdb/v2.4/reference/glossary/#data-type). + +### Syntax + +```sql +SELECT SUM( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`SUM(field_key)` + +Returns the sum of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`SUM(/regular_expression/)` + +Returns the sum of field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/#regular-expressions). + +`SUM(*)` + +Returns the sums of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Calculate the sum of the field values associated with a field key" %}} + +Return the summed total of the field values in the `water_level` field key and +in the `h2o_feet` measurement. + +```sql +SELECT SUM("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ----------------: | +| 1970-01-01T00:00:00Z | 271069.4053333958 | + +{{% /expand %}} + +{{% expand "Calculate the sum of the field values associated with each field key in a measurement" %}} + +Return the summed total of numeric fields in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT SUM(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sum_water_level | +| :------------------- | ----------------: | +| 1970-01-01T00:00:00Z | 271069.4053333958 | + +{{% /expand %}} + +{{% expand "Calculate the sum of the field values associated with each field key that matches a regular expression" %}} + +Return the summed total of numeric fields with `water` in the field key in the `h2o_feet` measurement. + +```sql +SELECT SUM(/water/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sum_water_level | +| :------------------- | ----------------: | +| 1970-01-01T00:00:00Z | 271069.4053333958 | + +{{% /expand %}} + +{{% expand "Calculate the sum of the field values associated with a field key and include several clauses" %}} + +Return the summed total of the field values in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) +results into 12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with 18000, and [limit](/influxdb/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to four and one. + +```sql +SELECT SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m),* fill(18000) LIMIT 4 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | sum | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | 16.9230000000 | +| 2019-08-18T00:12:00Z | 16.5450000000 | +| 2019-08-18T00:24:00Z | 16.1420000000 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/functions/selectors.md b/content/influxdb/v2.4/query-data/influxql/functions/selectors.md new file mode 100644 index 0000000000..6dc37b5db0 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/functions/selectors.md @@ -0,0 +1,1301 @@ +--- +title: InfluxQL selector functions +list_title: Selector functions +description: > + Select data with InfluxQL selector functions. +menu: + influxdb_2_4: + name: Selectors + parent: InfluxQL functions +weight: 205 +--- + +Use selector functions to assess, select, and return values in your data. +Selector functions return one or more rows with the selected values from each InfluxQL group. + +Each selector function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data). + +- [BOTTOM()](#bottom) +- [FIRST()](#first) +- [LAST()](#last) +- [MAX()](#max) +- [MIN()](#min) +- [PERCENTILE()](#percentile) +- [SAMPLE()](#sample) +- [TOP()](#top) + +## BOTTOM() + +Returns the smallest `N` [field values](/influxdb/v2.4/reference/glossary/#field-value). `BOTTOM()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +{{% note %}} +**Note:** `BOTTOM()` returns the field value with the earliest timestamp if there's a tie between two or more values for the smallest value. +{{% /note %}} + +### Syntax + +```sql +SELECT BOTTOM([,], )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`BOTTOM(field_key,N)` +Returns the smallest N field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`BOTTOM(field_key,tag_key,N)` +Returns the smallest field value for N tag values of the [tag key](/influxdb/v2.4/reference/glossary/#tag-key). Add a comma between multiple tag keys: `tag_key,tag_key`. + +`BOTTOM((field_key,N),tag_key,field_key)` +Returns the smallest N field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). Add a comma between multiple tag or field keys: `tag_key,tag_key,field_key,field_key`. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Select the bottom three field values associated with a field key" %}} + +Return the smallest three field values in the `water_level` field key and in the +`h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +```sql +SELECT BOTTOM("water_level",3) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | +| :------------------- | -----: | +| 2019-08-29T14:30:00Z | -0.610 | +| 2019-08-29T14:36:00Z | -0.591 | +| 2019-08-30T15:18:00Z | -0.594 | + +{{% /expand %}} + +{{% expand "Select the bottom field value associated with a field key for two tags" %}} + +Return the smallest field values in the `water_level` field key for two tag +values associated with the `location` tag key. + +```sql +SELECT BOTTOM("water_level","location",2) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | location | +| :------------------- | -----: | :----------- | +| 2019-08-29T10:36:00Z | -0.243 | santa_monica | +| 2019-08-29T14:30:00Z | -0.610 | coyote_creek | + +{{% /expand %}} + +{{% expand "Select the bottom four field values associated with a field key and the relevant tags and fields" %}} + +Return the smallest four field values in the `water_level` field key and the +relevant values of the `location` tag key and the `level description` field key. + +```sql +SELECT BOTTOM("water_level",4),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | location | level description | +| :------------------- | -----: | :----------- | :---------------- | +| 2019-08-29T14:24:00Z | -0.587 | coyote_creek | below 3 feet | +| 2019-08-29T14:30:00Z | -0.610 | coyote_creek | below 3 feet | +| 2019-08-29T14:36:00Z | -0.591 | coyote_creek | below 3 feet | +| 2019-08-30T15:18:00Z | -0.594 | coyote_creek | below 3 feet | + +{{% /expand %}} + +{{% expand "Select the bottom three field values associated with a field key and include several clauses" %}} + +Return the smallest three values in the `water_level` field key for each 24-minute +[interval](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#basic-group-by-time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:54:00Z` with results in +[descending timestamp](/influxdb/v2.4/query-data/influxql/explore-data/order-by/) order. + +```sql +SELECT BOTTOM("water_level",3),"location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) ORDER BY time DESC +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | location | +| :------------------- | -----------: | :----------- | +| 2019-08-18T00:54:00Z | 2.172 | santa_monica | +| 2019-08-18T00:54:00Z | 7.510 | coyote_creek | +| 2019-08-18T00:48:00Z | 2.087 | santa_monica | +| 2019-08-18T00:42:00Z | 2.093 | santa_monica | +| 2019-08-18T00:36:00Z | 2.1261441420 | santa_monica | +| 2019-08-18T00:24:00Z | 2.264 | santa_monica | +| 2019-08-18T00:18:00Z | 2.329 | santa_monica | +| 2019-08-18T00:12:00Z | 2.343 | santa_monica | +| 2019-08-18T00:00:00Z | 2.352 | santa_monica | + +Notice that the [GROUP BY time() clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) +does not override the points’ original timestamps. +See [Issue 1](#bottom-with-a-group-by-time-clause) in the section below for a +more detailed explanation of that behavior. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with BOTTOM() + +#### BOTTOM() with a GROUP BY time() clause + +Queries with `BOTTOM()` and a `GROUP BY time()` clause return the specified +number of points per `GROUP BY time()` interval. +For [most `GROUP BY time()` queries](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals), +the returned timestamps mark the start of the `GROUP BY time()` interval. +`GROUP BY time()` queries with the `BOTTOM()` function behave differently; +they maintain the timestamp of the original data point. + +##### Example + +The query below returns two points per 18-minute +`GROUP BY time()` interval. +Notice that the returned timestamps are the points' original timestamps; they +are not forced to match the start of the `GROUP BY time()` intervals. + +```sql +SELECT BOTTOM("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | +| :------------------- | -----: | +| 2019-08-18T00:00:00Z | 2.064 | +| 2019-08-18T00:12:00Z | 2.028 | +| 2019-08-18T00:24:00Z | 2.041 | +| 2019-08-18T00:30:00Z | 2.051 | + +_Notice that the first two rows contain the smallest values from the first time interval +and the last two rows contains the smallest values for the second time interval._ + +#### BOTTOM() and a tag key with fewer than N tag values + +Queries with the syntax `SELECT BOTTOM(,,)` can return fewer points than expected. +If the tag key has `X` tag values, the query specifies `N` values, and `X` is smaller than `N`, then the query returns `X` points. + +##### Example + +The query below asks for the smallest field values of `water_level` for three tag values of the `location` tag key. +Because the `location` tag key has two tag values (`santa_monica` and `coyote_creek`), the query returns two points instead of three. + +```sql +SELECT BOTTOM("water_level","location",3) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | bottom | location | +| :------------------- | -----: | :----------- | +| 2019-08-29T10:36:00Z | -0.243 | santa_monica | +| 2019-08-29T14:30:00Z | -0.610 | coyote_creek | + +## FIRST() + +Returns the [field value ](/influxdb/v2.4/reference/glossary/#field-value) with the oldest timestamp. + +### Syntax + +```sql +SELECT FIRST()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`FIRST(field_key)` +Returns the oldest field value (determined by timestamp) associated with the field key. + +`FIRST(/regular_expression/)` +Returns the oldest field value (determined by timestamp) associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`FIRST(*)` +Returns the oldest field value (determined by timestamp) associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`FIRST(field_key),tag_key(s),field_key(s)` +Returns the oldest field value (determined by timestamp) associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`FIRST()` supports all field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the first field value associated with a field key" %}} + +Return the oldest field value (determined by timestamp) associated with the +`level description` field key and in the `h2o_feet` measurement. + +```sql +SELECT FIRST("level description") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | first | +| :------------------- | :------------------- | +| 2019-08-17T00:00:00Z | between 6 and 9 feet | + +{{% /expand %}} + +{{% expand "Select the first field value associated with each field key in a measurement" %}} + +Return the oldest field value (determined by timestamp) for each field key in the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT FIRST(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | first_level description | first_water_level | +| :------------------- | :---------------------- | ----------------: | +| 1970-01-01T00:00:00Z | between 6 and 9 feet | 8.120 | + +{{% /expand %}} + +{{% expand "Select the first field value associated with each field key that matches a regular expression" %}} + +Return the oldest field value for each field key that includes the word `level` in the `h2o_feet` measurement. + +```sql +SELECT FIRST(/level/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | first_level description | first_water_level | +| :------------------- | :---------------------- | ----------------: | +| 1970-01-01T00:00:00Z | between 6 and 9 feet | 8.120 | + +{{% /expand %}} + +{{% expand "Select the first value associated with a field key and the relevant tags and fields" %}} + +Return the oldest field value (determined by timestamp) in the `level description` +field key and the relevant values of the `location` tag key and the `water_level` field key. + +```sql +SELECT FIRST("level description"),"location","water_level" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | first | location | water_level | +| :------------------- | :------------------- | :----------- | ----------: | +| 2019-08-17T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.120 | + +{{% /expand %}} + +{{% expand "Select the first field value associated with a field key and include several clauses" %}} + +Returns the oldest field value (determined by timestamp) in the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and +[groups](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) results into +12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `9.01`, and it [limit](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to four and one. + +```sql +SELECT FIRST("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | first | +| :------------------- | ----: | +| 2019-08-17T23:48:00Z | 8.635 | +| 2019-08-18T00:00:00Z | 8.504 | +| 2019-08-18T00:12:00Z | 8.320 | +| 2019-08-18T00:24:00Z | 8.130 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points' original timestamps. +The timestamps in the results indicate the the start of each 12-minute time interval; +the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## LAST() + +Returns the [field value](/influxdb/v2.4/reference/glossary/#field-value) with the most recent timestamp. + +### Syntax + +```sql +SELECT LAST()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`LAST(field_key)` +Returns the newest field value (determined by timestamp) associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`LAST(/regular_expression/)` +Returns the newest field value (determined by timestamp) associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`LAST(*)` +Returns the newest field value (determined by timestamp) associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`LAST(field_key),tag_key(s),field_key(s)` +Returns the newest field value (determined by timestamp) associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`LAST()` supports all field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the last field values associated with a field key" %}} + +Return the newest field value (determined by timestamp) associated with the +`level description` field key and in the `h2o_feet` measurement. + +```sql +SELECT LAST("level description") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | last | +| :------------------- | :------------------- | +| 2019-09-17T21:42:00Z | between 3 and 6 feet | + +{{% /expand %}} + +{{% expand "Select the last field values associated with each field key in a measurement" %}} + +Return the newest field value (determined by timestamp) for each field key in the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT LAST(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | last_level description | last_water_level | +| :------------------- | :--------------------- | ---------------: | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | 4.938 | + +{{% /expand %}} + +{{% expand "Select the last field value associated with each field key that matches a regular expression" %}} + +Return the newest field value for each field key that includes the word `level` +in the `h2o_feet` measurement. + +```sql +SELECT LAST(/level/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | last_level description | last_water_level | +| :------------------- | :--------------------- | ---------------: | +| 1970-01-01T00:00:00Z | between 3 and 6 feet | 4.938 | + +{{% /expand %}} + +{{% expand "Select the last field value associated with a field key and the relevant tags and fields" %}} + +Return the newest field value (determined by timestamp) in the `level description` +field key and the relevant values of the `location` tag key and the `water_level` field key. + +```sql +SELECT LAST("level description"),"location","water_level" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | last | location | water_level | +| :------------------- | :------------------- | :----------- | ----------: | +| 2019-09-17T21:42:00Z | between 3 and 6 feet | santa_monica | 4.938 | + +{{% /expand %}} + +{{% expand "Select the last field value associated with a field key and include several clauses" %}} + +Return the newest field value (determined by timestamp) in the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and +[groups](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) results into +12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `9.01`, and it [limit](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to four and one. + +```sql +SELECT LAST("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | last | +| :------------------- | ----: | +| 2019-08-17T23:48:00Z | 8.570 | +| 2019-08-18T00:00:00Z | 8.419 | +| 2019-08-18T00:12:00Z | 8.225 | +| 2019-08-18T00:24:00Z | 8.012 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points' original timestamps. +The timestamps in the results indicate the the start of each 12-minute time interval; +the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## MAX() + +Returns the greatest [field value](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SELECT MAX()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MAX(field_key)` +Returns the greatest field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MAX(/regular_expression/)` +Returns the greatest field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`MAX(*)` +Returns the greatest field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`MAX(field_key),tag_key(s),field_key(s)` +Returns the greatest field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`MAX()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the maximum field value associated with a field key" %}} + +Return the greatest field value in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT MAX("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ----: | +| 2019-08-28T07:24:00Z | 9.964 | + +{{% /expand %}} + +{{% expand "Select the maximum field value associated with each field key in a measurement" %}} + +Return the greatest field value for each field key that stores numeric values +in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT MAX(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max_water_level | +| :------------------- | --------------: | +| 2019-08-28T07:24:00Z | 9.964 | + +{{% /expand %}} + +{{% expand "Select the maximum field value associated with each field key that matches a regular expression" %}} + +Return the greatest field value for each field key that stores numeric values +and includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT MAX(/level/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max_water_level | +| :------------------- | --------------: | +| 2019-08-28T07:24:00Z | 9.964 | + +{{% /expand %}} + +{{% expand "Select the maximum field value associated with a field key and the relevant tags and fields" %}} + +Return the greatest field value in the `water_level` field key and the relevant +values of the `location` tag key and the `level description` field key. + +```sql +SELECT MAX("water_level"),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | max | location | level description | +| :------------------- | ----: | :----------- | :------------------------ | +| 2019-08-28T07:24:00Z | 9.964 | coyote_creek | at or greater than 9 feet | + +{{% /expand %}} + +{{% expand "Select the maximum field value associated with a field key and include several clauses" %}} + +Return the greatest field value in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and +[groups](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) results into +12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `9.01`, and it [limit](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to four and one. + +```sql +SELECT MAX("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | max | +| :------------------- | ----: | +| 2019-08-17T23:48:00Z | 8.635 | +| 2019-08-18T00:00:00Z | 8.504 | +| 2019-08-18T00:12:00Z | 8.320 | +| 2019-08-18T00:24:00Z | 8.130 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. +The timestamps in the results indicate the the start of each 12-minute time interval; +the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## MIN() + +Returns the lowest [field value](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SELECT MIN()[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MIN(field_key)` +Returns the lowest field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MIN(/regular_expression/)` +Returns the lowest field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`MIN(*)` +Returns the lowest field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`MIN(field_key),tag_key(s),field_key(s)` +Returns the lowest field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`MIN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the minimum field value associated with a field key" %}} + +Return the lowest field value in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT MIN("water_level") FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | min | +| :------------------- | -----: | +| 2019-08-28T14:30:00Z | -0.610 | + +{{% /expand %}} + +{{% expand "Select the minimum field value associated with each field key in a measurement" %}} + +Return the lowest field value for each field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT MIN(*) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | min_water_level | +| :------------------- | --------------: | +| 2019-08-28T14:30:00Z | -0.610 | + +{{% /expand %}} + +{{% expand "Select the minimum field value associated with each field key that matches a regular expression" %}} + +Return the lowest field value for each numeric field with `water` in the field +key in the `h2o_feet` measurement. + +```sql +SELECT MIN(/level/) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | min_water_level | +| :------------------- | --------------: | +| 2019-08-28T14:30:00Z | -0.610 | + +{{% /expand %}} + +{{% expand "Select the minimum field value associated with a field key and the relevant tags and fields" %}} + +Return the lowest field value in the `water_level` field key and the relevant +values of the `location` tag key and the `level description` field key. + +```sql +SELECT MIN("water_level"),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | min | location | level description | +| :------------------- | -----: | :----------- | :---------------- | +| 2019-08-28T14:30:00Z | -0.610 | coyote_creek | below 3 feet | + +{{% /expand %}} + +{{% expand "Select the minimum field value associated with a field key and include several clauses" %}} + +Return the lowest field value in the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and +[groups](/influxdb/v2.4/query-data/influxql/explore-data/group-by/) results into +12-minute time intervals and per tag. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `9.01`, and it [limit](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points and series returned to four and one. + +```sql +SELECT MIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m),* fill(9.01) LIMIT 4 SLIMIT 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +tags: location=coyote_creek +{{% /influxql/table-meta %}} + +| time | min | +| :------------------- | ----: | +| 2019-08-17T23:48:00Z | 8.570 | +| 2019-08-18T00:00:00Z | 8.419 | +| 2019-08-18T00:12:00Z | 8.225 | +| 2019-08-18T00:24:00Z | 8.012 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. +The timestamps in the results indicate the the start of each 12-minute time interval; +the first point in the results covers the time interval between `2019-08-17T23:48:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:24:00Z` and just before `2019-08-18T00:36:00Z`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## PERCENTILE() + +Returns the `N`th percentile [field value](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SELECT PERCENTILE(, )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`PERCENTILE(field_key,N)` +Returns the Nth percentile field value associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`PERCENTILE(/regular_expression/,N)` +Returns the Nth percentile field value associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`PERCENTILE(*,N)` +Returns the Nth percentile field value associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`PERCENTILE(field_key,N),tag_key(s),field_key(s)` +Returns the Nth percentile field value associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`N` must be an integer or floating point number between `0` and `100`, inclusive. +`PERCENTILE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the fifth percentile field value associated with a field key" %}} + +Return the field value that is larger than five percent of the field values in +the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT PERCENTILE("water_level",5) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | percentile | +| :------------------- | ---------: | +| 2019-09-01T17:54:00Z | 1.122 | + +{{% /expand %}} + +{{% expand "Select the fifth percentile field value associated with each field key in a measurement" %}} + +Return the field value that is larger than five percent of the field values in +each field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT PERCENTILE(*,5) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | percentile_water_level | +| :------------------- | ---------------------: | +| 2019-09-01T17:54:00Z | 1.122 | + +{{% /expand %}} + +{{% expand "Select fifth percentile field value associated with each field key that matches a regular expression" %}} + +Return the field value that is larger than five percent of the field values in +each numeric field with `water` in the field key. + +```sql +SELECT PERCENTILE(/level/,5) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | percentile_water_level | +| :------------------- | ---------------------: | +| 2019-09-01T17:54:00Z | 1.122 | + +{{% /expand %}} + +{{% expand "Select the fifth percentile field values associated with a field key and the relevant tags and fields" %}} + +Return the field value that is larger than five percent of the field values in +the `water_level` field key and the relevant values of the `location` tag key +and the `level description` field key. + +```sql +SELECT PERCENTILE("water_level",5),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | percentile | location | level description | +| :------------------- | ---------: | :----------- | :---------------- | +| 2019-08-24T10:18:00Z | 1.122 | coyote_creek | below 3 feet | + +{{% /expand %}} + +{{% expand "Select the twentieth percentile field value associated with a field key and include several clauses" %}} + +Return the field value that is larger than 20 percent of the values in the +`water_level` field in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T23:48:00Z` and `2019-08-18T00:54:00Z` and [group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) results into 24-minute intervals. +Then [fill](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals-and-fill) +empty time intervals with `15` and [limit](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to two. + +```sql +SELECT PERCENTILE("water_level",20) FROM "h2o_feet" WHERE time >= '2019-08-17T23:48:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) fill(15) LIMIT 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | percentile | +| :------------------- | ---------: | +| 2019-08-17T23:36:00Z | 2.398 | +| 2019-08-18T00:00:00Z | 2.343 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) overrides the points’ original timestamps. +The timestamps in the results indicate the the start of each 24-minute time interval; the first point in the results covers the time interval between `2019-08-17T23:36:00Z` and just before `2019-08-18T00:00:00Z` and the last point in the results covers the time interval between `2019-08-18T00:00:00Z` and just before `2019-08-18T00:24:00Z`. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with PERCENTILE() + +#### PERCENTILE() compared to other InfluxQL functions + +- `PERCENTILE(,100)` is equivalent to [`MAX()`](#max). +- `PERCENTILE(, 50)` is nearly equivalent to [`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), except the `MEDIAN()` function returns the average of the two middle values if the field key contains an even number of field values. +- `PERCENTILE(,0)` is not equivalent to [`MIN()`](#min). This is a known [issue](https://github.com/influxdata/influxdb/issues/4418). + +## SAMPLE() + +Returns a random sample of `N` [field values](/influxdb/v2.4/reference/glossary/#field-value). +`SAMPLE()` uses [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling) to generate the random points. + +### Syntax + +```sql +SELECT SAMPLE(, )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`SAMPLE(field_key,N)` +Returns N randomly selected field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`SAMPLE(/regular_expression/,N)` +Returns N randomly selected field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`SAMPLE(*,N)` +Returns N randomly selected field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`SAMPLE(field_key,N),tag_key(s),field_key(s)` +Returns N randomly selected field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`N` must be an integer. +`SAMPLE()` supports all field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select a sample of the field values associated with a field key" %}} + +Return two randomly selected points from the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT SAMPLE("water_level",2) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample | +| :------------------- | -----: | +| 2019-08-22T03:42:00Z | 7.218 | +| 2019-08-28T20:18:00Z | 2.848 | + +{{% /expand %}} + +{{% expand "Select a sample of the field values associated with each field key in a measurement" %}} + +Return two randomly selected points for each field key in the `h2o_feet` measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT SAMPLE(*,2) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample_level description | sample_water_level | +| :------------------- | :----------------------- | -----------------: | +| 2019-08-23T17:30:00Z | below 3 feet | | +| 2019-09-08T19:18:00Z | | 8.379 | +| 2019-09-09T03:54:00Z | between 6 and 9 feet | | +| 2019-09-16T04:48:00Z | | 1.437 | + +{{% /expand %}} + +{{% expand "Select a sample of the field values associated with each field key that matches a regular expression" %}} + +Return two randomly selected points for each field key that includes the word +`level` in the `h2o_feet` measurement. + +```sql +SELECT SAMPLE(/level/,2) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample_level description | sample_water_level | +| :------------------- | :----------------------- | -----------------: | +| 2019-08-19T20:24:00Z | | 4.951 | +| 2019-08-26T06:30:00Z | below 3 feet | | +| 2019-09-10T09:06:00Z | | 1.312 | +| 2019-09-16T21:00:00Z | between 3 and 6 feet | | + +{{% /expand %}} + +{{% expand "Select a sample of the field values associated with a field key and the relevant tags and fields" %}} + +Return two randomly selected points from the `water_level` field key and the +relevant values of the `location` tag and the `level description` field. + +```sql +SELECT SAMPLE("water_level",2),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample | location | level description | +| :------------------- | -----: | :----------- | :------------------- | +| 2019-08-31T04:30:00Z | 4.954 | santa_monica | between 3 and 6 feet | +| 2019-09-13T01:24:00Z | 3.389 | santa_monica | between 3 and 6 feet | + +{{% /expand %}} + +{{% expand "Select a sample of the field values associated with a field key and include several clauses" %}} + +Return one randomly selected point from the `water_level` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` and +[group](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) +results into 18-minute intervals. + +```sql +SELECT SAMPLE("water_level",1) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample | +| :------------------- | -----: | +| 2019-08-18T00:12:00Z | 2.343 | +| 2019-08-18T00:24:00Z | 2.264 | + +Notice that the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) does not override the points' original timestamps. +See [Issue 1](#sample-with-a-group-by-time-clause) in the section below for a +more detailed explanation of that behavior. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with SAMPLE() + +#### SAMPLE() with a GROUP BY time() clause + +Queries with `SAMPLE()` and a `GROUP BY time()` clause return the specified +number of points (`N`) per `GROUP BY time()` interval. +For [most `GROUP BY time()` queries](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals), +the returned timestamps mark the start of the `GROUP BY time()` interval. +`GROUP BY time()` queries with the `SAMPLE()` function behave differently; +they maintain the timestamp of the original data point. + +##### Example + +The query below returns two randomly selected points per 18-minute +`GROUP BY time()` interval. +Notice that the returned timestamps are the points' original timestamps; they +are not forced to match the start of the `GROUP BY time()` intervals. + +```sql +SELECT SAMPLE("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sample | +| :------------------- | -----: | +| 2019-08-18T00:06:00Z | 2.116 | +| 2019-08-18T00:12:00Z | 2.028 | +| 2019-08-18T00:18:00Z | 2.126 | +| 2019-08-18T00:30:00Z | 2.051 | + +Notice that the first two rows are randomly-selected points from the first time +interval and the last two rows are randomly-selected points from the second time interval. + +## TOP() + +Returns the greatest `N` [field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SELECT TOP( [,], )[,|] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`TOP(field_key,N)` +Returns the greatest N field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`TOP(field_key,tag_key(s),N)` +Returns the greatest field value for N tag values of the [tag key](/influxdb/v2.4/reference/glossary/#tag-key). + +`TOP(field_key,N),tag_key(s),field_key(s)` +Returns the greatest N field values associated with the field key in the parentheses and the relevant [tag](/influxdb/v2.4/reference/glossary/#tag) and/or [field](/influxdb/v2.4/reference/glossary/#field). + +`TOP()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +{{% note %}} +**Note:** `TOP()` returns the field value with the earliest timestamp if there's a tie between two or more values for the greatest value. +{{% /note %}} + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Select the top three field values associated with a field key" %}} + +Return the greatest three field values in the `water_level` field key and in the +`h2o_feet` [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +```sql +SELECT TOP("water_level",3) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | +| :------------------- | ----: | +| 2019-08-28T07:18:00Z | 9.957 | +| 2019-08-28T07:24:00Z | 9.964 | +| 2019-08-28T07:30:00Z | 9.954 | + +{{% /expand %}} + +{{% expand "Select the top field value associated with a field key for two tags" %}} + +Return the greatest field values in the `water_level` field key for two tag +values associated with the `location` tag key. + +```sql +SELECT TOP("water_level","location",2) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | location | +| :------------------- | ----: | :----------- | +| 2019-08-28T03:54:00Z | 7.205 | santa_monica | +| 2019-08-28T07:24:00Z | 9.964 | coyote_creek | + +{{% /expand %}} + +{{% expand "Select the top four field values associated with a field key and the relevant tags and fields" %}} + +Return the greatest four field values in the `water_level` field key and the +relevant values of the `location` tag key and the `level description` field key. + +```sql +SELECT TOP("water_level",4),"location","level description" FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | location | level description | +| :------------------- | ----: | :----------- | :------------------------ | +| 2019-08-28T07:18:00Z | 9.957 | coyote_creek | at or greater than 9 feet | +| 2019-08-28T07:24:00Z | 9.964 | coyote_creek | at or greater than 9 feet | +| 2019-08-28T07:30:00Z | 9.954 | coyote_creek | at or greater than 9 feet | +| 2019-08-28T07:36:00Z | 9.941 | coyote_creek | at or greater than 9 feet | + +{{% /expand %}} + +{{% expand "Select the top three field values associated with a field key and include several clauses" %}} + +Return the greatest three values in the `water_level` field key for each 24-minute +[interval](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#basic-group-by-time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:54:00Z` with results in +[descending timestamp](/influxdb/v2.4/query-data/influxql/explore-data/order-by/) order. + +```sql +SELECT TOP("water_level",3),"location" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(24m) ORDER BY time DESC +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | location | +| :------------------- | ----: | :----------- | +| 2019-08-18T00:54:00Z | 6.982 | coyote_creek | +| 2019-08-18T00:54:00Z | 2.054 | santa_monica | +| 2019-08-18T00:48:00Z | 7.110 | coyote_creek | +| 2019-08-18T00:36:00Z | 7.372 | coyote_creek | +| 2019-08-18T00:30:00Z | 7.500 | coyote_creek | +| 2019-08-18T00:24:00Z | 7.635 | coyote_creek | +| 2019-08-18T00:12:00Z | 7.887 | coyote_creek | +| 2019-08-18T00:06:00Z | 8.005 | coyote_creek | +| 2019-08-18T00:00:00Z | 8.120 | coyote_creek | + +Notice that the [GROUP BY time() clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) does not override the points’ original timestamps. +See [Issue 1](#top-with-a-group-by-time-clause) in the section below for a more detailed explanation of that behavior. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with `TOP()` + +#### `TOP()` with a `GROUP BY time()` clause + +Queries with `TOP()` and a `GROUP BY time()` clause return the specified +number of points per `GROUP BY time()` interval. +For [most `GROUP BY time()` queries](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals), +the returned timestamps mark the start of the `GROUP BY time()` interval. +`GROUP BY time()` queries with the `TOP()` function behave differently; +they maintain the timestamp of the original data point. + +##### Example + +The query below returns two points per 18-minute +`GROUP BY time()` interval. +Notice that the returned timestamps are the points' original timestamps; they +are not forced to match the start of the `GROUP BY time()` intervals. + +```sql +SELECT TOP("water_level",2) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | +| :------------------- | ----: | +| 2019-08-18T00:00:00Z | 2.064 | +| 2019-08-18T00:06:00Z | 2.116 | +| 2019-08-18T00:18:00Z | 2.126 | +| 2019-08-18T00:30:00Z | 2.051 | + +Notice that the first two rows are the greatest points for the first time interval +and the last two rows are the greatest points for the second time interval. + +#### TOP() and a tag key with fewer than N tag values + +Queries with the syntax `SELECT TOP(,,)` can return fewer points than expected. +If the tag key has `X` tag values, the query specifies `N` values, and `X` is smaller than `N`, then the query returns `X` points. + +##### Example + +The query below asks for the greatest field values of `water_level` for three tag values of the `location` tag key. +Because the `location` tag key has two tag values (`santa_monica` and `coyote_creek`), the query returns two points instead of three. + +```sql +SELECT TOP("water_level","location",3) FROM "h2o_feet" +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | top | location | +| :------------------- | ----: | :----------- | +| 2019-08-29T03:54:00Z | 7.205 | santa_monica | +| 2019-08-29T07:24:00Z | 9.964 | coyote_creek | + + diff --git a/content/influxdb/v2.4/query-data/influxql/functions/technical-analysis.md b/content/influxdb/v2.4/query-data/influxql/functions/technical-analysis.md new file mode 100644 index 0000000000..07983e4e68 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/functions/technical-analysis.md @@ -0,0 +1,659 @@ +--- +title: InfluxQL analysis functions +list_title: Technical analysis functions +description: > + Use technical analysis functions to apply algorithms to your data. +menu: + influxdb_2_4: + name: Technical analysis + parent: InfluxQL functions +weight: 205 +--- + +Use technical analysis functions to apply algorithms to your data--often used to analyze financial and investment data. + +Each analysis function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data). + +- [Predictive analysis](#predictive-analysis): + - [HOLT_WINTERS()](#holt_winters) +- [Technical analysis](#technical-analysis-functions): + - [CHANDE_MOMENTUM_OSCILLATOR()](#chande_momentum_oscillator) + - [EXPONENTIAL_MOVING_AVERAGE()](#exponential_moving_average) + - [DOUBLE_EXPONENTIAL_MOVING_AVERAGE()](#double_exponential_moving_average) + - [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) + - [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) + - [TRIPLE_EXPONENTIAL_MOVING_AVERAGE()](#triple_exponential_moving_average) + - [TRIPLE_EXPONENTIAL_DERIVATIVE()](#triple_exponential_derivative) + - [RELATIVE_STRENGTH_INDEX()](#relative_strength_index) + +## Predictive analysis + +Predictive analysis functions are a type of technical analysis algorithms that +predict and forecast future values. + +### HOLT_WINTERS() + +Returns N number of predicted [field values](/influxdb/v2.4/reference/glossary/#field-value) +using the [Holt-Winters](https://www.otexts.org/fpp/7/5) seasonal method. +Supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). +Works with data that occurs at consistent time intervals. +Requires an InfluxQL function and the `GROUP BY time()` clause to ensure that +the Holt-Winters function operates on regular data. + +Use `HOLT_WINTERS()` to: + +- Predict when data values will cross a given threshold +- Compare predicted values with actual values to detect anomalies in your data + +#### Syntax + +``` +SELECT HOLT_WINTERS[_WITH-FIT]((),,) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`HOLT_WINTERS(function(field_key),N,S)` returns `N` seasonally adjusted +predicted field values for the specified [field key](/influxdb/v2.4/reference/glossary/#field-key). + +The `N` predicted values occur at the same interval as the [`GROUP BY time()` interval](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +If your `GROUP BY time()` interval is `6m` and `N` is `3` you'll +receive three predicted values that are each six minutes apart. + +`S` is the seasonal pattern parameter and delimits the length of a seasonal +pattern according to the `GROUP BY time()` interval. +If your `GROUP BY time()` interval is `2m` and `S` is `3`, then the +seasonal pattern occurs every six minutes, that is, every three data points. +If you do not want to seasonally adjust your predicted values, set `S` to `0` +or `1.` + +`HOLT_WINTERS_WITH_FIT(function(field_key),N,S)` returns the fitted values in +addition to `N` seasonally adjusted predicted field values for the specified field key. + +#### Examples + +{{< expand-wrapper >}} +{{% expand "Predict field values associated with a field key" %}} + +##### Sample data + +The examples use the following subset of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >= '2019-08-17T00:00:00Z' AND time <= '2019-08-22T00:00:00Z' +``` + +##### Step 1: Match the trends of the raw data + +Write a `GROUP BY time()` query that matches the general trends of the raw `water_level` data. +Here, we use the [`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first) function: + +```sql +SELECT FIRST("water_level") FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' and time >= '2019-08-17T00:00:00Z' AND time <= '2019-08-22T00:00:00Z' GROUP BY time(6h,6h) +``` + +In the `GROUP BY time()` clause, the first argument (`6h`) matches +the length of time that occurs between each peak and trough in the `water_level` data. +The second argument (`6h`) is the +[offset interval](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#advanced-group-by-time-syntax). +The offset interval alters the default `GROUP BY time()` boundaries to +match the time range of the raw data. + +{{< img-hd src="/img/influxdb/2-4-influxql-holtwinters-1.png" alt="Holt Winters base data" />}} + +###### Step 2: Determine the seasonal pattern + +Identify the seasonal pattern in the data using the information from the +query in step 1. + +The pattern in the `water_level` data repeats about every 12 hours. +There are two data points per season, so `2` is the seasonal pattern argument. + +{{< img-hd src="/img/influxdb/2-4-influxql-holtwinters-2.png" alt="Holt Winters seasonal data" />}} + +###### Step 3: Apply the HOLT_WINTERS() function + +Add the Holt-Winters function to the query. +Here, we use `HOLT_WINTERS_WITH_FIT()` to view both the fitted values and the predicted values: + +```sql +SELECT HOLT_WINTERS_WITH_FIT(FIRST("water_level"),10,2) FROM "noaa"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >= '2019-08-17 00:00:00' AND time <= '2019-08-22 00:00:00' GROUP BY time(6h,6h) +``` + +In the `HOLT_WINTERS_WITH_FIT()` function, the first argument (`10`) requests 10 predicted field values. +Each predicted point is `6h` apart, the same interval as the first argument in the `GROUP BY time()` clause. +The second argument in the `HOLT_WINTERS_WITH_FIT()` function (`2`) is the seasonal pattern that we determined in the previous step. + +{{< img-hd src="/img/influxdb/2-4-influxql-holtwinters-3.png" alt="Holt Winters predicted data" />}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +#### Common issues with `HOLT_WINTERS()` + +##### Receiving fewer than `N` points + +In some cases, you may receive fewer predicted points than requested by the `N` parameter. +That behavior typically occurs when the math becomes unstable and cannot forecast more +points. In this case, `HOLT_WINTERS()` may not be suited for the dataset or the seasonal adjustment parameter is invalid. + +## Technical analysis functions + +Technical analysis functions apply widely used algorithms to your data. +While they are primarily used in finance and investing, they have +application in other industries. + +For technical analysis functions, consider whether to include the `PERIOD`, `HOLD_PERIOD`, and `WARMUP_TYPE` arguments: + +#### `PERIOD` + +**Required, integer, min=1** + +The sample size for the algorithm, which is the number of historical samples with significant +effect on the output of the algorithm. +For example, `2` means the current point and the point before it. +The algorithm uses an exponential decay rate to determine the weight of a historical point, +generally known as the alpha (α). The `PERIOD` controls the decay rate. + +{{% note %}} +**Note:** Older points can still have an impact. +{{% /note %}} + +#### `HOLD_PERIOD` + +**integer, min=-1** + +How many samples the algorithm needs before emitting results. +The default of `-1` means the value is based on the algorithm, the `PERIOD`, +and the `WARMUP_TYPE`. Verify this value is enough for the algorithm to emit meaningful results. + +_**Default hold periods:**_ + +For most technical analysis functions, the default `HOLD_PERIOD` is +determined by the function and the [`WARMUP_TYPE`](#warmup_type) shown in the following table: + +| Algorithm \ Warmup Type | simple | exponential | none | +| --------------------------------- | ---------------------- | ----------- |:----------: | +| [EXPONENTIAL_MOVING_AVERAGE](#exponential_moving_average) | PERIOD - 1 | PERIOD - 1 | n/a | +| [DOUBLE_EXPONENTIAL_MOVING_AVERAGE](#double_exponential_moving_average) | ( PERIOD - 1 ) * 2 | PERIOD - 1 | n/a | +| [TRIPLE_EXPONENTIAL_MOVING_AVERAGE](#triple_exponential_moving_average) | ( PERIOD - 1 ) * 3 | PERIOD - 1 | n/a | +| [TRIPLE_EXPONENTIAL_DERIVATIVE](#triple_exponential_derivative) | ( PERIOD - 1 ) * 3 + 1 | PERIOD | n/a | +| [RELATIVE_STRENGTH_INDEX](#relative_strength_index) | PERIOD | PERIOD | n/a | +| [CHANDE_MOMENTUM_OSCILLATOR](#chande_momentum_oscillator) | PERIOD | PERIOD | PERIOD - 1 | + +_**Kaufman algorithm default hold periods:**_ + +| Algorithm | Default Hold Period | +| --------- | ------------------- | +| [KAUFMANS_EFFICIENCY_RATIO()](#kaufmans_efficiency_ratio) | PERIOD | +| [KAUFMANS_ADAPTIVE_MOVING_AVERAGE()](#kaufmans_adaptive_moving_average) | PERIOD | + +#### `WARMUP_TYPE` + +**default='exponential'** + +Controls how the algorithm initializes for the first `PERIOD` samples. +It is essentially the duration for which it has an incomplete sample set. + +##### simple + +Simple moving average (SMA) of the first `PERIOD` samples. +This is the method used by [ta-lib](https://www.ta-lib.org/). + +##### exponential + +Exponential moving average (EMA) with scaling alpha (α). +Uses an EMA with `PERIOD=1` for the first point, `PERIOD=2` +for the second point, and so on, until the algorithm has consumed `PERIOD` number of points. +As the algorithm immediately starts using an EMA, when this method is used and +`HOLD_PERIOD` is unspecified or `-1`, the algorithm may start emitting points +after a much smaller sample size than with `simple`. + +##### none + +The algorithm does not perform any smoothing at all. +Method used by [ta-lib](https://www.ta-lib.org/). +When this method is used and `HOLD_PERIOD` is unspecified, `HOLD_PERIOD` +defaults to `PERIOD - 1`. + +{{% note %}} +**Note:** The `none` warmup type is only available with the [`CHANDE_MOMENTUM_OSCILLATOR()`](#chande_momentum_oscillator) function. +{{% /note %}} + +## CHANDE_MOMENTUM_OSCILLATOR() + +The Chande Momentum Oscillator (CMO) is a technical momentum indicator developed by Tushar Chande. +The CMO indicator is created by calculating the difference between the sum of all +recent higher data points and the sum of all recent lower data points, +then dividing the result by the sum of all data movement over a given time period. +The result is multiplied by 100 to give the -100 to +100 range. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). To use `CHANDE_MOMENTUM_OSCILLATOR()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +CHANDE_MOMENTUM_OSCILLATOR([ * | | /regular_expression/ ], [, , [warmup_type]]) +``` + +### Arguments + +- [period](#period) +- (Optional) [hold_period](#hold_period) +- (Optional) [warmup_type](#warmup_type) + +`CHANDE_MOMENTUM_OSCILLATOR(field_key, 2)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Chande Momentum Oscillator algorithm with a 2-value period +and the default hold period and warmup type. + +`CHANDE_MOMENTUM_OSCILLATOR(field_key, 10, 9, 'none')` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Chande Momentum Oscillator algorithm with a 10-value period +a 9-value hold period, and the `none` warmup type. + +`CHANDE_MOMENTUM_OSCILLATOR(MEAN(), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Chande Momentum Oscillator algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `CHANDE_MOMENTUM_OSCILLATOR()` function. +{{% /note %}} + +`CHANDE_MOMENTUM_OSCILLATOR(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Chande Momentum Oscillator algorithm with a 2-value period +and the default hold period and warmup type. + +`CHANDE_MOMENTUM_OSCILLATOR(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Chande Momentum Oscillator algorithm with a 2-value period +and the default hold period and warmup type. + +`CHANDE_MOMENTUM_OSCILLATOR()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +## EXPONENTIAL_MOVING_AVERAGE() + +An exponential moving average (EMA) (or exponentially weighted moving average) is a type of moving average similar to a [simple moving average](/influxdb/v2.4/query-data/influxql/functions/transformations/#moving_average), +except more weight is given to the latest data. + +This type of moving average reacts faster to recent data changes than a simple moving average. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +```sql +EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `EXPONENTIAL_MOVING_AVERAGE()` function. +{{% /note %}} + +`EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`EXPONENTIAL_MOVING_AVERAGE(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +### Arguments + +- [period](#period) +- (Optional) [hold_period](#hold_period) +- (Optional) [warmup_type](#warmup_type) + +## DOUBLE_EXPONENTIAL_MOVING_AVERAGE() + +The Double Exponential Moving Average (DEMA) attempts to remove the inherent lag +associated with moving averages by placing more weight on recent values. +The name suggests this is achieved by applying a double exponential smoothing which is not the case. +The value of an [EMA](#exponential_moving_average) is doubled. +To keep the value in line with the actual data and to remove the lag, the value "EMA of EMA" +is subtracted from the previously doubled EMA. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +DOUBLE_EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Double Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` function. +{{% /note %}} + +`DOUBLE_EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Double Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`DOUBLE_EXPONENTIAL_MOVING_AVERAGE(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Double Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`DOUBLE_EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +### Arguments + +- [period](#period) +- (Optional) [hold_period](#hold_period) +- (Optional) [warmup_type](#warmup_type) + +## KAUFMANS_EFFICIENCY_RATIO() + +Kaufman's Efficiency Ration, or simply "Efficiency Ratio" (ER), is calculated by +dividing the data change over a period by the absolute sum of the data movements +that occurred to achieve that change. +The resulting ratio ranges between 0 and 1 with higher values representing a +more efficient or trending market. + +The ER is very similar to the [Chande Momentum Oscillator](#chande_momentum_oscillator) (CMO). +The difference is that the CMO takes market direction into account, but if you take the absolute CMO and divide by 100, you you get the Efficiency Ratio. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `KAUFMANS_EFFICIENCY_RATIO()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +KAUFMANS_EFFICIENCY_RATIO([ * | | /regular_expression/ ], [, ]) +``` + +`KAUFMANS_EFFICIENCY_RATIO(field_key, 2)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Efficiency Index algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_EFFICIENCY_RATIO(field_key, 10, 10)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Efficiency Index algorithm with a 10-value period and +a 10-value hold period. + +`KAUFMANS_EFFICIENCY_RATIO(MEAN(), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Efficiency Index algorithm with a 2-value period +and the default hold period. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `KAUFMANS_EFFICIENCY_RATIO()` function. +{{% /note %}} + +`KAUFMANS_EFFICIENCY_RATIO(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Efficiency Index algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_EFFICIENCY_RATIO(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Efficiency Index algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_EFFICIENCY_RATIO()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +**Arguments:** + +- [period](#period) +- (Optional) [hold_period](#hold_period) + +## KAUFMANS_ADAPTIVE_MOVING_AVERAGE() + +Kaufman's Adaptive Moving Average (KAMA) is a moving average designed to +account for sample noise or volatility. +KAMA will closely follow data points when the data swings are relatively small and noise is low. +KAMA will adjust when the data swings widen and follow data from a greater distance. +This trend-following indicator can be used to identify the overall trend, +time turning points and filter data movements. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +KAUFMANS_ADAPTIVE_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ]) +``` + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_key, 2)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_key, 10, 10)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Kaufman Adaptive Moving Average algorithm with a 10-value period +and a 10-value hold period. + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE(MEAN(), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period +and the default hold period. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` function. +{{% /note %}} + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Kaufman Adaptive Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`KAUFMANS_ADAPTIVE_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +**Arguments:** +- [period](#period) +- (Optional) [hold_period](#hold_period) + +## TRIPLE_EXPONENTIAL_MOVING_AVERAGE() + +The triple exponential moving average (TEMA) filters out +volatility from conventional moving averages. +While the name implies that it's a triple exponential smoothing, it's actually a +composite of a [single exponential moving average](#exponential_moving_average), +a [double exponential moving average](#double_exponential_moving_average), +and a triple exponential moving average. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +TRIPLE_EXPONENTIAL_MOVING_AVERAGE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Triple Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` function. +{{% /note %}} + +`TRIPLE_EXPONENTIAL_MOVING_AVERAGE(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Triple Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`TRIPLE_EXPONENTIAL_MOVING_AVERAGE(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Triple Exponential Moving Average algorithm with a 2-value period +and the default hold period and warmup type. + +`TRIPLE_EXPONENTIAL_MOVING_AVERAGE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +**Arguments:** +- [period](#period) +- (Optional) [hold_period](#hold_period) +- (Optional) [warmup_type](#warmup_type) + +## TRIPLE_EXPONENTIAL_DERIVATIVE() + +The triple exponential derivative indicator, commonly referred to as "TRIX," is +an oscillator used to identify oversold and overbought markets, and can also be +used as a momentum indicator. +TRIX calculates a [triple exponential moving average](#triple_exponential_moving_average) +of the [log](/influxdb/v2.4/query-data/influxql/functions/transformations/#log) +of the data input over the period of time. +The previous value is subtracted from the previous value. +This prevents cycles that are shorter than the defined period from being considered by the indicator. + +Like many oscillators, TRIX oscillates around a zero line. When used as an oscillator, +a positive value indicates an overbought market while a negative value indicates an oversold market. +When used as a momentum indicator, a positive value suggests momentum is increasing +while a negative value suggests momentum is decreasing. +Many analysts believe that when the TRIX crosses above the zero line it gives a +buy signal, and when it closes below the zero line, it gives a sell signal. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `TRIPLE_EXPONENTIAL_DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +TRIPLE_EXPONENTIAL_DERIVATIVE([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Triple Exponential Derivative algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `TRIPLE_EXPONENTIAL_DERIVATIVE()` function. +{{% /note %}} + +`TRIPLE_EXPONENTIAL_DERIVATIVE(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Triple Exponential Derivative algorithm with a 2-value period +and the default hold period and warmup type. + +`TRIPLE_EXPONENTIAL_DERIVATIVE(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Triple Exponential Derivative algorithm with a 2-value period +and the default hold period and warmup type. + +`TRIPLE_EXPONENTIAL_DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +## RELATIVE_STRENGTH_INDEX() + +The relative strength index (RSI) is a momentum indicator that compares the magnitude of recent increases and decreases over a specified time period to measure speed and change of data movements. +Source + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). + +To use `RELATIVE_STRENGTH_INDEX()` with a `GROUP BY time()` clause, see [Advanced syntax](/influxdb/v2.4/query-data/influxql/functions/transformations/#advanced-syntax). + +### Basic syntax + +``` +RELATIVE_STRENGTH_INDEX([ * | | /regular_expression/ ], [, ), 2) ... GROUP BY time(1d)` +Returns the mean of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) +processed using the Relative Strength Index algorithm with a 2-value period +and the default hold period and warmup type. + +{{% note %}} +**Note:** When aggregating data with a `GROUP BY` clause, you must include an [aggregate function](/influxdb/v2.4/query-data/influxql/functions/aggregates/) in your call to the `RELATIVE_STRENGTH_INDEX()` function. +{{% /note %}} + +`RELATIVE_STRENGTH_INDEX(/regular_expression/, 2)` +Returns the field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/) +processed using the Relative Strength Index algorithm with a 2-value period +and the default hold period and warmup type. + +`RELATIVE_STRENGTH_INDEX(*, 2)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +processed using the Relative Strength Index algorithm with a 2-value period +and the default hold period and warmup type. + +`RELATIVE_STRENGTH_INDEX()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +**Arguments:** +- [period](#period) +- (Optional) [hold_period](#hold_period) +- (Optional) [warmup_type](#warmup_type) diff --git a/content/influxdb/v2.4/query-data/influxql/functions/transformations.md b/content/influxdb/v2.4/query-data/influxql/functions/transformations.md new file mode 100644 index 0000000000..5f24199658 --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/functions/transformations.md @@ -0,0 +1,4265 @@ +--- +title: InfluxQL transformation functions +list_title: Tranfsormation functions +description: > + Use transformation functions modify and return values each row of queried data. +menu: + influxdb_2_4: + name: Transformations + parent: InfluxQL functions +weight: 205 +--- + +InfluxQL transformation functions modify and return values each row of queried data. + +Each transformation function below covers **syntax**, including parameters to pass to the function, and **examples** of how to use the function. Examples use [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data) and data from [sample_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). + +- [ABS()](#abs) +- [ACOS()](#acos) +- [ASIN()](#asin) +- [ATAN()](#atan) +- [ATAN2()](#atan2) +- [CEIL()](#ceil) +- [COS()](#cos) +- [CUMULATIVE_SUM()](#cumulative_sum) +- [DERIVATIVE()](#derivative) +- [DIFFERENCE()](#difference) +- [ELAPSED()](#elapsed) +- [EXP()](#exp) +- [FLOOR()](#floor) +- [HISTOGRAM()](#histogram) +- [LN()](#ln) +- [LOG()](#log) +- [LOG2()](#log2) +- [LOG10()](#log10) +- [MOVING_AVERAGE()](#moving_average) +- [NON_NEGATIVE_DERIVATIVE()](#non_negative_derivative) +- [NON_NEGATIVE_DIFFERENCE](#non_negative_difference) +- [POW](#pow) +- [ROUND](#round) +- [SIN](#sin) +- [SQRT](#sqrt) +- [TAN](#tan) + +## ABS() + +Returns the absolute value of the field value. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). + +### Basic syntax + +```sql +SELECT ABS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ABS(field_key)` +Returns the absolute values of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`ABS(*)` +Returns the absolute values of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`ABS()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the absolute values of field values associated with a field key" %}} + +Return the absolute values of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT ABS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:15:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | abs | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 8.5040000000 | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 8.4190000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 8.3200000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | + +{{% /expand %}} + +{{% expand "Calculate the absolute values of field values associated with each field key in a measurement" %}} + +Return the absolute values of field values for each field key that stores numeric values in the `data` measurement. +The `h2o_feet` measurement has one numeric field `water_level`. + +```sql +SELECT ABS(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:15:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | abs_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | 8.5040000000 | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 8.4190000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 8.3200000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | + + +{{% /expand %}} + +{{% expand "Calculate the absolute values of field values associated with a field key and include several clauses" %}} + +Return the absolute values of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT ABS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | abs | +| :------------------- | -----------: | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:24:00Z | 8.1300000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:18:00Z | 8.2250000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ABS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ABS()` function to those results. + +`ABS()` supports the following nested functions: + +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the absolute values of mean values" %}} + +Return the absolute values of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT ABS(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | abs | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 5.4135000000 | +| 2019-08-18T00:12:00Z | 5.3042500000 | +| 2019-08-18T00:24:00Z | 5.1682500000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ACOS() + +Returns the arccosine (in radians) of the field value. Field values must be between -1 and 1. Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but does not support [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). + +### Basic syntax + +```sql +SELECT ACOS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ACOS(field_key)` +Returns the arccosine of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`ACOS(*)` +Returns the arccosine of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`ACOS()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. + +#### Examples + +The examples below use a subset of data from [sample_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a), which only includes field values within the calculable range (-1 to 1). This value range is required for the `ACOS()` function: + +| time | a | +| :------------------- | -----------------: | +| 2018-06-24T12:01:00Z | -0.774984088561186 | +| 2018-06-24T12:02:00Z | -0.921037167720451 | +| 2018-06-24T12:04:00Z | -0.905980032168252 | +| 2018-06-24T12:05:00Z | -0.891164752631417 | +| 2018-06-24T12:09:00Z | 0.416579917279588 | +| 2018-06-24T12:10:00Z | 0.328968116955350 | +| 2018-06-24T12:11:00Z | 0.263585064411983 | + + +{{< expand-wrapper >}} + +{{% expand "Calculate the arccosine of field values associated with a field key" %}} + +Return the arccosine of field values in the `a` field key in the `data` measurement. + +```sql +SELECT ACOS("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | acos | +| :------------------- | -----------: | +| 2018-06-24T12:00:00Z | | +| 2018-06-24T12:01:00Z | 2.4574862443 | +| 2018-06-24T12:02:00Z | 2.7415314737 | +| 2018-06-24T12:03:00Z | | +| 2018-06-24T12:04:00Z | 2.7044854503 | +| 2018-06-24T12:05:00Z | 2.6707024029 | +| 2018-06-24T12:06:00Z | | +| 2018-06-24T12:07:00Z | | +| 2018-06-24T12:08:00Z | | +| 2018-06-24T12:09:00Z | 1.1411163210 | +| 2018-06-24T12:10:00Z | 1.2355856616 | +| 2018-06-24T12:11:00Z | 1.3040595066 | + +{{% /expand %}} + +{{% expand "Calculate the arccosine of field values associated with each field key in a measurement" %}} + +Return the arccosine of field values for each field key that stores numeric values in the `data` measurement, field `a` and `b`. + +```sql +SELECT ACOS(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | acos_a | acos_b | +| :------------------- | -----------: | -----------: | +| 2018-06-24T12:00:00Z | | 1.7351786976 | +| 2018-06-24T12:01:00Z | 2.4574862443 | 1.4333294161 | +| 2018-06-24T12:02:00Z | 2.7415314737 | 2.0748091141 | +| 2018-06-24T12:03:00Z | | 1.6438345404 | +| 2018-06-24T12:04:00Z | 2.7044854503 | | +| 2018-06-24T12:05:00Z | 2.6707024029 | 0.7360183965 | +| 2018-06-24T12:06:00Z | | 1.2789990384 | +| 2018-06-24T12:07:00Z | | 2.1522589654 | +| 2018-06-24T12:08:00Z | | 0.6128438977 | +| 2018-06-24T12:09:00Z | 1.1411163210 | | +| 2018-06-24T12:10:00Z | 1.2355856616 | | +| 2018-06-24T12:11:00Z | 1.3040595066 | 1.7595349692 | +| 2018-06-24T12:12:00Z | 1.8681669412 | 2.5213034266 | + +{{% /expand %}} + +{{% expand "Calculate the arccosine of field values associated with a field key and include several clauses" %}} + +Return the arccosine of field values associated with the `a` field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) between `2018-06-24T00:00:00Z` and `2018-06-25T00:00:00Z` with results in [descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) results by two points. + +```sql +SELECT ACOS("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | acos | +| :------------------- | -----------: | +| 2018-06-24T23:58:00Z | 1.5361053361 | +| 2018-06-24T23:57:00Z | | +| 2018-06-24T23:56:00Z | 0.5211076815 | +| 2018-06-24T23:55:00Z | 1.647695085 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ACOS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ACOS()` function to those results. + +`ACOS()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the arccosine of mean values" %}} + +Return the arccosine of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `a` that are calculated at 3 hour intervals. + +```sql +SELECT ACOS(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | acos | +| :------------------- | -----------: | +| 2018-06-24T00:00:00Z | | +| 2018-06-24T03:00:00Z | | +| 2018-06-24T06:00:00Z | | +| 2018-06-24T09:00:00Z | | +| 2018-06-24T12:00:00Z | 1.5651603194 | +| 2018-06-24T15:00:00Z | 1.6489104619 | +| 2018-06-24T18:00:00Z | 1.4851295699 | +| 2018-06-24T21:00:00Z | 1.6209901549 | +| 2018-06-25T00:00:00Z | 1.7149309371 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ASIN() + +Returns the arcsine (in radians) of the field value. Field values must be between -1 and 1. + +### Basic syntax + +```sql +SELECT ASIN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ASIN(field_key)` +Returns the arcsine of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`ASIN(*)` +Returns the arcsine of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`ASIN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `ASIN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following data from [sample_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). + +The following data from this data set only includes field value within the calculable range (-1 to 1) required for the `ASIN()` function: + +| time | a | +| :------------------- | -----------------: | +| 2018-06-24T12:01:00Z | -0.774984088561186 | +| 2018-06-24T12:02:00Z | -0.921037167720451 | +| 2018-06-24T12:04:00Z | -0.905980032168252 | +| 2018-06-24T12:05:00Z | -0.891164752631417 | +| 2018-06-24T12:09:00Z | 0.416579917279588 | +| 2018-06-24T12:10:00Z | 0.328968116955350 | +| 2018-06-24T12:11:00Z | 0.263585064411983 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the arcsine of field values associated with a field key" %}} + +Return the arcsine of field values in the `a` field key in the `data` measurement. + +```sql +SELECT ASIN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | asin | +| :------------------- | ------------: | +| 2018-06-24T12:00:00Z | | +| 2018-06-24T12:01:00Z | -0.8866899175 | +| 2018-06-24T12:02:00Z | -1.1707351469 | +| 2018-06-24T12:03:00Z | | +| 2018-06-24T12:04:00Z | -1.1336891235 | +| 2018-06-24T12:05:00Z | -1.0999060761 | +| 2018-06-24T12:06:00Z | | +| 2018-06-24T12:07:00Z | | +| 2018-06-24T12:08:00Z | | +| 2018-06-24T12:09:00Z | 0.4296800058 | +| 2018-06-24T12:10:00Z | 0.3352106652 | +| 2018-06-24T12:11:00Z | 0.2667368202 | +| 2018-06-24T12:12:00Z | -0.2973706144 | + +{{% /expand %}} + +{{% expand "Calculate the arcsine of field values associated with each field key in a measurement" %}} + +Return the arcsine of field values for each field key that stores numeric values in the `data` measurement. +The `data` measurement has one numeric field: `a`. + +```sql +SELECT ASIN(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | asin_a | asin_b | +| :------------------- | ------------: | ------------: | +| 2018-06-24T12:00:00Z | | -0.1643823708 | +| 2018-06-24T12:01:00Z | -0.8866899175 | 0.1374669107 | +| 2018-06-24T12:02:00Z | -1.1707351469 | -0.5040127873 | +| 2018-06-24T12:03:00Z | | -0.0730382136 | +| 2018-06-24T12:04:00Z | -1.1336891235 | | +| 2018-06-24T12:05:00Z | -1.0999060761 | 0.8347779303 | +| 2018-06-24T12:06:00Z | | 0.2917972884 | +| 2018-06-24T12:07:00Z | | -0.5814626386 | +| 2018-06-24T12:08:00Z | | 0.9579524291 | +| 2018-06-24T12:09:00Z | 0.4296800058 | | +| 2018-06-24T12:10:00Z | 0.3352106652 | | +| 2018-06-24T12:11:00Z | 0.2667368202 | -0.1887386424 | +| 2018-06-24T12:12:00Z | -0.2973706144 | -0.9505070998 | + +{{% /expand %}} + +{{% expand "Calculate the arcsine of field values associated with a field key and include several clauses" %}} + +Return the arcsine of field values associated with the `a` field key in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2018-06-24T00:00:00Z` and `2018-06-25T00:00:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT ASIN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | asin | +| :------------------- | -----------: | +| 2018-06-24T23:58:00Z | 0.0346909907 | +| 2018-06-24T23:57:00Z | | +| 2018-06-24T23:56:00Z | 1.0496886453 | +| 2018-06-24T23:55:00Z | 0.0768987583 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ASIN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ASIN()` function to those results. + +`ASIN()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the arcsine of mean values" %}} + +Return the arcsine of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `a`s that are calculated at 3-hour intervals. + +```sql +SELECT ASIN(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | asin | +| :------------------- | ------------: | +| 2018-06-24T00:00:00Z | | +| 2018-06-24T03:00:00Z | | +| 2018-06-24T06:00:00Z | | +| 2018-06-24T09:00:00Z | | +| 2018-06-24T12:00:00Z | 0.0056360073 | +| 2018-06-24T15:00:00Z | -0.0781141351 | +| 2018-06-24T18:00:00Z | 0.0856667569 | +| 2018-06-24T21:00:00Z | -0.0501938281 | +| 2018-06-25T00:00:00Z | -0.1441346103 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ATAN() + +Returns the arctangent (in radians) of the field value. Field values must be between -1 and 1. + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `ATAN()` with a `GROUP BY time()` clause, see the [Advanced syntax](#advanced-syntax). + +### Basic syntax + +```sql +SELECT ATAN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ATAN(field_key)` +Returns the arctangent of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + + + +`ATAN(*)` +Returns the arctangent of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`ATAN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types) with values between -1 and 1. + +#### Examples + +The examples below use a subset of data from [sample_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a) that only includes field values within the calculable range (-1 to 1) required for the of the `ATAN()` function. + +{{< expand-wrapper >}} + +{{% expand "Calculate the arctangent of field values associated with a field key" %}} + +Return the arctangent of field values in the `a` field key in the `data` measurement. + +```sql +SELECT ATAN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan | +| :------------------- | ------------: | +| 2018-06-24T12:00:00Z | 0.9293622934 | +| 2018-06-24T12:01:00Z | -0.6593001275 | +| 2018-06-24T12:02:00Z | -0.7443170184 | +| 2018-06-24T12:03:00Z | -1.0488818071 | +| 2018-06-24T12:04:00Z | -0.7361091801 | +| 2018-06-24T12:05:00Z | -0.7279122495 | +| 2018-06-24T12:06:00Z | 0.8379907133 | +| 2018-06-24T12:07:00Z | -0.9117032768 | +| 2018-06-24T12:08:00Z | -1.0364006848 | +| 2018-06-24T12:09:00Z | 0.3947172008 | +| 2018-06-24T12:10:00Z | 0.3178167283 | +| 2018-06-24T12:11:00Z | 0.2577231762 | +| 2018-06-24T12:12:00Z | -0.2850291359 | + +{{% /expand %}} + +{{% expand "Calculate the arctangent of field values associated with each field key in a measurement" %}} + +Return the arctangent of field values for each field key that stores numeric values in the `data` measurement--fields `a` and `b`. + +```sql +SELECT ATAN(*) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan_a | atan_b | +| :------------------- | ------------: | ------------: | +| 2018-06-24T12:00:00Z | 0.9293622934 | -0.1622053541 | +| 2018-06-24T12:01:00Z | -0.6593001275 | 0.1361861379 | +| 2018-06-24T12:02:00Z | -0.7443170184 | -0.4499093122 | +| 2018-06-24T12:03:00Z | -1.0488818071 | -0.0728441751 | +| 2018-06-24T12:04:00Z | -0.7361091801 | 1.0585985451 | +| 2018-06-24T12:05:00Z | -0.7279122495 | 0.6378113578 | +| 2018-06-24T12:06:00Z | 0.8379907133 | 0.2801105336 | +| 2018-06-24T12:07:00Z | -0.9117032768 | -0.5022647489 | +| 2018-06-24T12:08:00Z | -1.0364006848 | 0.6856298940 | +| 2018-06-24T12:09:00Z | 0.3947172008 | -0.8711781065 | +| 2018-06-24T12:10:00Z | 0.3178167283 | -0.8273348593 | +| 2018-06-24T12:11:00Z | 0.2577231762 | -0.1854639556 | +| 2018-06-24T12:12:00Z | -0.2850291359 | -0.6830451940 | + +{{% /expand %}} + +{{% expand "Calculate the arctangent of field values associated with a field key and include several clauses" %}} + +Return the arctangent of field values associated with the `a` field key in +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2017-05-01T00:00:00Z` and `2017-05-09T00:00:00Z` and returns results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT ATAN("a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan | +| :------------------- | ------------: | +| 2018-06-24T23:58:00Z | 0.0346701348 | +| 2018-06-24T23:57:00Z | -0.8582372146 | +| 2018-06-24T23:56:00Z | 0.7144341473 | +| 2018-06-24T23:55:00Z | -0.0766723939 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ATAN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ATAN()` function to those results. + +`ATAN()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples of advanced syntax + +{{< expand-wrapper >}} + +{{% expand "Calculate the arctangent of mean values" %}} + +Return the arctangent of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `a`s that are calculated at 3-hour intervals. + +```sql +SELECT ATAN(MEAN("a")) FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(3h) +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan | +| :------------------- | ------------: | +| 2018-06-24T00:00:00Z | | +| 2018-06-24T03:00:00Z | | +| 2018-06-24T06:00:00Z | | +| 2018-06-24T09:00:00Z | | +| 2018-06-24T12:00:00Z | 0.0056359178 | +| 2018-06-24T15:00:00Z | -0.0778769005 | +| 2018-06-24T18:00:00Z | 0.0853541301 | +| 2018-06-24T21:00:00Z | -0.0501307176 | +| 2018-06-25T00:00:00Z | -0.1426603174 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ATAN2() + +Returns the the arctangent of `y/x` in radians. + +### Basic syntax + +```sql +SELECT ATAN2( [ * | | num ], [ | num ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ATAN2(field_key_y, field_key_x)` +Returns the arctangent of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key), `field_key_y`, divided by field values associated with `field_key_x`. + +`ATAN2(*, field_key_x)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) +divided by field values associated with `field_key_x`. + +`ATAN2()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `ATAN2()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use [sample_test.txt](https://gist.github.com/sanderson/244e3dc2d778d5c37783483c6c2b548a). + +{{< expand-wrapper >}} + +{{% expand "Calculate the arctangent of field_key_b over field_key_a" %}} + +Return the arctangents of field values in the `a` field key divided by values in the `b` field key. Both are part of the `data` measurement. + +```sql +SELECT ATAN2("a", "b") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan2 | +| :------------------- | ------------: | +| 2018-06-24T12:00:00Z | 1.6923979639 | +| 2018-06-24T12:01:00Z | -1.3957831900 | +| 2018-06-24T12:02:00Z | -2.0537314089 | +| 2018-06-24T12:03:00Z | -1.6127391493 | +| 2018-06-24T12:04:00Z | -0.4711275404 | +| 2018-06-24T12:05:00Z | -0.8770454978 | +| 2018-06-24T12:06:00Z | 1.3174573347 | +| 2018-06-24T12:07:00Z | -1.9730696643 | +| 2018-06-24T12:08:00Z | -1.1199236554 | +| 2018-06-24T12:09:00Z | 2.8043757212 | +| 2018-06-24T12:10:00Z | 2.8478694533 | +| 2018-06-24T12:11:00Z | 2.1893985296 | +| 2018-06-24T12:12:00Z | -2.7959592806 | + +{{% /expand %}} + +{{% expand "Calculate the arctangent of values associated with each field key in a measurement divided by field_key_a" %}} + +Return the arctangents of all numeric field values in the `data` measurement divided by values in the `a` field key. +The `data` measurement has two numeric fields: `a` and `b`. + +```sql +SELECT ATAN2(*, "a") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan2_a | atan2_b | +| :------------------- | ------------: | ------------: | +| 2018-06-24T12:00:00Z | 0.7853981634 | -0.1216016371 | +| 2018-06-24T12:01:00Z | -2.3561944902 | 2.9665795168 | +| 2018-06-24T12:02:00Z | -2.3561944902 | -2.6586575715 | +| 2018-06-24T12:03:00Z | -2.3561944902 | -3.0996498311 | +| 2018-06-24T12:04:00Z | -2.3561944902 | 2.0419238672 | +| 2018-06-24T12:05:00Z | -2.3561944902 | 2.4478418246 | +| 2018-06-24T12:06:00Z | 0.7853981634 | 0.2533389921 | +| 2018-06-24T12:07:00Z | -2.3561944902 | -2.7393193161 | +| 2018-06-24T12:08:00Z | -2.3561944902 | 2.6907199822 | +| 2018-06-24T12:09:00Z | 0.7853981634 | -1.2335793944 | +| 2018-06-24T12:10:00Z | 0.7853981634 | -1.2770731265 | +| 2018-06-24T12:11:00Z | 0.7853981634 | -0.6186022028 | +| 2018-06-24T12:12:00Z | -2.3561944902 | -1.9164296997 | + +{{% /expand %}} + +{{% expand "Calculate the arctangents of field values and include several clauses" %}} + +Return the arctangent of field values associated with the `a` field key divided +by the `b` field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2018-05-16T12:10:00Z` and `2018-05-16T12:10:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT ATAN2("a", "b") FROM "data" WHERE time >= '2018-06-24T00:00:00Z' AND time <= '2018-06-25T00:00:00Z' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan2 | +| :------------------- | ------------: | +| 2018-06-24T23:58:00Z | 0.0166179004 | +| 2018-06-24T23:57:00Z | -2.3211306482 | +| 2018-06-24T23:56:00Z | 1.8506549463 | +| 2018-06-24T23:55:00Z | -0.0768444917 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ATAN2(, ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ATAN2()` function to those results. + +`ATAN2()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate arctangents of mean values" %}} + +Return the arctangents of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `a`s divided by average `b`s. Averages are calculated at 2-hour intervals. + +```sql +SELECT ATAN2(MEAN("b"), MEAN("a")) FROM "data" WHERE time >= '2018-06-24T12:00:00Z' AND time <= '2018-06-25T00:00:00Z' GROUP BY time(2h) +``` + +{{% influxql/table-meta %}} +name: data +{{% /influxql/table-meta %}} + +| time | atan2 | +| :------------------- | ------------: | +| 2018-06-24T12:00:00Z | -0.8233039154 | +| 2018-06-24T14:00:00Z | 1.6676707651 | +| 2018-06-24T16:00:00Z | 2.3853882606 | +| 2018-06-24T18:00:00Z | -1.0180694195 | +| 2018-06-24T20:00:00Z | -0.2601965301 | +| 2018-06-24T22:00:00Z | 2.1893237434 | +| 2018-06-25T00:00:00Z | -2.5572285037 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## CEIL() + +Returns the subsequent value rounded up to the nearest integer. + +### Basic syntax + +```sql +SELECT CEIL( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`CEIL(field_key)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) rounded up to the nearest integer. + +`CEIL(*)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) rounded up to the nearest integer. + +`CEIL()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `CEIL()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the ceiling of field values associated with a field key" %}} + +Return field values in the `water_level` field key in the `h2o_feet` measurement rounded up to the nearest integer. + +```sql +SELECT CEIL("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ceil | +| :------------------- | -----------: | +| 2019-08-17T00:00:00Z | 3.0000000000 | +| 2019-08-17T00:06:00Z | 3.0000000000 | +| 2019-08-17T00:12:00Z | 3.0000000000 | +| 2019-08-17T00:18:00Z | 3.0000000000 | +| 2019-08-17T00:24:00Z | 3.0000000000 | +| 2019-08-17T00:30:00Z | 3.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the ceiling of field values associated with each field key in a measurement" %}} + +Return field values for each field key that stores numeric values in the `h2o_feet` +measurement rounded up to the nearest integer. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT CEIL(*) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ceil_water_level | +| :------------------- | ---------------: | +| 2019-08-17T00:00:00Z | 3.0000000000 | +| 2019-08-17T00:06:00Z | 3.0000000000 | +| 2019-08-17T00:12:00Z | 3.0000000000 | +| 2019-08-17T00:18:00Z | 3.0000000000 | +| 2019-08-17T00:24:00Z | 3.0000000000 | +| 2019-08-17T00:30:00Z | 3.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the ceiling of field values associated with a field key and include several clauses" %}} + +Return field values associated with the `water_level` field key rounded up to the +nearest integer in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT CEIL("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ceil | +| :------------------- | -----------: | +| 2019-08-17T00:18:00Z | 3.0000000000 | +| 2019-08-17T00:12:00Z | 3.0000000000 | +| 2019-08-17T00:06:00Z | 3.0000000000 | +| 2019-08-17T00:00:00Z | 3.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT CEIL(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `CEIL()` function to those results. + +`CEIL()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate mean values rounded up to the nearest integer" %}} + +Return the [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds them up to the nearest integer. + +```sql +SELECT CEIL(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ceil | +| :------------------- | -----------: | +| 2019-08-17T00:00:00Z | 3.0000000000 | +| 2019-08-17T00:12:00Z | 3.0000000000 | +| 2019-08-17T00:24:00Z | 3.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## COS() + +Returns the cosine of the field value. + +### Basic syntax + +```sql +SELECT COS( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`COS(field_key)` +Returns the cosine of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`COS(*)` +Returns the cosine of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`COS()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `COS()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the cosine of field values associated with a field key" %}} + +Return the cosine of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT COS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cos | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -0.7041346171 | +| 2019-08-18T00:06:00Z | -0.7230474420 | +| 2019-08-18T00:12:00Z | -0.6977155876 | +| 2019-08-18T00:18:00Z | -0.6876182920 | +| 2019-08-18T00:24:00Z | -0.6390047316 | +| 2019-08-18T00:30:00Z | -0.6413094611 | + +{{% /expand %}} + +{{% expand "Calculate the cosine of field values associated with each field key in a measurement" %}} + +Return the cosine of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT COS(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cos_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | -0.7041346171 | +| 2019-08-18T00:06:00Z | -0.7230474420 | +| 2019-08-18T00:12:00Z | -0.6977155876 | +| 2019-08-18T00:18:00Z | -0.6876182920 | +| 2019-08-18T00:24:00Z | -0.6390047316 | +| 2019-08-18T00:30:00Z | -0.6413094611 | + +{{% /expand %}} + +{{% expand "Calculate the cosine of field values associated with a field key and include several clauses" %}} + +Return the cosine of field values associated with the `water_level` field key +in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT COS("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cos | +| :------------------- | ------------: | +| 2019-08-18T00:18:00Z | -0.6876182920 | +| 2019-08-18T00:12:00Z | -0.6977155876 | +| 2019-08-18T00:06:00Z | -0.7230474420 | +| 2019-08-18T00:00:00Z | -0.7041346171 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT COS(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `COS()` function to those results. + +`COS()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the cosine of mean values" %}} + +Return the cosine of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT COS(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cos | +| ---- | --- | +| 2019-08-18T00:00:00Z | -0.7136560605 | +| 2019-08-18T00:12:00Z | -0.6926839105 | +| 2019-08-18T00:24:00Z | -0.6401578165 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## CUMULATIVE_SUM() + +Returns the running total of subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Basic syntax + +```sql +SELECT CUMULATIVE_SUM( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`CUMULATIVE_SUM(field_key)` +Returns the running total of subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`CUMULATIVE_SUM(/regular_expression/)` +Returns the running total of subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`CUMULATIVE_SUM(*)` +Returns the running total of subsequent field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`CUMULATIVE_SUM()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `CUMULATIVE_SUM()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the cumulative sum of the field values associated with a field key" %}} + +Return the running total of the field values in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT CUMULATIVE_SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cumulative_sum | +| :------------------- | -------------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 4.7310000000 | +| 2019-08-18T00:12:00Z | 7.0740000000 | +| 2019-08-18T00:18:00Z | 9.4030000000 | +| 2019-08-18T00:24:00Z | 11.6670000000 | +| 2019-08-18T00:30:00Z | 13.9340000000 | + +{{% /expand %}} + +{{% expand "Calculate the cumulative sum of the field values associated with each field key in a measurement" %}} + +Return the running total of the field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT CUMULATIVE_SUM(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cumulative_sum_water_level | +| :------------------- | -------------------------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 4.7310000000 | +| 2019-08-18T00:12:00Z | 7.0740000000 | +| 2019-08-18T00:18:00Z | 9.4030000000 | +| 2019-08-18T00:24:00Z | 11.6670000000 | +| 2019-08-18T00:30:00Z | 13.9340000000 | + +{{% /expand %}} + +{{% expand "Calculate the cumulative sum of the field values associated with each field key that matches a regular expression" %}} + +Return the running total of the field values for each field key that stores +numeric values and includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT CUMULATIVE_SUM(/water/) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cumulative_sum_water_level | +| :------------------- | -------------------------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 4.7310000000 | +| 2019-08-18T00:12:00Z | 7.0740000000 | +| 2019-08-18T00:18:00Z | 9.4030000000 | +| 2019-08-18T00:24:00Z | 11.6670000000 | +| 2019-08-18T00:30:00Z | 13.9340000000 | + +{{% /expand %}} + +{{% expand "Calculate the cumulative sum of the field values associated with a field key and include several clauses" %}} + +Return the running total of the field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT CUMULATIVE_SUM("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cumulative_sum | +| :------------------- | -------------: | +| 2019-08-18T00:18:00Z | 6.8600000000 | +| 2019-08-18T00:12:00Z | 9.2030000000 | +| 2019-08-18T00:06:00Z | 11.5820000000 | +| 2019-08-18T00:00:00Z | 13.9340000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT CUMULATIVE_SUM(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `CUMULATIVE_SUM()` function to those results. + +`CUMULATIVE_SUM()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the cumulative sum of mean values" %}} + +Return the running total of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT CUMULATIVE_SUM(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | cumulative_sum | +| :------------------- | -------------: | +| 2019-08-18T00:00:00Z | 2.3655000000 | +| 2019-08-18T00:12:00Z | 4.7015000000 | +| 2019-08-18T00:24:00Z | 6.9670000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## DERIVATIVE() + +Returns the rate of change between subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Basic syntax + +```sql +SELECT DERIVATIVE( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +InfluxDB calculates the difference between subsequent field values and converts those results into the rate of change per `unit`. +The `unit` argument is an integer followed by a [duration](/influxdb/v2.4/reference/glossary/#duration) and it is optional. +If the query does not specify the `unit` the unit defaults to one second (`1s`). + +`DERIVATIVE(field_key)` +Returns the rate of change between subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`DERIVATIVE(/regular_expression/)` +Returns the rate of change between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`DERIVATIVE(*)` +Returns the rate of change between subsequent field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples in this section use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the derivative between the field values associated with a field key" %}} + +Return the one-second rate of change between the `water_level` field values in the `h2o_feet` measurement. + +```sql +SELECT DERIVATIVE("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | ------------: | +| 2019-08-18T00:06:00Z | 0.0000750000 | +| 2019-08-18T00:12:00Z | -0.0001000000 | +| 2019-08-18T00:18:00Z | -0.0000388889 | +| 2019-08-18T00:24:00Z | -0.0001805556 | +| 2019-08-18T00:30:00Z | 0.0000083333 | + +The first result (`0.0000750000`) is the one-second rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the one-second rate of change (dividing the difference between the field values' timestamps in seconds (`360s`) by the default unit (`1s`)): + +``` +(2.379 - 2.352) / (360s / 1s) +``` + +{{% /expand %}} + +{{% expand "Calculate the derivative between the field values associated with a field key and specify the unit option" %}} + +Return the six-minute rate of change between the field values in the `water_level` field in the `h2o_feet` measurement. + +```sql +SELECT DERIVATIVE("water_level",6m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | ------------: | +| 2019-08-18T00:06:00Z | 0.0270000000 | +| 2019-08-18T00:12:00Z | -0.0360000000 | +| 2019-08-18T00:18:00Z | -0.0140000000 | +| 2019-08-18T00:24:00Z | -0.0650000000 | +| 2019-08-18T00:30:00Z | 0.0030000000 | + +The first result (`0.0270000000`) is the six-minute rate of change between the first two subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the six-minute rate of change (dividing the difference between the field values' timestamps in minutes (`6m`) by the specified interval (`6m`)): + +``` +(2.379 - 2.352) / (6m / 6m) +``` + +{{% /expand %}} + +{{% expand "Calculate the derivative between the field values associated with each field key in a measurement and specify the unit option" %}} + +Returns three-minute rate of change between the field values associated with each field key that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT DERIVATIVE(*,3m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative_water_level | +| :------------------- | ---------------------: | +| 2019-08-18T00:06:00Z | 0.0135000000 | +| 2019-08-18T00:12:00Z | -0.0180000000 | +| 2019-08-18T00:18:00Z | -0.0070000000 | +| 2019-08-18T00:24:00Z | -0.0325000000 | +| 2019-08-18T00:30:00Z | 0.0015000000 | + +The first result (`0.0135000000`) is the three-minute rate of change between the first two subsequent field values in the raw data. + +InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the three-minute rate of change (dividing the difference between the field values' timestamps in minutes (`6m`) by the specified interval (`3m`)): + +``` +(2.379 - 2.352) / (6m / 3m) +``` + +{{% /expand %}} + +{{% expand "Calculate the derivative between the field values associated with each field key that matches a regular expression and specify the unit option" %}} + +Return the two-minute rate of change between the field values associated with +each field key that stores numeric values and includes the word `water` in the +`h2o_feet` measurement. + +```sql +SELECT DERIVATIVE(/water/,2m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative_water_level | +| :------------------- | ---------------------: | +| 2019-08-18T00:06:00Z | 0.0090000000 | +| 2019-08-18T00:12:00Z | -0.0120000000 | +| 2019-08-18T00:18:00Z | -0.0046666667 | +| 2019-08-18T00:24:00Z | -0.0216666667 | +| 2019-08-18T00:30:00Z | 0.0010000000 | + +The first result (`0.0090000000`) is the two-minute rate of change between the first two subsequent field values in the raw data. + +InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the three-minute rate of change (dividing the difference between the field values' timestamps in minutes (`6m`) by the specified interval (`2m`)): + +``` +(2.379 - 2.352) / (6m / 2m) +``` + +{{% /expand %}} + +{{% expand "Calculate the derivative between the field values associated with a field key and include several clauses" %}} + +Return the one-second rate of change between `water_level` field values in the +`h2o_feet` measurement in [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) the number of points returned to one and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) results by two points. + +```sql +SELECT DERIVATIVE("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 1 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative | +| -------------------- | ------------ | +| 2019-08-18T00:12:00Z | 0.0000388889 | + +The only result (`0.0000388889`) is the one-second rate of change between the relevant subsequent field values in the raw data. InfluxDB calculates the difference between the field values (subtracts the first field value from the second field value) and then normalizes that value to the one-second rate of change (dividing the difference between the field values' timestamps in seconds (`360`) by the specified rate of change (`1s`)): + +``` +(2.379 - 2.352) / (360s / 1s) +``` + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT DERIVATIVE( ([ * | | // ]) [ , ] ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `DERIVATIVE()` function to those results. + +The `unit` argument is an integer followed by a [duration](//influxdb/v2.4/reference/glossary/#duration) and it is optional. +If the query does not specify the `unit` the `unit` defaults to the `GROUP BY time()` interval. +Note that this behavior is different from the [basic syntax's](#basic-syntax-1) default behavior. + +`DERIVATIVE()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples +{{< expand-wrapper >}} + +{{% expand "Calculate the derivative of mean values" %}} + +Return the 12-minute rate of change between [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT DERIVATIVE(MEAN("water_level")) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -0.1375000000 | +| 2019-08-18T00:12:00Z | -0.0295000000 | +| 2019-08-18T00:24:00Z | -0.0705000000 | + +{{% /expand %}} + +{{% expand "Calculate the derivative of mean values and specify the unit option" %}} + +Return the six-minute rate of change between average `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT DERIVATIVE(MEAN("water_level"),6m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | derivative | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -0.0687500000 | +| 2019-08-18T00:12:00Z | -0.0147500000 | +| 2019-08-18T00:24:00Z | -0.0352500000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## DIFFERENCE() + +Returns the result of subtraction between subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Syntax + +```sql +SELECT DIFFERENCE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`DIFFERENCE(field_key)` +Returns the difference between subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`DIFFERENCE(/regular_expression/)` +Returns the difference between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`DIFFERENCE(*)` +Returns the difference between subsequent field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `DIFFERENCE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the difference between the field values associated with a field key" %}} + +Return the difference between the subsequent field values in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT DIFFERENCE("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | difference | +| :------------------- | ------------: | +| 2019-08-18T00:06:00Z | 0.0270000000 | +| 2019-08-18T00:12:00Z | -0.0360000000 | +| 2019-08-18T00:18:00Z | -0.0140000000 | +| 2019-08-18T00:24:00Z | -0.0650000000 | +| 2019-08-18T00:30:00Z | 0.0030000000 | + +{{% /expand %}} + +{{% expand "Calculate the difference between the field values associated with each field key in a measurement" %}} + +Return the difference between the subsequent field values for each field key +that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT DIFFERENCE(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | difference_water_level | +| :------------------- | ---------------------: | +| 2019-08-18T00:06:00Z | 0.0270000000 | +| 2019-08-18T00:12:00Z | -0.0360000000 | +| 2019-08-18T00:18:00Z | -0.0140000000 | +| 2019-08-18T00:24:00Z | -0.0650000000 | +| 2019-08-18T00:30:00Z | 0.0030000000 | + +{{% /expand %}} + +{{% expand "Calculate the difference between the field values associated with each field key that matches a regular expression" %}} + +Return the difference between the subsequent field values for each field key +that stores numeric values and includes the word `water` in the `h2o_feet` measurement. + +```sql +SELECT DIFFERENCE(/water/) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | difference_water_level | +| :------------------- | ---------------------: | +| 2019-08-18T00:06:00Z | 0.0270000000 | +| 2019-08-18T00:12:00Z | -0.0360000000 | +| 2019-08-18T00:18:00Z | -0.0140000000 | +| 2019-08-18T00:24:00Z | -0.0650000000 | +| 2019-08-18T00:30:00Z | 0.0030000000 | + +{{% /expand %}} + +{{% expand "Calculate the difference between the field values associated with a field key and include several clauses" %}} + +```sql +SELECT DIFFERENCE("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 2 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | difference | +| :------------------- | -----------: | +| 2019-08-18T00:12:00Z | 0.0140000000 | +| 2019-08-18T00:06:00Z | 0.0360000000 | + +Return the difference between the subsequent field values in the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +They query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to two and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT DIFFERENCE(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `DIFFERENCE()` function to those results. + +`DIFFERENCE()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the difference between maximum values" %}} + +Return the difference between [maximum](/influxdb/v2.4/query-data/influxql/functions/selectors/#max) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT DIFFERENCE(MAX("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | difference | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -0.2290000000 | +| 2019-08-18T00:12:00Z | -0.0360000000 | +| 2019-08-18T00:24:00Z | -0.0760000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ELAPSED() + +Returns the difference between subsequent [field value's](/influxdb/v2.4/reference/glossary/#field-value) timestamps. + +### Syntax + +```sql +SELECT ELAPSED( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +InfluxDB calculates the difference between subsequent timestamps. +The `unit` option is an integer followed by a [duration](/influxdb/v2.4/reference/glossary/#duration) and it determines the unit of the returned difference. +If the query does not specify the `unit` option the query returns the difference between timestamps in nanoseconds. + +`ELAPSED(field_key)` +Returns the difference between subsequent timestamps associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`ELAPSED(/regular_expression/)` +Returns the difference between subsequent timestamps associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`ELAPSED(*)` +Returns the difference between subsequent timestamps associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`ELAPSED()` supports all field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +#### Examples + +The examples use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the elapsed time between field values associated with a field key" %}} + +Return the elapsed time (in nanoseconds) between subsequent timestamps in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT ELAPSED("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | ----------------------: | +| 2019-08-18T00:06:00Z | 360000000000.0000000000 | +| 2019-08-18T00:12:00Z | 360000000000.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the elapsed time between field values associated with a field key and specify the unit option" %}} + +Return the elapsed time (in minutes) between subsequent timestamps in the `water_level` field key and in the `h2o_feet` measurement. + +```sql +SELECT ELAPSED("water_level",1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | -----------: | +| 2019-08-18T00:06:00Z | 6.0000000000 | +| 2019-08-18T00:12:00Z | 6.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the elapsed time between field values associated with each field key in a measurement and specify the unit option" %}} + +Return the difference (in minutes) between subsequent timestamps associated with +each field key in the `h2o_feet`measurement. +The `h2o_feet` measurement has two field keys: `level description` and `water_level`. + +```sql +SELECT ELAPSED(*,1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed_level description | elapsed_water_level | +| :------------------- | ------------------------: | ------------------: | +| 2019-08-18T00:06:00Z | 6.0000000000 | 6.0000000000 | +| 2019-08-18T00:12:00Z | 6.0000000000 | 6.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the elapsed time between field values associated with each field key that matches a regular expression and specify the unit option" %}} + +Return the difference (in seconds) between subsequent timestamps associated with +each field key that includes the word `level` in the `h2o_feet` measurement. + +```sql +SELECT ELAPSED(/level/,1s) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed_level description | elapsed_water_level | +| :------------------- | ------------------------: | ------------------: | +| 2019-08-18T00:06:00Z | 360.0000000000 | 360.0000000000 | +| 2019-08-18T00:12:00Z | 360.0000000000 | 360.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the elapsed time between field values associated with a field key and include several clauses" %}} + +Return the difference (in milliseconds) between subsequent timestamps in the +`water_level` field key and in the `h2o_feet` measurement in the +[time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-17T00:00:00Z` and `2019-08-17T00:12:00Z` with timestamps in +[descending order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to one and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by one point. + +```sql +SELECT ELAPSED("water_level",1ms) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' ORDER BY time DESC LIMIT 1 OFFSET 1 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | -----------------: | +| 2019-08-18T00:00:00Z | -360000.0000000000 | + +Notice that the result is negative; the [`ORDER BY time DESC` clause](/influxdb/v2.4/query-data/influxql/explore-data/order-by/) sorts timestamps in descending order so `ELAPSED()` calculates the difference between timestamps in reverse order. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Common issues with ELAPSED() + +#### ELAPSED() and units greater than the elapsed time + +InfluxDB returns `0` if the `unit` option is greater than the difference between the timestamps. + +##### Example + +The timestamps in the `h2o_feet` measurement occur at six-minute intervals. +If the query sets the `unit` option to one hour, InfluxDB returns `0`: + +```sql +SELECT ELAPSED("water_level",1h) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:12:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | -----------: | +| 2019-08-18T00:06:00Z | 0.0000000000 | +| 2019-08-18T00:12:00Z | 0.0000000000 | + +#### ELAPSED() with GROUP BY time() clauses + +The `ELAPSED()` function supports the [`GROUP BY time()` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) but the query results aren't particularly useful. +Currently, an `ELAPSED()` query with a nested function and a `GROUP BY time()` clause simply returns the interval specified in the `GROUP BY time()` clause. + +The `GROUP BY time()` clause determines the timestamps in the results; each timestamp marks the start of a time interval. +That behavior also applies to nested selector functions (like [`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first) or [`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max)) which would, in all other cases, return a specific timestamp from the raw data. +Because the `GROUP BY time()` clause overrides the original timestamps, the `ELAPSED()` calculation always returns the same value as the `GROUP BY time()` interval. + +##### Example + +In the codeblock below, the first query attempts to use the `ELAPSED()` function with a `GROUP BY time()` clause to find the time elapsed (in minutes) between [minimum](/influxdb/v2.4/query-data/influxql/functions/selectors/#min) `water_level`s. +Returns 12 minutes for both time intervals. + +To get those results, InfluxDB first calculates the minimum `water_level`s at 12-minute intervals. +The second query in the codeblock shows the results of that step. +The step is the same as using the `MIN()` function with the `GROUP BY time()` clause and without the `ELAPSED()` function. +Notice that the timestamps returned by the second query are 12 minutes apart. +In the raw data, the first result (`2.0930000000`) occurs at `2019-08-18T00:42:00Z` but the `GROUP BY time()` clause overrides that original timestamp. +Because the timestamps are determined by the `GROUP BY time()` interval and not by the original data, the `ELAPSED()` calculation always returns the same value as the `GROUP BY time()` interval. + +```sql +SELECT ELAPSED(MIN("water_level"),1m) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:36:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | elapsed | +| :------------------- | ------------: | +| 2019-08-18T00:36:00Z | 12.0000000000 | +| 2019-08-18T00:48:00Z | 12.0000000000 | + +```sql +SELECT MIN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:36:00Z' AND time <= '2019-08-18T00:54:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | min | +| -------------------- | ------------ | +| 2019-08-18T00:36:00Z | 2.0930000000 | +| 2019-08-18T00:48:00Z | 2.0870000000 | + +{{% note %}} +The first point actually occurs at 2019-08-18T00:42:00Z, not 2019-08-18T00:36:00Z. +{{% /note %}} + +## EXP() + +Returns the exponential of the field value. + +### Syntax + +```sql +SELECT EXP( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`EXP(field_key)` +Returns the exponential of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + + + +`EXP(*)` +Returns the exponential of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`EXP()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `EXP()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the exponential of field values associated with a field key" %}} + +Return the exponential of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT EXP("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | exp | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | 10.5065618493 | +| 2019-08-18T00:06:00Z | 10.7941033617 | +| 2019-08-18T00:12:00Z | 10.4124270347 | +| 2019-08-18T00:18:00Z | 10.2676687288 | +| 2019-08-18T00:24:00Z | 9.6214982905 | +| 2019-08-18T00:30:00Z | 9.6504061254 | + +{{% /expand %}} + +{{% expand "Calculate the exponential of field values associated with each field key in a measurement" %}} + +Return the exponential of field values for each field key that stores numeric +values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT EXP(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | exp_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | 10.5065618493 | +| 2019-08-18T00:06:00Z | 10.7941033617 | +| 2019-08-18T00:12:00Z | 10.4124270347 | +| 2019-08-18T00:18:00Z | 10.2676687288 | +| 2019-08-18T00:24:00Z | 9.6214982905 | +| 2019-08-18T00:30:00Z | 9.6504061254 | + +{{% /expand %}} + +{{% expand "Calculate the exponential of field values associated with a field key and include several clauses" %}} + +```sql +SELECT EXP("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | exp | +| :------------------- | ------------: | +| 2019-08-18T00:18:00Z | 10.2676687288 | +| 2019-08-18T00:12:00Z | 10.4124270347 | +| 2019-08-18T00:06:00Z | 10.7941033617 | +| 2019-08-18T00:00:00Z | 10.5065618493 | + +Return the exponentials of field values associated with the `water_level` field key in +the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT EXP(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `EXP()` function to those results. + +`EXP()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the exponential of mean values" %}} + +Return the exponential of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT EXP(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | exp | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | 10.6493621676 | +| 2019-08-18T00:12:00Z | 10.3397945558 | +| 2019-08-18T00:24:00Z | 9.6359413675 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## FLOOR() + +Returns the subsequent value rounded down to the nearest integer. + +### Syntax + +```sql +SELECT FLOOR( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`FLOOR(field_key)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) rounded down to the nearest integer. + +`FLOOR(*)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) rounded down to the nearest integer. + +`FLOOR()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `FLOOR()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the floor of field values associated with a field key" %}} + +Return field values in the `water_level` field key in the `h2o_feet` measurement rounded down to the nearest integer. + +```sql +SELECT FLOOR("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | floor | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | +| 2019-08-18T00:30:00Z | 2.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the floor of field values associated with each field key in a measurement" %}} + +Return field values for each field key that stores numeric values in the +`h2o_feet` measurement rounded down to the nearest integer. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT FLOOR(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | floor_water_level | +| :------------------- | ----------------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | +| 2019-08-18T00:30:00Z | 2.0000000000 | + +{{% /expand %}} + +{{% expand "Calculate the floor of field values associated with a field key and include several clauses" %}} + +Return field values associated with the `water_level` field key rounded down to +the nearest integer in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT FLOOR("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | floor | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:00:00Z | 2.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT FLOOR(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `FLOOR()` function to those results. + +`FLOOR()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate mean values rounded down to the nearest integer" %}} + +Return the [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds them up to the nearest integer. + +```sql +SELECT FLOOR(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | floor | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## HISTOGRAM() + +_InfluxQL does not currently support histogram generation. +For information about creating histograms with data stored in InfluxDB, see +[Flux's `histogram()` function](/{{< latest "flux" >}}/stdlib/universe/histogram)._ + +## LN() + +Returns the natural logarithm of the field value. + +### Syntax + +```sql +SELECT LN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`LN(field_key)` +Returns the natural logarithm of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`LN(*)` +Returns the natural logarithm of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`LN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `LN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the natural logarithm of field values associated with a field key" %}} + +Return the natural logarithm of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT LN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ln | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.8552660300 | +| 2019-08-18T00:06:00Z | 0.8666802313 | +| 2019-08-18T00:12:00Z | 0.8514321595 | +| 2019-08-18T00:18:00Z | 0.8454389909 | +| 2019-08-18T00:24:00Z | 0.8171331603 | +| 2019-08-18T00:30:00Z | 0.8184573715 | + +{{% /expand %}} + +{{% expand "Calculate the natural logarithm of field values associated with each field key in a measurement" %}} + +Return the natural logarithm of field values for each field key that stores +numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT LN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ln_water_level | +| :------------------- | -------------: | +| 2019-08-18T00:00:00Z | 0.8552660300 | +| 2019-08-18T00:06:00Z | 0.8666802313 | +| 2019-08-18T00:12:00Z | 0.8514321595 | +| 2019-08-18T00:18:00Z | 0.8454389909 | +| 2019-08-18T00:24:00Z | 0.8171331603 | +| 2019-08-18T00:30:00Z | 0.8184573715 | + +{{% /expand %}} + +{{% expand "Calculate the natural logarithm of field values associated with a field key and include several clauses" %}} + +```sql +SELECT LN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ln | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 0.8454389909 | +| 2019-08-18T00:12:00Z | 0.8514321595 | +| 2019-08-18T00:06:00Z | 0.8666802313 | +| 2019-08-18T00:00:00Z | 0.8552660300 | + +Return the natural logarithms of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT LN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LN()` function to those results. + +`LN()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the natural logarithm of mean values" %}} + +Return the natural logarithm of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT LN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | ln | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.8609894161 | +| 2019-08-18T00:12:00Z | 0.8484400650 | +| 2019-08-18T00:24:00Z | 0.8177954851 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## LOG() + +Returns the logarithm of the field value with base `b`. + +### Basic syntax + +```sql +SELECT LOG( [ * | ], ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`LOG(field_key, b)` +Returns the logarithm of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) with base `b`. + +`LOG(*, b)` +Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) with base `b`. + +`LOG()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `LOG()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 4 of field values associated with a field key" %}} + +Return the logarithm base 4 of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT LOG("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.6169440301 | +| 2019-08-18T00:06:00Z | 0.6251776359 | +| 2019-08-18T00:12:00Z | 0.6141784771 | +| 2019-08-18T00:18:00Z | 0.6098553198 | +| 2019-08-18T00:24:00Z | 0.5894369791 | +| 2019-08-18T00:30:00Z | 0.5903921955 | + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 4 of field values associated with each field key in a measurement" %}} + +Return the logarithm base 4 of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT LOG(*, 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | 0.6169440301 | +| 2019-08-18T00:06:00Z | 0.6251776359 | +| 2019-08-18T00:12:00Z | 0.6141784771 | +| 2019-08-18T00:18:00Z | 0.6098553198 | +| 2019-08-18T00:24:00Z | 0.5894369791 | +| 2019-08-18T00:30:00Z | 0.5903921955 | + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 4 of field values associated with a field key and include several clauses" %}} + +Return the logarithm base 4 of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT LOG("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 0.6098553198 | +| 2019-08-18T00:12:00Z | 0.6141784771 | +| 2019-08-18T00:06:00Z | 0.6251776359 | +| 2019-08-18T00:00:00Z | 0.6169440301 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT LOG(( [ * | ] ), ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG()` function to those results. + +`LOG()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 4 of mean values" %}} + +Return the logarithm base 4 of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT LOG(MEAN("water_level"), 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.6210725804 | +| 2019-08-18T00:12:00Z | 0.6120201371 | +| 2019-08-18T00:24:00Z | 0.5899147454 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## LOG2() + +Returns the logarithm of the field value to the base 2. + +### Basic syntax + +```sql +SELECT LOG2( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`LOG2(field_key)` +Returns the logarithm of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) to the base 2. + +`LOG2(*)` +Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) to the base 2. + +`LOG2()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `LOG2()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 2 of field values associated with a field key" %}} + +Return the logarithm base 2 of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT LOG2("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log2 | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.2338880602 | +| 2019-08-18T00:06:00Z | 1.2503552718 | +| 2019-08-18T00:12:00Z | 1.2283569542 | +| 2019-08-18T00:18:00Z | 1.2197106395 | +| 2019-08-18T00:24:00Z | 1.1788739582 | +| 2019-08-18T00:30:00Z | 1.1807843911 | + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 2 of field values associated with each field key in a measurement" %}} + +```sql +SELECT LOG2(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log2_water_level | +| :------------------- | ---------------: | +| 2019-08-18T00:00:00Z | 1.2338880602 | +| 2019-08-18T00:06:00Z | 1.2503552718 | +| 2019-08-18T00:12:00Z | 1.2283569542 | +| 2019-08-18T00:18:00Z | 1.2197106395 | +| 2019-08-18T00:24:00Z | 1.1788739582 | +| 2019-08-18T00:30:00Z | 1.1807843911 | + +Return the logarithm base 2 of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 2 of field values associated with a field key and include several clauses" %}} + +Return the logarithm base 2 of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT LOG2("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log2 | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 1.2197106395 | +| 2019-08-18T00:12:00Z | 1.2283569542 | +| 2019-08-18T00:06:00Z | 1.2503552718 | +| 2019-08-18T00:00:00Z | 1.2338880602 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT LOG2(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG2()` function to those results. + +`LOG2()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 2 of mean values" %}} + +Return the logarithm base 2 of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT LOG2(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log2 | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.2421451608 | +| 2019-08-18T00:12:00Z | 1.2240402742 | +| 2019-08-18T00:24:00Z | 1.1798294909 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## LOG10() + +Returns the logarithm of the field value to the base 10. + +### Basic syntax + +```sql +SELECT LOG10( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`LOG10(field_key)` +Returns the logarithm of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) to the base 10. + +`LOG10(*)` +Returns the logarithm of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) to the base 10. + +`LOG10()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `LOG10()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 10 of field values associated with a field key" %}} + +Return the logarithm base 10 of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT LOG10("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log10 | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.3714373174 | +| 2019-08-18T00:06:00Z | 0.3763944420 | +| 2019-08-18T00:12:00Z | 0.3697722886 | +| 2019-08-18T00:18:00Z | 0.3671694885 | +| 2019-08-18T00:24:00Z | 0.3548764225 | +| 2019-08-18T00:30:00Z | 0.3554515201 | + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 10 of field values associated with each field key in a measurement" %}} + +Return the logarithm base 10 of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT LOG10(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log10_water_level | +| :------------------- | ----------------: | +| 2019-08-18T00:00:00Z | 0.3714373174 | +| 2019-08-18T00:06:00Z | 0.3763944420 | +| 2019-08-18T00:12:00Z | 0.3697722886 | +| 2019-08-18T00:18:00Z | 0.3671694885 | +| 2019-08-18T00:24:00Z | 0.3548764225 | +| 2019-08-18T00:30:00Z | 0.3554515201 | + +{{% /expand %}} + +{{% expand "Calculate the logarithm base 10 of field values associated with a field key and include several clauses" %}} + +Return the logarithm base 10 of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT LOG10("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log10 | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 0.3671694885 | +| 2019-08-18T00:12:00Z | 0.3697722886 | +| 2019-08-18T00:06:00Z | 0.3763944420 | +| 2019-08-18T00:00:00Z | 0.3714373174 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT LOG10(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `LOG10()` function to those results. + +`LOG10()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the logarithm base 10 of mean values" %}} + +Return the logarithm base 10 of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT LOG10(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | log10 | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.3739229524 | +| 2019-08-18T00:12:00Z | 0.3684728384 | +| 2019-08-18T00:24:00Z | 0.3551640665 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## MOVING_AVERAGE() + +Returns the rolling average across a window of subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). + +### Basic syntax + +```sql +SELECT MOVING_AVERAGE( [ * | | // ] , ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`MOVING_AVERAGE()` calculates the rolling average across a window of `N` subsequent field values. +The `N` argument is an integer and it is required. + +`MOVING_AVERAGE(field_key,N)` +Returns the rolling average across `N` field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`MOVING_AVERAGE(/regular_expression/,N)` +Returns the rolling average across `N` field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`MOVING_AVERAGE(*,N)` +Returns the rolling average across `N` field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`MOVING_AVERAGE()` int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `MOVING_AVERAGE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the moving average of the field values associated with a field key" %}} + +Return the rolling average across a two-field-value window for the `water_level` field key and the `h2o_feet` measurement. + +```sql +SELECT MOVING_AVERAGE("water_level",2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | moving_average | +| :------------------- | -------------: | +| 2019-08-18T00:06:00Z | 2.3655000000 | +| 2019-08-18T00:12:00Z | 2.3610000000 | +| 2019-08-18T00:18:00Z | 2.3360000000 | +| 2019-08-18T00:24:00Z | 2.2965000000 | +| 2019-08-18T00:30:00Z | 2.2655000000 | + +The first result (`2.3655000000`) is the average of the first two points in the raw data: (`2.3520000000 + 2.3790000000) / 2`). +The second result (`2.3610000000`) is the average of the second two points in the raw data: (`2.3790000000 + 2.3430000000) / 2`). + +{{% /expand %}} + +{{% expand "Calculate the moving average of the field values associated with each field key in a measurement" %}} + +Return the rolling average across a three-field-value window for each field key +that stores numeric values in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT MOVING_AVERAGE(*,3) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | moving_average_water_level | +| :------------------- | -------------------------: | +| 2019-08-18T00:12:00Z | 2.3580000000 | +| 2019-08-18T00:18:00Z | 2.3503333333 | +| 2019-08-18T00:24:00Z | 2.3120000000 | +| 2019-08-18T00:30:00Z | 2.2866666667 | + +{{% /expand %}} + +{{% expand "Calculate the moving average of the field values associated with each field key that matches a regular expression" %}} + +Return the rolling average across a four-field-value window for each numeric +field with a field key that includes the word `level` in the `h2o_feet` measurement. + +```sql +SELECT MOVING_AVERAGE(/level/,4) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | moving_average_water_level | +| :------------------- | -------------------------: | +| 2019-08-18T00:18:00Z | 2.3507500000 | +| 2019-08-18T00:24:00Z | 2.3287500000 | +| 2019-08-18T00:30:00Z | 2.3007500000 | + +{{% /expand %}} + +{{% expand "Calculate the moving average of the field values associated with a field key and include several clauses" %}} + +Return the rolling average across a two-field-value window for the `water_level` +field key in the `h2o_feet` measurement in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to two and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by three points. + +```sql +SELECT MOVING_AVERAGE("water_level",2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' ORDER BY time DESC LIMIT 2 OFFSET 3 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | moving_average | +| :------------------- | -------------: | +| 2019-08-18T00:06:00Z | 2.3610000000 | +| 2019-08-18T00:00:00Z | 2.3655000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT MOVING_AVERAGE( ([ * | | // ]) , N ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `MOVING_AVERAGE()` function to those results. + +`MOVING_AVERAGE()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the moving average of maximum values" %}} + +Return the rolling average across a two-value window of [maximum](/influxdb/v2.4/query-data/influxql/functions/selectors/#max) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT MOVING_AVERAGE(MAX("water_level"),2) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | moving_average | +| :------------------- | -------------: | +| 2019-08-18T00:00:00Z | 2.4935000000 | +| 2019-08-18T00:12:00Z | 2.3610000000 | +| 2019-08-18T00:24:00Z | 2.3050000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## NON_NEGATIVE_DERIVATIVE() + +Returns the non-negative rate of change between subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). +Non-negative rates of change include positive rates of change and rates of change that equal zero. + +### Basic syntax + +```sql +SELECT NON_NEGATIVE_DERIVATIVE( [ * | | // ] [ , ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +InfluxDB calculates the difference between subsequent field values and converts those results into the rate of change per `unit`. +The `unit` argument is an integer followed by a [duration](/influxdb/v2.4/reference/glossary/#duration) and it is optional. +If the query does not specify the `unit`, the unit defaults to one second (`1s`). +`NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. + +`NON_NEGATIVE_DERIVATIVE(field_key)` +Returns the non-negative rate of change between subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`NON_NEGATIVE_DERIVATIVE(/regular_expression/)` +Returns the non-negative rate of change between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`NON_NEGATIVE_DERIVATIVE(*)` +Returns the non-negative rate of change between subsequent field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`NON_NEGATIVE_DERIVATIVE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `NON_NEGATIVE_DERIVATIVE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +See the examples in the [`DERIVATIVE()` documentation](#basic-syntax-8). +`NON_NEGATIVE_DERIVATIVE()` behaves the same as the `DERIVATIVE()` function but `NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. + +### Advanced syntax + +```sql +SELECT NON_NEGATIVE_DERIVATIVE( ([ * | | // ]) [ , ] ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `NON_NEGATIVE_DERIVATIVE()` function to those results. + +The `unit` argument is an integer followed by a [duration](/influxdb/v2.4/reference/glossary/#duration) and it is optional. +If the query does not specify the `unit`, the `unit` defaults to the `GROUP BY time()` interval. +Note that this behavior is different from the [basic syntax's](#basic-syntax-4) default behavior. +`NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. + +`NON_NEGATIVE_DERIVATIVE()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +See the examples in the [`DERIVATIVE()` documentation](#advanced-syntax-8). +`NON_NEGATIVE_DERIVATIVE()` behaves the same as the `DERIVATIVE()` function but `NON_NEGATIVE_DERIVATIVE()` returns only positive rates of change or rates of change that equal zero. + +## NON_NEGATIVE_DIFFERENCE() + +Returns the non-negative result of subtraction between subsequent [field values](/influxdb/v2.4/reference/glossary/#field-value). +Non-negative results of subtraction include positive differences and differences that equal zero. + +### Basic syntax + +```sql +SELECT NON_NEGATIVE_DIFFERENCE( [ * | | // ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`NON_NEGATIVE_DIFFERENCE(field_key)` +Returns the non-negative difference between subsequent field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`NON_NEGATIVE_DIFFERENCE(/regular_expression/)` +Returns the non-negative difference between subsequent field values associated with each field key that matches the [regular expression](/influxdb/v2.4/query-data/influxql/explore-data/regular-expressions/). + +`NON_NEGATIVE_DIFFERENCE(*)` +Returns the non-negative difference between subsequent field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`NON_NEGATIVE_DIFFERENCE()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `NON_NEGATIVE_DIFFERENCE()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +See the examples in the [`DIFFERENCE()` documentation](#basic-syntax-9). +`NON_NEGATIVE_DIFFERENCE()` behaves the same as the `DIFFERENCE()` function but `NON_NEGATIVE_DIFFERENCE()` returns only positive differences or differences that equal zero. + +### Advanced syntax + +```sql +SELECT NON_NEGATIVE_DIFFERENCE(( [ * | | // ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `NON_NEGATIVE_DIFFERENCE()` function to those results. + +`NON_NEGATIVE_DIFFERENCE()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +See the examples in the [`DIFFERENCE()` documentation](#advanced-syntax-9). +`NON_NEGATIVE_DIFFERENCE()` behaves the same as the `DIFFERENCE()` function but `NON_NEGATIVE_DIFFERENCE()` returns only positive differences or differences that equal zero. + +## POW() + +Returns the field value to the power of `x`. + +### Basic syntax + +```sql +SELECT POW( [ * | ], ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`POW(field_key, x)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) to the power of `x`. + +`POW(*, x)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) to the power of `x`. + +`POW()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `POW()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate field values associated with a field key to the power of 4" %}} + +Return field values in the `water_level` field key in the `h2o_feet` measurement +multiplied to a power of 4. + +```sql +SELECT POW("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | pow | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | 30.6019618652 | +| 2019-08-18T00:06:00Z | 32.0315362489 | +| 2019-08-18T00:12:00Z | 30.1362461432 | +| 2019-08-18T00:18:00Z | 29.4223904261 | +| 2019-08-18T00:24:00Z | 26.2727594844 | +| 2019-08-18T00:30:00Z | 26.4122914255 | + +{{% /expand %}} + +{{% expand "Calculate field values associated with each field key in a measurement to the power of 4" %}} + +Return field values for each field key that stores numeric values in the `h2o_feet` measurement multiplied to the power of 4. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT POW(*, 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | pow_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | 30.6019618652 | +| 2019-08-18T00:06:00Z | 32.0315362489 | +| 2019-08-18T00:12:00Z | 30.1362461432 | +| 2019-08-18T00:18:00Z | 29.4223904261 | +| 2019-08-18T00:24:00Z | 26.2727594844 | +| 2019-08-18T00:30:00Z | 26.4122914255 | + +{{% /expand %}} + +{{% expand "Calculate field values associated with a field key to the power of 4 and include several clauses" %}} + +Return field values associated with the `water_level` field key multiplied to +the power of 4 in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT POW("water_level", 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | pow | +| :------------------- | ------------: | +| 2019-08-18T00:18:00Z | 29.4223904261 | +| 2019-08-18T00:12:00Z | 30.1362461432 | +| 2019-08-18T00:06:00Z | 32.0315362489 | +| 2019-08-18T00:00:00Z | 30.6019618652 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT POW(( [ * | ] ), ) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `POW()` function to those results. + +`POW()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate mean values to the power of 4" %}} + +Return [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals multiplied to the power of 4. + +```sql +SELECT POW(MEAN("water_level"), 4) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | pow | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | 31.3106302459 | +| 2019-08-18T00:12:00Z | 29.7777139548 | +| 2019-08-18T00:24:00Z | 26.3424561663 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## ROUND() + +Returns the subsequent value rounded to the nearest integer. + +### Basic syntax + +```sql +SELECT ROUND( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`ROUND(field_key)` +Returns the field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key) rounded to the nearest integer. + +`ROUND(*)` +Returns the field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement) rounded to the nearest integer. + +`ROUND()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/. To use `ROUND()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Round field values associated with a field key" %}} + +Return field values in the `water_level` field key in the `h2o_feet` measurement +rounded to the nearest integer. + +```sql +SELECT ROUND("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | round | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | +| 2019-08-18T00:30:00Z | 2.0000000000 | + +{{% /expand %}} + +{{% expand "Round field values associated with each field key in a measurement" %}} + +Return field values for each numeric field in the `h2o_feet` measurement rounded to the nearest integer. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT ROUND(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | round_water_level | +| :------------------- | ----------------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | +| 2019-08-18T00:30:00Z | 2.0000000000 | + +{{% /expand %}} + +{{% expand "Round field values associated with a field key and include several clauses" %}} + +Return field values associated with the `water_level` field key rounded to the +nearest integer in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT ROUND("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | round | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:06:00Z | 2.0000000000 | +| 2019-08-18T00:00:00Z | 2.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT ROUND(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `ROUND()` function to those results. + +`ROUND()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate mean values rounded to the nearest integer" %}} + +Return the [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals and rounds to the nearest integer. + +```sql +SELECT ROUND(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | round | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.0000000000 | +| 2019-08-18T00:12:00Z | 2.0000000000 | +| 2019-08-18T00:24:00Z | 2.0000000000 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## SIN() + +Returns the sine of the field value. + +### Basic syntax + +```sql +SELECT SIN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`SIN(field_key)` +Returns the sine of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`SIN(*)` +Returns the sine of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`SIN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `SIN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the sine of field values associated with a field key" %}} + +Return the sine of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT SIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sin | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.7100665046 | +| 2019-08-18T00:06:00Z | 0.6907983763 | +| 2019-08-18T00:12:00Z | 0.7163748731 | +| 2019-08-18T00:18:00Z | 0.7260723687 | +| 2019-08-18T00:24:00Z | 0.7692028035 | +| 2019-08-18T00:30:00Z | 0.7672823308 | + +{{% /expand %}} + +{{% expand "Calculate the sine of field values associated with each field key in a measurement" %}} + +Return the sine of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT SIN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sin_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | 0.7100665046 | +| 2019-08-18T00:06:00Z | 0.6907983763 | +| 2019-08-18T00:12:00Z | 0.7163748731 | +| 2019-08-18T00:18:00Z | 0.7260723687 | +| 2019-08-18T00:24:00Z | 0.7692028035 | +| 2019-08-18T00:30:00Z | 0.7672823308 | + +{{% /expand %}} + +{{% expand "Calculate the sine of field values associated with a field key and include several clauses" %}} + +Return the sine of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT SIN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sin | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 0.7260723687 | +| 2019-08-18T00:12:00Z | 0.7163748731 | +| 2019-08-18T00:06:00Z | 0.6907983763 | +| 2019-08-18T00:00:00Z | 0.7100665046 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT SIN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `SIN()` function to those results. + +`SIN()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the sine of mean values" %}} + +Return the sine of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT SIN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sin | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 0.7004962722 | +| 2019-08-18T00:12:00Z | 0.7212412912 | +| 2019-08-18T00:24:00Z | 0.7682434314 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## SQRT() + +Returns the square root of field value. + +### Basic syntax + +```sql +SELECT SQRT( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`SQRT(field_key)` +Returns the square root of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`SQRT(*)` +Returns the square root field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`SQRT()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `SQRT()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the square root of field values associated with a field key" %}} + +Return the square roots of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT SQRT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sqrt | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.5336231610 | +| 2019-08-18T00:06:00Z | 1.5424007261 | +| 2019-08-18T00:12:00Z | 1.5306861207 | +| 2019-08-18T00:18:00Z | 1.5261061562 | +| 2019-08-18T00:24:00Z | 1.5046594299 | +| 2019-08-18T00:30:00Z | 1.5056560032 | + +{{% /expand %}} + +{{% expand "Calculate the square root of field values associated with each field key in a measurement" %}} + +Return the square roots of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT SQRT(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sqrt_water_level | +| :------------------- | ---------------: | +| 2019-08-18T00:00:00Z | 1.5336231610 | +| 2019-08-18T00:06:00Z | 1.5424007261 | +| 2019-08-18T00:12:00Z | 1.5306861207 | +| 2019-08-18T00:18:00Z | 1.5261061562 | +| 2019-08-18T00:24:00Z | 1.5046594299 | +| 2019-08-18T00:30:00Z | 1.5056560032 | + +{{% /expand %}} + +{{% expand "Calculate the square root of field values associated with a field key and include several clauses" %}} + +Return the square roots of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT SQRT("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sqrt | +| :------------------- | -----------: | +| 2019-08-18T00:18:00Z | 1.5261061562 | +| 2019-08-18T00:12:00Z | 1.5306861207 | +| 2019-08-18T00:06:00Z | 1.5424007261 | +| 2019-08-18T00:00:00Z | 1.5336231610 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT SQRT(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `SQRT()` function to those results. + +`SQRT()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the square root of mean values" %}} + +Return the square roots of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT SQRT(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | sqrt | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 1.5380182054 | +| 2019-08-18T00:12:00Z | 1.5283978540 | +| 2019-08-18T00:24:00Z | 1.5051577990 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +## TAN() + +Returns the tangent of the field value. + +### Basic syntax + +```sql +SELECT TAN( [ * | ] ) FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +`TAN(field_key)` +Returns the tangent of field values associated with the [field key](/influxdb/v2.4/reference/glossary/#field-key). + +`TAN(*)` +Returns the tangent of field values associated with each field key in the [measurement](/influxdb/v2.4/reference/glossary/#measurement). + +`TAN()` supports int64 and float64 field value [data types](/influxdb/v2.4/query-data/influxql/explore-data/select/#data-types). + +Supports `GROUP BY` clauses that [group by tags](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-tags) but not `GROUP BY` clauses that [group by time](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals). +To use `TAN()` with a `GROUP BY time()` clause, see [Advanced syntax](#advanced-syntax). + +#### Examples + +The examples below use the following subsample of the [NOAA water sample data](/influxdb/v2.4/reference/sample-data/#noaa-water-sample-data): + +```sql +SELECT "water_level" FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | water_level | +| :------------------- | -----------: | +| 2019-08-18T00:00:00Z | 2.3520000000 | +| 2019-08-18T00:06:00Z | 2.3790000000 | +| 2019-08-18T00:12:00Z | 2.3430000000 | +| 2019-08-18T00:18:00Z | 2.3290000000 | +| 2019-08-18T00:24:00Z | 2.2640000000 | +| 2019-08-18T00:30:00Z | 2.2670000000 | + +{{< expand-wrapper >}} + +{{% expand "Calculate the tangent of field values associated with a field key" %}} + +Return the tangent of field values in the `water_level` field key in the `h2o_feet` measurement. + +```sql +SELECT TAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | tan | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -1.0084243657 | +| 2019-08-18T00:06:00Z | -0.9553984098 | +| 2019-08-18T00:12:00Z | -1.0267433979 | +| 2019-08-18T00:18:00Z | -1.0559235802 | +| 2019-08-18T00:24:00Z | -1.2037513424 | +| 2019-08-18T00:30:00Z | -1.1964307053 | + +{{% /expand %}} + +{{% expand "Calculate the tangent of field values associated with each field key in a measurement" %}} + +Return the tangent of field values for each numeric field in the `h2o_feet` measurement. +The `h2o_feet` measurement has one numeric field: `water_level`. + +```sql +SELECT TAN(*) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | tan_water_level | +| :------------------- | --------------: | +| 2019-08-18T00:00:00Z | -1.0084243657 | +| 2019-08-18T00:06:00Z | -0.9553984098 | +| 2019-08-18T00:12:00Z | -1.0267433979 | +| 2019-08-18T00:18:00Z | -1.0559235802 | +| 2019-08-18T00:24:00Z | -1.2037513424 | +| 2019-08-18T00:30:00Z | -1.1964307053 | + +{{% /expand %}} + +{{% expand "Calculate the tangent of field values associated with a field key and include several clauses" %}} + +Return the tangent of field values associated with the `water_level` +field key in the [time range](/influxdb/v2.4/query-data/influxql/explore-data/time-and-timezone/#time-syntax) +between `2019-08-18T00:00:00Z` and `2019-08-18T00:30:00Z` with results in +[descending timestamp order](/influxdb/v2.4/query-data/influxql/explore-data/order-by/). +The query also [limits](/influxdb/v2.4/query-data/influxql/explore-data/limit-and-slimit/) +the number of points returned to four and [offsets](/influxdb/v2.4/query-data/influxql/explore-data/offset-and-soffset/) +results by two points. + +```sql +SELECT TAN("water_level") FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' ORDER BY time DESC LIMIT 4 OFFSET 2 +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | tan | +| :------------------- | ------------: | +| 2019-08-18T00:18:00Z | -1.0559235802 | +| 2019-08-18T00:12:00Z | -1.0267433979 | +| 2019-08-18T00:06:00Z | -0.9553984098 | +| 2019-08-18T00:00:00Z | -1.0084243657 | + +{{% /expand %}} + +{{< /expand-wrapper >}} + +### Advanced syntax + +```sql +SELECT TAN(( [ * | ] )) FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] +``` + +The advanced syntax requires a [`GROUP BY time() ` clause](/influxdb/v2.4/query-data/influxql/explore-data/group-by/#group-by-time-intervals) and a nested InfluxQL function. +The query first calculates the results for the nested function at the specified `GROUP BY time()` interval and then applies the `TAN()` function to those results. + +`TAN()` supports the following nested functions: +[`COUNT()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#count), +[`MEAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean), +[`MEDIAN()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#median), +[`MODE()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mode), +[`SUM()`](/influxdb/v2.4/query-data/influxql/functions/aggregates/#sum), +[`FIRST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#first), +[`LAST()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#last), +[`MIN()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#min), +[`MAX()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#max), and +[`PERCENTILE()`](/influxdb/v2.4/query-data/influxql/functions/selectors/#percentile). + +#### Examples + +{{< expand-wrapper >}} + +{{% expand "Calculate the tangent of mean values" %}} + +Return the tangent of [mean](/influxdb/v2.4/query-data/influxql/functions/aggregates/#mean) `water_level`s that are calculated at 12-minute intervals. + +```sql +SELECT TAN(MEAN("water_level")) FROM "h2o_feet" WHERE time >= '2019-08-18T00:00:00Z' AND time <= '2019-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(12m) +``` + +{{% influxql/table-meta %}} +name: h2o_feet +{{% /influxql/table-meta %}} + +| time | tan | +| :------------------- | ------------: | +| 2019-08-18T00:00:00Z | -0.9815600413 | +| 2019-08-18T00:12:00Z | -1.0412271461 | +| 2019-08-18T00:24:00Z | -1.2000844348 | + +{{% /expand %}} + +{{< /expand-wrapper >}} diff --git a/content/influxdb/v2.4/query-data/influxql/manage-data.md b/content/influxdb/v2.4/query-data/influxql/manage-data.md new file mode 100644 index 0000000000..f01ad2f4aa --- /dev/null +++ b/content/influxdb/v2.4/query-data/influxql/manage-data.md @@ -0,0 +1,149 @@ +--- +title: Manage your data using InfluxQL +description: > + Use InfluxQL data management commands to write and delete data. +menu: + influxdb_2_4: + name: Manage your data + parent: Query with InfluxQL + identifier: manage-database +weight: 204 +--- + +Use the following data management commands to write and delete data with InfluxQL: + +- [Write data with INSERT](#write-data-with-insert) +- [Delete series with DELETE](#delete-series-with-delete) +- [Delete measurements with DROP MEASUREMENT](#delete-measurements-with-drop-measurement) + +## Write data with INSERT + +The `INSERT` statement writes [line protocol](/influxdb/v2.4/reference/syntax/line-protocol/) +to a database and retention policy. + +### Syntax +```sql +INSERT [INTO [.]] +``` + +- The `INTO` clause is optional. + If the command does not include `INTO`, you must specify the + database with `USE ` when using the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell/) + or with the `db` query string parameter in the + [InfluxDB 1.x compatibility API](/influxdb/v2.4/reference/api/influxdb-1x/) request. + +### Examples + +- [Insert data into the a specific database and retention policy](#insert-data-into-the-a-specific-database-and-retention-policy) +- [Insert data into the a the default retention policy of a database](#insert-data-into-the-a-the-default-retention-policy-of-a-database) +- [Insert data into the currently used database](#insert-data-into-the-currently-used-database) + +#### Insert data into the a specific database and retention policy + +```sql +INSERT INTO mydb.myrp example-m,tag1=value1 field1=1i 1640995200000000000 +``` + +#### Insert data into the a the default retention policy of a database + +```sql +INSERT INTO mydb example-m,tag1=value1 field1=1i 1640995200000000000 +``` + +#### Insert data into the currently used database + +The following example uses the [InfluxQL shell](/influxdb/v2.4/tools/influxql-shell). + +```sql +> USE mydb +> INSERT example-m,tag1=value1 field1=1i 1640995200000000000 +``` + +## Delete series with DELETE + +The `DELETE` statement deletes all points from a [series](/influxdb/v2.4/reference/glossary/#series) in a database. + +### Syntax + +```sql +DELETE FROM WHERE [=''] | [