From 86bee7caf6f781b2f9a61e80c12fbd1746fea2c3 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 23 Jan 2025 10:18:45 -0700 Subject: [PATCH] Add InfluxDB 3 query guides (#5798) * base content for influxdb3 query guides * added enterprise versions of query guides * Apply suggestions from code review Co-authored-by: Jason Stirnaman * update template titles to use .RenderString --------- Co-authored-by: Jason Stirnaman --- assets/js/custom-timestamps.js | 2 +- assets/styles/layouts/article/_buttons.scss | 4 + content/influxdb3/core/query-data/_index.md | 15 + .../core/query-data/execute-queries/_index.md | 20 + .../execute-queries/influxdb-v1-api.md | 31 ++ .../execute-queries/influxdb3-cli.md | 28 + .../core/query-data/influxql/_index.md | 16 + .../query-data/influxql/aggregate-select.md | 41 ++ .../core/query-data/influxql/basic-query.md | 23 + .../query-data/influxql/explore-schema.md | 39 ++ .../influxql/parameterized-queries.md | 45 ++ .../core/query-data/influxql/troubleshoot.md | 15 + .../influxdb3/core/query-data/sql/_index.md | 17 + .../core/query-data/sql/aggregate-select.md | 43 ++ .../core/query-data/sql/basic-query.md | 23 + .../core/query-data/sql/cast-types.md | 29 + .../core/query-data/sql/explore-schema.md | 27 + .../core/query-data/sql/fill-gaps.md | 30 ++ .../query-data/sql/parameterized-queries.md | 42 ++ .../core/reference/cli/influxdb3/serve.md | 2 + .../core/reference/config-options.md | 2 +- .../influxdb3/core/reference/sample-data.md | 17 + .../influxdb3/enterprise/query-data/_index.md | 15 + .../query-data/execute-queries/_index.md | 20 + .../execute-queries/influxdb-v1-api.md | 31 ++ .../execute-queries/influxdb3-cli.md | 28 + .../enterprise/query-data/influxql/_index.md | 16 + .../query-data/influxql/aggregate-select.md | 41 ++ .../query-data/influxql/basic-query.md | 23 + .../query-data/influxql/explore-schema.md | 39 ++ .../influxql/parameterized-queries.md | 45 ++ .../query-data/influxql/troubleshoot.md | 15 + .../enterprise/query-data/sql/_index.md | 17 + .../query-data/sql/aggregate-select.md | 43 ++ .../enterprise/query-data/sql/basic-query.md | 23 + .../enterprise/query-data/sql/cast-types.md | 29 + .../query-data/sql/explore-schema.md | 27 + .../enterprise/query-data/sql/fill-gaps.md | 30 ++ .../query-data/sql/parameterized-queries.md | 42 ++ .../enterprise/reference/sample-data.md | 17 + content/shared/influxdb3-cli/query.md | 2 +- .../shared/influxdb3-cli/show/databases.md | 2 +- .../shared/influxdb3-query-guides/_index.md | 4 + .../execute-queries/_index.md | 11 + .../execute-queries/influxdb-v1-api.md | 66 +++ .../execute-queries/influxdb3-cli.md | 155 ++++++ .../influxdb3-query-guides/influxql/_index.md | 8 + .../influxql/aggregate-select.md | 216 ++++++++ .../influxql/basic-query.md | 230 ++++++++ .../influxql/explore-schema.md | 323 +++++++++++ .../influxql/parameterized-queries.md | 315 +++++++++++ .../influxql/troubleshoot.md | 259 +++++++++ .../influxdb3-query-guides/sql/_index.md | 8 + .../sql/aggregate-select.md | 322 +++++++++++ .../influxdb3-query-guides/sql/basic-query.md | 208 +++++++ .../influxdb3-query-guides/sql/cast-types.md | 328 ++++++++++++ .../sql/explore-schema.md | 53 ++ .../influxdb3-query-guides/sql/fill-gaps.md | 112 ++++ .../sql/parameterized-queries.md | 310 +++++++++++ .../influxdb3-sample-data/sample-data.md | 506 ++++++++++++++++++ .../functions/date-time.md | 2 +- .../influxql-v3-reference/functions/misc.md | 2 +- .../functions/technical-analysis.md | 60 +-- .../influxql-v3-reference/limit-and-slimit.md | 2 +- .../offset-and-soffset.md | 2 +- .../shared/influxql-v3-reference/order-by.md | 2 +- .../regular-expressions.md | 2 +- .../shared/influxql-v3-reference/select.md | 2 +- .../influxql-v3-reference/subqueries.md | 2 +- .../time-and-timezone.md | 4 +- content/shared/influxql-v3-reference/where.md | 2 +- content/shared/sql-reference/group-by.md | 67 +-- .../shared/sql-reference/operators/logical.md | 2 +- content/shared/sql-reference/subqueries.md | 2 +- content/shared/v3-core-get-started/_index.md | 2 +- .../v3-enterprise-get-started/_index.md | 2 +- layouts/partials/article.html | 2 +- layouts/partials/article/related.html | 2 +- layouts/partials/article/stable-version.html | 4 +- layouts/partials/header.html | 2 +- layouts/partials/header/title.html | 2 +- layouts/shortcodes/children.html | 14 +- .../influxql/v1-v3-data-model-note.md | 16 + layouts/shortcodes/sql/sql-schema-intro.md | 12 +- 84 files changed, 4564 insertions(+), 97 deletions(-) create mode 100644 content/influxdb3/core/query-data/_index.md create mode 100644 content/influxdb3/core/query-data/execute-queries/_index.md create mode 100644 content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md create mode 100644 content/influxdb3/core/query-data/execute-queries/influxdb3-cli.md create mode 100644 content/influxdb3/core/query-data/influxql/_index.md create mode 100644 content/influxdb3/core/query-data/influxql/aggregate-select.md create mode 100644 content/influxdb3/core/query-data/influxql/basic-query.md create mode 100644 content/influxdb3/core/query-data/influxql/explore-schema.md create mode 100644 content/influxdb3/core/query-data/influxql/parameterized-queries.md create mode 100644 content/influxdb3/core/query-data/influxql/troubleshoot.md create mode 100644 content/influxdb3/core/query-data/sql/_index.md create mode 100644 content/influxdb3/core/query-data/sql/aggregate-select.md create mode 100644 content/influxdb3/core/query-data/sql/basic-query.md create mode 100644 content/influxdb3/core/query-data/sql/cast-types.md create mode 100644 content/influxdb3/core/query-data/sql/explore-schema.md create mode 100644 content/influxdb3/core/query-data/sql/fill-gaps.md create mode 100644 content/influxdb3/core/query-data/sql/parameterized-queries.md create mode 100644 content/influxdb3/core/reference/sample-data.md create mode 100644 content/influxdb3/enterprise/query-data/_index.md create mode 100644 content/influxdb3/enterprise/query-data/execute-queries/_index.md create mode 100644 content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md create mode 100644 content/influxdb3/enterprise/query-data/execute-queries/influxdb3-cli.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/_index.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/aggregate-select.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/basic-query.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/explore-schema.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/parameterized-queries.md create mode 100644 content/influxdb3/enterprise/query-data/influxql/troubleshoot.md create mode 100644 content/influxdb3/enterprise/query-data/sql/_index.md create mode 100644 content/influxdb3/enterprise/query-data/sql/aggregate-select.md create mode 100644 content/influxdb3/enterprise/query-data/sql/basic-query.md create mode 100644 content/influxdb3/enterprise/query-data/sql/cast-types.md create mode 100644 content/influxdb3/enterprise/query-data/sql/explore-schema.md create mode 100644 content/influxdb3/enterprise/query-data/sql/fill-gaps.md create mode 100644 content/influxdb3/enterprise/query-data/sql/parameterized-queries.md create mode 100644 content/influxdb3/enterprise/reference/sample-data.md create mode 100644 content/shared/influxdb3-query-guides/_index.md create mode 100644 content/shared/influxdb3-query-guides/execute-queries/_index.md create mode 100644 content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md create mode 100644 content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md create mode 100644 content/shared/influxdb3-query-guides/influxql/_index.md create mode 100644 content/shared/influxdb3-query-guides/influxql/aggregate-select.md create mode 100644 content/shared/influxdb3-query-guides/influxql/basic-query.md create mode 100644 content/shared/influxdb3-query-guides/influxql/explore-schema.md create mode 100644 content/shared/influxdb3-query-guides/influxql/parameterized-queries.md create mode 100644 content/shared/influxdb3-query-guides/influxql/troubleshoot.md create mode 100644 content/shared/influxdb3-query-guides/sql/_index.md create mode 100644 content/shared/influxdb3-query-guides/sql/aggregate-select.md create mode 100644 content/shared/influxdb3-query-guides/sql/basic-query.md create mode 100644 content/shared/influxdb3-query-guides/sql/cast-types.md create mode 100644 content/shared/influxdb3-query-guides/sql/explore-schema.md create mode 100644 content/shared/influxdb3-query-guides/sql/fill-gaps.md create mode 100644 content/shared/influxdb3-query-guides/sql/parameterized-queries.md create mode 100644 content/shared/influxdb3-sample-data/sample-data.md create mode 100644 layouts/shortcodes/influxql/v1-v3-data-model-note.md diff --git a/assets/js/custom-timestamps.js b/assets/js/custom-timestamps.js index 2442931f8e..9f8cb6d4c9 100644 --- a/assets/js/custom-timestamps.js +++ b/assets/js/custom-timestamps.js @@ -131,7 +131,7 @@ function updateTimestamps (newStartDate) { oldDatePart = datePart(x.rfc3339.replace(/T.*$/, '')); newDatePart = datePart(x.rfc3339_new.replace(/T.*$/, '')); rfc3339Regex = new RegExp( - `${oldDatePart.year}(.*)${oldDatePart.month}(.*)${oldDatePart.day}`, + `${oldDatePart.year}(.*?)${oldDatePart.month}(.*?)${oldDatePart.day}`, 'g' ); rfc3339Repl = `${newDatePart.year}$1${newDatePart.month}$2${newDatePart.day}`; diff --git a/assets/styles/layouts/article/_buttons.scss b/assets/styles/layouts/article/_buttons.scss index d05d412651..abd4394c76 100644 --- a/assets/styles/layouts/article/_buttons.scss +++ b/assets/styles/layouts/article/_buttons.scss @@ -56,6 +56,10 @@ a.btn { margin-right: -.65rem; } + &.small { + padding: .4rem 1rem; + } + &.small-plus { padding: .25em; line-height: .65rem; diff --git a/content/influxdb3/core/query-data/_index.md b/content/influxdb3/core/query-data/_index.md new file mode 100644 index 0000000000..6dc8883385 --- /dev/null +++ b/content/influxdb3/core/query-data/_index.md @@ -0,0 +1,15 @@ +--- +title: Query data in {{< product-name >}} +description: > + Learn to query data stored in InfluxDB using SQL and InfluxQL. +menu: + influxdb3_core: + name: Query data +weight: 4 +influxdb3/core/tags: [query] +source: /shared/influxdb3-query-guides/_index.md +--- + + diff --git a/content/influxdb3/core/query-data/execute-queries/_index.md b/content/influxdb3/core/query-data/execute-queries/_index.md new file mode 100644 index 0000000000..cfd303dab4 --- /dev/null +++ b/content/influxdb3/core/query-data/execute-queries/_index.md @@ -0,0 +1,20 @@ +--- +title: Execute queries +description: > + Use tools and libraries to query data stored in {{< product-name >}}. +weight: 101 +menu: + influxdb3_core: + name: Execute queries + parent: Query data +influxdb3/core/tags: [query, sql, influxql] +aliases: + - /influxdb3/core/query-data/tools/ + - /influxdb3/core/query-data/sql/execute-queries/ + - /influxdb3/core/query-data/influxql/execute-queries/ +source: /shared/influxdb3-query-guides/execute-queries/_index.md +--- + + diff --git a/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md b/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md new file mode 100644 index 0000000000..a5e9220cae --- /dev/null +++ b/content/influxdb3/core/query-data/execute-queries/influxdb-v1-api.md @@ -0,0 +1,31 @@ +--- +title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data +seotitle: Use InfluxQL and InfluxDB v1 HTTP query API +list_title: Use the v1 query API and InfluxQL +description: > + Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}} + with InfluxQL. +weight: 302 +menu: + influxdb3_core: + parent: Execute queries + name: Use the v1 query API +influxdb3/core/tags: [query, influxql, python] +metadata: [InfluxQL] +related: + - /influxdb3/core/api-compatibility/v1/ +aliases: + - /influxdb3/core/query-data/influxql/execute-queries/influxdb-v1-api/ +list_code_example: | + ```sh + curl --get http://{{< influxdb/host >}}/query \ + --header "Authorization: Token DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" + ``` +source: /shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md +--- + + diff --git a/content/influxdb3/core/query-data/execute-queries/influxdb3-cli.md b/content/influxdb3/core/query-data/execute-queries/influxdb3-cli.md new file mode 100644 index 0000000000..43222ff08c --- /dev/null +++ b/content/influxdb3/core/query-data/execute-queries/influxdb3-cli.md @@ -0,0 +1,28 @@ +--- +title: Use the influxdb3 CLI to query data +list_title: Use the influxdb3 CLI +description: > + Use the `influxdb3 query` command to query data in {{< product-name >}} with SQL. +weight: 301 +menu: + influxdb3_core: + parent: Execute queries + name: Use the influxdb3 CLI +influxdb3/core/tags: [query, sql, influxql, influxdb3, CLI] +related: + - /influxdb3/core/reference/cli/influxdb3/query/ + - /influxdb3/core/reference/sql/ + - /influxdb3/core/reference/influxql/ + # - /influxdb3/core/get-started/query/#execute-an-sql-query, Get started querying data +list_code_example: | + ```sh + influxdb3 query \ + --database DATABASE_NAME \ + "SELECT * FROM home" + ``` +source: /shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/_index.md b/content/influxdb3/core/query-data/influxql/_index.md new file mode 100644 index 0000000000..110f0365df --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/_index.md @@ -0,0 +1,16 @@ +--- +title: Query data with InfluxQL +description: > + Learn to use InfluxQL to query data stored in {{< product-name >}}. +menu: + influxdb3_core: + name: Query with InfluxQL + parent: Query data +weight: 102 +influxdb3/core/tags: [query, influxql] +source: /shared/influxdb3-query-guides/influxql/_index.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/aggregate-select.md b/content/influxdb3/core/query-data/influxql/aggregate-select.md new file mode 100644 index 0000000000..3e0f02a80f --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/aggregate-select.md @@ -0,0 +1,41 @@ +--- +title: Aggregate data with InfluxQL +seotitle: Aggregate or apply selector functions to data with InfluxQL +description: > + Use InfluxQL aggregate and selector functions to perform aggregate operations + on your time series data. +menu: + influxdb3_core: + name: Aggregate data + parent: Query with InfluxQL + identifier: query-influxql-aggregate +weight: 203 +influxdb3/core/tags: [query, influxql] +related: + - /influxdb3/core/reference/influxql/functions/aggregates/ + - /influxdb3/core/reference/influxql/functions/selectors/ +list_code_example: | + ##### Aggregate fields by groups + ```sql + SELECT + MEAN(temp) AS mean, + FIRST(hum) as first, + FROM home + GROUP BY tag + ``` + + ##### Aggregate by time-based intervals + ```sql + SELECT + MEAN(temp), + sum(hum), + FROM home + WHERE time >= now() - 24h + GROUP BY time(1h),room + ``` +source: /shared/influxdb3-query-guides/influxql/aggregate-select.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/basic-query.md b/content/influxdb3/core/query-data/influxql/basic-query.md new file mode 100644 index 0000000000..feaef1157d --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/basic-query.md @@ -0,0 +1,23 @@ +--- +title: Perform a basic InfluxQL query +seotitle: Perform a basic InfluxQL query in {{< product-name >}} +description: > + A basic InfluxQL query that queries data from InfluxDB most commonly includes + `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb3_core: + name: Basic query + parent: Query with InfluxQL + identifier: query-influxql-basic +weight: 202 +influxdb3/core/tags: [query, influxql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - 1d + ``` +source: /shared/influxdb3-query-guides/influxql/basic-query.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/explore-schema.md b/content/influxdb3/core/query-data/influxql/explore-schema.md new file mode 100644 index 0000000000..9852216046 --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/explore-schema.md @@ -0,0 +1,39 @@ +--- +title: Explore your schema with InfluxQL +description: > + Use InfluxQL `SHOW` statements to return information about your data schema. +menu: + influxdb3_core: + name: Explore your schema + parent: Query with InfluxQL + identifier: query-influxql-schema +weight: 201 +influxdb3/core/tags: [query, influxql] +related: + - /influxdb3/core/reference/influxql/show/ +list_code_example: | + ##### List measurements + ```sql + SHOW MEASUREMENTS + ``` + + ##### List field keys in a measurement + ```sql + SHOW FIELD KEYS FROM "measurement" + ``` + + ##### List tag keys in a measurement + ```sql + SHOW TAG KEYS FROM "measurement" + ``` + + ##### List tag values for a specific tag key + ```sql + SHOW TAG VALUES FROM "measurement" WITH KEY = "tag-key" WHERE time > now() - 1d + ``` +source: /shared/influxdb3-query-guides/influxql/explore-schema.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/parameterized-queries.md b/content/influxdb3/core/query-data/influxql/parameterized-queries.md new file mode 100644 index 0000000000..e6ef5e1f95 --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/parameterized-queries.md @@ -0,0 +1,45 @@ +--- +title: Use parameterized queries with InfluxQL +description: > + Use parameterized queries to prevent injection attacks and make queries more reusable. +weight: 404 +menu: + influxdb3_core: + name: Parameterized queries + parent: Query with InfluxQL + identifier: parameterized-queries-influxql +influxdb3/core/tags: [query, security, influxql] +list_code_example: | + ##### Using Go and the influxdb3-go client + + ```go + // Use the $parameter syntax to reference parameters in a query. + // The following InfluxQL query contains $room and $min_time parameters. + query := ` + SELECT * FROM home + WHERE time >= $min_time + AND temp >= $min_temp + AND room = $room` + + // Assign parameter names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + "min_time": "2024-03-18 00:00:00.00", + } + + // Call the client's function to query InfluxDB with parameters and the + // the InfluxQL QueryType. + iterator, err := client.QueryWithParameters(context.Background(), + query, + parameters, + influxdb3.WithQueryType(influxdb3.InfluxQL)) + ``` +# Leaving in draft until tested +draft: true +source: /shared/influxdb3-query-guides/influxql/parameterized-queries.md +--- + + diff --git a/content/influxdb3/core/query-data/influxql/troubleshoot.md b/content/influxdb3/core/query-data/influxql/troubleshoot.md new file mode 100644 index 0000000000..9c9d0bef6d --- /dev/null +++ b/content/influxdb3/core/query-data/influxql/troubleshoot.md @@ -0,0 +1,15 @@ +--- +title: Troubleshoot InfluxQL errors +description: > + Learn how to troubleshoot and fix common InfluxQL errors. +menu: + influxdb3_core: + name: Troubleshoot errors + parent: Query with InfluxQL +weight: 230 +source: /shared/influxdb3-query-guides/influxql/troubleshoot.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/_index.md b/content/influxdb3/core/query-data/sql/_index.md new file mode 100644 index 0000000000..bb77b902f9 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/_index.md @@ -0,0 +1,17 @@ +--- +title: Query data with SQL +seotitle: Query data with SQL +description: > + Learn to query data stored in {{< product-name >}} using SQL. +menu: + influxdb3_core: + name: Query with SQL + parent: Query data +weight: 101 +influxdb3/core/tags: [query, sql] +source: /shared/influxdb3-query-guides/sql/_index.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/aggregate-select.md b/content/influxdb3/core/query-data/sql/aggregate-select.md new file mode 100644 index 0000000000..b35b753968 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/aggregate-select.md @@ -0,0 +1,43 @@ +--- +title: Aggregate data with SQL +description: > + Use aggregate and selector functions to perform aggregate operations on your + time series data. +menu: + influxdb3_core: + name: Aggregate data + parent: Query with SQL + identifier: query-sql-aggregate +weight: 203 +influxdb3/core/tags: [query, sql] +related: + - /influxdb3/core/reference/sql/functions/aggregate/ + - /influxdb3/core/reference/sql/functions/selector/ + - /influxdb3/core/reference/sql/group-by/ +list_code_example: | + ##### Aggregate fields by groups + ```sql + SELECT + mean(field1) AS mean, + selector_first(field2)['value'] as first, + tag1 + FROM home + GROUP BY tag + ``` + + ##### Aggregate by time-based intervals + ```sql + SELECT + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + mean(field1), + sum(field2), + tag1 + FROM home + GROUP BY 1, tag1 + ``` +source: /shared/influxdb3-query-guides/sql/aggregate-select.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/basic-query.md b/content/influxdb3/core/query-data/sql/basic-query.md new file mode 100644 index 0000000000..9c61e63c97 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/basic-query.md @@ -0,0 +1,23 @@ +--- +title: Perform a basic SQL query +seotitle: Perform a basic SQL query in InfluxDB 3 Core +description: > + A basic SQL query that queries data from {{< product-name >}} most commonly + includes `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb3_core: + name: Basic query + parent: Query with SQL + identifier: query-sql-basic +weight: 202 +influxdb3/core/tags: [query, sql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - INTERVAL '1 day' + ``` +source: /shared/influxdb3-query-guides/sql/basic-query.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/cast-types.md b/content/influxdb3/core/query-data/sql/cast-types.md new file mode 100644 index 0000000000..6b56078b84 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/cast-types.md @@ -0,0 +1,29 @@ +--- +title: Cast values to different types +seotitle: Cast values to different data types in SQL +description: > + Use the `CAST` function or double-colon `::` casting shorthand syntax to cast + a value to a specific type. +menu: + influxdb3_core: + name: Cast types + parent: Query with SQL + identifier: query-sql-cast-types +weight: 205 +influxdb3/core/tags: [query, sql] +related: + - /influxdb3/core/reference/sql/data-types/ +list_code_example: | + ```sql + -- CAST clause + SELECT CAST(1234.5 AS BIGINT) + + -- Double-colon casting shorthand + SELECT 1234.5::BIGINT + ``` +source: /shared/influxdb3-query-guides/sql/cast-types.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/explore-schema.md b/content/influxdb3/core/query-data/sql/explore-schema.md new file mode 100644 index 0000000000..31d234ff1e --- /dev/null +++ b/content/influxdb3/core/query-data/sql/explore-schema.md @@ -0,0 +1,27 @@ +--- +title: Explore your schema with SQL +description: > + Use SQL to explore your data schema in your {{< product-name >}} database. +menu: + influxdb3_core: + name: Explore your schema + parent: Query with SQL + identifier: query-sql-schema +weight: 201 +influxdb3/core/tags: [query, sql] +list_code_example: | + ##### List tables + ```sql + SHOW TABLES + ``` + + ##### List columns in a table + ```sql + SHOW COLUMNS IN table + ``` +source: /shared/influxdb3-query-guides/sql/explore-schema.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/fill-gaps.md b/content/influxdb3/core/query-data/sql/fill-gaps.md new file mode 100644 index 0000000000..4c9fd6dd59 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/fill-gaps.md @@ -0,0 +1,30 @@ +--- +title: Fill gaps in data +seotitle: Fill gaps in data with SQL +description: > + Use [`date_bin_gapfill`](/influxdb3/core/reference/sql/functions/time-and-date/#date_bin_gapfill) + with [`interpolate`](/influxdb3/core/reference/sql/functions/misc/#interpolate) + or [`locf`](/influxdb3/core/reference/sql/functions/misc/#locf) to + fill gaps of time where no data is returned. +menu: + influxdb3_core: + parent: Query with SQL +weight: 206 +list_code_example: | + ```sql + SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as time, + room, + interpolate(avg(temp)) + FROM home + WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' + GROUP BY 1, room + ``` +source: /shared/influxdb3-query-guides/sql/fill-gaps.md +--- + + diff --git a/content/influxdb3/core/query-data/sql/parameterized-queries.md b/content/influxdb3/core/query-data/sql/parameterized-queries.md new file mode 100644 index 0000000000..5a4959ffa9 --- /dev/null +++ b/content/influxdb3/core/query-data/sql/parameterized-queries.md @@ -0,0 +1,42 @@ +--- +title: Use parameterized queries with SQL +description: > + Use parameterized queries to prevent injection attacks and make queries more reusable. +weight: 404 +menu: + influxdb3_core: + name: Parameterized queries + parent: Query with SQL + identifier: parameterized-queries-sql +influxdb3/core/tags: [query, security, sql] +list_code_example: | + ##### Using Go and the influxdb3-go client + + ```go + // Use the $parameter syntax to reference parameters in a query. + // The following SQL query contains $room and $min_temp placeholders. + query := ` + SELECT * FROM home + WHERE time >= $min_time + AND temp >= $min_temp + AND room = $room` + + // Assign parameter names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + "min_time": "2024-03-18 00:00:00.00", + + } + + // Call the client's function to query InfluxDB with parameters. + iterator, err := client.QueryWithParameters(context.Background(), query, parameters) + ``` +# Leaving in draft until tested +draft: true +source: /shared/influxdb3-query-guides/sql/parameterized-queries.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/core/reference/cli/influxdb3/serve.md b/content/influxdb3/core/reference/cli/influxdb3/serve.md index 4c2521950a..baffa696c8 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/core/reference/cli/influxdb3/serve.md @@ -7,6 +7,8 @@ menu: parent: influxdb3 name: influxdb3 serve weight: 300 +related: + - /influxdb3/core/reference/config-options/ --- The `influxdb3 serve` command starts the {{< product-name >}} server. diff --git a/content/influxdb3/core/reference/config-options.md b/content/influxdb3/core/reference/config-options.md index b2ac4d6389..88e4619b88 100644 --- a/content/influxdb3/core/reference/config-options.md +++ b/content/influxdb3/core/reference/config-options.md @@ -1,5 +1,5 @@ --- -title: InfluxDB 3 Core configuration options +title: '{{< product-name >}} configuration options' description: > InfluxDB 3 Core lets you customize your server configuration by using `influxdb3 serve` command options or by setting environment variables. diff --git a/content/influxdb3/core/reference/sample-data.md b/content/influxdb3/core/reference/sample-data.md new file mode 100644 index 0000000000..5fa671c087 --- /dev/null +++ b/content/influxdb3/core/reference/sample-data.md @@ -0,0 +1,17 @@ +--- +title: Sample data +description: > + Sample datasets are used throughout the the {{< product-name >}} documentation + to demonstrate functionality. + Use the following sample datasets to replicate provided examples. +menu: + influxdb3_core: + name: Sample data + parent: Reference +weight: 182 +source: /shared/influxdb3-sample-data/sample-data.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/query-data/_index.md b/content/influxdb3/enterprise/query-data/_index.md new file mode 100644 index 0000000000..ffa486a04e --- /dev/null +++ b/content/influxdb3/enterprise/query-data/_index.md @@ -0,0 +1,15 @@ +--- +title: Query data in {{< product-name >}} +description: > + Learn to query data stored in InfluxDB using SQL and InfluxQL. +menu: + influxdb3_enterprise: + name: Query data +weight: 4 +influxdb3/enterprise/tags: [query] +source: /shared/influxdb3-query-guides/_index.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/execute-queries/_index.md b/content/influxdb3/enterprise/query-data/execute-queries/_index.md new file mode 100644 index 0000000000..6f3676f359 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/execute-queries/_index.md @@ -0,0 +1,20 @@ +--- +title: Execute queries +description: > + Use tools and libraries to query data stored in {{< product-name >}}. +weight: 101 +menu: + influxdb3_enterprise: + name: Execute queries + parent: Query data +influxdb3/enterprise/tags: [query, sql, influxql] +aliases: + - /influxdb3/enterprise/query-data/tools/ + - /influxdb3/enterprise/query-data/sql/execute-queries/ + - /influxdb3/enterprise/query-data/influxql/execute-queries/ +source: /shared/influxdb3-query-guides/execute-queries/_index.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md new file mode 100644 index 0000000000..0c40fafc5b --- /dev/null +++ b/content/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api.md @@ -0,0 +1,31 @@ +--- +title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data +seotitle: Use InfluxQL and InfluxDB v1 HTTP query API +list_title: Use the v1 query API and InfluxQL +description: > + Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}} + with InfluxQL. +weight: 302 +menu: + influxdb3_enterprise: + parent: Execute queries + name: Use the v1 query API +influxdb3/enterprise/tags: [query, influxql, python] +metadata: [InfluxQL] +related: + - /influxdb3/enterprise/api-compatibility/v1/ +aliases: + - /influxdb3/enterprise/query-data/influxql/execute-queries/influxdb-v1-api/ +list_code_example: | + ```sh + curl --get http://{{< influxdb/host >}}/query \ + --header "Authorization: Token DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" + ``` +source: /shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/execute-queries/influxdb3-cli.md b/content/influxdb3/enterprise/query-data/execute-queries/influxdb3-cli.md new file mode 100644 index 0000000000..8b19fdc9c9 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/execute-queries/influxdb3-cli.md @@ -0,0 +1,28 @@ +--- +title: Use the influxdb3 CLI to query data +list_title: Use the influxdb3 CLI +description: > + Use the `influxdb3 query` command to query data in {{< product-name >}} with SQL. +weight: 301 +menu: + influxdb3_enterprise: + parent: Execute queries + name: Use the influxdb3 CLI +influxdb3/enterprise/tags: [query, sql, influxql, influxdb3, CLI] +related: + - /influxdb3/enterprise/reference/cli/influxdb3/query/ + - /influxdb3/enterprise/reference/sql/ + - /influxdb3/enterprise/reference/influxql/ + # - /influxdb3/enterprise/get-started/query/#execute-an-sql-query, Get started querying data +list_code_example: | + ```sh + influxdb3 query \ + --database DATABASE_NAME \ + "SELECT * FROM home" + ``` +source: /shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/_index.md b/content/influxdb3/enterprise/query-data/influxql/_index.md new file mode 100644 index 0000000000..c8fccfa37d --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/_index.md @@ -0,0 +1,16 @@ +--- +title: Query data with InfluxQL +description: > + Learn to use InfluxQL to query data stored in {{< product-name >}}. +menu: + influxdb3_enterprise: + name: Query with InfluxQL + parent: Query data +weight: 102 +influxdb3/enterprise/tags: [query, influxql] +source: /shared/influxdb3-query-guides/influxql/_index.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/aggregate-select.md b/content/influxdb3/enterprise/query-data/influxql/aggregate-select.md new file mode 100644 index 0000000000..610c1d23c4 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/aggregate-select.md @@ -0,0 +1,41 @@ +--- +title: Aggregate data with InfluxQL +seotitle: Aggregate or apply selector functions to data with InfluxQL +description: > + Use InfluxQL aggregate and selector functions to perform aggregate operations + on your time series data. +menu: + influxdb3_enterprise: + name: Aggregate data + parent: Query with InfluxQL + identifier: query-influxql-aggregate +weight: 203 +influxdb3/enterprise/tags: [query, influxql] +related: + - /influxdb3/enterprise/reference/influxql/functions/aggregates/ + - /influxdb3/enterprise/reference/influxql/functions/selectors/ +list_code_example: | + ##### Aggregate fields by groups + ```sql + SELECT + MEAN(temp) AS mean, + FIRST(hum) as first, + FROM home + GROUP BY tag + ``` + + ##### Aggregate by time-based intervals + ```sql + SELECT + MEAN(temp), + sum(hum), + FROM home + WHERE time >= now() - 24h + GROUP BY time(1h),room + ``` +source: /shared/influxdb3-query-guides/influxql/aggregate-select.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/basic-query.md b/content/influxdb3/enterprise/query-data/influxql/basic-query.md new file mode 100644 index 0000000000..ee43ba7b84 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/basic-query.md @@ -0,0 +1,23 @@ +--- +title: Perform a basic InfluxQL query +seotitle: Perform a basic InfluxQL query in {{< product-name >}} +description: > + A basic InfluxQL query that queries data from InfluxDB most commonly includes + `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb3_enterprise: + name: Basic query + parent: Query with InfluxQL + identifier: query-influxql-basic +weight: 202 +influxdb3/enterprise/tags: [query, influxql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - 1d + ``` +source: /shared/influxdb3-query-guides/influxql/basic-query.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/explore-schema.md b/content/influxdb3/enterprise/query-data/influxql/explore-schema.md new file mode 100644 index 0000000000..08d606e4d6 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/explore-schema.md @@ -0,0 +1,39 @@ +--- +title: Explore your schema with InfluxQL +description: > + Use InfluxQL `SHOW` statements to return information about your data schema. +menu: + influxdb3_enterprise: + name: Explore your schema + parent: Query with InfluxQL + identifier: query-influxql-schema +weight: 201 +influxdb3/enterprise/tags: [query, influxql] +related: + - /influxdb3/enterprise/reference/influxql/show/ +list_code_example: | + ##### List measurements + ```sql + SHOW MEASUREMENTS + ``` + + ##### List field keys in a measurement + ```sql + SHOW FIELD KEYS FROM "measurement" + ``` + + ##### List tag keys in a measurement + ```sql + SHOW TAG KEYS FROM "measurement" + ``` + + ##### List tag values for a specific tag key + ```sql + SHOW TAG VALUES FROM "measurement" WITH KEY = "tag-key" WHERE time > now() - 1d + ``` +source: /shared/influxdb3-query-guides/influxql/explore-schema.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/parameterized-queries.md b/content/influxdb3/enterprise/query-data/influxql/parameterized-queries.md new file mode 100644 index 0000000000..c681656b7e --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/parameterized-queries.md @@ -0,0 +1,45 @@ +--- +title: Use parameterized queries with InfluxQL +description: > + Use parameterized queries to prevent injection attacks and make queries more reusable. +weight: 404 +menu: + influxdb3_enterprise: + name: Parameterized queries + parent: Query with InfluxQL + identifier: parameterized-queries-influxql +influxdb3/enterprise/tags: [query, security, influxql] +list_code_example: | + ##### Using Go and the influxdb3-go client + + ```go + // Use the $parameter syntax to reference parameters in a query. + // The following InfluxQL query contains $room and $min_time parameters. + query := ` + SELECT * FROM home + WHERE time >= $min_time + AND temp >= $min_temp + AND room = $room` + + // Assign parameter names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + "min_time": "2024-03-18 00:00:00.00", + } + + // Call the client's function to query InfluxDB with parameters and the + // the InfluxQL QueryType. + iterator, err := client.QueryWithParameters(context.Background(), + query, + parameters, + influxdb3.WithQueryType(influxdb3.InfluxQL)) + ``` +# Leaving in draft until tested +draft: true +source: /shared/influxdb3-query-guides/influxql/parameterized-queries.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/influxql/troubleshoot.md b/content/influxdb3/enterprise/query-data/influxql/troubleshoot.md new file mode 100644 index 0000000000..32a6de79f9 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/influxql/troubleshoot.md @@ -0,0 +1,15 @@ +--- +title: Troubleshoot InfluxQL errors +description: > + Learn how to troubleshoot and fix common InfluxQL errors. +menu: + influxdb3_enterprise: + name: Troubleshoot errors + parent: Query with InfluxQL +weight: 230 +source: /shared/influxdb3-query-guides/influxql/troubleshoot.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/_index.md b/content/influxdb3/enterprise/query-data/sql/_index.md new file mode 100644 index 0000000000..6767cb686f --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/_index.md @@ -0,0 +1,17 @@ +--- +title: Query data with SQL +seotitle: Query data with SQL +description: > + Learn to query data stored in {{< product-name >}} using SQL. +menu: + influxdb3_enterprise: + name: Query with SQL + parent: Query data +weight: 101 +influxdb3/enterprise/tags: [query, sql] +source: /shared/influxdb3-query-guides/sql/_index.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/aggregate-select.md b/content/influxdb3/enterprise/query-data/sql/aggregate-select.md new file mode 100644 index 0000000000..e314ea263d --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/aggregate-select.md @@ -0,0 +1,43 @@ +--- +title: Aggregate data with SQL +description: > + Use aggregate and selector functions to perform aggregate operations on your + time series data. +menu: + influxdb3_enterprise: + name: Aggregate data + parent: Query with SQL + identifier: query-sql-aggregate +weight: 203 +influxdb3/enterprise/tags: [query, sql] +related: + - /influxdb3/enterprise/reference/sql/functions/aggregate/ + - /influxdb3/enterprise/reference/sql/functions/selector/ + - /influxdb3/enterprise/reference/sql/group-by/ +list_code_example: | + ##### Aggregate fields by groups + ```sql + SELECT + mean(field1) AS mean, + selector_first(field2)['value'] as first, + tag1 + FROM home + GROUP BY tag + ``` + + ##### Aggregate by time-based intervals + ```sql + SELECT + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + mean(field1), + sum(field2), + tag1 + FROM home + GROUP BY 1, tag1 + ``` +source: /shared/influxdb3-query-guides/sql/aggregate-select.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/basic-query.md b/content/influxdb3/enterprise/query-data/sql/basic-query.md new file mode 100644 index 0000000000..8649b1e138 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/basic-query.md @@ -0,0 +1,23 @@ +--- +title: Perform a basic SQL query +seotitle: Perform a basic SQL query in {{< product-name >}} +description: > + A basic SQL query that queries data from {{< product-name >}} most commonly + includes `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb3_enterprise: + name: Basic query + parent: Query with SQL + identifier: query-sql-basic +weight: 202 +influxdb3/enterprise/tags: [query, sql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - INTERVAL '1 day' + ``` +source: /shared/influxdb3-query-guides/sql/basic-query.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/cast-types.md b/content/influxdb3/enterprise/query-data/sql/cast-types.md new file mode 100644 index 0000000000..b2732c98aa --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/cast-types.md @@ -0,0 +1,29 @@ +--- +title: Cast values to different types +seotitle: Cast values to different data types in SQL +description: > + Use the `CAST` function or double-colon `::` casting shorthand syntax to cast + a value to a specific type. +menu: + influxdb3_enterprise: + name: Cast types + parent: Query with SQL + identifier: query-sql-cast-types +weight: 205 +influxdb3/enterprise/tags: [query, sql] +related: + - /influxdb3/enterprise/reference/sql/data-types/ +list_code_example: | + ```sql + -- CAST clause + SELECT CAST(1234.5 AS BIGINT) + + -- Double-colon casting shorthand + SELECT 1234.5::BIGINT + ``` +source: /shared/influxdb3-query-guides/sql/cast-types.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/explore-schema.md b/content/influxdb3/enterprise/query-data/sql/explore-schema.md new file mode 100644 index 0000000000..b513f62d39 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/explore-schema.md @@ -0,0 +1,27 @@ +--- +title: Explore your schema with SQL +description: > + Use SQL to explore your data schema in your {{< product-name >}} database. +menu: + influxdb3_enterprise: + name: Explore your schema + parent: Query with SQL + identifier: query-sql-schema +weight: 201 +influxdb3/enterprise/tags: [query, sql] +list_code_example: | + ##### List tables + ```sql + SHOW TABLES + ``` + + ##### List columns in a table + ```sql + SHOW COLUMNS IN table + ``` +source: /shared/influxdb3-query-guides/sql/explore-schema.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/fill-gaps.md b/content/influxdb3/enterprise/query-data/sql/fill-gaps.md new file mode 100644 index 0000000000..7e67057310 --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/fill-gaps.md @@ -0,0 +1,30 @@ +--- +title: Fill gaps in data +seotitle: Fill gaps in data with SQL +description: > + Use [`date_bin_gapfill`](/influxdb3/enterprise/reference/sql/functions/time-and-date/#date_bin_gapfill) + with [`interpolate`](/influxdb3/enterprise/reference/sql/functions/misc/#interpolate) + or [`locf`](/influxdb3/enterprise/reference/sql/functions/misc/#locf) to + fill gaps of time where no data is returned. +menu: + influxdb3_enterprise: + parent: Query with SQL +weight: 206 +list_code_example: | + ```sql + SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as time, + room, + interpolate(avg(temp)) + FROM home + WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' + GROUP BY 1, room + ``` +source: /shared/influxdb3-query-guides/sql/fill-gaps.md +--- + + diff --git a/content/influxdb3/enterprise/query-data/sql/parameterized-queries.md b/content/influxdb3/enterprise/query-data/sql/parameterized-queries.md new file mode 100644 index 0000000000..72bcf69a0f --- /dev/null +++ b/content/influxdb3/enterprise/query-data/sql/parameterized-queries.md @@ -0,0 +1,42 @@ +--- +title: Use parameterized queries with SQL +description: > + Use parameterized queries to prevent injection attacks and make queries more reusable. +weight: 404 +menu: + influxdb3_enterprise: + name: Parameterized queries + parent: Query with SQL + identifier: parameterized-queries-sql +influxdb3/enterprise/tags: [query, security, sql] +list_code_example: | + ##### Using Go and the influxdb3-go client + + ```go + // Use the $parameter syntax to reference parameters in a query. + // The following SQL query contains $room and $min_temp placeholders. + query := ` + SELECT * FROM home + WHERE time >= $min_time + AND temp >= $min_temp + AND room = $room` + + // Assign parameter names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + "min_time": "2024-03-18 00:00:00.00", + + } + + // Call the client's function to query InfluxDB with parameters. + iterator, err := client.QueryWithParameters(context.Background(), query, parameters) + ``` +# Leaving in draft until tested +draft: true +source: /shared/influxdb3-query-guides/sql/parameterized-queries.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/reference/sample-data.md b/content/influxdb3/enterprise/reference/sample-data.md new file mode 100644 index 0000000000..506d100f91 --- /dev/null +++ b/content/influxdb3/enterprise/reference/sample-data.md @@ -0,0 +1,17 @@ +--- +title: Sample data +description: > + Sample datasets are used throughout the the {{< product-name >}} documentation + to demonstrate functionality. + Use the following sample datasets to replicate provided examples. +menu: + influxdb3_enterprise: + name: Sample data + parent: Reference +weight: 182 +source: /shared/influxdb3-sample-data/sample-data.md +--- + + \ No newline at end of file diff --git a/content/shared/influxdb3-cli/query.md b/content/shared/influxdb3-cli/query.md index 3fb14fcca6..04f40f5d46 100644 --- a/content/shared/influxdb3-cli/query.md +++ b/content/shared/influxdb3-cli/query.md @@ -26,7 +26,7 @@ influxdb3 query [OPTIONS] --database [QUERY]... | `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | | | `--token` | Authentication token | | `-l` | `--language` | Query language of the query string (`sql` _(default)_ or `influxql`) | -| | `--format` | Output format (`pretty` _(default)_, `json`, `json_lines`, `csv`, `parquet`) | +| | `--format` | Output format (`pretty` _(default)_, `json`, `jsonl`, `csv`, `parquet`) | | `-o` | `--output` | Output query results to the specified file | | `-h` | `--help` | Print help information | diff --git a/content/shared/influxdb3-cli/show/databases.md b/content/shared/influxdb3-cli/show/databases.md index 0012d5988c..8f2c888669 100644 --- a/content/shared/influxdb3-cli/show/databases.md +++ b/content/shared/influxdb3-cli/show/databases.md @@ -18,7 +18,7 @@ influxdb3 show databases [OPTIONS] | `-d` | `--database` | _({{< req >}})_ Name of the database to operate on | | | `--token` | Authentication token | | | `--show-deleted` | Include databases marked as deleted in the output | -| | `--format` | Output format (`pretty` _(default)_, `json`, `json_lines`, or `csv`) | +| | `--format` | Output format (`pretty` _(default)_, `json`, `jsonl`, or `csv`) | | `-h` | `--help` | Print help information | ### Option environment variables diff --git a/content/shared/influxdb3-query-guides/_index.md b/content/shared/influxdb3-query-guides/_index.md new file mode 100644 index 0000000000..72fae2ee5f --- /dev/null +++ b/content/shared/influxdb3-query-guides/_index.md @@ -0,0 +1,4 @@ + +Learn to query data stored in {{< product-name >}}. + +{{< children >}} diff --git a/content/shared/influxdb3-query-guides/execute-queries/_index.md b/content/shared/influxdb3-query-guides/execute-queries/_index.md new file mode 100644 index 0000000000..d82abd6a21 --- /dev/null +++ b/content/shared/influxdb3-query-guides/execute-queries/_index.md @@ -0,0 +1,11 @@ +Use tools and libraries to query data stored in an {{< product-name >}} database. + +InfluxDB client libraries and Flight clients can use the Flight+gRPC protocol to +query with SQL or InfluxQL and retrieve data in the +[Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html). +HTTP clients can use the InfluxDB v1 `/query` REST API to query with InfluxQL +and retrieve data in JSON format. + +Learn how to connect to InfluxDB and query your data using the following tools: + +{{< children readmore=true hr=true hlevel="h2" >}} diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md new file mode 100644 index 0000000000..bc04a8fef1 --- /dev/null +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb-v1-api.md @@ -0,0 +1,66 @@ + +Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}} +with InfluxQL. + +The examples below use **cURL** to send HTTP requests to the InfluxDB v1 HTTP API, +but you can use any HTTP client. + +{{% warn %}} +#### InfluxQL feature support + +InfluxQL is being rearchitected to work with the InfluxDB 3 storage engine. +This process is ongoing and some InfluxQL features are still being implemented. +For information about the current implementation status of InfluxQL features, +see [InfluxQL feature support](/influxdb3/version/reference/influxql/feature-support/). +{{% /warn %}} + +Use the v1 `/query` endpoint and the `GET` request method to query data with InfluxQL: + +{{< api-endpoint endpoint="http://{{< influxdb/host >}}/query" method="get" api-ref="/influxdb3/version/api/#tag/Query" >}} + +Provide the following with your request: + +- **Headers:** + - **Authorization:** `Bearer AUTH_TOKEN` + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization + > token. You can either omit this header or include it with an arbitrary + > token string. + +- **Query parameters:** + - **db**: the database to query + - **rp**: Optional: the retention policy to query + - **q**: URL-encoded InfluxQL query + +{{% code-placeholders "(DATABASE|AUTH)_(NAME|TOKEN)" %}} +```sh +curl --get https://{{< influxdb/host >}}/query \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" +``` +{{% /code-placeholders %}} + +Replace the following configuration values: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of the database to query +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your authorization token + +## Return results as JSON or CSV + +By default, the `/query` endpoint returns results in **JSON**, but it can also +return results in **CSV**. To return results as CSV, include the `Accept` header +with the `application/csv` or `text/csv` MIME type: + +{{% code-placeholders "(DATABASE|AUTH)_(NAME|TOKEN)" %}} +```sh +curl --get https://{{< influxdb/host >}}/query \ + --header "Authorization: BEARER AUTH_TOKEN" \ + --header "Accept: application/csv" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SELECT * FROM home" +``` +{{% /code-placeholders %}} diff --git a/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md new file mode 100644 index 0000000000..cbceb3a08c --- /dev/null +++ b/content/shared/influxdb3-query-guides/execute-queries/influxdb3-cli.md @@ -0,0 +1,155 @@ + +Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) +to query data in {{< product-name >}} with SQL or InfluxQL. + +Provide the following with your command: + + + +- **Database name**: The name of the database to query. + Provide this using one of the following: + + - `-d`, `--database` command option + - `INFLUXDB3_DATABASE_NAME` environment variable + +- **Query language** (Optional): The query language of the query. + Use the `-l`, `--language` option to specify one of the following query languages: + + - `sql` _(default)_ + - `influxql` + +- **Query**: SQL or InfluxQL query string to execute. + +{{% code-placeholders "(DATABASE|AUTH)_(TOKEN|NAME)" %}} + +{{< tabs-wrapper >}} +{{% tabs %}} +[SQL](#) +[InfluxQL](#) +{{% /tabs %}} + +{{% tab-content %}} + +```sh +influxdb3 query \ + --database DATABASE_NAME \ + "SELECT * FROM home" +``` +{{% /tab-content %}} + +{{% tab-content %}} + +```sh +influxdb3 query \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT * FROM home" +``` + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% /code-placeholders %}} + +In the examples above and below, replace the following: + + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database to query + +## Output format + +The `influxdb3 query` command supports the following output formats: + +- `pretty` _(default)_ +- `json` +- `jsonl` +- `csv` +- `parquet` _(must [output to a file](#output-query-results-to-a-parquet-file))_ + +Use the `--format` flag to specify the output format: + +{{% code-placeholders "(DATABASE|AUTH)_(TOKEN|NAME)" %}} +{{% influxdb/custom-timestamps %}} +```sh +influxdb3 query \ + --database DATABASE_NAME \ + --format json \ + "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" +``` +{{% /influxdb/custom-timestamps %}} +{{% /code-placeholders %}} + +{{< expand-wrapper >}} +{{% expand "View example pretty-formatted results" %}} +{{% influxdb/custom-timestamps %}} +``` ++----+------+-------------+------+---------------------+ +| co | hum | room | temp | time | ++----+------+-------------+------+---------------------+ +| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00 | +| 0 | 35.9 | Kitchen | 21.0 | 2022-01-01T08:00:00 | +| 0 | 35.9 | Living Room | 21.4 | 2022-01-01T09:00:00 | +| 0 | 36.2 | Kitchen | 23.0 | 2022-01-01T09:00:00 | +| 0 | 36.0 | Living Room | 21.8 | 2022-01-01T10:00:00 | ++----+------+-------------+------+---------------------+ +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example JSON-formatted results" %}} +{{% influxdb/custom-timestamps %}} +```json +[{"co":0,"hum":35.9,"room":"Living Room","temp":21.1,"time":"2022-01-01T08:00:00"},{"co":0,"hum":35.9,"room":"Kitchen","temp":21.0,"time":"2022-01-01T08:00:00"},{"co":0,"hum":35.9,"room":"Living Room","temp":21.4,"time":"2022-01-01T09:00:00"},{"co":0,"hum":36.2,"room":"Kitchen","temp":23.0,"time":"2022-01-01T09:00:00"},{"co":0,"hum":36.0,"room":"Living Room","temp":21.8,"time":"2022-01-01T10:00:00"}] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example JSON-line-formatted results" %}} +{{% influxdb/custom-timestamps %}} +```json +{"co":0,"hum":35.9,"room":"Living Room","temp":21.1,"time":"2022-01-01T08:00:00"} +{"co":0,"hum":35.9,"room":"Kitchen","temp":21.0,"time":"2022-01-01T08:00:00"} +{"co":0,"hum":35.9,"room":"Living Room","temp":21.4,"time":"2022-01-01T09:00:00"} +{"co":0,"hum":36.2,"room":"Kitchen","temp":23.0,"time":"2022-01-01T09:00:00"} +{"co":0,"hum":36.0,"room":"Living Room","temp":21.8,"time":"2022-01-01T10:00:00"} +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example CSV-formatted results" %}} +{{% influxdb/custom-timestamps %}} +```csv +co,hum,room,temp,time +0,35.9,Living Room,21.1,2022-01-01T08:00:00 +0,35.9,Kitchen,21.0,2022-01-01T08:00:00 +0,35.9,Living Room,21.4,2022-01-01T09:00:00 +0,36.2,Kitchen,23.0,2022-01-01T09:00:00 +0,36.0,Living Room,21.8,2022-01-01T10:00:00 +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## Output query results to a Parquet file + +To output query results to a Parquet file, provide the following options with +the `influxdb3 query` command: + +- `--format`: `parquet` +- `-o`, `--output`: the filepath to the Parquet file to store results in + +{{% code-placeholders "(DATABASE|AUTH)_(TOKEN|NAME)" %}} +{{% influxdb/custom-timestamps %}} +```sh +influxdb3 query \ + --database DATABASE_NAME \ + --format parquet \ + --output path/to/results.parquet \ + "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" +``` +{{% /influxdb/custom-timestamps %}} +{{% /code-placeholders %}} diff --git a/content/shared/influxdb3-query-guides/influxql/_index.md b/content/shared/influxdb3-query-guides/influxql/_index.md new file mode 100644 index 0000000000..7e70a0c1c3 --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/_index.md @@ -0,0 +1,8 @@ + +Learn to use InfluxQL to query data stored in {{< product-name >}}. + +{{< children type="anchored-list" >}} + +--- + +{{< children readmore=true hr=true >}} \ No newline at end of file diff --git a/content/shared/influxdb3-query-guides/influxql/aggregate-select.md b/content/shared/influxdb3-query-guides/influxql/aggregate-select.md new file mode 100644 index 0000000000..79493e0ddf --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/aggregate-select.md @@ -0,0 +1,216 @@ + +An InfluxQL query that aggregates data includes the following clauses: + +{{< req type="key" >}} + +- {{< req "\*">}} `SELECT`: Specify fields and calculations to output from a + measurement or use the wildcard alias (`*`) to select all fields and tags + from a measurement. +- {{< req "\*">}} `FROM`: Specify the measurement to query data from. +- `WHERE`: Only retrieve data that meets the specified conditions--for example, + time is in a time range, contains specific tag values, or contains a field + value outside specified thresholds. +- `GROUP BY`: Group data by tag values and time intervals. + +{{% note %}} +For simplicity, the term _"aggregate"_ in this guide refers to applying +both aggregate and selector functions to a dataset. +{{% /note %}} + +Learn how to apply aggregate operations to your queried data: + +- [Aggregate and selector functions](#aggregate-and-selector-functions) + - [Aggregate functions](#aggregate-functions) + - [Selector functions](#selector-functions) +- [Example aggregate queries](#example-aggregate-queries) + +{{% influxql/v1-v3-data-model-note %}} + +## Aggregate and selector functions + +Both aggregate and selector functions return a limited number of rows from each group. +Aggregate functions return a single row, whereas some selector functions let you +specify the number of rows to return from each group. +For example, if you `GROUP BY room` and perform an aggregate operation +in your `SELECT` clause, results include an aggregate value for each unique +value of `room`. + +### Aggregate functions + +Use **aggregate functions** to aggregate values in a specified field for each +group and return a single row per group containing the aggregate field value. + +View InfluxQL aggregate functions + +##### Basic aggregate query + +```sql +SELECT MEAN(co) from home +``` + +### Selector functions + +Use **selector functions** to "select" a value from a specified field. + +View InfluxQL selector functions + +##### Basic selector query + +```sql +SELECT TOP(co, 3) from home +``` + +## Example aggregate queries + +- [Perform an ungrouped aggregation](#perform-an-ungrouped-aggregation) +- [Group and aggregate data](#group-and-aggregate-data) + - [Downsample data by applying interval-based aggregates](#downsample-data-by-applying-interval-based-aggregates) +- [Query rows based on aggregate values](#query-rows-based-on-aggregate-values) + +> [!Note] +> +> #### Sample data +> +> The following examples use the [Home sensor data](/influxdb3/version/reference/sample-data/#home-sensor-data). +> To run the example queries and return results, +> [write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +> to your {{% product-name %}} database before running the example queries. + +### Perform an ungrouped aggregation + +To aggregate _all_ queried values in a specified field: + +- Use aggregate or selector functions in your `SELECT` statement. +- Do not include a `GROUP BY` clause to leave your data ungrouped. + +```sql +SELECT MEAN(co) AS "average co" FROM home +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| time | average co | +| :--- | ----------------: | +| 0 | 5.269230769230769 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Group and aggregate data + +To apply aggregate or selector functions to grouped data: + +- Use aggregate or selector functions in your `SELECT` statement. +- Include a `GROUP BY` clause with a comma-delimited list of tags to group by. + +Keep the following in mind when using `GROUP BY`: + +- `GROUP BY` can use column aliases that are defined in the `SELECT` clause. + +```sql +SELECT + MEAN(temp) AS "average temp" +FROM home +GROUP BY room +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} + +{{% influxql/table-meta %}} +name: home +tags: room=Kitchen +{{% /influxql/table-meta %}} + +| time | average temp | +| :--- | -----------------: | +| 0 | 22.623076923076926 | + +{{% influxql/table-meta %}} +name: home +tags: room=Living Room +{{% /influxql/table-meta %}} + +| time | average temp | +| :--- | ----------------: | +| 0 | 22.16923076923077 | +{{% /expand %}} +{{< /expand-wrapper >}} + +#### Downsample data by applying interval-based aggregates + +A common use case when querying time series is downsampling data by applying +aggregates to time-based groups. To group and aggregate data into time-based +groups: + +- In your `SELECT` clause, apply [aggregate](/influxdb3/version/reference/influxql/functions/aggregates/) + or [selector](/influxdb3/version/reference/influxql/functions/selectors/) + functions to queried fields. + +- In your `WHERE` clause, include time bounds for the query. + Interval-based aggregates produce a row for each specified time interval. + If no time bounds are specified in the `WHERE` clause, the query uses the + default time range (1970-01-01T00:00:00Z to now) and returns a row for each + interval in that time range. + +- In your `GROUP BY` clause: + + - Use the [`time()` function](/influxdb3/version/reference/influxql/functions/date-time/#time) + to specify the time interval to group by. + - _Optional_: Specify other tags to group by. + + +The following example retrieves unique combinations of time intervals and rooms with their minimum, maximum, and average temperatures. + +```sql +SELECT + MAX(temp) AS "max temp", + MIN(temp) AS "min temp", + MEAN(temp) AS "average temp" +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time < '2022-01-01T20:00:00Z' +GROUP BY time(2h), room +``` + +{{< expand-wrapper >}} +{{% expand "View example results" "1" %}} +{{% influxdb/custom-timestamps %}} + +{{% influxql/table-meta %}} +name: home +tags: room=Kitchen +{{% /influxql/table-meta %}} + +| time | max temp | min temp | average temp | +| :------------------- | -------: | -------: | -----------------: | +| 2022-01-01T08:00:00Z | 23 | 21 | 22 | +| 2022-01-01T10:00:00Z | 22.7 | 22.4 | 22.549999999999997 | +| 2022-01-01T12:00:00Z | 22.8 | 22.5 | 22.65 | +| 2022-01-01T14:00:00Z | 22.8 | 22.7 | 22.75 | +| 2022-01-01T16:00:00Z | 22.7 | 22.4 | 22.549999999999997 | +| 2022-01-01T18:00:00Z | 23.3 | 23.1 | 23.200000000000003 | +| 2022-01-01T20:00:00Z | 22.7 | 22.7 | 22.7 | + +{{% influxql/table-meta %}} +name: home +tags: room=Living Room +{{% /influxql/table-meta %}} + +| time | max temp | min temp | average temp | +| :------------------- | -------: | -------: | -----------------: | +| 2022-01-01T08:00:00Z | 21.4 | 21.1 | 21.25 | +| 2022-01-01T10:00:00Z | 22.2 | 21.8 | 22 | +| 2022-01-01T12:00:00Z | 22.4 | 22.2 | 22.299999999999997 | +| 2022-01-01T14:00:00Z | 22.3 | 22.3 | 22.3 | +| 2022-01-01T16:00:00Z | 22.6 | 22.4 | 22.5 | +| 2022-01-01T18:00:00Z | 22.8 | 22.5 | 22.65 | +| 2022-01-01T20:00:00Z | 22.2 | 22.2 | 22.2 | + +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxdb3-query-guides/influxql/basic-query.md b/content/shared/influxdb3-query-guides/influxql/basic-query.md new file mode 100644 index 0000000000..f44441c0d5 --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/basic-query.md @@ -0,0 +1,230 @@ + +InfluxQL (Influx Query Language) is an SQL-like query language used to interact +with InfluxDB and work with times series data. + +{{% influxql/v1-v3-data-model-note %}} + +A basic InfluxQL query that queries data from InfluxDB most commonly includes the +following clauses: + +{{< req type="key" >}} + +- {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to return + from a [table](/influxdb3/version/reference/glossary/#table) or use the + wildcard alias (`*`) to select all fields and tags from a table. It requires + at least one + [field key](/influxdb3/version/reference/glossary/#field-key) or the + wildcard alias (`*`). For more information, see + [Notable SELECT statement behaviors](/influxdb3/version/reference/influxql/select/#notable-select-statement-behaviors). +- {{< req "\*">}} `FROM`: Specify the + [table](/influxdb3/version/reference/glossary/#table) to query from. + + It requires one or more comma-delimited + [measurement expressions](/influxdb3/version/reference/influxql/select/#measurement_expression). + +- `WHERE`: Filter data based on + [field values](/influxdb3/version/reference/glossary/#field), + [tag values](/influxdb3/version/reference/glossary/#tag), or + [timestamps](/influxdb3/version/reference/glossary/#timestamp). Only + return data that meets the specified conditions--for example, falls within a + time range, contains specific tag values, or contains a field value outside a + specified range. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + temp, + hum, + room +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +{{% /influxdb/custom-timestamps %}} + +## Result set + +If at least one row satisfies the query, {{% product-name %}} returns row data +in the query result set. +If a query uses a `GROUP BY` clause, the result set +includes the following: + +- Columns listed in the query's `SELECT` clause +- A `time` column that contains the timestamp for the record or the group +- An `iox::measurement` column that contains the record's + [table](/influxdb3/version/reference/glossary/#table) name +- Columns listed in the query's `GROUP BY` clause; each row in the result set + contains the values used for grouping + +### GROUP BY result columns + +If a query uses `GROUP BY` and the `WHERE` clause doesn't filter by time, then +groups are based on the +[default time range](/influxdb3/version/reference/influxql/group-by/#default-time-range). + +## Basic query examples + +- [Query data within time boundaries](#query-data-within-time-boundaries) +- [Query data without time boundaries](#query-data-without-time-boundaries) +- [Query specific fields and tags](#query-specific-fields-and-tags) +- [Query fields based on tag values](#query-fields-based-on-tag-values) +- [Query points based on field values](#query-points-based-on-field-values) +- [Alias queried fields and tags](#alias-queried-fields-and-tags) + +> [!Note] +> +> #### Sample data +> +> The following examples use the [Home sensor data](/influxdb3/version/reference/sample-data/#home-sensor-data). +> To run the example queries and return results, +> [write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +> to your {{% product-name %}} database before running the example queries. + +### Query data within time boundaries + +- Use the `SELECT` clause to specify what tags and fields to return. + Specify at least one field key. + To return all tags and fields, use the wildcard alias (`*`). +- Specify the [table](/influxdb3/version/reference/glossary/#table) to + query in the `FROM` clause. +- Specify time boundaries in the `WHERE` clause. Include time-based predicates + that compare the value of the `time` column to a timestamp. + Use the `AND` logical operator to chain multiple predicates together. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +``` + +{{% /influxdb/custom-timestamps %}} + +Query time boundaries can be relative or absolute. + +{{< expand-wrapper >}} +{{% expand "Query with relative time boundaries" %}} + +To query data from relative time boundaries, compare the value of the `time` +column to a timestamp calculated by subtracting an interval from a timestamp. +Use `now()` to return the timestamp for the current time (UTC). + +##### Query all data from the last month + +```sql +SELECT * FROM home WHERE time >= now() - 30d +``` + +##### Query one day of data from a week ago + +```sql +SELECT * +FROM home +WHERE + time >= now() - 7d + AND time <= now() - 6d +``` + +{{% /expand %}} + +{{% expand "Query with absolute time boundaries" %}} + +To query data from absolute time boundaries, compare the value of the `time` +column to a timestamp literal. +Use the `AND` logical operator to chain together +multiple predicates and define both start and stop boundaries for the query. + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` + +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Query data without time boundaries + +To query data without time boundaries, do not include any time-based predicates +in your `WHERE` clause. +If a time range is not defined in the `WHERE` clause, +the default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. + +{{% warn %}} +Querying data _without time bounds_ can return an unexpected amount of data. +The query may take a long time to complete and results may be truncated. +{{% /warn %}} + +```sql +SELECT * FROM home +``` + +### Query specific fields and tags + +To query specific fields, include them in the `SELECT` clause. +If querying multiple fields or tags, comma-delimit each. +If a field or tag key includes special characters or spaces or is +case-sensitive, wrap the key in _double-quotes_. + +```sql +SELECT time, room, temp, hum FROM home +``` + +### Query fields based on tag values + +- In the `SELECT` clause, include fields you want to query and tags you want to + base conditions on. +- In the `WHERE` clause, include predicates that compare the tag identifier to a + string literal. Use + [logical operators](/influxdb3/version/reference/influxql/where/#logical-operators) + to chain multiple predicates together and apply multiple conditions. + +```sql +SELECT * FROM home WHERE room = 'Kitchen' +``` + +### Query points based on field values + +- In the `SELECT` clause, include fields you want to query. +- In the `WHERE` clause, include predicates that compare the field identifier to + a value or expression. + Use + [logical operators](/influxdb3/version/reference/influxql/where/#logical-operators) + (`AND`, `OR`) to chain multiple predicates together and apply multiple + conditions. + +```sql +SELECT co, time FROM home WHERE co >= 10 OR co <= -10 +``` + +### Alias queried fields and tags + +To alias or rename fields and tags that you query, use the `AS` clause. +After the tag, field, or expression you want to alias, pass `AS` followed by the +alias name as an identifier (wrap in double quotes (`"`) if the alias includes +spaces or special characters)--for example: + +```sql +SELECT temp AS temperature, hum AS "humidity (%)" FROM home +``` + +{{% note %}} +When aliasing columns in **InfluxQL**, use the `AS` clause and an +[identifier](/influxdb3/version/reference/influxql/#identifiers). When +[aliasing columns in **SQL**](/influxdb3/version/query-data/sql/basic-query/#alias-queried-fields-and-tags), +you can use the `AS` clause to define the alias, but it isn't necessary. +{{% /note %}} diff --git a/content/shared/influxdb3-query-guides/influxql/explore-schema.md b/content/shared/influxdb3-query-guides/influxql/explore-schema.md new file mode 100644 index 0000000000..7685878b4b --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/explore-schema.md @@ -0,0 +1,323 @@ + +Use InfluxQL `SHOW` statements to return information about your data schema. + +{{% influxql/v1-v3-data-model-note %}} + +- [List measurements in a database](#list-measurements-in-a-database) + - [List measurements that contain specific tag key-value pairs](#list-measurements-that-contain-specific-tag-key-value-pairs) + - [List measurements that match a regular expression](#list-measurements-that-match-a-regular-expression) +- [List field keys in a measurement](#list-field-keys-in-a-measurement) +- [List tag keys in a measurement](#list-tag-keys-in-a-measurement) + - [List tag keys in measurements that contain a specific tag key-value pair](#list-tag-keys-in-measurements-that-contain-a-specific-tag-key-value-pair) +- [List tag values for a specific tag key](#list-tag-values-for-a-specific-tag-key) + - [List tag values for multiple tags](#list-tag-values-for-multiple-tags) + - [List tag values for tags that match a regular expression](#list-tag-values-for-tags-that-match-a-regular-expression) + - [List tag values associated with a specific tag key-value pair](#list-tag-values-associated-with-a-specific-tag-key-value-pair) + +> [!Note] +> +> #### Sample data +> +> The following examples use data provided in [sample data sets](/influxdb3/version/reference/sample-data/). +> To run the example queries and return identical results, follow the instructions +> provided for each sample data set to write the data to your {{% product-name %}} +> database. + +## List measurements in a database + +Use [`SHOW MEASUREMENTS`](/influxdb3/version/reference/influxql/show/#show-measurements) +to list measurements in your InfluxDB database. + +```sql +SHOW MEASUREMENTS +``` + +{{< expand-wrapper >}} +{{% expand "View example output" %}} + +{{% influxql/table-meta %}} +name: measurements +{{% /influxql/table-meta %}} + +| name | +| :----------- | +| bitcoin | +| home | +| home_actions | +| numbers | +| weather | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List measurements that contain specific tag key-value pairs + +To return only measurements with specific tag key-value pairs, include a `WHERE` +clause with tag key-value pairs to query for. + +```sql +SHOW MEASUREMENTS WHERE room = 'Kitchen' +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "1" %}} + +{{% influxql/table-meta %}} +name: measurements +{{% /influxql/table-meta %}} + +| name | +| :----------- | +| home | +| home_actions | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List measurements that match a regular expression + +To return only measurements with names that match a +[regular expression](/influxdb3/version/reference/influxql/regular-expressions/), +include a `WITH` clause that compares the `MEASUREMENT` to a regular expression. + +```sql +SHOW MEASUREMENTS WITH MEASUREMENT =~ /^home/ +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "2" %}} + +{{% influxql/table-meta %}} +name: measurements +{{% /influxql/table-meta %}} + +| name | +| :----------- | +| home | +| home_actions | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## List field keys in a measurement + +Use [`SHOW FIELD KEYS`](/influxdb3/version/reference/influxql/show/#show-field-keys) +to return all field keys in a measurement. +Include a `FROM` clause to specify the measurement. +If no measurement is specified, the query returns all field keys in the database. + +```sql +SHOW FIELD KEYS FROM home +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "3" %}} + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| fieldKey | fieldType | +| :------- | :-------- | +| co | integer | +| hum | float | +| temp | float | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## List tag keys in a measurement + +Use [`SHOW TAG KEYS`](/influxdb3/version/reference/influxql/show/#show-field-keys) +to return all tag keys in a measurement. +Include a `FROM` clause to specify the measurement. +If no measurement is specified, the query returns all tag keys in the database. + +```sql +SHOW TAG KEYS FROM home_actions +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "4" %}} + +{{% influxql/table-meta %}} +name: home_actions +{{% /influxql/table-meta %}} + +| tagKey | +| :----- | +| action | +| level | +| room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List tag keys in measurements that contain a specific tag key-value pair + +To return all tag keys measurements that contain specific tag key-value pairs, +include a `WHERE` clause with the tag key-value pairs to query for. + +```sql +SHOW TAG KEYS WHERE room = 'Kitchen' +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "5" %}} + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| tagKey | +| :----- | +| room | + +{{% influxql/table-meta %}} +name: home_actions +{{% /influxql/table-meta %}} + +| tagKey | +| :----- | +| action | +| level | +| room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## List tag values for a specific tag key + +Use [`SHOW TAG VALUES`](/influxdb3/version/reference/influxql/show/#show-field-values) +to return all values for specific tags in a measurement. + +- Include a `FROM` clause to specify one or more measurements to query. +- Use the `WITH` clause to compare `KEY` to tag keys to list the values of. +- Use the `WHERE` clause to restrict the search to a specific time range + (default time range is the last day). + +```sql +SHOW TAG VALUES FROM weather WITH KEY = location +``` + +{{% note %}} + +#### Include a FROM clause + +We strongly recommend including a `FROM` clause with the `SHOW TAG VALUES` +statement that specifies 1-50 tables to query. +Without a `FROM` clause, the InfluxDB query engine must read data from all +tables and return unique tag values from each. + +Depending on the number of tables in your database and the number of unique tag +values in each table, excluding a `FROM` clause can result in poor query performance, +query timeouts, or unnecessary resource allocation that may affect other queries. + +{{% /note %}} + +{{< expand-wrapper >}} +{{% expand "View example output" "5" %}} + +{{% influxql/table-meta %}} +name: weather +{{% /influxql/table-meta %}} + +| key | value | +| :------- | :------------ | +| location | Concord | +| location | Hayward | +| location | San Francisco | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List tag values for multiple tags + +To return tag values for multiple specific tag keys, use the `IN` operator in +the `WITH` clause to compare `KEY` to a list of tag keys. + +```sql +SHOW TAG VALUES FROM home_actions WITH KEY IN ("level", "action") +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "6" %}} + +{{% influxql/table-meta %}} +name: home_actions +{{% /influxql/table-meta %}} + +| key | value | +| :----- | :---- | +| action | alert | +| action | cool | +| level | ok | +| level | warn | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List tag values for tags that match a regular expression + +To return only tag values from tags keys that match a regular expression, use +regular expression comparison operators in your `WITH` clause to compare `KEY` +to the regular expression. + +```sql +SHOW TAG VALUES FROM home, home_actions WITH KEY =~ /oo/ +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "7" %}} + +{{% influxql/table-meta %}} +name: home +{{% /influxql/table-meta %}} + +| key | value | +| :--- | :---------- | +| room | Kitchen | +| room | Living Room | + +{{% influxql/table-meta %}} +name: home_actions +{{% /influxql/table-meta %}} + +| key | value | +| :--- | :---------- | +| room | Kitchen | +| room | Living Room | + +{{% /expand %}} +{{< /expand-wrapper >}} + +### List tag values associated with a specific tag key-value pair + +To list tag values for tags associated with a specific tag key-value pair: + +- Use the `WITH` clause to identify what tag keys to return values for. +- Include a `WHERE` clause that identifies the tag key-value pair to query for. + +The following example returns tag values for the `action` and `level` tags for +points where the `room` tag value is `Kitchen`. + +```sql +SHOW TAG VALUES FROM home_actions WITH KEY IN ("action", "level") WHERE room = 'Kitchen' +``` + +{{< expand-wrapper >}} +{{% expand "View example output" "8" %}} + +{{% influxql/table-meta %}} +name: home_actions +{{% /influxql/table-meta %}} + +| key | value | +| :----- | :---- | +| action | alert | +| action | cool | +| level | ok | +| level | warn | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxdb3-query-guides/influxql/parameterized-queries.md b/content/shared/influxdb3-query-guides/influxql/parameterized-queries.md new file mode 100644 index 0000000000..bc2279218a --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/parameterized-queries.md @@ -0,0 +1,315 @@ + +Parameterized queries in {{% product-name %}} let you dynamically and safely change values in a query. +If your application code allows user input to customize values or expressions in a query, use a parameterized query to make sure untrusted input is processed strictly as data and not executed as code. + +Parameterized queries: + +- help prevent injection attacks, which can occur if input is executed as code +- help make queries more reusable + +{{% note %}} +#### Prevent injection attacks + +For more information on security and query parameterization, +see the [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html#defense-option-1-prepared-statements-with-parameterized-queries). +{{% /note %}} + +In InfluxDB 3, a parameterized query is an InfluxQL or SQL query that contains one or more named parameter placeholders–variables that represent input data. + +- [Use parameters in `WHERE` expressions](#use-parameters-in-where-expressions) +- [Parameter data types](#parameter-data-types) + - [Data type examples](#data-type-examples) + - [Time expressions](#time-expressions) + - [Not compatible with parameters](#not-compatible-with-parameters) +- [Parameterize an SQL query](#parameterize-an-sql-query) +- [Execute parameterized InfluxQL queries](#execute-parameterized-influxql-queries) + - [Use InfluxDB Flight RPC clients](#use-influxdb-flight-rpc-clients) +- [Client support for parameterized queries](#client-support-for-parameterized-queries) +- [Not supported](#not-supported) + +{{% note %}} + +#### Parameters only supported in `WHERE` expressions + +InfluxDB 3 supports parameters in `WHERE` clause **predicate expressions**. +Parameter values must be one of the [allowed parameter data types](#parameter-data-types). + +If you use parameters in other expressions or clauses, +such as function arguments, `SELECT`, or `GROUP BY`, then your query might not work as you expect. + +{{% /note %}} + +## Use parameters in `WHERE` expressions + +You can use parameters in `WHERE` clause **predicate expressions**-–for example, the following query contains a `$temp` parameter: + +```sql +SELECT * FROM measurement WHERE temp > $temp +``` + +When executing a query, you specify parameter name-value pairs. +The value that you assign to a parameter must be one of the [parameter data types](#parameter-data-types). + +```go +{"temp": 22.0} +``` + +The InfluxDB Querier parses the query text with the parameter placeholders, and then generates query plans that replace the placeholders with the values that you provide. +This separation of query structure from input data ensures that input is treated as one of the allowed [data types](#parameter-data-types) and not as executable code. + +## Parameter data types + +A parameter value can be one of the following data types: + +- Null +- Boolean +- Unsigned integer (`u_int64`) +- Integer (`int64`) +- Double (`float64`) +- String + +### Data type examples + +```js +{ + "string": "Living Room", + "double": 3.14, + "unsigned_integer": 1234, + "integer": -1234, + "boolean": false, + "null": Null, +} +``` + +### Time expressions + +To parameterize time bounds, substitute a parameter for a timestamp literal--for example: + +```sql +SELECT * +FROM home +WHERE time >= $min_time +``` + +For the parameter value, specify the timestamp literal as a string--for example: + +{{% influxdb/custom-timestamps %}} + +```go +// Assign a timestamp string literal to the min_time parameter. +parameters := influxdb3.QueryParameters{ + "min_time": "2022-01-01 00:00:00.00", +} +``` + +{{% /influxdb/custom-timestamps %}} + +InfluxDB executes the query as the following: + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE time >= '2022-01-01 00:00:00.00' +``` + +{{% /influxdb/custom-timestamps %}} + +### Not compatible with parameters + +If you use parameters for the following, your query might not work as you expect: + +- In clauses other than `WHERE`, such as `SELECT` or `GROUP BY` +- As function arguments, such as `avg($temp)` +- In place of identifiers, such as column or table names +- In place of duration literals, such as `time > now() - $min_duration` + +## Parameterize an SQL query + +{{% note %}} +#### Sample data + +The following examples use the +[Get started home sensor data](/influxdb3/version/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% product-name %}} database before running the example queries. +{{% /note %}} + +To use a parameterized query, do the following: + +1. In your query text, use the `$parameter` syntax to reference a parameter name--for example, +the following query contains `$room` and `$min_temp` parameter placeholders: + + ```sql + SELECT * + FROM home + WHERE time > now() - 7d + AND temp >= $min_temp + AND room = $room + ``` + +2. Provide a value for each parameter name. + If you don't assign a value for a parameter, InfluxDB returns an error. + The syntax for providing parameter values depends on the client you use--for example: + + + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} + [Go](#) + {{% /code-tabs %}} + {{% code-tab-content %}} + + ```go + // Define a QueryParameters struct--a map of parameters to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + } + ``` + + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +After InfluxDB receives your request and parses the query, it executes the query as + +```sql +SELECT * +FROM home +WHERE time > now() - 7d +AND temp >= 20.0 +AND room = 'Kitchen' +``` + +## Execute parameterized InfluxQL queries + +{{% note %}} +#### Sample data + +The following examples use the +[Get started home sensor data](/influxdb3/version/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% product-name %}} database before running the example queries. +{{% /note %}} + +### Use InfluxDB Flight RPC clients + +Using the InfluxDB 3 native Flight RPC protocol and supported clients, you can send a parameterized query and a list of parameter name-value pairs. +InfluxDB Flight clients that support parameterized queries pass the parameter name-value pairs in a Flight ticket `params` field. + +The following examples show how to use client libraries to execute parameterized InfluxQL queries: + + + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Go](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} + +```go +import ( + "context" + "fmt" + "io" + "os" + "text/tabwriter" + "time" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" +) + +func Query(query string, parameters influxdb3.QueryParameters, + options influxdb3.QueryOptions) error { + url := os.Getenv("INFLUX_HOST") + token := os.Getenv("INFLUX_TOKEN") + database := os.Getenv("INFLUX_DATABASE") + + // Instantiate the influxdb3 client. + client, err := influxdb3.New(influxdb3.ClientConfig{ + Host: url, + Token: token, + Database: database, + }) + + if err != nil { + panic(err) + } + + // Ensure the client is closed after the Query function finishes. + defer func(client *influxdb3.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) + + // Call the client's QueryWithParameters function. + // Provide the query, parameters, and the InfluxQL QueryType option. + iterator, err := client.QueryWithParameters(context.Background(), query, + parameters, influxdb3.WithQueryType(options.QueryType)) + + // Create a buffer for storing rows as you process them. + w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) + w.Init(os.Stdout, 0, 8, 0, '\t', 0) + + fmt.Fprintf(w, "time\troom\tco\thum\ttemp\n") + + // Format and write each row to the buffer. + // Process each row as key-value pairs. + for iterator.Next() { + row := iterator.Value() + // Use Go time package to format unix timestamp + // as a time with timezone layout (RFC3339 format) + time := (row["time"].(time.Time)). + Format(time.RFC3339) + + fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", + time, row["room"], row["co"], row["hum"], row["temp"]) + } + w.Flush() + + return nil +} + +func main() { + // Use the $placeholder syntax in a query to reference parameter placeholders + // for input data. + // The following InfluxQL query contains the placeholders $room and $min_temp. + query := ` + SELECT * + FROM home + WHERE time > now() - 7d + AND temp >= $min_temp + AND room = $room` + + // Define a QueryParameters struct--a map of placeholder names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + } + + Query(query, parameters, influxdb3.QueryOptions{ + QueryType: influxdb3.InfluxQL, + }) +} +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Client support for parameterized queries + +- Not all [InfluxDB 3 Flight clients](/influxdb3/version/reference/client-libraries/v3/) support parameterized queries. +- InfluxDB doesn't currently support parameterized queries or DataFusion prepared statements for Flight SQL or Flight SQL clients. +- InfluxDB 3 SQL and InfluxQL parameterized queries aren’t supported in InfluxDB v1 and v2 clients. + +## Not supported + +Currently, parameterized queries in {{% product-name %}} don't provide the following: + +- support for DataFusion prepared statements +- query caching, optimization, or performance benefits diff --git a/content/shared/influxdb3-query-guides/influxql/troubleshoot.md b/content/shared/influxdb3-query-guides/influxql/troubleshoot.md new file mode 100644 index 0000000000..d7a1b74360 --- /dev/null +++ b/content/shared/influxdb3-query-guides/influxql/troubleshoot.md @@ -0,0 +1,259 @@ + +Learn how to troubleshoot and fix common InfluxQL errors. + +> [!Note] +> **Disclaimer:** This document does not contain an exhaustive list of all +> possible InfluxQL errors. + +- [error: database name required](#error-database-name-required) +- [error parsing query: found ..., expected identifier at ...](#error-parsing-query-found--expected-identifier-at-) +- [error parsing query: mixing aggregate and non-aggregate queries is not supported](#error-parsing-query-mixing-aggregate-and-non-aggregate-queries-is-not-supported) +- [invalid operation: time and \*influxql.VarRef are not compatible](#invalid-operation-time-and-influxqlvarref-are-not-compatible) + +{{% influxql/v1-v3-data-model-note %}} + +## error: database name required + +``` +error: database name required +``` + +### Cause + +The `database name required` error occurs when certain +[`SHOW` queries](/influxdb3/version/reference/influxql/show/) +do not specify a [database](/influxdb3/version/reference/glossary/#database) +in the query or with the query request. + +For example, the following `SHOW` query doesn't specify the database and assumes +the `db` is not specified in the `/query` API request: + +```sql +SHOW MEASUREMENTS +``` + +### Solution + +To resolve this error, specify a database with your query request by doing one +of the following: + +{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}} + +- Include an `ON` clause with the `SHOW` statement that specifies the database + to query: + + ```sql + SHOW MEASUREMENTS ON DATABASE_NAME + ``` + +- If using the [InfluxDB v1 query API](/enterprise_influxdb/v1/tools/api/#query-string-parameters), + Include the `db` query parameter in your request: + + ```sh + curl --get https://{{< influxdb/host >}}/query \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SHOW MEASUREMENTS" + ``` + +{{% /code-placeholders %}} + +**Related:** +[InfluxQL `SHOW` statements](/influxdb3/version/reference/influxql/show/), +[Explore your schema with InfluxQL](/influxdb3/version/query-data/influxql/explore-schema/) + +--- + +## error parsing query: found ..., expected identifier at ... + +``` +error parsing query: found EXAMPLE, expected identifier at line 1, char 14 +``` + +### Causes + +This error occurs when InfluxDB anticipates an identifier in a query but doesn't find it. +Identifiers are tokens that refer to database names, retention policy names, +measurement names, field keys, and tag keys. + +This error is generally caused by one of the following: + +- [A required identifier is missing](#a-required-identifier-is-missing) +- [A string literal is used instead of an identifier](#a-string-literal-is-used-instead-of-an-identifier) +- [An InfluxQL keyword is used as an unquoted identifier](#an-influxql-keyword-is-used-as-an-unquoted-identifier) + +#### A required identifier is missing + +Some InfluxQL statements and clauses require identifiers to identify databases, +measurements, tags, or fields. If the statement is missing a required identifier, +the query returns the `expected identifier` error. + +For example, the following query omits the measurement name from the +[`FROM` clause](/influxdb3/version/reference/influxql/select/#from-clause): + +```sql +SELECT * FROM WHERE color = 'blue' +``` + +##### Solution + +Update the query to include the expected identifier in the `FROM` clause that +identifies the measurement to query: + +```sql +SELECT * FROM measurement_name WHERE color = 'blue' +``` + +#### A string literal is used instead of an identifier + +In InfluxQL, string literals are wrapped in single quotes (`''`) while character +sequences wrapped in double quotes (`""`) are parsed as identifiers. If you use +single quotes to wrap an identifier, the identifier is parsed as a string +literal and returns the `expected identifier` error. + +For example, the following query wraps the measurement name in single quotes: + +```sql +SELECT * FROM 'measurement-name' WHERE color = 'blue' +``` + +Results in the following error: + +``` +error parsing query: found measurement-name, expected identifier at line 1, char 14 +``` + +##### Solution + +Update single-quoted identifiers to use double quotes so they are parsed as +identifiers and not as string literals. + +```sql +SELECT * FROM "measurement-name" WHERE color = 'blue' +``` + +#### An InfluxQL keyword is used as an unquoted identifier + +[InfluxQL keyword](/influxdb3/version/reference/influxql/#keywords) +are character sequences reserved for specific functionality in the InfluxQL syntax. +It is possible to use a keyword as an identifier, but the identifier must be +wrapped in double quotes (`""`). + +{{% note %}} +While wrapping identifiers that are InfluxQL keywords in double quotes is an +acceptable workaround, for simplicity, you should avoid using +[InfluxQL keywords](/influxdb3/version/reference/influxql/#keywords) +as identifiers. +{{% /note %}} + +```sql +SELECT duration FROM runs +``` + +Returns the following error: + +``` +error parsing query: found DURATION, expected identifier, string, number, bool at line 1, char 8 +``` + +##### Solution + +Double quote [InfluxQL keywords](/influxdb3/version/reference/influxql/#keywords) +when used as identifiers: + +```sql +SELECT "duration" FROM runs +``` + +**Related:** +[InfluxQL keywords](/influxdb3/version/reference/influxql/#keywords) + +--- + +## error parsing query: mixing aggregate and non-aggregate queries is not supported + +``` +error parsing query: mixing aggregate and non-aggregate queries is not supported +``` + +### Cause + +The `mixing aggregate and non-aggregate` error occurs when a `SELECT` statement +includes both an [aggregate function](/influxdb3/version/reference/influxql/functions/aggregates/) +and a standalone [field key](/influxdb3/version/reference/glossary/#field-key) or +[tag key](/influxdb3/version/reference/glossary/#tag-key). + +Aggregate functions return a single calculated value per group and column and +there is no obvious single value to return for any un-aggregated fields or tags. + +For example, the following example queries two fields from the `home` +measurement--`temp` and `hum`. However, it only applies the aggregate function, +`MEAN` to the `temp` field. + +```sql +SELECT MEAN(temp), hum FROM home +``` + +### Solution + +To fix this error, apply an aggregate or selector function to each of the queried +fields: + +```sql +SELECT MEAN(temp), MAX(hum) FROM home +``` + +**Related:** +[InfluxQL functions](/influxdb3/version/reference/influxql/functions/), +[Aggregate data with InfluxQL](/influxdb3/version/query-data/influxql/aggregate-select/) + +--- + +## invalid operation: time and \*influxql.VarRef are not compatible + +``` +invalid operation: time and *influxql.VarRef are not compatible +``` + +### Cause + +The `time and \*influxql.VarRef are not compatible` error occurs when +date-time strings are double-quoted in a query. +Date-time strings should be formatted as string literals and wrapped in single quotes (`''`). + +For example: + +{{% influxdb/custom-timestamps %}} +```sql +SELECT temp +FROM home +WHERE + time >= "2022-01-01T08:00:00Z" + AND time <= "2022-01-01T00:20:00Z" +``` +{{% /influxdb/custom-timestamps %}} + +Returns the following error: + +``` +invalid operation: time and *influxql.VarRef are not compatible +``` + +### Solution + +To fix the error, wrap RFC3339 timestamps in single quotes rather than double quotes. + +{{% influxdb/custom-timestamps %}} +```sql +SELECT temp +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T00:20:00Z' +``` +{{% /influxdb/custom-timestamps %}} + +**Related:** +[Query data within time boundaries](/influxdb3/version/query-data/influxql/basic-query/#query-data-within-time-boundaries), +[`WHERE` clause--Time ranges](/influxdb3/version/reference/influxql/where/#time-ranges), +[InfluxQL time syntax](/influxdb3/version/reference/influxql/time-and-timezone/#time-syntax) diff --git a/content/shared/influxdb3-query-guides/sql/_index.md b/content/shared/influxdb3-query-guides/sql/_index.md new file mode 100644 index 0000000000..b0c677e4f8 --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/_index.md @@ -0,0 +1,8 @@ + +Learn to query data stored in {{< product-name >}} using SQL. + +{{< children type="anchored-list" >}} + +--- + +{{< children readmore=true hr=true >}} \ No newline at end of file diff --git a/content/shared/influxdb3-query-guides/sql/aggregate-select.md b/content/shared/influxdb3-query-guides/sql/aggregate-select.md new file mode 100644 index 0000000000..1db4da3c10 --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/aggregate-select.md @@ -0,0 +1,322 @@ + +An SQL query that aggregates data includes the following clauses: + +{{< req type="key" >}} + +- {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output from a + table or use the wildcard alias (`*`) to select all fields and tags + from a table. +- {{< req "\*">}} `FROM`: Specify the table to query data from. +- `WHERE`: Only return rows that meets the specified conditions--for example, + the time is within a time range, a tag has a specific value, or a field value + is above or below a specified threshold. +- `GROUP BY`: Group data that have the same values for specified columns and + expressions (for example, an aggregate function result). + +{{% note %}} +For simplicity, the verb, **"aggregate,"** in this guide refers to applying +both aggregate and selector functions to a dataset. +{{% /note %}} + +Learn how to apply aggregate operations to your queried data: + +- [Aggregate and selector functions](#aggregate-and-selector-functions) + - [Aggregate functions](#aggregate-functions) + - [Selector functions](#selector-functions) +- [Example aggregate queries](#example-aggregate-queries) + +## Aggregate and selector functions + +Both aggregate and selector functions return a single row from each SQL group. +For example, if you `GROUP BY room` and perform an aggregate operation +in your `SELECT` clause, results include an aggregate value for each unique +value of `room`. + +### Aggregate functions + +Use **aggregate functions** to aggregate values in a specified column for each +group and return a single row per group containing the aggregate value. + +View SQL aggregate functions + +##### Basic aggregate query + +```sql +SELECT AVG(co) from home +``` + +### Selector functions + +Use **selector functions** to "select" a value from a specified column. +The available selector functions are designed to work with time series data. + +View SQL selector functions + +Each selector function returns a Rust _struct_ (similar to a JSON object) +representing a single time and value from the specified column in the each group. +What time and value get returned depend on the logic in the selector function. +For example, `selector_first` returns the value of specified column in the first +row of the group. `selector_max` returns the maximum value of the specified +column in the group. + +#### Selector struct schema + +The struct returned from a selector function has two properties: + +- **time**: `time` value in the selected row +- **value**: value of the specified column in the selected row + +```js +{time: 2023-01-01T00:00:00Z, value: 72.1} +``` + +#### Use selector functions + +Each selector function has two arguments: + +- The first is the column to operate on. +- The second is the time column to use in the selection logic. + +In your `SELECT` statement, execute a selector function and use bracket notation +to reference properties of the [returned struct](#selector-struct-schema) to +populate the column value: + +```sql +SELECT + selector_first(temp, time)['time'] AS time, + selector_first(temp, time)['value'] AS temp, + room +FROM home +GROUP BY room +``` + +## Example aggregate queries + +- [Perform an ungrouped aggregation](#perform-an-ungrouped-aggregation) +- [Group and aggregate data](#group-and-aggregate-data) + - [Downsample data by applying interval-based aggregates](#downsample-data-by-applying-interval-based-aggregates) +- [Query rows based on aggregate values](#query-rows-based-on-aggregate-values) + +> [!Note] +> #### Sample data +> +> The following examples use the +> [Home sensor sample data](/influxdb3/version/reference/sample-data/#home-sensor-data). +> To run the example queries and return results, +> [write the sample data](/influxdb3/version/reference/sample-data/#write-home-sensor-data-to-influxdb) +> to your {{% product-name %}} database before running the example queries. + +### Perform an ungrouped aggregation + +To aggregate _all_ queried values in a specified column: + +- Use aggregate or selector functions in your `SELECT` statement. +- Do not include a `GROUP BY` clause to leave your data ungrouped. + +```sql +SELECT avg(co) AS 'average co' from home +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +| average co | +| :---------------: | +| 5.269230769230769 | +{{% /expand %}} +{{< /expand-wrapper >}} + +### Group and aggregate data + +To apply aggregate or selector functions to grouped data: + +- Use aggregate or selector functions in your `SELECT` statement. +- Include columns to group by in your `SELECT` statement. +- Include a `GROUP BY` clause with a comma-delimited list of columns and + expressions to group by. + +Keep the following in mind when using `GROUP BY`: + +- `GROUP BY` can use column aliases that are defined in the `SELECT` clause. +- `GROUP BY` won't use an aliased value if the alias is the same as the original + column name. `GROUP BY` will use the original value of the column, not the + transformed, aliased value. + +```sql +SELECT + room, + avg(temp) AS 'average temp' +FROM home +GROUP BY room +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +| room | average temp | +| :---------- | -----------------: | +| Living Room | 22.16923076923077 | +| Kitchen | 22.623076923076926 | +{{% /expand %}} +{{< /expand-wrapper >}} + +#### Downsample data by applying interval-based aggregates + +A common use case when querying time series is downsampling data by applying +aggregates to time-based groups. To group and aggregate data into time-based +groups: + +- In your `SELECT` clause: + + - Use the [`DATE_BIN` function](/influxdb3/version/reference/sql/functions/time-and-date/#date_bin) + to calculate time intervals and output a column that contains the start of + the interval nearest to the `time` timestamp in each row--for example, the + following clause calculates two-hour intervals (originating at the Unix epoch) + and returns a new `time` column that contains the start of the interval + nearest to `home.time`: + + ```sql + SELECT + DATE_BIN(INTERVAL '2 hours', time) AS time + FROM home + ... + ``` + + Given a `time` value + {{% influxdb/custom-timestamps-span %}}`2022-01-01T13:00:50.000Z`{{% /influxdb/custom-timestamps-span %}}, + the output `time` column contains + {{% influxdb/custom-timestamps-span %}}`2022-01-01T12:00:00.000Z`{{% /influxdb/custom-timestamps-span %}}. + + - Use [aggregate](/influxdb3/version/reference/sql/functions/aggregate/) or + [selector](/influxdb3/version/reference/sql/functions/selector/) functions on + specified columns. + +- In your `GROUP BY` clause: + + - Specify the `DATE_BIN(...)` column ordinal reference (`1`). + This lets you group by the transformed `time` value and maintain the `time` + column name. + - Specify other columns (for example, `room`) that are specified in the + `SELECT` clause and aren't used in a selector function. + + ```sql + SELECT + DATE_BIN(INTERVAL '2 hours', time) AS time + ... + GROUP BY 1, room + ... + ``` + + To reference the `DATE_BIN(...)` result column by _name_ in the `GROUP BY` + clause, assign an alias other than "time" in the `SELECT` clause--for example: + + ```sql + SELECT + DATE_BIN(INTERVAL '2 hours', time) AS _time + FROM home + ... + GROUP BY _time, room + ``` + +- Include an `ORDER BY` clause with columns to sort by. + +The following example retrieves unique combinations of time intervals and rooms +with their minimum, maximum, and average temperatures: + +```sql +SELECT + DATE_BIN(INTERVAL '2 hours', time) AS time, + room, + selector_max(temp, time)['value'] AS 'max temp', + selector_min(temp, time)['value'] AS 'min temp', + avg(temp) AS 'average temp' +FROM home +GROUP BY 1, room +ORDER BY room, 1 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +{{% influxdb/custom-timestamps %}} +| time | room | max temp | min temp | average temp | +| :------------------- | :---------- | -------: | -------: | -----------------: | +| 2022-01-01T08:00:00Z | Kitchen | 23 | 21 | 22 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | 22.4 | 22.549999999999997 | +| 2022-01-01T12:00:00Z | Kitchen | 22.8 | 22.5 | 22.65 | +| 2022-01-01T14:00:00Z | Kitchen | 22.8 | 22.7 | 22.75 | +| 2022-01-01T16:00:00Z | Kitchen | 22.7 | 22.4 | 22.549999999999997 | +| 2022-01-01T18:00:00Z | Kitchen | 23.3 | 23.1 | 23.200000000000003 | +| 2022-01-01T20:00:00Z | Kitchen | 22.7 | 22.7 | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.4 | 21.1 | 21.25 | +| 2022-01-01T10:00:00Z | Living Room | 22.2 | 21.8 | 22 | +| 2022-01-01T12:00:00Z | Living Room | 22.4 | 22.2 | 22.299999999999997 | +| 2022-01-01T14:00:00Z | Living Room | 22.3 | 22.3 | 22.3 | +| 2022-01-01T16:00:00Z | Living Room | 22.6 | 22.4 | 22.5 | +| 2022-01-01T18:00:00Z | Living Room | 22.8 | 22.5 | 22.65 | +| 2022-01-01T20:00:00Z | Living Room | 22.2 | 22.2 | 22.2 | +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +> [!Note] +> +> #### GROUP BY time +> +> In the `GROUP BY` clause, the name "time" always refers to the `time` column +> in the source table. If you want to reference a calculated time column by name, +> use an alias different from "time" or use the column ordinal--for example: +> +> {{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Column alias](#) +[Column ordinal](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + DATE_BIN(INTERVAL '2 hours', time) AS _time, + room, + selector_max(temp, time)['value'] AS 'max temp', + selector_min(temp, time)['value'] AS 'min temp', + avg(temp) AS 'average temp' +FROM home +GROUP BY _time, room +ORDER BY room, _time +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + DATE_BIN(INTERVAL '2 hours', time) AS time, + room, + selector_max(temp, time)['value'] AS 'max temp', + selector_min(temp, time)['value'] AS 'min temp', + avg(temp) AS 'average temp' +FROM home +GROUP BY 1, room +ORDER BY room, 1 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +### Query rows based on aggregate values + +To query data based on values after an aggregate operation, include a `HAVING` +clause with defined predicate conditions such as a value threshold. +Predicates in the `WHERE` clause are applied _before_ data is aggregated. +Predicates in the `HAVING` clause are applied _after_ data is aggregated. + +```sql +SELECT + room, + avg(co) AS 'average co' +FROM home +GROUP BY room +HAVING "average co" > 5 +``` + +{{< expand-wrapper >}} +{{% expand "View example results" %}} +| room | average co | +| :------ | -----------------: | +| Kitchen | 6.6923076923076925 | +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxdb3-query-guides/sql/basic-query.md b/content/shared/influxdb3-query-guides/sql/basic-query.md new file mode 100644 index 0000000000..be4af1e2d0 --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/basic-query.md @@ -0,0 +1,208 @@ + +The InfluxDB SQL implementation is powered by the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) +query engine which provides an SQL syntax similar to other relational query languages. + +A basic SQL query that queries data from {{< product-name >}} most commonly +includes the following clauses: + +{{< req type="key" >}} + +- {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output + from a table or use the wildcard alias (`*`) to select all fields and tags + from a table. +- {{< req "\*">}} `FROM`: Specify the table to query data from. +- `WHERE`: Only return rows that meets the specified conditions--for example, + the time is within a time range, a tag has a specific value, or a field value + is above or below a specified threshold. + +{{% influxdb/custom-timestamps %}} +```sql +SELECT + temp, + hum, + room +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` +{{% /influxdb/custom-timestamps %}} + +## Result set + +If at least one row satisfies the query, {{% product-name %}} returns row data +in the query result set. An SQL query result set includes columns listed in the +query's `SELECT` statement. + +## Basic query examples + +- [Query data within time boundaries](#query-data-within-time-boundaries) +- [Query data without time boundaries](#query-data-without-time-boundaries) +- [Query specific fields and tags](#query-specific-fields-and-tags) +- [Query fields based on tag values](#query-fields-based-on-tag-values) +- [Query points based on field values](#query-points-based-on-field-values) +- [Alias queried fields and tags](#alias-queried-fields-and-tags) + +> [!Note] +> #### Sample data +> +> The following examples use the +> [Home sensor sample data](/influxdb3/version/reference/sample-data/#home-sensor-data). +> To run the example queries and return results, +> [write the sample data](/influxdb3/version/reference/sample-data/#write-home-sensor-data-to-influxdb) +> to your {{% product-name %}} database before running the example queries. + +### Query data within time boundaries + +- Use the `SELECT` clause to specify what tags and fields to return. + To return all tags and fields, use the wildcard alias (`*`). +- Specify the table to query in the `FROM` clause. +- Specify time boundaries in the `WHERE` clause. + Include time-based predicates that compare the value of the `time` column to a timestamp. + Use the `AND` logical operator to chain multiple predicates together. + +{{% influxdb/custom-timestamps %}} +```sql +SELECT * +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T12:00:00Z' +``` +{{% /influxdb/custom-timestamps %}} + +Query time boundaries can be relative or absolute. + +{{< expand-wrapper >}} +{{% expand "Query with relative time boundaries" %}} + +To query data from relative time boundaries, compare the value of the `time` +column to a timestamp calculated by subtracting an interval from a timestamp. +Use `now()` to return the timestamp for the current time (UTC). + +##### Query all data from the last month + +```sql +SELECT * FROM home WHERE time >= now() - INTERVAL '1 month' +``` + +##### Query one day of data data from a week ago +```sql +SELECT * +FROM home +WHERE + time >= now() - INTERVAL '7 days' + AND time <= now() - INTERVAL '6 days' +``` +{{% /expand %}} + +{{% expand "Query with absolute time boundaries" %}} + +To query data from absolute time boundaries, compare the value of the `time` column +to a timestamp literal. +Use the `AND` logical operator to chain together multiple predicates and define +both start and stop boundaries for the query. + +{{% influxdb/custom-timestamps %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' +``` +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} + +{{% expand "Query data using a time zone offset" %}} + +To query data using a time zone offset, use the +[`AT TIME ZONE` operator](/influxdb3/version/reference/sql/operators/other/#at-time-zone) +to apply a time zone offset to timestamps in the `WHERE` clause. + +{{% note %}} +Timestamp types in InfluxDB always represent a UTC time. `AT TIME ZONE` returns +a UTC timestamp adjusted for the offset of the specified time zone. +Timestamps in the `time` column are not updated. +If you need to display the timestamps in your current timezone, this should be handled +client-side. +{{% /note %}} + +{{% influxdb/custom-timestamps %}} +```sql +SELECT + * +FROM + home +WHERE + time >= '2022-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' + AND time <= '2022-01-01 12:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +### Query data without time boundaries + +To query data without time boundaries, do not include any time-based predicates +in your `WHERE` clause. + +{{% warn %}} +Querying data _without time bounds_ can return an unexpected amount of data. +The query may take a long time to complete and results may be truncated. +{{% /warn %}} + +```sql +SELECT * FROM home +``` + +### Query specific fields and tags + +To query specific fields, include them in the `SELECT` clause. +If querying multiple fields or tags, comma-delimit each. +If a field or tag key includes special characters or spaces or is case-sensitive, +wrap the key in _double-quotes_. + +```sql +SELECT time, room, temp, hum FROM home +``` + +### Query fields based on tag values + +- Include the fields you want to query and the tags you want to base conditions + on in the `SELECT` clause. +- Include predicates in the `WHERE` clause that compare the tag identifier to + a string literal. + Use [logical operators](/influxdb3/version/reference/sql/operators/logical/) to + chain multiple predicates together and apply multiple conditions. + +```sql +SELECT * FROM home WHERE room = 'Kitchen' +``` + +### Query points based on field values + +- In the `SELECT` clause, include fields you want to query. +- In the `WHERE` clause, include predicates that compare the field identifier to a value or expression. + Use [logical operators](/influxdb3/version/reference/sql/where/#logical-operators) (`AND`, `OR`) to chain multiple predicates together + and apply multiple conditions. + +```sql +SELECT co, time FROM home WHERE co >= 10 OR co <= -10 +``` + +### Alias queried fields and tags + +To alias or rename fields and tags that you query, pass a string literal after +the field or tag identifier in the `SELECT` clause. +You can use the `AS` clause to define the alias, but it isn't necessary. +The following queries are functionally the same: + +```sql +SELECT temp 'temperature', hum 'humidity' FROM home + +SELECT temp AS 'temperature', hum AS 'humidity' FROM home +``` diff --git a/content/shared/influxdb3-query-guides/sql/cast-types.md b/content/shared/influxdb3-query-guides/sql/cast-types.md new file mode 100644 index 0000000000..5a11f47b0f --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/cast-types.md @@ -0,0 +1,328 @@ + +Use the `CAST` function or double-colon `::` casting shorthand syntax to cast a +value to a specific type. + +```sql +-- CAST function +SELECT CAST(1234.5 AS BIGINT) + +-- Double-colon casting shorthand +SELECT 1234.5::BIGINT +``` + +- [Cast to a string type](#cast-to-a-string-type) +- [Cast to numeric types](#cast-to-numeric-types) + - [Float](#cast-to-a-float) + - [Integer](#cast-to-an-integer) + - [Unsigned integer](#cast-to-an-unsigned-integer) +- [Cast to a boolean type](#cast-to-a-boolean-type) +- [Cast to a timestamp type](#cast-to-a-timestamp-type) + +Casting operations can be performed on a column expression or a literal value. +For example, the following query uses the +[Home sensor sample data](/influxdb3/version/reference/sample-data/#home-sensor-data) +and: + +- Casts all values in the `time` column to integers (Unix nanosecond timestamps). +- Casts the literal string value `'1234'` to a 64-bit float for each row. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +SELECT + time::BIGINT AS unix_time, + '1234'::DOUBLE AS string_to_float +FROM home +LIMIT 5 +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +SELECT + CAST(time AS BIGINT) AS unix_time, + CAST('1234' AS DOUBLE) AS string_to_float +FROM home +LIMIT 5 +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% influxdb/custom-timestamps %}} + +| unix_time | string_to_float | +| :------------------ | --------------: | +| 1641024000000000000 | 1234 | +| 1641027600000000000 | 1234 | +| 1641031200000000000 | 1234 | +| 1641034800000000000 | 1234 | +| 1641038400000000000 | 1234 | + +{{% /influxdb/custom-timestamps %}} + +--- + +## Cast to a string type + +Use the `STRING`, `CHAR`, `VARCHAR`, or `TEXT` type in a casting operation to +cast a value to a string. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::STRING +value::CHAR +value::VARCHAR +value::TEXT +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS STRING) +CAST(value AS CHAR) +CAST(value AS VARCHAR) +CAST(value AS TEXT) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to a string value: + +- **Floats** +- **Integers** +- **Unsigned integers** +- **Booleans** +- **Timestamps** + +--- + +## Cast to numeric types + +The InfluxDB SQL implementation supports 64-bit floats (`DOUBLE`), +integers (`BIGINT`), and unsigned integers (`BIGINT UNSIGNED`). + +### Cast to a float + +Use the `DOUBLE` type in a casting operation to cast a value to a 64-bit float. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::DOUBLE +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS DOUBLE) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to a float value: + +- **Strings**: Returns the float equivalent of the numeric string (`[0-9]`). + The following string patterns are also supported: + + - Scientific notation (`'123.4E+10'`) + - Infinity (`'±Inf'`) + - NaN (`'NaN'`) + +- **Integers** +- **Unsigned integers** + +### Cast to an integer + +Use the `BIGINT` type in a casting operation to cast a value to a 64-bit signed integer. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::BIGINT +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS BIGINT) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to an integer: + +- **Strings**: Returns the integer equivalent of the numeric string (`[0-9]`). +- **Floats**: Truncates the float value at the decimal. +- **Unsigned integers**: Returns the signed integer equivalent of the unsigned integer. +- **Booleans**: Returns `1` for `true` and `0` for `false`. +- **Timestamps**: Returns the equivalent + [nanosecond epoch timestamp](/influxdb3/version/reference/glossary/#unix-timestamp). + +### Cast to an unsigned integer + +Use the `BIGINT UNSIGNED` type in a casting operation to cast a value to a +64-bit unsigned integer. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::BIGINT UNSIGNED +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS BIGINT UNSIGNED) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to an unsigned integer: + +- **Strings**: Returns the unsigned integer equivalent of the numeric string (`[0-9]`). +- **Floats**: Truncates the float value at the decimal. +- **Integers**: Returns the unsigned integer equivalent of the signed integer. +- **Booleans**: Returns `1` for `true` and `0` for `false`. +- **Timestamps**: Returns the equivalent + [nanosecond epoch timestamp](/influxdb3/version/reference/glossary/#unix-timestamp). + +--- + +## Cast to a boolean type + +Use the `BOOLEAN` type in a casting operation to cast a value to a boolean. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::BOOLEAN +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS BOOLEAN) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to a boolean: + +- **Strings** + - Return `true`: + - `'true'` _(case-insensitive)_ + - `'t'`, _(case-insensitive)_ + - `'1'` + - Return `false`: + - `'false'` _(case-insensitive)_ + - `'f'` _(case-insensitive)_ + - `'0'` +- **Integers** + - Returns `true`: positive non-zero integer + - Returns `false`: `0` +- **Unsigned integers** + - Returns `true`: non-zero unsigned integer + - Returns `false`: `0` + +--- + +## Cast to a timestamp type + +Use the `TIMESTAMP` type in a casting operation to cast a value to a timestamp. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +value::TIMESTAMP +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(value AS TIMESTAMP) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +SQL supports casting the following to a timestamp: + +- **Strings**: Returns the timestamp equivalent of the string value. + The following RFC3339 and RFC339-like string patterns are supported: + + - `YYYY-MM-DDT00:00:00.000Z` + - `YYYY-MM-DDT00:00:00.000-00:00` + - `YYYY-MM-DD 00:00:00.000-00:00` + - `YYYY-MM-DDT00:00:00Z` + - `YYYY-MM-DD 00:00:00.000` + - `YYYY-MM-DD 00:00:00` + - `YYYY-MM-DD` + +- **Integers**: Parses the integer as a Unix _second_ timestamp and returns + the equivalent timestamp. +- **Unsigned integers**: Parses the unsigned integer as a Unix nanosecond timestamp + and returns the equivalent timestamp. + +{{% note %}} +#### Cast Unix nanosecond timestamps to a timestamp type + +To cast a Unix nanosecond timestamp to a timestamp type, first cast the numeric +value to an unsigned integer (`BIGINT UNSIGNED`) and then a timestamp. +You can also use the [`to_timestamp_nanos`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp_nanos) +function. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[:: shorthand](#) +[CAST()](#) +[to_timestamp_nanos](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sql +1704067200000000000::BIGINT UNSIGNED::TIMESTAMP +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +CAST(CAST(1704067200000000000 AS BIGINT UNSIGNED) AS TIMESTAMP) +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sql +to_timestamp_nanos(1704067200000000000) +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +{{% /note %}} + +### Timestamp functions + +You can also use the following SQL functions to cast a value to a timestamp type: + +- [`to_timestamp`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp) +- [`to_timestamp_millis`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp_millis) +- [`to_timestamp_micros`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp_micros) +- [`to_timestamp_nanos`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp_nanos) +- [`to_timestamp_seconds`](/influxdb3/version/reference/sql/functions/time-and-date/#to_timestamp_seconds) +- [to_unixtime](/influxdb3/version/reference/sql/functions/time-and-date/#to_unixtime) diff --git a/content/shared/influxdb3-query-guides/sql/explore-schema.md b/content/shared/influxdb3-query-guides/sql/explore-schema.md new file mode 100644 index 0000000000..cec04bf86c --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/explore-schema.md @@ -0,0 +1,53 @@ + +Use SQL to explore your data schema in your {{< product-name >}} database. + +## List tables in a database + +Use `SHOW TABLES` to list tables in your InfluxDB database. + +```sql +SHOW TABLES +``` + +{{< expand-wrapper >}} +{{% expand "View example output" %}} + +Tables listed with the `table_schema` of `iox` are tables. +Tables with `system` or `information_schema` table schemas are system tables +that store internal metadata. + +| table_catalog | table_schema | table_name | table_type | +| :------------ | :----------------- | :---------- | ---------: | +| public | iox | home | BASE TABLE | +| public | iox | noaa | BASE TABLE | +| public | system | queries | BASE TABLE | +| public | information_schema | tables | VIEW | +| public | information_schema | views | VIEW | +| public | information_schema | columns | VIEW | +| public | information_schema | df_settings | VIEW | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## List columns in a table + +Use the `SHOW COLUMNS` statement to view what columns are in a table. +Use the `IN` clause to specify the table. + +```sql +SHOW COLUMNS IN home +``` + +{{< expand-wrapper >}} +{{% expand "View example output" %}} + +| table_catalog | table_schema | table_name | column_name | data_type | is_nullable | +| :------------ | :----------- | :--------- | :---------- | :-------------------------- | ----------: | +| public | iox | home | co | Int64 | YES | +| public | iox | home | hum | Float64 | YES | +| public | iox | home | room | Dictionary(Int32, Utf8) | YES | +| public | iox | home | temp | Float64 | YES | +| public | iox | home | time | Timestamp(Nanosecond, None) | NO | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxdb3-query-guides/sql/fill-gaps.md b/content/shared/influxdb3-query-guides/sql/fill-gaps.md new file mode 100644 index 0000000000..e786a8ff7a --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/fill-gaps.md @@ -0,0 +1,112 @@ + +Use [`date_bin_gapfill`](/influxdb3/version/reference/sql/functions/time-and-date/#date_bin_gapfill) +with [`interpolate`](/influxdb3/version/reference/sql/functions/misc/#interpolate) +or [`locf`](/influxdb3/version/reference/sql/functions/misc/#locf) to +fill gaps of time where no data is returned. +Gap-filling SQL queries handle missing data in time series data by filling in +gaps with interpolated values or by carrying forward the last available observation. + +**To fill gaps in data:** + +1. Use the `date_bin_gapfill` function to window your data into time-based groups + and apply an [aggregate function](/influxdb3/version/reference/sql/functions/aggregate/) + to each window. If no data exists in a window, `date_bin_gapfill` inserts + a new row with the starting timestamp of the window, all columns in the + `GROUP BY` clause populated, and null values for the queried fields. + +2. Use either `interpolate` or `locf` to fill the inserted null values in the + specified column. + + - **interpolate**: fills null values by interpolating values between non-null values. + - **locf**: fills null values by carrying the last observed value forward. + + > [!Note] + > The expression passed to `interpolate` or `locf` must use an + > [aggregate function](/influxdb3/version/reference/sql/functions/aggregate/). + +3. Include a `WHERE` clause that sets upper and lower time bounds. + For example: + +{{% influxdb/custom-timestamps %}} +```sql +WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T10:00:00Z' +``` +{{% /influxdb/custom-timestamps %}} + + +## Example of filling gaps in data + +The following examples use the [Home sensor sample data](/influxdb3/version/reference/sample-data/#home-sensor-data) +to show how to use `date_bin_gapfill` and the different results of `interplate` +and `locf`. + +{{< tabs-wrapper >}} +{{% tabs "small" %}} +[interpolate](#) +[locf](#) +{{% /tabs %}} +{{% tab-content %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as time, + room, + interpolate(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY 1, room +``` + +| time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 22 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 22.85 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.25 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.6 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{% tab-content %}} + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT + date_bin_gapfill(INTERVAL '30 minutes', time) as time, + room, + locf(avg(temp)) +FROM home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T10:00:00Z' +GROUP BY 1, room +``` + +| time | room | AVG(home.temp) | +| :------------------- | :---------- | -------------: | +| 2022-01-01T08:00:00Z | Kitchen | 21 | +| 2022-01-01T08:30:00Z | Kitchen | 21 | +| 2022-01-01T09:00:00Z | Kitchen | 23 | +| 2022-01-01T09:30:00Z | Kitchen | 23 | +| 2022-01-01T10:00:00Z | Kitchen | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 21.1 | +| 2022-01-01T08:30:00Z | Living Room | 21.1 | +| 2022-01-01T09:00:00Z | Living Room | 21.4 | +| 2022-01-01T09:30:00Z | Living Room | 21.4 | +| 2022-01-01T10:00:00Z | Living Room | 21.8 | + +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{< /tabs-wrapper >}} diff --git a/content/shared/influxdb3-query-guides/sql/parameterized-queries.md b/content/shared/influxdb3-query-guides/sql/parameterized-queries.md new file mode 100644 index 0000000000..07efb64a84 --- /dev/null +++ b/content/shared/influxdb3-query-guides/sql/parameterized-queries.md @@ -0,0 +1,310 @@ + +Parameterized queries in {{% product-name %}} let you dynamically and safely change values in a query. +If your application code allows user input to customize values or expressions in a query, use a parameterized query to make sure untrusted input is processed strictly as data and not executed as code. + +Parameterized queries: + +- help prevent injection attacks, which can occur if input is executed as code +- help make queries more reusable + +{{% note %}} +#### Prevent injection attacks + +For more information on security and query parameterization, +see the [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html#defense-option-1-prepared-statements-with-parameterized-queries). +{{% /note %}} + +In InfluxDB 3, a parameterized query is an InfluxQL or SQL query that contains one or more named parameter placeholders–variables that represent input data. + +- [Use parameters in `WHERE` expressions](#use-parameters-in-where-expressions) +- [Parameter data types](#parameter-data-types) + - [Data type examples](#data-type-examples) + - [Time expressions](#time-expressions) + - [Not compatible with parameters](#not-compatible-with-parameters) +- [Parameterize an SQL query](#parameterize-an-sql-query) +- [Execute parameterized SQL queries](#execute-parameterized-sql-queries) + - [Use InfluxDB Flight RPC clients](#use-influxdb-flight-rpc-clients) +- [Client support for parameterized queries](#client-support-for-parameterized-queries) +- [Not supported](#not-supported) + +{{% note %}} + +#### Parameters only supported in `WHERE` expressions + +InfluxDB 3 supports parameters in `WHERE` clause **predicate expressions**. +Parameter values must be one of the [allowed parameter data types](#parameter-data-types). + +If you use parameters in other expressions or clauses, +such as function arguments, `SELECT`, or `GROUP BY`, then your query might not work as you expect. + +{{% /note %}} + +## Use parameters in `WHERE` expressions + +You can use parameters in `WHERE` clause **predicate expressions**-–for example, the following query contains a `$temp` parameter: + +```sql +SELECT * FROM measurement WHERE temp > $temp +``` + +When executing a query, you specify parameter name-value pairs. +The value that you assign to a parameter must be one of the [parameter data types](#parameter-data-types). + +```go +{"temp": 22.0} +``` + +The InfluxDB Querier parses the query text with the parameter placeholders, and then generates query plans that replace the placeholders with the values that you provide. +This separation of query structure from input data ensures that input is treated as one of the allowed [data types](#parameter-data-types) and not as executable code. + +## Parameter data types + +A parameter value can be one of the following data types: + +- Null +- Boolean +- Unsigned integer (`u_int64`) +- Integer (`int64`) +- Double (`float64`) +- String + +### Data type examples + +```js +{ + "string": "Living Room", + "double": 3.14, + "unsigned_integer": 1234, + "integer": -1234, + "boolean": false, + "null": Null, +} +``` + +### Time expressions + +To parameterize time bounds, substitute a parameter for a timestamp literal--for example: + +```sql +SELECT * +FROM home +WHERE time >= $min_time +``` + +For the parameter value, specify the timestamp literal as a string--for example: + +{{% influxdb/custom-timestamps %}} + +```go +// Assign a timestamp string literal to the min_time parameter. +parameters := influxdb3.QueryParameters{ + "min_time": "2022-01-01 00:00:00.00", +} +``` + +{{% /influxdb/custom-timestamps %}} + +InfluxDB executes the query as the following: + +{{% influxdb/custom-timestamps %}} + +```sql +SELECT * +FROM home +WHERE time >= '2022-01-01 00:00:00.00' +``` + +{{% /influxdb/custom-timestamps %}} + +### Not compatible with parameters + +If you use parameters for the following, your query might not work as you expect: + +- In clauses other than `WHERE`, such as `SELECT` or `GROUP BY` +- As function arguments, such as `avg($temp)` +- In place of identifiers, such as column or table names +- In place of duration literals, such as `INTERVAL $minutes` + +## Parameterize an SQL query + +{{% note %}} +#### Sample data + +The following examples use the +[Get started home sensor data](/influxdb3/version/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% product-name %}} database before running the example queries. +{{% /note %}} + +To use a parameterized query, do the following: + +1. In your query text, use the `$parameter` syntax to reference a parameter name--for example, +the following query contains `$room` and `$min_temp` parameter placeholders: + + ```sql + SELECT * + FROM home + WHERE time > now() - INTERVAL '7 days' + AND temp >= $min_temp + AND room = $room + ``` + +2. Provide a value for each parameter name. + If you don't assign a value for a parameter, InfluxDB returns an error. + The syntax for providing parameter values depends on the client you use--for example: + + + + {{< code-tabs-wrapper >}} + {{% code-tabs %}} + [Go](#) + {{% /code-tabs %}} + {{% code-tab-content %}} + + ```go + // Define a QueryParameters struct--a map of parameters to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + } + ``` + + {{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} + +After InfluxDB receives your request and parses the query, it executes the query as + +```sql +SELECT * +FROM home +WHERE time > now() - INTERVAL '7 days' +AND temp >= 20.0 +AND room = 'Kitchen' +``` + +## Execute parameterized SQL queries + +{{% note %}} +#### Sample data + +The following examples use the +[Get started home sensor data](/influxdb3/version/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb3/version/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% product-name %}} database before running the example queries. +{{% /note %}} + +### Use InfluxDB Flight RPC clients + +Using the InfluxDB 3 native Flight RPC protocol and supported clients, you can send a parameterized query and a list of parameter name-value pairs. +InfluxDB Flight clients that support parameterized queries pass the parameter name-value pairs in a Flight ticket `params` field. + +The following examples show how to use client libraries to execute parameterized SQL queries: + + + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Go](#) +{{% /code-tabs %}} + +{{% code-tab-content %}} + +```go +import ( + "context" + "fmt" + "io" + "os" + "text/tabwriter" + "time" + "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3" +) + +func Query(query string, parameters influxdb3.QueryParameters) error { + url := os.Getenv("INFLUX_HOST") + token := os.Getenv("INFLUX_TOKEN") + database := os.Getenv("INFLUX_DATABASE") + + // Instantiate the influxdb3 client. + client, err := influxdb3.New(influxdb3.ClientConfig{ + Host: url, + Token: token, + Database: database, + }) + + if err != nil { + panic(err) + } + + // Ensure the client is closed after the Query function finishes. + defer func(client *influxdb3.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) + + // Call the client's QueryWithParameters function. + // Provide the query and parameters. The default QueryType is SQL. + iterator, err := client.QueryWithParameters(context.Background(), query, + parameters) + + // Create a buffer for storing rows as you process them. + w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) + w.Init(os.Stdout, 0, 8, 0, '\t', 0) + + fmt.Fprintf(w, "time\troom\tco\thum\ttemp\n") + + // Format and write each row to the buffer. + // Process each row as key-value pairs. + for iterator.Next() { + row := iterator.Value() + // Use Go time package to format unix timestamp + // as a time with timezone layout (RFC3339 format) + time := (row["time"].(time.Time)). + Format(time.RFC3339) + + fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n", + time, row["room"], row["co"], row["hum"], row["temp"]) + } + w.Flush() + + return nil +} + +func main() { + // Use the $placeholder syntax in a query to reference parameter placeholders + // for input data. + // The following SQL query contains the placeholders $room and $min_temp. + query := ` + SELECT * + FROM home + WHERE time > now() - INTERVAL '7 days' + AND temp >= $min_temp + AND room = $room` + + // Define a QueryParameters struct--a map of placeholder names to input values. + parameters := influxdb3.QueryParameters{ + "room": "Kitchen", + "min_temp": 20.0, + } +} +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Client support for parameterized queries + +- Not all [InfluxDB 3 Flight clients](/influxdb3/version/reference/client-libraries/v3/) support parameterized queries. +- InfluxDB doesn't currently support parameterized queries or DataFusion prepared statements for Flight SQL or Flight SQL clients. +- InfluxDB 3 SQL and InfluxQL parameterized queries aren’t supported in InfluxDB v1 and v2 clients. + +## Not supported + +Currently, parameterized queries in {{% product-name %}} don't provide the following: + +- support for DataFusion prepared statements +- query caching, optimization, or performance benefits diff --git a/content/shared/influxdb3-sample-data/sample-data.md b/content/shared/influxdb3-sample-data/sample-data.md new file mode 100644 index 0000000000..326ad35c3d --- /dev/null +++ b/content/shared/influxdb3-sample-data/sample-data.md @@ -0,0 +1,506 @@ + +Sample datasets are used throughout the {{< product-name >}} documentation to +demonstrate functionality. +Use the following sample datasets to replicate provided examples. + +- [Home sensor data](#home-sensor-data) +- [Home sensor actions data](#home-sensor-actions-data) +- [NOAA Bay Area weather data](#noaa-bay-area-weather-data) +- [Bitcoin price data](#bitcoin-price-data) +- [Random numbers sample data](#random-numbers-sample-data) + +## Home sensor data + +Includes simulated hourly home sensor data with anomalous sensor readings to +demonstrate processing and alerting on time series data. +To customize timestamps in the dataset, use the {{< icon "clock" >}} button in +the lower right corner of the page. + +##### Time Range + +**{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}}** +to +**{{% influxdb/custom-timestamps-span %}}2022-01-01T20:00:00Z{{% /influxdb/custom-timestamps-span %}}** +(Customizable) + +##### Schema + +- home (measurement) + - **tags**: + - room + - Kitchen + - Living Room + - **fields**: + - co (integer) + - temp (float) + - hum (float) + +{{< expand-wrapper >}} +{{% expand "Write home sensor data to InfluxDB" %}} + +#### Write the home sensor data to InfluxDB + +Use the InfluxDB v2 or v1 API to write the home sensor sample data to {{< product-name >}}. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[v2 API](#) +[v1 API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: text/plain; charset=utf-8" \ + --header "Accept: application/json" \ + --data-binary " +home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 +" +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary " +home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 +" +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following in the sample script: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of database to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your InfluxDB authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + > You can either omit the `Authorization` header or you can provide an + > arbitrary token string. + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Home sensor actions data + +Includes hypothetical actions triggered by data in the [Get started home sensor data](#get-started-home-sensor-data) +and is a companion dataset to that sample dataset. +To customize timestamps in the dataset, use the {{< icon "clock" >}} button in +the lower right corner of the page. +This lets you modify the sample dataset to stay within the retention period of +the database you write it to. + +##### Time Range + +**{{% influxdb/custom-timestamps-span %}}2022-01-01T08:00:00Z{{% /influxdb/custom-timestamps-span %}}** +to +**{{% influxdb/custom-timestamps-span %}}2022-01-01T20:00:00Z{{% /influxdb/custom-timestamps-span %}}** +(Customizable) + +##### Schema + +- home_actions (measurement) + - **tags**: + - room + - Kitchen + - Living Room + - action + - alert + - cool + - level + - ok + - warn + - **fields**: + - description (string) + +{{< expand-wrapper >}} +{{% expand "Write home sensor actions data to InfluxDB" %}} + +#### Write the home sensor actions data to InfluxDB + +Use the InfluxDB v2 or v1 API to write the home sensor actions sample data +to {{< product-name >}}. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[v2 API](#) +[v1 API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + https://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: text/plain; charset=utf-8" \ + --header "Accept: application/json" \ + --data-binary ' +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23°C). Cooling to 22°C." 1641027600 +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.3°C). Cooling to 22°C." 1641060000 +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.1°C). Cooling to 22°C." 1641063600 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 18 ppm." 1641060000 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 22 ppm." 1641063600 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 26 ppm." 1641067200 +home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 14 ppm." 1641063600 +home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 17 ppm." 1641067200 +' +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary ' +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23°C). Cooling to 22°C." 1641027600 +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.3°C). Cooling to 22°C." 1641060000 +home_actions,room=Kitchen,action=cool,level=ok description="Temperature at or above 23°C (23.1°C). Cooling to 22°C." 1641063600 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 18 ppm." 1641060000 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 22 ppm." 1641063600 +home_actions,room=Kitchen,action=alert,level=warn description="Carbon monoxide level above normal: 26 ppm." 1641067200 +home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 14 ppm." 1641063600 +home_actions,room=Living\ Room,action=alert,level=warn description="Carbon monoxide level above normal: 17 ppm." 1641067200 +' +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following in the sample script: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of database to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your InfluxDB authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + > You can either omit the `Authorization` header or you can provide an + > arbitrary token string. + +{{% /expand %}} +{{< /expand-wrapper >}} + +## NOAA Bay Area weather data + +Includes daily weather metrics from three San Francisco Bay Area airports from +**January 1, 2020 to December 31, 2022**. +This sample dataset includes seasonal trends and is good for exploring time +series use cases that involve seasonality. + +##### Time Range + +**2020-01-01T00:00:00Z** to **2022-12-31T00:00:00Z** + +##### Schema + +- weather (measurement) + - **tags**: + - location + - Concord + - Hayward + - San Francisco + - **fields** + - precip (float) + - temp_avg (float) + - temp_max (float) + - temp_min (float) + - wind_avg (float) + +{{< expand-wrapper >}} +{{% expand "Write the NOAA Bay Area weather data to InfluxDB" %}} + +#### Write the NOAA Bay Area weather data to InfluxDB + +Use the InfluxDB v2 or v1 API to write the NOAA Bay Area weather sample data to +{{< product-name >}}. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[v2 API](#) +[v1 API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: text/plain; charset=utf-8" \ + --header "Accept: application/json" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/write?db=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bay-area-weather.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following in the sample script: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of database to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your InfluxDB authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + > You can either omit the `Authorization` header or you can provide an + > arbitrary token string. + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Bitcoin price data + +The Bitcoin price sample dataset provides Bitcoin prices from +**2023-05-01T00:00:00Z to 2023-05-15T00:00:00Z**—_[Powered by CoinDesk](https://www.coindesk.com/price/bitcoin)_. + +##### Time Range + +**2023-05-01T00:19:00Z** to **2023-05-14T23:48:00Z** + +##### Schema + +- bitcoin (measurement) + - **tags**: + - code + - EUR + - GBP + - USD + - crypto + - bitcoin + - description + - Euro + - British Pound Sterling + - United States Dollar + - symbol + - \€ (€) + - \£ (£) + - \$ ($) + - **fields** + - price (float) + +{{< expand-wrapper >}} +{{% expand "Write the Bitcoin sample data to InfluxDB" %}} + +#### Write the Bitcoin price sample data to InfluxDB + +Use the InfluxDB v2 or v1 API to write the Bitcoin price sample data to +{{< product-name >}}. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[v2 API](#) +[v1 API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: text/plain; charset=utf-8" \ + --header "Accept: application/json" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/write?db=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/bitcoin.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following in the sample script: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of database to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your InfluxDB authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + > You can either omit the `Authorization` header or you can provide an + > arbitrary token string. + +{{% /expand %}} +{{< /expand-wrapper >}} + +## Random numbers sample data + +Includes two fields with randomly generated numbers reported every minute. +Each field has a specific range of randomly generated numbers. +This sample dataset is used to demonstrate mathematic operations and +transformation functions. + +##### Time Range + +**2023-01-01T00:00:00Z** to **2023-01-01T12:00:00Z** + +##### Schema + +- numbers (measurement) + - **fields** + - a (float between -1 and 1) + - b (float between -3 and 3) + +{{< expand-wrapper >}} +{{% expand "Write the random number sample data to InfluxDB" %}} + +#### Write the random number sample data to InfluxDB + +Use the InfluxDB v2 or v1 API to write the random number sample data to +{{< product-name >}}. + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[v2 API](#) +[v1 API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: text/plain; charset=utf-8" \ + --header "Accept: application/json" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +{{% code-placeholders "AUTH_TOKEN|DATABASE_NAME" %}} +```sh +curl --request POST \ + http://{{< influxdb/host >}}/write?db=DATABASE_NAME \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-type: text/plain; charset=utf-8" \ + --data-binary "$(curl --request GET https://docs.influxdata.com/downloads/random-numbers.lp)" +``` +{{% /code-placeholders %}} + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following in the sample script: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + the name of database to write to +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: + your InfluxDB authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + > You can either omit the `Authorization` header or you can provide an + > arbitrary token string. + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/functions/date-time.md b/content/shared/influxql-v3-reference/functions/date-time.md index 2647bdb5f4..0da11223f5 100644 --- a/content/shared/influxql-v3-reference/functions/date-time.md +++ b/content/shared/influxql-v3-reference/functions/date-time.md @@ -102,7 +102,7 @@ tz(time_zone) {{% expand "Return the UTC offset for Chicago's time zone" %}} The following example uses the -[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample dataset](/influxdb/version/reference/sample-data/#home-sensor-data). {{% influxdb/custom-timestamps %}} diff --git a/content/shared/influxql-v3-reference/functions/misc.md b/content/shared/influxql-v3-reference/functions/misc.md index 3bb5231610..629c0dce42 100644 --- a/content/shared/influxql-v3-reference/functions/misc.md +++ b/content/shared/influxql-v3-reference/functions/misc.md @@ -201,7 +201,7 @@ tz(time_zone) {{% expand "Return the UTC offset for Chicago's time zone" %}} The following example uses the -[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample dataset](/influxdb/version/reference/sample-data/#home-sensor-data). {{% influxdb/custom-timestamps %}} diff --git a/content/shared/influxql-v3-reference/functions/technical-analysis.md b/content/shared/influxql-v3-reference/functions/technical-analysis.md index c81d0efbdc..b631db1d62 100644 --- a/content/shared/influxql-v3-reference/functions/technical-analysis.md +++ b/content/shared/influxql-v3-reference/functions/technical-analysis.md @@ -278,7 +278,7 @@ CHANDE_MOMENTUM_OSCILLATOR(field_expression, period[, hold_period[, warmup_type] {{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -313,7 +313,7 @@ name: home {{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -348,7 +348,7 @@ name: home {{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -380,7 +380,7 @@ name: home {{% expand "Apply `CHANDE_MOMENTUM_OSCILLATOR` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -502,7 +502,7 @@ DOUBLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmu {{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -537,7 +537,7 @@ name: home {{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -572,7 +572,7 @@ name: home {{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -604,7 +604,7 @@ name: home {{% expand "Apply `DOUBLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -724,7 +724,7 @@ EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmup_type] {{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -759,7 +759,7 @@ name: home {{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -794,7 +794,7 @@ name: home {{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -826,7 +826,7 @@ name: home {{% expand "Apply `EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -938,7 +938,7 @@ KAUFMANS_EFFICIENCY_RATIO(field_expression, period[, hold_period]) {{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -972,7 +972,7 @@ name: home {{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1006,7 +1006,7 @@ name: home {{% expand "Apply `KAUFMANS_EFFICIENCY_RATIO` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1111,7 +1111,7 @@ KAUFMANS_ADAPTIVE_MOVING_AVERAGE(field_expression, period[, hold_period]) {{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1145,7 +1145,7 @@ name: home {{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1179,7 +1179,7 @@ name: home {{% expand "Apply `KAUFMANS_ADAPTIVE_MOVING_AVERAGE` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1289,7 +1289,7 @@ RELATIVE_STRENGTH_INDEX(field_expression, period[, hold_period[, warmup_type]]) {{% expand "Apply `RELATIVE_STRENGTH_INDEX` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1323,7 +1323,7 @@ name: home {{% expand "Apply `RELATIVE_STRENGTH_INDEX` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1357,7 +1357,7 @@ name: home {{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1389,7 +1389,7 @@ name: home {{% expand "Apply `RELATIVE_STRENGTH_INDEX` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1510,7 +1510,7 @@ TRIPLE_EXPONENTIAL_MOVING_AVERAGE(field_expression, period[, hold_period[, warmu {{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1545,7 +1545,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1580,7 +1580,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1612,7 +1612,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_MOVING_AVERAGE` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1738,7 +1738,7 @@ TRIPLE_EXPONENTIAL_DERIVATIVE(field_expression, period[, hold_period[, warmup_ty {{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to a field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1772,7 +1772,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` to each field" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1806,7 +1806,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a custom hold period" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT @@ -1838,7 +1838,7 @@ name: home {{% expand "Apply `TRIPLE_EXPONENTIAL_DERIVATIVE` with a default non-default warmup type" %}} The following example uses the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT diff --git a/content/shared/influxql-v3-reference/limit-and-slimit.md b/content/shared/influxql-v3-reference/limit-and-slimit.md index 29b6a737e2..f476d75ca6 100644 --- a/content/shared/influxql-v3-reference/limit-and-slimit.md +++ b/content/shared/influxql-v3-reference/limit-and-slimit.md @@ -36,7 +36,7 @@ SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIM ### Examples {#limit-examples} The following examples use the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/offset-and-soffset.md b/content/shared/influxql-v3-reference/offset-and-soffset.md index 1954e01389..918de06c24 100644 --- a/content/shared/influxql-v3-reference/offset-and-soffset.md +++ b/content/shared/influxql-v3-reference/offset-and-soffset.md @@ -46,7 +46,7 @@ SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LI ### Examples {#offset-examples} The following examples use the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/order-by.md b/content/shared/influxql-v3-reference/order-by.md index 7942e91199..fc24520b06 100644 --- a/content/shared/influxql-v3-reference/order-by.md +++ b/content/shared/influxql-v3-reference/order-by.md @@ -26,7 +26,7 @@ SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time [ASC|DE ## Examples The following examples use the -[Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data). {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/regular-expressions.md b/content/shared/influxql-v3-reference/regular-expressions.md index 13acb02c67..ebeae6b674 100644 --- a/content/shared/influxql-v3-reference/regular-expressions.md +++ b/content/shared/influxql-v3-reference/regular-expressions.md @@ -63,7 +63,7 @@ the [`WHERE` clause](/influxdb/version/reference/influxql/where/). The examples below use the following sample data sets: - [NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) -- [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +- [Get started home sensor data](/influxdb/version/reference/sample-data/#home-sensor-data) {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/select.md b/content/shared/influxql-v3-reference/select.md index c0a3c0566f..66a0e56a19 100644 --- a/content/shared/influxql-v3-reference/select.md +++ b/content/shared/influxql-v3-reference/select.md @@ -198,7 +198,7 @@ is truncated at the decimal point. No rounding is performed. The examples below use the following sample data sets: -- [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +- [Get started home sensor data](/influxdb/version/reference/sample-data/#home-sensor-data) - [NOAA Bay Area weather data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/subqueries.md b/content/shared/influxql-v3-reference/subqueries.md index befdfd710f..e15156e347 100644 --- a/content/shared/influxql-v3-reference/subqueries.md +++ b/content/shared/influxql-v3-reference/subqueries.md @@ -36,7 +36,7 @@ SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] > > The examples below use the following sample data sets: > -> - [Get started home sensor data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Get started home sensor data](/influxdb/version/reference/sample-data/#home-sensor-data) > - [Random numbers sample data](/influxdb/version/reference/sample-data/#random-numbers-sample-data) {{< expand-wrapper >}} diff --git a/content/shared/influxql-v3-reference/time-and-timezone.md b/content/shared/influxql-v3-reference/time-and-timezone.md index 8ba494b1bb..5793f031a9 100644 --- a/content/shared/influxql-v3-reference/time-and-timezone.md +++ b/content/shared/influxql-v3-reference/time-and-timezone.md @@ -116,7 +116,7 @@ Conditional expressions with time operands support the following comparison oper ## Query examples The following examples use the -[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample dataset](/influxdb/version/reference/sample-data/#home-sensor-data). {{< expand-wrapper >}} @@ -284,7 +284,7 @@ SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LI {{% influxdb/custom-timestamps %}} The following example uses the -[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample dataset](/influxdb/version/reference/sample-data/#home-sensor-data). ```sql SELECT * diff --git a/content/shared/influxql-v3-reference/where.md b/content/shared/influxql-v3-reference/where.md index af54684829..12c9b36392 100644 --- a/content/shared/influxql-v3-reference/where.md +++ b/content/shared/influxql-v3-reference/where.md @@ -115,7 +115,7 @@ For more information about InfluxQL regular expression syntax, see ## WHERE clause examples The following examples use the -[Get started home sensor sample dataset](/influxdb/version/reference/sample-data/#get-started-home-sensor-data). +[Home sensor sample dataset](/influxdb/version/reference/sample-data/#home-sensor-data). {{< expand-wrapper >}} {{% expand "Select data with a specific tag value" %}} diff --git a/content/shared/sql-reference/group-by.md b/content/shared/sql-reference/group-by.md index 7720787dd4..58d08afd33 100644 --- a/content/shared/sql-reference/group-by.md +++ b/content/shared/sql-reference/group-by.md @@ -5,9 +5,16 @@ To output an aggregation for each group, include an aggregate or selector functi When `GROUP BY` appears in a query, the `SELECT` list can only use columns that appear in the `GROUP BY` list or in aggregate expressions. -`GROUP BY` can use column aliases that are defined in the `SELECT` clause. -`GROUP BY` can't use an alias named `time`. -In a `GROUP BY` list, `time` always refers to the measurement `time` column. +> [!Note] +> +> #### Group by aliases +> +> - `GROUP BY` can use column aliases that are defined in the `SELECT` clause. +> - `GROUP BY` won't use an aliased value if the alias is the same as the +> original column name. `GROUP BY` uses the original value of the column, +> not the transformed, aliased value. We recommended using column ordinals in +> in the `GROUP BY` clause to group by transformed values and maintain the +> alias identifier. - [Syntax](#syntax) - [Examples](#examples) @@ -28,13 +35,13 @@ GROUP BY tag1 ```sql SELECT - AVG("water_level") AS "avg_water_level", - "location" -FROM "h2o_feet" -GROUP BY "location" + AVG(water_level) AS avg_water_level, + location +FROM h2o_feet +GROUP BY location ``` -{{< expand-wrapper >}}} +{{< expand-wrapper >}} {{% expand "View example results" %}} | avg_water_level | location | @@ -45,43 +52,39 @@ GROUP BY "location" {{% /expand %}} {{< /expand-wrapper >}} -Group results in 15 minute time intervals by tag: +### Group data into 15 minute time intervals by tag ```sql SELECT - "location", - DATE_BIN(INTERVAL '15 minutes', time, TIMESTAMP '2022-01-01 00:00:00Z') AS _time, - COUNT("water_level") AS count -FROM "h2o_feet" + location, + DATE_BIN(INTERVAL '15 minutes', time) AS time, + COUNT(water_level) AS count +FROM h2o_feet WHERE time >= timestamp '2019-09-17T00:00:00Z' AND time <= timestamp '2019-09-17T01:00:00Z' -GROUP BY - _time, - location -ORDER BY - location, - _time +GROUP BY 1, location +ORDER BY location, 1 ``` -{{< expand-wrapper >}}} +{{< expand-wrapper >}} {{% expand "View example results" %}} The query uses the `COUNT()` function to count the number of `water_level` points per 15 minute interval. Results are then ordered by location and time. -| location | _time | count | -| :----------- | :-------------------- | ----: | -| coyote_creek | 2019-09-16T23:45:00Z | 1 | -| coyote_creek | 2019-09-17T00:00:00Z | 2 | -| coyote_creek | 2019-09-17T00:15:00Z | 3 | -| coyote_creek | 2019-09-17T00:30:00Z | 2 | -| coyote_creek | 2019-09-17T00:45:00Z | 3 | -| santa_monica | 2019-09-16T23:45:00Z | 1 | -| santa_monica | 2019-09-17T00:00:00Z | 2 | -| santa_monica | 2019-09-17T00:15:00Z | 3 | -| santa_monica | 2019-09-17T00:30:00Z | 2 | -| santa_monica | 2019-09-17T00:45:00Z | 3 | +| location | time | count | +| :----------- | :------------------- | ----: | +| coyote_creek | 2019-09-16T23:45:00Z | 1 | +| coyote_creek | 2019-09-17T00:00:00Z | 2 | +| coyote_creek | 2019-09-17T00:15:00Z | 3 | +| coyote_creek | 2019-09-17T00:30:00Z | 2 | +| coyote_creek | 2019-09-17T00:45:00Z | 3 | +| santa_monica | 2019-09-16T23:45:00Z | 1 | +| santa_monica | 2019-09-17T00:00:00Z | 2 | +| santa_monica | 2019-09-17T00:15:00Z | 3 | +| santa_monica | 2019-09-17T00:30:00Z | 2 | +| santa_monica | 2019-09-17T00:45:00Z | 3 | {{% /expand %}} {{< /expand-wrapper >}} diff --git a/content/shared/sql-reference/operators/logical.md b/content/shared/sql-reference/operators/logical.md index 092e191707..424dab488d 100644 --- a/content/shared/sql-reference/operators/logical.md +++ b/content/shared/sql-reference/operators/logical.md @@ -16,7 +16,7 @@ Logical operators combine or manipulate conditions in a SQL query. > > Query examples on this page use the following sample data sets: > -> - [Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data) > - [Home sensor actions sample data](/influxdb/version/reference/sample-data/#home-sensor-actions-data) ## AND {.monospace} diff --git a/content/shared/sql-reference/subqueries.md b/content/shared/sql-reference/subqueries.md index adae0c0b41..924b9bc743 100644 --- a/content/shared/sql-reference/subqueries.md +++ b/content/shared/sql-reference/subqueries.md @@ -20,7 +20,7 @@ Subqueries can be used in `SELECT`, `FROM`, `WHERE`, and `HAVING` clauses. > > Query examples on this page use the following sample data sets: > -> - [Get started home sensor sample data](/influxdb/version/reference/sample-data/#get-started-home-sensor-data) +> - [Home sensor sample data](/influxdb/version/reference/sample-data/#home-sensor-data) > - [Home sensor actions sample data](/influxdb/version/reference/sample-data/#home-sensor-actions-data) > - [NOAA Bay Area weather sample data](/influxdb/version/reference/sample-data/#noaa-bay-area-weather-data) diff --git a/content/shared/v3-core-get-started/_index.md b/content/shared/v3-core-get-started/_index.md index 0716921ad5..dd84b6c68d 100644 --- a/content/shared/v3-core-get-started/_index.md +++ b/content/shared/v3-core-get-started/_index.md @@ -335,7 +335,7 @@ The `query` subcommand includes options to help ensure that the right database i | `--database` | The name of the database to operate on | Yes | | `--token` | The authentication token for the {{% product-name %}} server | No | | `--language` | The query language of the provided query string [default: `sql`] [possible values: `sql`, `influxql`] | No | -| `--format` | The format in which to output the query [default: `pretty`] [possible values: `pretty`, `json`, `json_lines`, `csv`, `parquet`] | No | +| `--format` | The format in which to output the query [default: `pretty`] [possible values: `pretty`, `json`, `jsonl`, `csv`, `parquet`] | No | | `--output` | The path to output data to | No | #### Example: query `“SHOW TABLES”` on the `servers` database: diff --git a/content/shared/v3-enterprise-get-started/_index.md b/content/shared/v3-enterprise-get-started/_index.md index 74b27151fd..e13382ce21 100644 --- a/content/shared/v3-enterprise-get-started/_index.md +++ b/content/shared/v3-enterprise-get-started/_index.md @@ -330,7 +330,7 @@ The `query` subcommand includes options to help ensure that the right database i | `--database` | The name of the database to operate on | Yes | | `--token` | The authentication token for the {{% product-name %}} server | No | | `--language` | The query language of the provided query string [default: `sql`] [possible values: `sql`, `influxql`] | No | -| `--format` | The format in which to output the query [default: `pretty`] [possible values: `pretty`, `json`, `json_lines`, `csv`, `parquet`] | No | +| `--format` | The format in which to output the query [default: `pretty`] [possible values: `pretty`, `json`, `jsonl`, `csv`, `parquet`] | No | | `--output` | The path to output data to | No | #### Example: query `“SHOW TABLES”` on the `servers` database: diff --git a/layouts/partials/article.html b/layouts/partials/article.html index 110045713a..faf1170ce8 100644 --- a/layouts/partials/article.html +++ b/layouts/partials/article.html @@ -1,7 +1,7 @@
-

{{ .Title }}

+

{{ .Title | .RenderString }}

{{ partial "article/supported-versions.html" . }} {{ partial "article/page-meta.html" . }}
diff --git a/layouts/partials/article/related.html b/layouts/partials/article/related.html index b02551af4d..184b7f6dd3 100644 --- a/layouts/partials/article/related.html +++ b/layouts/partials/article/related.html @@ -26,7 +26,7 @@ {{ else }} {{ $sanitizedPath := replaceRE `\/$` "" (print $relatedItem) }} {{ with $.Page.GetPage $sanitizedPath }} -
  • {{ .Title }}
    • +
  • {{ .Title | .RenderString }}
    • {{ end }} {{ end }} {{ end }} diff --git a/layouts/partials/article/stable-version.html b/layouts/partials/article/stable-version.html index dd89bda215..cc53ed7364 100644 --- a/layouts/partials/article/stable-version.html +++ b/layouts/partials/article/stable-version.html @@ -25,7 +25,7 @@ View this page in the {{ $stableVersion }} documentation. {{ else if $stablePageExists }} - See the equivalent InfluxDB {{ $stableVersion }} documentation: {{ $stableEquivalentPage.Title }}. + See the equivalent InfluxDB {{ $stableVersion }} documentation: {{ $stableEquivalentPage.Title | .RenderString }}. {{ else }} See the InfluxDB {{ $stableVersion }} documentation. {{ end }} @@ -38,7 +38,7 @@

    {{ if $stablePageExists }} - See the equivalent InfluxDB {{ $stableVersion }} documentation: {{ $stableEquivalentPage.Title }}. + See the equivalent InfluxDB {{ $stableVersion }} documentation: {{ $stableEquivalentPage.Title | .RenderString }}. {{ else }} See the equivalent InfluxDB {{ $stableVersion }} documentation. {{ end }} diff --git a/layouts/partials/header.html b/layouts/partials/header.html index b852cbc8ab..be1c71a9c7 100644 --- a/layouts/partials/header.html +++ b/layouts/partials/header.html @@ -11,7 +11,7 @@ {{ partial "header/title" . }} - + diff --git a/layouts/partials/header/title.html b/layouts/partials/header/title.html index 235b38d31d..e6b1c89105 100644 --- a/layouts/partials/header/title.html +++ b/layouts/partials/header/title.html @@ -54,4 +54,4 @@ {{ $pageTitle := $scratch.Get "pageTitle" }} {{ $siteTitle := $scratch.Get "siteTitle" }} -{{ $pageTitle }}{{ cond (ne (len $pageTitle) 0) " | " "" }}{{ $siteTitle }} +{{ $pageTitle | .RenderString }}{{ cond (ne (len $pageTitle) 0) " | " "" }}{{ $siteTitle }} diff --git a/layouts/shortcodes/children.html b/layouts/shortcodes/children.html index 658cae0ccd..701a6810bd 100644 --- a/layouts/shortcodes/children.html +++ b/layouts/shortcodes/children.html @@ -18,16 +18,16 @@ {{ if eq $type "articles" }}

    {{ range $pages.ByWeight }} - {{ $title := cond ( isset .Params "list_title" ) .Params.list_title .Title }} + {{ $title := cond ( isset .Params "list_title" ) (.Params.list_title | .RenderString) (.Title | .RenderString) }} {{ $url := cond ( isset .Params "external_url" ) .Params.external_url .RelPermalink }} {{ $target := cond ( isset .Params "external_url" ) "_blank" "" }} - {{ if eq $hlevel "h2"}}

    {{ $title }}

    + {{ if eq $hlevel "h2"}} <{{ $hlevel }} id="{{ anchorize $title }}">{{ $title }} {{ else if eq $hlevel "h3"}}

    {{ $title }}

    {{ else if eq $hlevel "h4"}}

    {{ $title }}

    {{end}}

    - {{- if .Description }}{{- .Description | markdownify -}} - {{ else }}{{- .Summary | markdownify -}} + {{- if .Description }}{{- .Description | .RenderString -}} + {{ else }}{{- .Summary | .RenderString -}} {{ end -}}

    {{ if .Params.list_image }} @@ -94,7 +94,7 @@
    Output:
      {{ range $pages.ByWeight }} - {{ $title := cond ( isset .Params "list_title" ) .Params.list_title .Title }} + {{ $title := cond ( isset .Params "list_title" ) (.Params.list_title | .RenderString) (.Title | .RenderString) }} {{ $url := cond ( isset .Params "external_url" ) .Params.external_url .RelPermalink }} {{ $target := cond ( isset .Params "external_url" ) "_blank" "" }} {{ $note := cond ( isset .Params "list_note" ) (print "" .Params.list_note "") "" }} @@ -108,7 +108,7 @@
      Output:
        {{ range $pages.ByWeight }} - {{ $title := cond ( isset .Params "list_title" ) .Params.list_title .Title }} + {{ $title := cond ( isset .Params "list_title" ) (.Params.list_title | .RenderString) (.Title | .RenderString)}} {{ $url := cond ( isset .Params "external_url" ) .Params.external_url .RelPermalink }} {{ $target := cond ( isset .Params "external_url" ) "_blank" "" }} {{ $note := cond ( isset .Params "list_note" ) (print "" .Params.list_note "") "" }} @@ -121,7 +121,7 @@
        Output:
          {{ range $pages.ByWeight }} - {{ $title := cond ( isset .Params "list_title" ) .Params.list_title .Title }} + {{ $title := cond ( isset .Params "list_title" ) (.Params.list_title | .RenderString) (.Title | .RenderString) }}
        • {{ $title }}
          • {{ end }}
        diff --git a/layouts/shortcodes/influxql/v1-v3-data-model-note.md b/layouts/shortcodes/influxql/v1-v3-data-model-note.md new file mode 100644 index 0000000000..2307e9d14b --- /dev/null +++ b/layouts/shortcodes/influxql/v1-v3-data-model-note.md @@ -0,0 +1,16 @@ +{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} +{{- $currentProduct := index $productPathData 1 -}} +{{- $productKey := print "influxdb3_" (replaceRE "-" "_" $currentProduct) }} +{{- $productData := index .Site.Data.products $productKey -}} +{{- $productName := $productData.name -}} +> [!Note] +> +> #### InfluxDB v1 to InfluxDB 3 data model +> +> InfluxQL was designed around the InfluxDB v1 data model, but can still be used +> to query data from {{ $productName }}. When using the {{ $productName }} +> InfluxQL implementation, the data model is different in the following ways: +> +> - an InfluxDB v1 **database and retention policy** combination is combined +> into a single InfluxDB 3 **database** entity. +> - an InfluxDB v1 **measurement** is equivalent to an InfluxDB 3 **table**. \ No newline at end of file diff --git a/layouts/shortcodes/sql/sql-schema-intro.md b/layouts/shortcodes/sql/sql-schema-intro.md index e2fd091c9c..88a230eb67 100644 --- a/layouts/shortcodes/sql/sql-schema-intro.md +++ b/layouts/shortcodes/sql/sql-schema-intro.md @@ -1,4 +1,10 @@ +{{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}} +{{- $currentProduct := index $productPathData 1 -}} +{{- $productKey := print "influxdb3_" (replaceRE "-" "_" $currentProduct) }} +{{- $productData := index .Site.Data.products $productKey -}} +{{- $productName := $productData.name -}} {{- $isDedicated := in .Page.RelPermalink "/cloud-dedicated/" -}} -When working with the InfluxDB SQL implementation, -{{ if not $isDedicated }}a **bucket** is equivalent to a database,{{ end }} a **measurement** is structured as a table, and **time**, -**fields**, and **tags** are structured as columns. \ No newline at end of file +When working with the {{ $productName }} SQL implementation +{{ if not $isDedicated }}a **bucket** is equivalent to a **database**,{{ end }} +a **measurement** is equivalent to a **table**, and **time**, **fields**, and +**tags** are structured as **columns**. \ No newline at end of file