diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index f5ca80f6a..7931267c3 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -67,7 +67,7 @@ InfluxDB SQL queries most commonly include the following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Identify specific fields and tags to query from a - measurement or use the wild card alias (`*`) to select all fields and tags + measurement or use the wildcard alias (`*`) to select all fields and tags from a measurement. - {{< req "\*">}} `FROM`: Identify the measurement to query. If coming from an SQL background, an InfluxDB measurement is the equivalent diff --git a/content/influxdb/cloud-dedicated/process-data/downsample.md b/content/influxdb/cloud-dedicated/process-data/downsample.md index b2b42ec4f..5be57ab75 100644 --- a/content/influxdb/cloud-dedicated/process-data/downsample.md +++ b/content/influxdb/cloud-dedicated/process-data/downsample.md @@ -87,11 +87,13 @@ influxdb_raw = InfluxDBClient3( database='RAW_DATABASE_NAME' ) -# Instantiate an InfluxDBClient3 client configured for your downsampled database +# Instantiate an InfluxDBClient3 client configured for your downsampled database. +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cluster-id.influxdb.io', token='DATABASE_TOKEN', - database='DOWNSAMPLED_DATABASE_NAME' + database='DOWNSAMPLED_DATABASE_NAME', + org='' ) ``` {{% /code-placeholders %}} @@ -242,9 +244,11 @@ data_frame = table.to_pandas() ## Write the downsampled data back to InfluxDB -1. Use the `sort_values` method to sort data in the Pandas DataFrame by `time` +1. _For InfluxQL query results_, delete (`drop`) the `iox::measurement` column _before_ writing data back to InfluxDB. + You'll avoid measurement name conflicts when querying your downsampled data later. +2. Use the `sort_values` method to sort data in the Pandas DataFrame by `time` to ensure writing back to InfluxDB is as performant as possible. -2. Use the `write` method of your [instantiated downsampled client](#create-an-influxdb-client) +3. Use the `write` method of your [instantiated downsampled client](#create-an-influxdb-client) to write the query results back to your InfluxDB database for downsampled data. Include the following arguments: @@ -294,10 +298,12 @@ influxdb_raw = InfluxDBClient3( database='RAW_DATABASE_NAME' ) +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cluster-id.influxdb.io', token='DATABASE_TOKEN', - database='DOWNSAMPLED_DATABASE_NAME' + database='DOWNSAMPLED_DATABASE_NAME', + org='' ) query = ''' @@ -343,10 +349,12 @@ influxdb_raw = InfluxDBClient3( database='RAW_DATABASE_NAME' ) +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cluster-id.influxdb.io', token='DATABASE_TOKEN', - database='DOWNSAMPLED_DATABASE_NAME' + database='DOWNSAMPLED_DATABASE_NAME', + org='' ) query = ''' @@ -359,6 +367,11 @@ WHERE time >= now() - 24h GROUP BY time(1h) ''' +# To prevent naming conflicts when querying downsampled data, +# drop the iox::measurement column before writing the data +# with the new measurement. +data_frame = data_frame.drop(columns=['iox::measurement']) + table = influxdb_raw.query(query=query, language="influxql") data_frame = table.to_pandas() data_frame = data_frame.sort_values(by="time") diff --git a/content/influxdb/cloud-dedicated/query-data/influxql/basic-query.md b/content/influxdb/cloud-dedicated/query-data/influxql/basic-query.md new file mode 100644 index 000000000..cca59c146 --- /dev/null +++ b/content/influxdb/cloud-dedicated/query-data/influxql/basic-query.md @@ -0,0 +1,217 @@ +--- +title: Perform a basic InfluxQL query +seotitle: Perform a basic InfluxQL query in InfluxDB Cloud +description: > + A basic InfluxQL query that queries data from InfluxDB most commonly includes + `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb_cloud_dedicated: + name: Basic query + parent: Query with InfluxQL + identifier: query-influxql-basic +weight: 202 +influxdb/cloud-dedicated/tags: [query, influxql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - 1d + ``` +--- + +InfluxQL (Influx Query Language) is an SQL-like query language used to interact +with InfluxDB and work with times series data. + +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 + measurement or use the wildcard alias (`*`) to select all fields and tags + from a measurement. It requires at least one + [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key) or the wildcard alias (`*`). + For more information, see [Notable SELECT statement behaviors](/influxdb/cloud-dedicated/reference/influxql/select/#notable-select-statement-behaviors). +- {{< req "\*">}} `FROM`: Specify the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to query from. +It requires one or more comma-delimited [measurement expressions](/influxdb/cloud-dedicated/reference/influxql/select/#measurement_expression). +- `WHERE`: Filter data based on +[field values](/influxdb/cloud-dedicated/reference/glossary/#field), +[tag values](/influxdb/cloud-dedicated/reference/glossary/#tag), or +[timestamps](/influxdb/cloud-dedicated/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, {{% cloud-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 measurement (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](/influxdb/cloud-dedicated/reference/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 +[Get started home sensor data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb/cloud-dedicated/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% cloud-name %}} database before running the example queries. +{{% /note %}} + +### 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 measurement 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 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](/influxdb/cloud-dedicated/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](/influxdb/cloud-dedicated/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](/influxdb/cloud-dedicated/reference/influxql/#identifiers). +When [aliasing columns in **SQL**](/influxdb/cloud-dedicated/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/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md b/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md index 5948296ef..4c51b0b16 100644 --- a/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md @@ -44,7 +44,7 @@ An SQL query that aggregates data includes the following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output from a - measurement or use the wild card alias (`*`) to select all fields and tags + 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 return data that meets the specified conditions--for example, falls within diff --git a/content/influxdb/cloud-dedicated/query-data/sql/basic-query.md b/content/influxdb/cloud-dedicated/query-data/sql/basic-query.md index fb74e3758..790e97a60 100644 --- a/content/influxdb/cloud-dedicated/query-data/sql/basic-query.md +++ b/content/influxdb/cloud-dedicated/query-data/sql/basic-query.md @@ -26,7 +26,7 @@ following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output from a - measurement or use the wild card alias (`*`) to select all fields and tags + 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 return data that meets the specified conditions--for example, falls within @@ -45,6 +45,11 @@ WHERE ``` {{% /influxdb/custom-timestamps %}} +## Result set + +If at least one row satisfies the query, {{% cloud-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) @@ -61,7 +66,7 @@ The following examples use the sample data written in the [Get started writing data guide](/influxdb/cloud-dedicated/get-started/write/). To run the example queries and return results, [write the sample data](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb) -to your InfluxDB Cloud dedicated database before running the example queries. +to your {{% cloud-name %}} database before running the example queries. {{% /note %}} ### Query data within time boundaries @@ -110,8 +115,8 @@ WHERE {{% expand "Query with absolute time boundaries" %}} -To query data from absolute time boundaries, compare the value of the `time column -to a timestamp literals. +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. @@ -148,7 +153,7 @@ SELECT * FROM home To query specific fields, include them in the `SELECT` clause. If querying multiple fields or tags, comma-delimit each. -If the field or tag keys include special characters or spaces or are case-sensitive, +If a field or tag key includes special characters or spaces or is case-sensitive, wrap the key in _double-quotes_. ```sql @@ -161,7 +166,7 @@ SELECT time, room, temp, hum FROM home on in the `SELECT` clause. - Include predicates in the `WHERE` clause that compare the tag identifier to a string literal. - Use [logical operators](#) to chain multiple predicates together and apply + Use [logical operators](/influxdb/cloud-dedicated/reference/sql/where/#logical-operators) to chain multiple predicates together and apply multiple conditions. ```sql @@ -170,10 +175,9 @@ SELECT * FROM home WHERE room = 'Kitchen' ### Query points based on field values -- Include the fields you want to query in the `SELECT` clause. -- Include predicates in the `WHERE` clause that compare the field identifier to - another value. - Use [logical operators](#) (`AND`, `OR`) to chain multiple predicates together +- 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](/influxdb/cloud-dedicated/reference/sql/where/#logical-operators) (`AND`, `OR`) to chain multiple predicates together and apply multiple conditions. ```sql diff --git a/content/influxdb/cloud-dedicated/reference/glossary.md b/content/influxdb/cloud-dedicated/reference/glossary.md index d89ebd470..bfd3dd001 100644 --- a/content/influxdb/cloud-dedicated/reference/glossary.md +++ b/content/influxdb/cloud-dedicated/reference/glossary.md @@ -276,6 +276,15 @@ Metrics gathered at irregular time intervals. A combination of one or more constants, variables, operators, and functions. +In the following SQL example, `now() - INTERVAL '7 days'` is an expression that calculates the difference between the `now()` function expression and the duration represented by `INTERVAL '7 days`: + +```sql +SELECT * +FROM home +WHERE + time >= now() - INTERVAL '7 days' +``` + ## F ### field @@ -422,7 +431,6 @@ Written in Go and optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. - ### InfluxQL The SQL-like query language used to query data in InfluxDB. diff --git a/content/influxdb/cloud-dedicated/reference/influxql/_index.md b/content/influxdb/cloud-dedicated/reference/influxql/_index.md index f1b21fdb7..430a85b56 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/_index.md @@ -10,7 +10,7 @@ menu: weight: 102 --- -InfluxQL (Influx Query Language) is a SQL-like query language used to interact +InfluxQL (Influx Query Language) is an SQL-like query language used to interact with InfluxDB and work with times series data. {{% warn %}} @@ -35,6 +35,7 @@ see [InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feat - [Expressions](#expressions) - [Comments](#comments) - [Other](#other) +- [Result set](#result-set) ### Literals @@ -717,6 +720,10 @@ unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | float_lit | bool_lit | duration_lit | regex_lit . ``` +## Default time range + +The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. + ## Comments Use comments with InfluxQL statements to describe your queries. diff --git a/content/influxdb/cloud-dedicated/reference/influxql/group-by.md b/content/influxdb/cloud-dedicated/reference/influxql/group-by.md index e52b25fb1..b93dce74e 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/group-by.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/group-by.md @@ -21,20 +21,32 @@ Use the `GROUP BY` clause to group data by one or more specified or [selector](/influxdb/cloud-dedicated/reference/influxql/functions/selectors/) function in the `SELECT` statement. + + - [Syntax](#syntax) +- [GROUP BY clause behaviors](#group-by-clause-behaviors) +- [GROUP BY tags](#group-by-tags) - [GROUP BY tags examples](#group-by-tags-examples) - [GROUP BY time](#group-by-time) - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) - [GROUP BY time examples](#group-by-time-examples) + - [GROUP BY time with offset](#group-by-time-with-offset) + - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) +- [Result set](#result-set) + - [Default time range](#default-time-range) - [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) - [Cannot group by fields](#cannot-group-by-fields) - [Tag order does not matter](#tag-order-does-not-matter) - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) + - [Example data](#example-data) + - [Query results](#query-results) - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) + + ## Syntax ```sql @@ -44,13 +56,13 @@ SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_ - **group_expression**: Expression to identify tags or time intervals to group by. Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key), constant, [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/), - wildcard (`*`), or [function](/influxdb/cloud-dedicated/reference/influxql/functions/). + wildcard (`*`), or [function expression](/influxdb/cloud-dedicated/reference/influxql/functions/). -#### GROUP BY clause behaviors +## GROUP BY clause behaviors - `GROUP BY tag_key` - Groups data by a specific tag - `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag -- `GROUP BY *` - Groups data by all [tags](/influxdb/v2.7/reference/glossary/#tag) +- `GROUP BY *` - Groups data by all [tags](/influxdb/cloud-dedicated/reference/glossary/#tag) - `GROUP BY /regex/` - Groups data by tag keys that match the regular expression - `GROUP BY time()` - Groups data into time intervals (windows) @@ -59,6 +71,10 @@ If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear af the `WHERE` clause. {{% /note %}} +## GROUP BY tags + +Groups data by one or more tag columns. + ### GROUP BY tags examples The following examples use the @@ -482,23 +498,24 @@ name: bitcoin {{< /expand-wrapper >}} -## Notable behaviors of the GROUP BY clause +## Result set -### Cannot group by fields +If at least one row satisfies the query, {{% cloud-name %}} returns row data in the query result set. +If a query uses a `GROUP BY` clause, the result set includes the following: -InfluxQL does not support grouping data by **fields**. +- 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 measurement (table) name +- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping -### Tag order does not matter +### Default time range -The order that tags are listed in the `GROUP BY` clause does not affect how -data is grouped. - -### Grouping by tag and no time range returns unexpected timestamps - -When grouping by tags and no time range is specified in the -[`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/), results -use the [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch) as the default timestamp for the aggregate timestamp. -For example: +If a query doesn't specify a time range in the +[`WHERE` clause](/influxdb/cloud-dedicated/reference/influxql/where/), InfluxDB uses the +[default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range) for filtering and grouping by time. +If a query includes the `GROUP BY` clause and doesn't specify a time range in the +`WHERE` clause, the default time group is the +[default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: ```sql SELECT mean(temp) FROM home GROUP BY room @@ -522,6 +539,21 @@ tags: room=Living Room | :------------------- | ----------------: | | 1970-01-01T00:00:00Z | 22.16923076923077 | +## Notable behaviors of the GROUP BY clause + +### Cannot group by fields + +InfluxQL does not support grouping data by **fields**. + +### Tag order does not matter + +The order that tags are listed in the `GROUP BY` clause does not affect how +data is grouped. + +### Grouping by tag and no time range returns unexpected timestamps + +The `time` column contains the start of the [default time range](#default-time-range). + ### Data grouped by time may return unexpected timestamps Because `GROUP BY time()` intervals use preset round-number time boundaries that diff --git a/content/influxdb/cloud-dedicated/reference/influxql/select.md b/content/influxdb/cloud-dedicated/reference/influxql/select.md index b4a0fc293..a1c0603e9 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/select.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/select.md @@ -44,7 +44,7 @@ It requires one or more **field expressions** and optional **tag expressions**. Can be a [field key](/influxdb/cloud-dedicated/reference/glossary/#field-key), constant, [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/), [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or - [function](/influxdb/cloud-dedicated/reference/influxql/functions/) and any + [function expression](/influxdb/cloud-dedicated/reference/influxql/functions/) and any combination of arithmetic operators. - **tag_expression**: Expression to identify one or more tags to return in query results. Can be a [tag key](/influxdb/cloud-dedicated/reference/glossary/#tag-key) or constant. @@ -69,7 +69,9 @@ The `FROM` clause specifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to query. It requires one or more comma-delimited **measurement expressions**. -- **measurement_expression**: Expression to identify one or more measurements to query. +- #### measurement_expression + + Expression to identify one or more measurements to query. Can be a measurement name, fully-qualified measurement, constant, or [regular expression](/influxdb/cloud-dedicated/reference/influxql/regular-expressions/). diff --git a/content/influxdb/cloud-dedicated/reference/influxql/where.md b/content/influxdb/cloud-dedicated/reference/influxql/where.md index 942b503b1..65a2668ff 100644 --- a/content/influxdb/cloud-dedicated/reference/influxql/where.md +++ b/content/influxdb/cloud-dedicated/reference/influxql/where.md @@ -72,18 +72,17 @@ Operators evaluate the relationship between two operands and return ## Time ranges Use the `WHERE` clause to specify a time range to query. -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_. +If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/cloud-dedicated/reference/influxql/#default-time-range) is used. -Timestamps are stored in the `time` columns. +Timestamps are stored in the `time` column. Use comparison operators to compare the value of the `time` column to a -timestamp literal, integer (Unix nanosecond timestamp), or function. +timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/cloud-dedicated/reference/glossary/#expression). {{< code-tabs-wrapper >}} {{% code-tabs %}} [Timestamp](#) [Integer](#) -[Function](#) +[Expression](#) {{% /code-tabs %}} {{% code-tab-content %}} ```sql diff --git a/content/influxdb/cloud-dedicated/reference/sql/_index.md b/content/influxdb/cloud-dedicated/reference/sql/_index.md index cf6eac9de..7999f66e5 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/sql/_index.md @@ -11,7 +11,7 @@ related: - /influxdb/cloud-dedicated/reference/internals/arrow-flightsql/ --- -InfluxDB Cloud Dedicated uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. +{{% cloud-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. - [Identifiers](#identifiers) - [Quoting and case sensitivity](#quoting-and-case-sensitivity) @@ -22,7 +22,7 @@ InfluxDB Cloud Dedicated uses the [Apache Arrow DataFusion](https://arrow.apache - [Conditional expressions](#conditional-expressions) - [Statements and clauses](#statements-and-clauses) - [Comments](#comments) -- [Functions](#functions) +- [Functions](#functions) ## Identifiers @@ -482,7 +482,7 @@ Use comments to describe and add detail or notes to your queries. ## Schema information -InfluxDB {{< current-version >}} backed by InfluxDB IOx supports the following metedata schema queries: +{{% cloud-name %}} supports the following metedata schema queries: ```sql SHOW tables @@ -621,4 +621,3 @@ GROUP BY time | :------------- | :---------------------------------------------------------------------------- | | REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | | REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | - diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 2661720e1..5eb10847f 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -69,7 +69,7 @@ InfluxDB SQL queries most commonly include the following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Identify specific fields and tags to query from a - measurement or use the wild card alias (`*`) to select all fields and tags + measurement or use the wildcard alias (`*`) to select all fields and tags from a measurement. - {{< req "\*">}} `FROM`: Identify the measurement to query. If coming from an SQL background, an InfluxDB measurement is the equivalent diff --git a/content/influxdb/cloud-serverless/process-data/downsample.md b/content/influxdb/cloud-serverless/process-data/downsample.md index 99d78ba39..3a9f877be 100644 --- a/content/influxdb/cloud-serverless/process-data/downsample.md +++ b/content/influxdb/cloud-serverless/process-data/downsample.md @@ -85,17 +85,17 @@ import pandas # Instantiate an InfluxDBClient3 client configured for your unmodified bucket influxdb_raw = InfluxDBClient3( host='cloud2.influxdata.com', - org='ORG_NAME', token='API_TOKEN', database='RAW_BUCKET_NAME' ) -# Instantiate an InfluxDBClient3 client configured for your downsampled bucket +# Instantiate an InfluxDBClient3 client configured for your downsampled database. +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cloud2.influxdata.com', - org='ORG_NAME', token='API_TOKEN', - database='DOWNSAMPLED_BUCKET_NAME' + database='DOWNSAMPLED_BUCKET_NAME', + org='' ) ``` {{% /code-placeholders %}} @@ -246,7 +246,9 @@ data_frame = table.to_pandas() ## Write the downsampled data back to InfluxDB -1. Use the `sort_values` method to sort data in the Pandas DataFrame by `time` +1. _For InfluxQL query results_, delete (`drop`) the `iox::measurement` column _before_ writing data back to InfluxDB. + You'll avoid measurement name conflicts when querying your downsampled data later. +2. Use the `sort_values` method to sort data in the Pandas DataFrame by `time` to ensure writing back to InfluxDB is as performant as possible. 2. Use the `write` method of your [instantiated downsampled client](#create-an-influxdb-client) to write the query results back to your InfluxDB bucket for downsampled data. @@ -294,16 +296,16 @@ import pandas influxdb_raw = InfluxDBClient3( host='cloud2.influxdata.com', - org='ORG_NAME', token='API_TOKEN', database='RAW_BUCKET_NAME' ) +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cloud2.influxdata.com', - org='ORG_NAME', token='API_TOKEN', - database='DOWNSAMPLED_BUCKET_NAME' + database='DOWNSAMPLED_BUCKET_NAME', + org='' ) query = ''' @@ -350,11 +352,12 @@ influxdb_raw = InfluxDBClient3( database='RAW_BUCKET_NAME' ) +# When writing, the org= argument is required by the client (but ignored by InfluxDB). influxdb_downsampled = InfluxDBClient3( host='cloud2.influxdata.com', - org='ORG_NAME', token='API_TOKEN', - database='DOWNSAMPLED_BUCKET_NAME' + database='DOWNSAMPLED_BUCKET_NAME', + org='' ) query = ''' @@ -367,6 +370,11 @@ WHERE time >= now() - 24h GROUP BY time(1h) ''' +# To prevent naming conflicts when querying downsampled data, +# drop the iox::measurement column before writing the data +# with the new measurement. +data_frame = data_frame.drop(columns=['iox::measurement']) + table = influxdb_raw.query(query=query, language="influxql") data_frame = table.to_pandas() data_frame = data_frame.sort_values(by="time") diff --git a/content/influxdb/cloud-serverless/query-data/influxql/basic-query.md b/content/influxdb/cloud-serverless/query-data/influxql/basic-query.md new file mode 100644 index 000000000..44cb09683 --- /dev/null +++ b/content/influxdb/cloud-serverless/query-data/influxql/basic-query.md @@ -0,0 +1,215 @@ +--- +title: Perform a basic InfluxQL query +seotitle: Perform a basic InfluxQL query in InfluxDB Cloud +description: > + A basic InfluxQL query that queries data from InfluxDB most commonly includes + `SELECT`, `FROM`, and `WHERE` clauses. +menu: + influxdb_cloud_serverless: + name: Basic query + parent: Query with InfluxQL + identifier: query-influxql-basic +weight: 202 +influxdb/cloud-serverless/tags: [query, influxql] +list_code_example: | + ```sql + SELECT temp, room FROM home WHERE time >= now() - 1d + ``` +--- + +InfluxQL (Influx Query Language) is an SQL-like query language used to interact +with InfluxDB and work with times series data. + +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 + measurement or use the wildcard alias (`*`) to select all fields and tags + from a measurement. It requires at least one + [field key](/influxdb/cloud-serverless/reference/glossary/#field-key) or the wildcard alias (`*`). + For more information, see [Notable SELECT statement behaviors](/influxdb/cloud-serverless/reference/influxql/select/#notable-select-statement-behaviors). +- {{< req "\*">}} `FROM`: Specify the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to query from. +It requires one or more comma-delimited [measurement expressions](/influxdb/cloud-serverless/reference/influxql/select/#measurement_expression). +- `WHERE`: Filter data based on +[field values](/influxdb/cloud-serverless/reference/glossary/#field), +[tag values](/influxdb/cloud-serverless/reference/glossary/#tag), or +[timestamps](/influxdb/cloud-serverless/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, {{% cloud-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 measurement (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](/influxdb/cloud-serverless/reference/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 +[Get started home sensor data](/influxdb/cloud-serverless/reference/sample-data/#get-started-home-sensor-data). +To run the example queries and return results, +[write the sample data](/influxdb/cloud-serverless/reference/sample-data/#write-the-home-sensor-data-to-influxdb) +to your {{% cloud-name %}} database before running the example queries. +{{% /note %}} + +### 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 measurement 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 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](/influxdb/cloud-serverless/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](/influxdb/cloud-serverless/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](/influxdb/cloud-serverless/reference/influxql/#identifiers). +When [aliasing columns in **SQL**](/influxdb/cloud-serverless/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/influxdb/cloud-serverless/query-data/sql/aggregate-select.md b/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md index 925fd9a21..e3930740e 100644 --- a/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md @@ -44,7 +44,7 @@ A SQL query that aggregates data includes the following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output from a - measurement or use the wild card alias (`*`) to select all fields and tags + 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 return data that meets the specified conditions--for example, falls within diff --git a/content/influxdb/cloud-serverless/query-data/sql/basic-query.md b/content/influxdb/cloud-serverless/query-data/sql/basic-query.md index 1c22f24df..3df4762b1 100644 --- a/content/influxdb/cloud-serverless/query-data/sql/basic-query.md +++ b/content/influxdb/cloud-serverless/query-data/sql/basic-query.md @@ -26,7 +26,7 @@ following clauses: {{< req type="key" >}} - {{< req "\*">}} `SELECT`: Specify fields, tags, and calculations to output from a - measurement or use the wild card alias (`*`) to select all fields and tags + 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 return data that meets the specified conditions--for example, falls within @@ -45,6 +45,11 @@ WHERE ``` {{% /influxdb/custom-timestamps %}} +## Result set + +If at least one row satisfies the query, {{% cloud-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) diff --git a/content/influxdb/cloud-serverless/reference/glossary.md b/content/influxdb/cloud-serverless/reference/glossary.md index bd5e4d42c..e04068f45 100644 --- a/content/influxdb/cloud-serverless/reference/glossary.md +++ b/content/influxdb/cloud-serverless/reference/glossary.md @@ -281,6 +281,15 @@ Metrics gathered at irregular time intervals. A combination of one or more constants, variables, operators, and functions. +In the following SQL example, `now() - INTERVAL '7 days'` is an expression that calculates the difference between the `now()` function expression and the duration represented by `INTERVAL '7 days`: + +```sql +SELECT * +FROM home +WHERE + time >= now() - INTERVAL '7 days' +``` + ## F ### field @@ -429,7 +438,6 @@ Written in Go and optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. - ### InfluxQL The SQL-like query language used to query data in InfluxDB. @@ -1109,4 +1117,3 @@ Related entries: Grouping data based on specified time intervals. This is also referred to as "time binning" or "date binning." - diff --git a/content/influxdb/cloud-serverless/reference/influxql/_index.md b/content/influxdb/cloud-serverless/reference/influxql/_index.md index 8b1bb16e5..8a348fd46 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/_index.md +++ b/content/influxdb/cloud-serverless/reference/influxql/_index.md @@ -35,6 +35,7 @@ see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/fea - [Expressions](#expressions) - [Comments](#comments) - [Other](#other) +- [Result set](#result-set) ### Literals @@ -717,6 +720,10 @@ unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit | float_lit | bool_lit | duration_lit | regex_lit . ``` +## Default time range + +The default time range is the Unix epoch (`1970-01-01T00:00:00Z`) to _now_. + ## Comments Use comments with InfluxQL statements to describe your queries. diff --git a/content/influxdb/cloud-serverless/reference/influxql/group-by.md b/content/influxdb/cloud-serverless/reference/influxql/group-by.md index 90e484d01..38b435f8c 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/group-by.md +++ b/content/influxdb/cloud-serverless/reference/influxql/group-by.md @@ -21,20 +21,32 @@ Use the `GROUP BY` clause to group data by one or more specified or [selector](/influxdb/cloud-serverless/reference/influxql/functions/selectors/) function in the `SELECT` statement. + + - [Syntax](#syntax) +- [GROUP BY clause behaviors](#group-by-clause-behaviors) +- [Group by tags](#group-by-tags) - [GROUP BY tags examples](#group-by-tags-examples) - [GROUP BY time](#group-by-time) - [GROUP by time and fill gaps](#group-by-time-and-fill-gaps) - [GROUP BY time examples](#group-by-time-examples) + - [GROUP BY time with offset](#group-by-time-with-offset) + - [GROUP BY time and fill gaps](#group-by-time-and-fill-gaps) +- [Result set](#result-set) + - [Default time range](#default-time-range) - [Notable behaviors of the GROUP BY clause](#notable-behaviors-of-the-group-by-clause) - [Cannot group by fields](#cannot-group-by-fields) - [Tag order does not matter](#tag-order-does-not-matter) - [Grouping by tag and no time range returns unexpected timestamps](#grouping-by-tag-and-no-time-range-returns-unexpected-timestamps) - [Data grouped by time may return unexpected timestamps](#data-grouped-by-time-may-return-unexpected-timestamps) + - [Example data](#example-data) + - [Query results](#query-results) - [Fill with no data in the queried time range](#fill-with-no-data-in-the-queried-time-range) - [Fill with previous if no previous value exists](#fill-with-previous-if-no-previous-value-exists) - [Fill with linear interpolation if there are not two values to interpolate between](#fill-with-linear-interpolation-if-there-are-not-two-values-to-interpolate-between) + + ## Syntax ```sql @@ -44,13 +56,13 @@ SELECT_clause FROM_clause [WHERE_clause] GROUP BY group_expression[, ..., group_ - **group_expression**: Expression to identify tags or time intervals to group by. Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key), constant, [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/), - wildcard (`*`), or [function](/influxdb/cloud-serverless/reference/influxql/functions/). + wildcard (`*`), or [function expression](/influxdb/cloud-serverless/reference/influxql/functions/). -#### GROUP BY clause behaviors +## GROUP BY clause behaviors - `GROUP BY tag_key` - Groups data by a specific tag - `GROUP BY tag_key1, tag_key2` - Groups data by more than one tag -- `GROUP BY *` - Groups data by all [tags](/influxdb/v2.7/reference/glossary/#tag) +- `GROUP BY *` - Groups data by all [tags](/influxdb/cloud-serverless/reference/glossary/#tag) - `GROUP BY /regex/` - Groups data by tag keys that match the regular expression - `GROUP BY time()` - Groups data into time intervals (windows) @@ -59,6 +71,10 @@ If a query includes `WHERE` and `GROUP BY`, the `GROUP BY` clause must appear af the `WHERE` clause. {{% /note %}} +## GROUP BY tags + +Groups data by one or more tag columns. + ### GROUP BY tags examples The following examples use the @@ -482,23 +498,24 @@ name: bitcoin {{< /expand-wrapper >}} -## Notable behaviors of the GROUP BY clause +## Result set -### Cannot group by fields +If at least one row satisfies the query, {{% cloud-name %}} returns row data in the query result set. +If a query uses a `GROUP BY` clause, the result set includes the following: -InfluxQL does not support grouping data by **fields**. +- 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 measurement (table) name +- Columns listed in the query's `GROUP BY` clause; each row in the result set contains the values used for grouping -### Tag order does not matter +### Default time range -The order that tags are listed in the `GROUP BY` clause does not affect how -data is grouped. - -### Grouping by tag and no time range returns unexpected timestamps - -When grouping by tags and no time range is specified in the -[`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/), results -use the [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch) as the default timestamp for the aggregate timestamp. -For example: +If a query doesn't specify a time range in the +[`WHERE` clause](/influxdb/cloud-serverless/reference/influxql/where/), InfluxDB uses the +[default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range) for filtering and grouping by time. +If a query includes the `GROUP BY` clause and doesn't specify a time range in the +`WHERE` clause, the default time group is the +[default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range), and the `time` column in the result set contains the start of the range--for example: ```sql SELECT mean(temp) FROM home GROUP BY room @@ -522,6 +539,21 @@ tags: room=Living Room | :------------------- | ----------------: | | 1970-01-01T00:00:00Z | 22.16923076923077 | +## Notable behaviors of the GROUP BY clause + +### Cannot group by fields + +InfluxQL does not support grouping data by **fields**. + +### Tag order does not matter + +The order that tags are listed in the `GROUP BY` clause does not affect how +data is grouped. + +### Grouping by tag and no time range returns unexpected timestamps + +The `time` column contains the start of the [default time range](#default-time-range). + ### Data grouped by time may return unexpected timestamps Because `GROUP BY time()` intervals use preset round-number time boundaries that diff --git a/content/influxdb/cloud-serverless/reference/influxql/select.md b/content/influxdb/cloud-serverless/reference/influxql/select.md index 7ea8d1c6d..743fcebd4 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/select.md +++ b/content/influxdb/cloud-serverless/reference/influxql/select.md @@ -44,7 +44,7 @@ It requires one or more **field expressions** and optional **tag expressions**. Can be a [field key](/influxdb/cloud-serverless/reference/glossary/#field-key), constant, [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/), [wildcard (`*`)](#wildcard-expressions-in-select-clauses), or - [function](/influxdb/cloud-serverless/reference/influxql/functions/) and any + [function expression](/influxdb/cloud-serverless/reference/influxql/functions/) and any combination of arithmetic operators. - **tag_expression**: Expression to identify one or more tags to return in query results. Can be a [tag key](/influxdb/cloud-serverless/reference/glossary/#tag-key) or constant. @@ -67,9 +67,11 @@ It requires one or more **field expressions** and optional **tag expressions**. The `FROM` clause specifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to query. -It requires one or more comma-delimited **measurement expressions**. +It requires one or more comma-delimited [measurement_expressions](#measurement_expression). -- **measurement_expression**: Expression to identify one or more measurements to query. +- #### measurement_expression + + Expression to identify one or more measurements to query. Can be a measurement name, fully-qualified measurement, constant, or [regular expression](/influxdb/cloud-serverless/reference/influxql/regular-expressions/). diff --git a/content/influxdb/cloud-serverless/reference/influxql/where.md b/content/influxdb/cloud-serverless/reference/influxql/where.md index a3573a6af..b69375095 100644 --- a/content/influxdb/cloud-serverless/reference/influxql/where.md +++ b/content/influxdb/cloud-serverless/reference/influxql/where.md @@ -72,18 +72,17 @@ Operators evaluate the relationship between two operands and return ## Time ranges Use the `WHERE` clause to specify a time range to query. -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_. +If a time range isn't specified in the `WHERE` clause, the [default time range](/influxdb/cloud-serverless/reference/influxql/#default-time-range) is used. -Timestamps are stored in the `time` columns. +Timestamps are stored in the `time` column. Use comparison operators to compare the value of the `time` column to a -timestamp literal, integer (Unix nanosecond timestamp), or function. +timestamp literal, integer (Unix nanosecond timestamp), or [expression](/influxdb/cloud-serverless/reference/glossary/#expression). {{< code-tabs-wrapper >}} {{% code-tabs %}} [Timestamp](#) [Integer](#) -[Function](#) +[Expression](#) {{% /code-tabs %}} {{% code-tab-content %}} ```sql diff --git a/content/influxdb/cloud-serverless/reference/sql/_index.md b/content/influxdb/cloud-serverless/reference/sql/_index.md index fc8b464d6..8f907e68c 100644 --- a/content/influxdb/cloud-serverless/reference/sql/_index.md +++ b/content/influxdb/cloud-serverless/reference/sql/_index.md @@ -9,7 +9,7 @@ menu: weight: 101 --- -InfluxDB Cloud Serverless uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. +{{% cloud-name %}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. - [Identifiers](#identifiers) - [Quoting and case sensitivity](#quoting-and-case-sensitivity) @@ -20,7 +20,7 @@ InfluxDB Cloud Serverless uses the [Apache Arrow DataFusion](https://arrow.apach - [Conditional expressions](#conditional-expressions) - [Statements and clauses](#statements-and-clauses) - [Comments](#comments) -- [Functions](#functions) +- [Functions](#functions) ## Identifiers @@ -480,7 +480,7 @@ Use comments to describe and add detail or notes to your queries. ## Schema information -InfluxDB Cloud Serverless supports the following metedata schema queries: +{{% cloud-name %}} supports the following metedata schema queries: ```sql SHOW tables @@ -619,4 +619,3 @@ GROUP BY time | :------------- | :---------------------------------------------------------------------------- | | REGEXP_MATCH | Matches a regular expression against a string and returns matched substrings. | | REGEXP_REPLACE | Replaces substrings that match a regular expression by a new substring. | -