From 0d99ebc3ab34a6c84451cec8ca0094daaa2173b4 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 28 Aug 2024 15:24:01 -0600 Subject: [PATCH 1/6] updated timezone-related functions and operators --- .../InfluxDataDocs/Terms/query-functions.txt | 1 + .../vocabularies/InfluxDataDocs/accept.txt | 2 +- .../reference/sql/data-types.md | 52 +-- .../reference/sql/functions/misc.md | 4 +- .../reference/sql/functions/time-and-date.md | 327 ++++++++++++++--- .../reference/sql/operators/other.md | 44 ++- .../reference/sql/data-types.md | 53 +-- .../reference/sql/functions/misc.md | 4 +- .../reference/sql/functions/time-and-date.md | 329 +++++++++++++++--- .../reference/sql/operators/other.md | 44 ++- .../clustered/reference/sql/data-types.md | 52 +-- .../clustered/reference/sql/functions/misc.md | 4 +- .../reference/sql/functions/time-and-date.md | 325 +++++++++++++++-- .../reference/sql/operators/other.md | 44 ++- 14 files changed, 1061 insertions(+), 224 deletions(-) diff --git a/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt b/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt index e74c2be313..85497d7855 100644 --- a/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt +++ b/.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt @@ -128,6 +128,7 @@ left level like local +locf lower match max diff --git a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt index dae2608d14..a758338d6c 100644 --- a/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt +++ b/.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt @@ -71,7 +71,7 @@ influxdata.com iox keep-url lat -locf +(locf|LOCF) logicalplan noaa|NOAA npm|NPM diff --git a/content/influxdb/cloud-dedicated/reference/sql/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index ea4763ffc9..7050893795 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/data-types.md +++ b/content/influxdb/cloud-dedicated/reference/sql/data-types.md @@ -13,16 +13,26 @@ related: - /influxdb/cloud-dedicated/query-data/sql/cast-types/ --- -InfluxDB Cloud Dedicated uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. +{{< product-name >}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) +implementation of SQL. Data types define the type of values that can be stored in table columns. In InfluxDB's SQL implementation, a **measurement** is structured as a table, and **tags**, **fields** and **timestamps** are exposed as columns. +## SQL and Arrow data types + +In SQL, each column, expression, and parameter has a data type. +A data type is an attribute that specifies the type of data that the object can hold. DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. +All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). + +Both SQL and Arrow data types play an important role is how data is operated on +during query execution and returned in query results. {{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. +When performing casting operations, cast to the SQL data type unless you use +[`arrow_cast()`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#arrow_cast) +to cast to a specific Arrow type. Names and identifiers in SQL are _case-insensitive_ by default. For example: ```sql @@ -47,12 +57,12 @@ SELECT ## String types -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | --------------------------------- | +| STRING | UTF8 | Character string, variable-length | +| CHAR | UTF8 | Character string, fixed-length | +| VARCHAR | UTF8 | Character string, variable-length | +| TEXT | UTF8 | Variable unlimited length | ##### Example string literals @@ -66,11 +76,11 @@ SELECT The following numeric types are supported: -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | +| SQL data type | Arrow data type | Description | +| :-------------- | :-------------- | :--------------------------- | +| BIGINT | INT64 | 64-bit signed integer | +| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | +| DOUBLE | FLOAT64 | 64-bit floating-point number | ### Integers @@ -122,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | +| SQL data type | Arrow data type | Description | +| :------------ | :----------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp @@ -180,9 +190,9 @@ INTERVAL '2 days 1 hour 31 minutes' Booleans store TRUE or FALSE values. -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | :------------------- | +| BOOLEAN | Boolean | True or false values | ##### Example boolean literals diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md b/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md index 189fbe5cbb..446963a242 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/misc.md @@ -32,7 +32,7 @@ arrow_cast(expression, datatype) - **expression**: Expression to cast. Can be a constant, column, or function, and any combination of arithmetic or string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) +- **datatype**: [Arrow data type](/influxdb/cloud-dedicated/reference/sql/data-types/#sql-and-arrow-data-types) to cast to. {{< expand-wrapper >}} @@ -60,7 +60,7 @@ LIMIT 1 ## arrow_typeof Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: +of the expression: ```sql arrow_typeof(expression) diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md index a05e253219..8140925c7b 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md @@ -22,12 +22,18 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [datepart](#datepart) - [extract](#extract) - [from_unixtime](#from_unixtime) +- [make_date](#make_date) - [now](#now) +- [today](#today) +- [to_char](#to_char) +- [to_date](#to_date) +- [to_local_time](#to_local_time) - [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) - [to_timestamp_micros](#to_timestamp_micros) +- [to_timestamp_millis](#to_timestamp_millis) - [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) +- [to_unixtime](#to_unixtime) ## current_date @@ -35,7 +41,7 @@ Returns the current UTC date. {{% note %}} `current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-a-timestamp-type). +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-dedicated/query-data/sql/cast-types/). {{% /note %}} The `current_date()` return value is determined at query time and will return @@ -121,8 +127,7 @@ Calculates time intervals and returns the start of the interval nearest to the s Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" and applying an aggregate or selector function to each window. -For example, given an input -timestamp of `2023-01-01T18:18:18Z`, if you bin data into 15-minute intervals, the output timestamp is `2023-01-01T18:15:00Z`--the start of the 15-minute bin that includes the input. +For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`. ```sql date_bin(interval, expression[, origin_timestamp]) @@ -463,7 +468,7 @@ date_part(part, expression) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **expression**: Time expression to operate on. Can be a constant, column, or function. @@ -529,7 +534,7 @@ extract(field FROM source) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **source**: Source time expression to operate on. Can be a constant, column, or function. @@ -567,6 +572,10 @@ from_unixtime(expression) - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +##### Related functions + +[to_unixtime](#to_unixtime) + {{< expand-wrapper >}} {{% expand "View `from_unixtime` query example" %}} @@ -582,6 +591,42 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} +## make_date + +Returns a date using the component parts (year, month, day). + +{{% note %}} +`make_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-dedicated/query-data/sql/cast-types/). +{{% /note %}} + +```sql +make_date(year, month, day) +``` + +##### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators + +{{< expand-wrapper >}} +{{% expand "View `make_date` query example" %}} + +```sql +SELECT make_date(2024, 01, 01)::STRING AS date +``` + +| date | +| :--------- | +| 2023-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## now Returns the current UTC timestamp. @@ -608,6 +653,156 @@ WHERE {{% /expand %}} {{< /expand-wrapper >}} +## today + +_Alias of [current_date](#current_date)._ + +## to_char + +Returns the string representation of a date, time, timestamp, or duration based on +a [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). + +{{% note %}} +Unlike the PostgreSQL `TO_CHAR()` function, this function does not support +numeric formatting. +{{% /note %}} + +```sql +to_char(expression, format) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a date, time, timestamp or duration. +- **format**: [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + to use to convert the expression. + +{{< expand-wrapper >}} +{{% expand "View `to_char` query example" %}} + +```sql +SELECT + to_char('2024-01-01T12:22:01Z'::TIMESTAMP, '%a %e-%b-%Y %H:%M:%S') AS datestring +``` + +| datestring | +| :----------------------- | +| Mon 1-Jan-2024 12:22:01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_date + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings and numeric types as input. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Numeric values are interpreted as days since the +[Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). + +{{% note %}} +`to_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-dedicated/query-data/sql/cast-types/). +{{% /note %}} + +```sql +to_date(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_date` query example" %}} + +```sql +SELECT + to_date('1-Jan-2024', '%e-%b-%Y')::STRING AS date +``` + +| date | +| :--------- | +| 2024-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_local_time + +Converts a timestamp with a timezone to a timestamp without a timezone +(no offset or timezone information). This function accounts for time shifts +like Daylight Saving Time (DST) or British Summer Time (BST). + +{{% note %}} +Use `to_local_time()` with [`date_bin()`](#date_bin) and +[`date_bin_gapfill`](#date_bin_gapfill) to generate window boundaries based the +local time zone rather than UTC. +{{% /note %}} + +```sql +to_local_time(expression) +``` + +##### Arguments + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `to_local_time` query example" %}} + +```sql +SELECT + to_local_time('2024-01-01 00:00:00'::TIMESTAMP) AS "local time"; +``` + +| local time | +| :------------------- | +| 2024-01-01T00:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with a time zone offset" %}} + +```sql +SELECT + to_local_time((arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))')) AT TIME ZONE 'America/Los_Angeles') AS "local time" +``` + +| local time | +| :------------------- | +| 2023-12-31T16:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with `date_bin`" %}} + +```sql +SELECT + date_bin(interval '1 day', time, to_local_time(0::TIMESTAMP)) AT TIME ZONE 'America/Los_Angeles' AS time, + avg(f1), + avg(f2) +FROM + (VALUES (arrow_cast('2024-01-01 12:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 1.23, 4.56), + (arrow_cast('2024-01-01 13:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 2.46, 8.1), + (arrow_cast('2024-01-01 14:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 4.81, 16.2) + ) AS data(time, f1, f2) +GROUP BY 1 +``` + +| time | avg(data.f1) | avg(data.f2) | +| :------------------------ | -----------------: | -----------: | +| 2023-12-31T16:00:00-08:00 | 2.8333333333333335 | 9.62 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## to_timestamp Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). @@ -639,96 +834,96 @@ SELECT to_timestamp(1704067200000000000) {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_millis +## to_timestamp_micros -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). +Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) +[Unix microsecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_millis(expression[, ..., format_n]) +to_timestamp_micros(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} +{{% expand "View `to_timestamp_micros` query example" %}} ```sql -SELECT to_timestamp_millis(1704067200001) AS time +SELECT to_timestamp_micros(1704067200000001) ``` -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - +| to_timestamp_micros(Int64(1704067200000001)) | +| :------------------------------------------- | +| 2024-01-01T00:00:00.000001Z | {{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} +{{% expand "View `to_timestamp_micros` example with string format parsing" %}} ```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond +SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond ``` -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | +| microsecond | +| :-------------------------- | +| 2024-01-01T01:01:59.123456Z | {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_micros +## to_timestamp_millis -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). +Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) +[Unix millisecond timestamps](/influxdb/cloud-dedicated/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_micros(expression[, ..., format_n]) +to_timestamp_millis(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} +{{% expand "View `to_timestamp_millis` query example" %}} ```sql -SELECT to_timestamp_micros(1704067200000001) +SELECT to_timestamp_millis(1704067200001) AS time ``` -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | +Results +| to_timestamp_millis(Int64(1704067200001)) | +| :---------------------------------------- | +| 2024-01-01T00:00:00.001Z | + {{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} +{{% expand "View `to_timestamp_millis` example with string format parsing" %}} ```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond +SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond ``` -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | +| millisecond | +| :----------------------- | +| 2024-01-01T01:01:59.123Z | {{% /expand %}} {{< /expand-wrapper >}} @@ -749,7 +944,7 @@ to_timestamp_nanos(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -795,7 +990,7 @@ to_timestamp_seconds(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -825,3 +1020,55 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: {{% /expand %}} {{< /expand-wrapper >}} + +## to_unixtime + +Converts a value to seconds since the [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). +Supports strings, timestamps, and floats as input. +Strings are parsed as RFC3339nano timestamps if no +[Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +are provided. + +```sql +to_unixtime(expression[, ..., format_n]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +##### Related functions + +[from_unixtime](#from_unixtime) + +{{< expand-wrapper >}} +{{% expand "View `to_unixtime` query example" %}} + +```sql +SELECT to_unixtime('2024-01-01T01:01:59.123456789Z') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{% expand "View `to_unixtime` example with string format parsing" %}} + +```sql +SELECT + to_unixtime('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md index 5fe800ec41..d3b8a10639 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md @@ -45,20 +45,42 @@ SELECT 'Hello' || ' world' AS "Concatenated" ## AT TIME ZONE -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. +The `AT TIME ZONE` operator takes the timestamp in the left operand and returns +an equivalent timestamp with the updated time and offset of the time zone +specified in the right operand. +If no time zone is included in the input timestamp's +[Arrow data type](/influxdb/cloud-dedicated/reference/sql/data-types/#sql-and-arrow-data-types), +the operator assumes the time is in the time zone specified. +Time zone offsets are provided by the operating system time zone database. -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} +```sql +SELECT time AT TIME ZONE 'America/Los_Angeles' FROM home +``` + +{{< expand-wrapper >}} +{{% expand "Convert a UTC timestamp to a specified timezone" %}} + +```sql +SELECT + arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))') + AT TIME ZONE 'America/Los_Angeles' AS 'Time with TZ offset' +``` + +| Time with TZ offset | +| :------------------------ | +| 2023-12-31T16:00:00-08:00 | + +{{% /expand %}} +{{% expand "Add a time zone offset to a timestamp without a specified timezone" %}} ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | +| Local time with TZ offset | +| :------------------------ | +| 2024-01-01T00:00:00-08:00 | + +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/data-types.md b/content/influxdb/cloud-serverless/reference/sql/data-types.md index 54dcc94bc8..cff4c51984 100644 --- a/content/influxdb/cloud-serverless/reference/sql/data-types.md +++ b/content/influxdb/cloud-serverless/reference/sql/data-types.md @@ -13,16 +13,26 @@ related: - /influxdb/cloud-serverless/query-data/sql/cast-types/ --- -InfluxDB Cloud Serverless uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. +{{< product-name >}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) +implementation of SQL. Data types define the type of values that can be stored in table columns. In InfluxDB's SQL implementation, a **measurement** is structured as a table, and **tags**, **fields** and **timestamps** are exposed as columns. +## SQL and Arrow data types + +In SQL, each column, expression, and parameter has a data type. +A data type is an attribute that specifies the type of data that the object can hold. DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. +All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). + +Both SQL and Arrow data types play an important role is how data is operated on +during query execution and returned in query results. {{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. +When performing casting operations, cast to the SQL data type unless you use +[`arrow_cast()`](/influxdb/cloud-serverless/reference/sql/functions/misc/#arrow_cast) +to cast to a specific Arrow type. Names and identifiers in SQL are _case-insensitive_ by default. For example: ```sql @@ -47,12 +57,12 @@ SELECT ## String types -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | --------------------------------- | +| STRING | UTF8 | Character string, variable-length | +| CHAR | UTF8 | Character string, fixed-length | +| VARCHAR | UTF8 | Character string, variable-length | +| TEXT | UTF8 | Variable unlimited length | ##### Example string literals @@ -66,11 +76,11 @@ SELECT The following numeric types are supported: -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | +| SQL data type | Arrow data type | Description | +| :-------------- | :-------------- | :--------------------------- | +| BIGINT | INT64 | 64-bit signed integer | +| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | +| DOUBLE | FLOAT64 | 64-bit floating-point number | ### Integers @@ -122,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | +| SQL data type | Arrow data type | Description | +| :------------ | :----------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp @@ -170,7 +180,6 @@ The INTERVAL data type can be used with the following precision: - century ##### Example interval literals - ```sql INTERVAL '10 minutes' INTERVAL '1 year' @@ -181,9 +190,9 @@ INTERVAL '2 days 1 hour 31 minutes' Booleans store TRUE or FALSE values. -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | :------------------- | +| BOOLEAN | Boolean | True or false values | ##### Example boolean literals diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/misc.md b/content/influxdb/cloud-serverless/reference/sql/functions/misc.md index 7996c011ae..25017d9c8e 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/misc.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/misc.md @@ -32,7 +32,7 @@ arrow_cast(expression, datatype) - **expression**: Expression to cast. Can be a constant, column, or function, and any combination of arithmetic or string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) +- **datatype**: [Arrow data type](/influxdb/cloud-serverless/reference/sql/data-types/#sql-and-arrow-data-types) to cast to. {{< expand-wrapper >}} @@ -60,7 +60,7 @@ LIMIT 1 ## arrow_typeof Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: +of the expression: ```sql arrow_typeof(expression) diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md index a3833aab0e..14449259c7 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md @@ -22,11 +22,18 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [datepart](#datepart) - [extract](#extract) - [from_unixtime](#from_unixtime) +- [make_date](#make_date) - [now](#now) +- [today](#today) +- [to_char](#to_char) +- [to_date](#to_date) +- [to_local_time](#to_local_time) - [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) - [to_timestamp_micros](#to_timestamp_micros) +- [to_timestamp_millis](#to_timestamp_millis) +- [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) +- [to_unixtime](#to_unixtime) ## current_date @@ -34,7 +41,7 @@ Returns the current UTC date. {{% note %}} `current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-a-timestamp-type). +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-serverless/query-data/sql/cast-types/). {{% /note %}} The `current_date()` return value is determined at query time and will return @@ -218,14 +225,10 @@ The following intervals are supported: - hours - days - weeks - - -The following intervals are not currently supported: - months - years - century - ##### Related functions [interpolate](/influxdb/cloud-serverless/reference/sql/functions/misc/#interpolate), @@ -465,7 +468,7 @@ date_part(part, expression) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **expression**: Time expression to operate on. Can be a constant, column, or function. @@ -531,7 +534,7 @@ extract(field FROM source) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **source**: Source time expression to operate on. Can be a constant, column, or function. @@ -569,6 +572,10 @@ from_unixtime(expression) - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +##### Related functions + +[to_unixtime](#to_unixtime) + {{< expand-wrapper >}} {{% expand "View `from_unixtime` query example" %}} @@ -584,6 +591,42 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} +## make_date + +Returns a date using the component parts (year, month, day). + +{{% note %}} +`make_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-serverless/query-data/sql/cast-types/). +{{% /note %}} + +```sql +make_date(year, month, day) +``` + +##### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators + +{{< expand-wrapper >}} +{{% expand "View `make_date` query example" %}} + +```sql +SELECT make_date(2024, 01, 01)::STRING AS date +``` + +| date | +| :--------- | +| 2023-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## now Returns the current UTC timestamp. @@ -610,6 +653,156 @@ WHERE {{% /expand %}} {{< /expand-wrapper >}} +## today + +_Alias of [current_date](#current_date)._ + +## to_char + +Returns the string representation of a date, time, timestamp, or duration based on +a [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). + +{{% note %}} +Unlike the PostgreSQL `TO_CHAR()` function, this function does not support +numeric formatting. +{{% /note %}} + +```sql +to_char(expression, format) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a date, time, timestamp or duration. +- **format**: [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + to use to convert the expression. + +{{< expand-wrapper >}} +{{% expand "View `to_char` query example" %}} + +```sql +SELECT + to_char('2024-01-01T12:22:01Z'::TIMESTAMP, '%a %e-%b-%Y %H:%M:%S') AS datestring +``` + +| datestring | +| :----------------------- | +| Mon 1-Jan-2024 12:22:01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_date + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings and numeric types as input. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Numeric values are interpreted as days since the +[Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). + +{{% note %}} +`to_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-serverless/query-data/sql/cast-types/). +{{% /note %}} + +```sql +to_date(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_date` query example" %}} + +```sql +SELECT + to_date('1-Jan-2024', '%e-%b-%Y')::STRING AS date +``` + +| date | +| :--------- | +| 2024-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_local_time + +Converts a timestamp with a timezone to a timestamp without a timezone +(no offset or timezone information). This function accounts for time shifts +like Daylight Saving Time (DST) or British Summer Time (BST). + +{{% note %}} +Use `to_local_time()` with [`date_bin()`](#date_bin) and +[`date_bin_gapfill`](#date_bin_gapfill) to generate window boundaries based the +local time zone rather than UTC. +{{% /note %}} + +```sql +to_local_time(expression) +``` + +##### Arguments + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `to_local_time` query example" %}} + +```sql +SELECT + to_local_time('2024-01-01 00:00:00'::TIMESTAMP) AS "local time"; +``` + +| local time | +| :------------------- | +| 2024-01-01T00:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with a time zone offset" %}} + +```sql +SELECT + to_local_time((arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))')) AT TIME ZONE 'America/Los_Angeles') AS "local time" +``` + +| local time | +| :------------------- | +| 2023-12-31T16:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with `date_bin`" %}} + +```sql +SELECT + date_bin(interval '1 day', time, to_local_time(0::TIMESTAMP)) AT TIME ZONE 'America/Los_Angeles' AS time, + avg(f1), + avg(f2) +FROM + (VALUES (arrow_cast('2024-01-01 12:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 1.23, 4.56), + (arrow_cast('2024-01-01 13:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 2.46, 8.1), + (arrow_cast('2024-01-01 14:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 4.81, 16.2) + ) AS data(time, f1, f2) +GROUP BY 1 +``` + +| time | avg(data.f1) | avg(data.f2) | +| :------------------------ | -----------------: | -----------: | +| 2023-12-31T16:00:00-08:00 | 2.8333333333333335 | 9.62 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## to_timestamp Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). @@ -641,96 +834,96 @@ SELECT to_timestamp(1704067200000000000) {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_millis +## to_timestamp_micros -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). +Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) +[Unix microsecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_millis(expression[, ..., format_n]) +to_timestamp_micros(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} +{{% expand "View `to_timestamp_micros` query example" %}} ```sql -SELECT to_timestamp_millis(1704067200001) AS time +SELECT to_timestamp_micros(1704067200000001) ``` -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - +| to_timestamp_micros(Int64(1704067200000001)) | +| :------------------------------------------- | +| 2024-01-01T00:00:00.000001Z | {{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} +{{% expand "View `to_timestamp_micros` example with string format parsing" %}} ```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond +SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond ``` -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | +| microsecond | +| :-------------------------- | +| 2024-01-01T01:01:59.123456Z | {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_micros +## to_timestamp_millis -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). +Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) +[Unix millisecond timestamps](/influxdb/cloud-serverless/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_micros(expression[, ..., format_n]) +to_timestamp_millis(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} +{{% expand "View `to_timestamp_millis` query example" %}} ```sql -SELECT to_timestamp_micros(1704067200000001) +SELECT to_timestamp_millis(1704067200001) AS time ``` -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | +Results +| to_timestamp_millis(Int64(1704067200001)) | +| :---------------------------------------- | +| 2024-01-01T00:00:00.001Z | + {{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} +{{% expand "View `to_timestamp_millis` example with string format parsing" %}} ```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond +SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond ``` -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | +| millisecond | +| :----------------------- | +| 2024-01-01T01:01:59.123Z | {{% /expand %}} {{< /expand-wrapper >}} @@ -751,7 +944,7 @@ to_timestamp_nanos(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -797,7 +990,7 @@ to_timestamp_seconds(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -827,3 +1020,55 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: {{% /expand %}} {{< /expand-wrapper >}} + +## to_unixtime + +Converts a value to seconds since the [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). +Supports strings, timestamps, and floats as input. +Strings are parsed as RFC3339nano timestamps if no +[Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +are provided. + +```sql +to_unixtime(expression[, ..., format_n]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +##### Related functions + +[from_unixtime](#from_unixtime) + +{{< expand-wrapper >}} +{{% expand "View `to_unixtime` query example" %}} + +```sql +SELECT to_unixtime('2024-01-01T01:01:59.123456789Z') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{% expand "View `to_unixtime` example with string format parsing" %}} + +```sql +SELECT + to_unixtime('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/other.md b/content/influxdb/cloud-serverless/reference/sql/operators/other.md index cd4521194e..1c9c7e6dd6 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/other.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/other.md @@ -44,20 +44,42 @@ SELECT 'Hello' || ' world' AS "Concatenated" ## AT TIME ZONE -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. +The `AT TIME ZONE` operator takes the timestamp in the left operand and returns +an equivalent timestamp with the updated time and offset of the time zone +specified in the right operand. +If no time zone is included in the input timestamp's +[Arrow data type](/influxdb/cloud-serverless/reference/sql/data-types/#sql-and-arrow-data-types), +the operator assumes the time is in the time zone specified. +Time zone offsets are provided by the operating system time zone database. -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} +```sql +SELECT time AT TIME ZONE 'America/Los_Angeles' FROM home +``` + +{{< expand-wrapper >}} +{{% expand "Convert a UTC timestamp to a specified timezone" %}} + +```sql +SELECT + arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))') + AT TIME ZONE 'America/Los_Angeles' AS 'Time with TZ offset' +``` + +| Time with TZ offset | +| :------------------------ | +| 2023-12-31T16:00:00-08:00 | + +{{% /expand %}} +{{% expand "Add a time zone offset to a timestamp without a specified timezone" %}} ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | +| Local time with TZ offset | +| :------------------------ | +| 2024-01-01T00:00:00-08:00 | + +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index bcd987f179..ed21550cbf 100644 --- a/content/influxdb/clustered/reference/sql/data-types.md +++ b/content/influxdb/clustered/reference/sql/data-types.md @@ -13,16 +13,26 @@ related: - /influxdb/clustered/query-data/sql/cast-types/ --- -InfluxDB Clustered uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL. +{{< product-name >}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) +implementation of SQL. Data types define the type of values that can be stored in table columns. In InfluxDB's SQL implementation, a **measurement** is structured as a table, and **tags**, **fields** and **timestamps** are exposed as columns. +## SQL and Arrow data types + +In SQL, each column, expression, and parameter has a data type. +A data type is an attribute that specifies the type of data that the object can hold. DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. -Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time. +All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). + +Both SQL and Arrow data types play an important role is how data is operated on +during query execution and returned in query results. {{% note %}} -When performing casting operations, cast to the **name** of the data type, not the actual data type. +When performing casting operations, cast to the SQL data type unless you use +[`arrow_cast()`](/influxdb/clustered/reference/sql/functions/misc/#arrow_cast) +to cast to a specific Arrow type. Names and identifiers in SQL are _case-insensitive_ by default. For example: ```sql @@ -47,12 +57,12 @@ SELECT ## String types -| Name | Data type | Description | -| :------ | :-------- | --------------------------------- | -| STRING | UTF8 | Character string, variable-length | -| CHAR | UTF8 | Character string, fixed-length | -| VARCHAR | UTF8 | Character string, variable-length | -| TEXT | UTF8 | Variable unlimited length | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | --------------------------------- | +| STRING | UTF8 | Character string, variable-length | +| CHAR | UTF8 | Character string, fixed-length | +| VARCHAR | UTF8 | Character string, variable-length | +| TEXT | UTF8 | Variable unlimited length | ##### Example string literals @@ -66,11 +76,11 @@ SELECT The following numeric types are supported: -| Name | Data type | Description | -| :-------------- | :-------- | :--------------------------- | -| BIGINT | INT64 | 64-bit signed integer | -| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | -| DOUBLE | FLOAT64 | 64-bit floating-point number | +| SQL data type | Arrow data type | Description | +| :-------------- | :-------------- | :--------------------------- | +| BIGINT | INT64 | 64-bit signed integer | +| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer | +| DOUBLE | FLOAT64 | 64-bit floating-point number | ### Integers @@ -122,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| Name | Data type | Description | -| :-------- | :-------- | :------------------------------------------------------------------- | -| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None | -| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) | +| SQL data type | Arrow data type | Description | +| :------------ | :----------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp @@ -180,9 +190,9 @@ INTERVAL '2 days 1 hour 31 minutes' Booleans store TRUE or FALSE values. -| Name | Data type | Description | -| :------ | :-------- | :------------------- | -| BOOLEAN | BOOLEAN | True or false values | +| SQL data type | Arrow data type | Description | +| :------------ | :-------------- | :------------------- | +| BOOLEAN | Boolean | True or false values | ##### Example boolean literals diff --git a/content/influxdb/clustered/reference/sql/functions/misc.md b/content/influxdb/clustered/reference/sql/functions/misc.md index 585e1ce7e5..5f77b78b60 100644 --- a/content/influxdb/clustered/reference/sql/functions/misc.md +++ b/content/influxdb/clustered/reference/sql/functions/misc.md @@ -32,7 +32,7 @@ arrow_cast(expression, datatype) - **expression**: Expression to cast. Can be a constant, column, or function, and any combination of arithmetic or string operators. -- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) +- **datatype**: [Arrow data type](/influxdb/clustered/reference/sql/data-types/#sql-and-arrow-data-types) to cast to. {{< expand-wrapper >}} @@ -60,7 +60,7 @@ LIMIT 1 ## arrow_typeof Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html) -of the the expression: +of the expression: ```sql arrow_typeof(expression) diff --git a/content/influxdb/clustered/reference/sql/functions/time-and-date.md b/content/influxdb/clustered/reference/sql/functions/time-and-date.md index 7257afa32d..17b04a70f9 100644 --- a/content/influxdb/clustered/reference/sql/functions/time-and-date.md +++ b/content/influxdb/clustered/reference/sql/functions/time-and-date.md @@ -22,11 +22,18 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [datepart](#datepart) - [extract](#extract) - [from_unixtime](#from_unixtime) +- [make_date](#make_date) - [now](#now) +- [today](#today) +- [to_char](#to_char) +- [to_date](#to_date) +- [to_local_time](#to_local_time) - [to_timestamp](#to_timestamp) -- [to_timestamp_millis](#to_timestamp_millis) - [to_timestamp_micros](#to_timestamp_micros) +- [to_timestamp_millis](#to_timestamp_millis) +- [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) +- [to_unixtime](#to_unixtime) ## current_date @@ -34,7 +41,7 @@ Returns the current UTC date. {{% note %}} `current_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. -To use with InfluxDB, [cast the return value to a timestamp](/influxdb/clustered/query-data/sql/cast-types/#cast-to-a-timestamp-type). +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/clustered/query-data/sql/cast-types/). {{% /note %}} The `current_date()` return value is determined at query time and will return @@ -461,7 +468,7 @@ date_part(part, expression) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **expression**: Time expression to operate on. Can be a constant, column, or function. @@ -527,7 +534,7 @@ extract(field FROM source) - microsecond - nanosecond - dow _(day of the week)_ - - doy _(day of the year)_ + - day _(day of the year)_ - **source**: Source time expression to operate on. Can be a constant, column, or function. @@ -565,6 +572,10 @@ from_unixtime(expression) - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +##### Related functions + +[to_unixtime](#to_unixtime) + {{< expand-wrapper >}} {{% expand "View `from_unixtime` query example" %}} @@ -580,6 +591,42 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} +## make_date + +Returns a date using the component parts (year, month, day). + +{{% note %}} +`make_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/clustered/query-data/sql/cast-types/). +{{% /note %}} + +```sql +make_date(year, month, day) +``` + +##### Arguments + +- **year**: Year to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **month**: Month to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators. +- **day**: Day to use when making the date. + Can be a constant, column or function, and any combination of arithmetic operators + +{{< expand-wrapper >}} +{{% expand "View `make_date` query example" %}} + +```sql +SELECT make_date(2024, 01, 01)::STRING AS date +``` + +| date | +| :--------- | +| 2023-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## now Returns the current UTC timestamp. @@ -606,6 +653,156 @@ WHERE {{% /expand %}} {{< /expand-wrapper >}} +## today + +_Alias of [current_date](#current_date)._ + +## to_char + +Returns the string representation of a date, time, timestamp, or duration based on +a [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). + +{{% note %}} +Unlike the PostgreSQL `TO_CHAR()` function, this function does not support +numeric formatting. +{{% /note %}} + +```sql +to_char(expression, format) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function that results in a date, time, timestamp or duration. +- **format**: [Rust Chrono format string](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + to use to convert the expression. + +{{< expand-wrapper >}} +{{% expand "View `to_char` query example" %}} + +```sql +SELECT + to_char('2024-01-01T12:22:01Z'::TIMESTAMP, '%a %e-%b-%Y %H:%M:%S') AS datestring +``` + +| datestring | +| :----------------------- | +| Mon 1-Jan-2024 12:22:01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_date + +Converts a value to a date (`YYYY-MM-DD`). +Supports strings and numeric types as input. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Numeric values are interpreted as days since the +[Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). + +{{% note %}} +`to_date` returns a `DATE32` Arrow type, which isn't supported by InfluxDB. +To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/clustered/query-data/sql/cast-types/). +{{% /note %}} + +```sql +to_date(expression[, ..., format_n]) +``` + +###### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `to_date` query example" %}} + +```sql +SELECT + to_date('1-Jan-2024', '%e-%b-%Y')::STRING AS date +``` + +| date | +| :--------- | +| 2024-01-01 | + +{{% /expand %}} +{{< /expand-wrapper >}} + +## to_local_time + +Converts a timestamp with a timezone to a timestamp without a timezone +(no offset or timezone information). This function accounts for time shifts +like Daylight Saving Time (DST) or British Summer Time (BST). + +{{% note %}} +Use `to_local_time()` with [`date_bin()`](#date_bin) and +[`date_bin_gapfill`](#date_bin_gapfill) to generate window boundaries based the +local time zone rather than UTC. +{{% /note %}} + +```sql +to_local_time(expression) +``` + +##### Arguments + +- **expression**: Time expression to operate on. + Can be a constant, column, or function. + +{{< expand-wrapper >}} +{{% expand "View `to_local_time` query example" %}} + +```sql +SELECT + to_local_time('2024-01-01 00:00:00'::TIMESTAMP) AS "local time"; +``` + +| local time | +| :------------------- | +| 2024-01-01T00:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with a time zone offset" %}} + +```sql +SELECT + to_local_time((arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))')) AT TIME ZONE 'America/Los_Angeles') AS "local time" +``` + +| local time | +| :------------------- | +| 2023-12-31T16:00:00Z | + +{{% /expand %}} +{{% expand "View `to_local_time` query example with `date_bin`" %}} + +```sql +SELECT + date_bin(interval '1 day', time, to_local_time(0::TIMESTAMP)) AT TIME ZONE 'America/Los_Angeles' AS time, + avg(f1), + avg(f2) +FROM + (VALUES (arrow_cast('2024-01-01 12:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 1.23, 4.56), + (arrow_cast('2024-01-01 13:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 2.46, 8.1), + (arrow_cast('2024-01-01 14:00:00', 'Timestamp(Nanosecond, Some("UTC"))'), 4.81, 16.2) + ) AS data(time, f1, f2) +GROUP BY 1 +``` + +| time | avg(data.f1) | avg(data.f2) | +| :------------------------ | -----------------: | -----------: | +| 2023-12-31T16:00:00-08:00 | 2.8333333333333335 | 9.62 | + +{{% /expand %}} +{{< /expand-wrapper >}} + ## to_timestamp Converts a value to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00Z`). @@ -637,96 +834,96 @@ SELECT to_timestamp(1704067200000000000) {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_millis +## to_timestamp_micros -Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). +Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix millisecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) +[Unix microsecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_millis(expression[, ..., format_n]) +to_timestamp_micros(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_millis` query example" %}} +{{% expand "View `to_timestamp_micros` query example" %}} ```sql -SELECT to_timestamp_millis(1704067200001) AS time +SELECT to_timestamp_micros(1704067200000001) ``` -Results -| to_timestamp_millis(Int64(1704067200001)) | -| :---------------------------------------- | -| 2024-01-01T00:00:00.001Z | - +| to_timestamp_micros(Int64(1704067200000001)) | +| :------------------------------------------- | +| 2024-01-01T00:00:00.000001Z | {{% /expand %}} -{{% expand "View `to_timestamp_millis` example with string format parsing" %}} +{{% expand "View `to_timestamp_micros` example with string format parsing" %}} ```sql -SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond +SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond ``` -| millisecond | -| :----------------------- | -| 2024-01-01T01:01:59.123Z | +| microsecond | +| :-------------------------- | +| 2024-01-01T01:01:59.123456Z | {{% /expand %}} {{< /expand-wrapper >}} -## to_timestamp_micros +## to_timestamp_millis -Converts a value to RFC3339 microsecond timestamp format (`YYYY-MM-DDT00:00:00.000000Z`). +Converts a value to RFC3339 millisecond timestamp format (`YYYY-MM-DDT00:00:00.000Z`). Supports timestamp, integer, and unsigned integer types as input. Integers and unsigned integers are parsed as -[Unix microsecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) +[Unix millisecond timestamps](/influxdb/clustered/reference/glossary/#unix-timestamp) and return the corresponding RFC3339 timestamp. ```sql -to_timestamp_micros(expression[, ..., format_n]) +to_timestamp_millis(expression[, ..., format_n]) ``` ##### Arguments: - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. If no formats parse successfully, the function returns an error. {{< expand-wrapper >}} -{{% expand "View `to_timestamp_micros` query example" %}} +{{% expand "View `to_timestamp_millis` query example" %}} ```sql -SELECT to_timestamp_micros(1704067200000001) +SELECT to_timestamp_millis(1704067200001) AS time ``` -| to_timestamp_micros(Int64(1704067200000001)) | -| :------------------------------------------- | -| 2024-01-01T00:00:00.000001Z | +Results +| to_timestamp_millis(Int64(1704067200001)) | +| :---------------------------------------- | +| 2024-01-01T00:00:00.001Z | + {{% /expand %}} -{{% expand "View `to_timestamp_micros` example with string format parsing" %}} +{{% expand "View `to_timestamp_millis` example with string format parsing" %}} ```sql -SELECT to_timestamp_micros('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS microsecond +SELECT to_timestamp_millis('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS millisecond ``` -| microsecond | -| :-------------------------- | -| 2024-01-01T01:01:59.123456Z | +| millisecond | +| :----------------------- | +| 2024-01-01T01:01:59.123Z | {{% /expand %}} {{< /expand-wrapper >}} @@ -747,7 +944,7 @@ to_timestamp_nanos(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -793,7 +990,7 @@ to_timestamp_seconds(expression[, ..., format_n]) - **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **format_n**: [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) pattern to use to parse the _string_ expression. Formats are attempted in the order that they appear. The function returns the timestamp from the first format to parse successfully. @@ -823,3 +1020,55 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: {{% /expand %}} {{< /expand-wrapper >}} + +## to_unixtime + +Converts a value to seconds since the [Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). +Supports strings, timestamps, and floats as input. +Strings are parsed as RFC3339nano timestamps if no +[Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) +are provided. + +```sql +to_unixtime(expression[, ..., format_n]) +``` + +##### Arguments + +- **expression**: Expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **format_n**: Optional [Rust strftime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) + pattern to use to parse the _string_ expression. + Formats are attempted in the order that they appear. + The function returns the timestamp from the first format to parse successfully. + If no formats parse successfully, the function returns an error. + +##### Related functions + +[from_unixtime](#from_unixtime) + +{{< expand-wrapper >}} +{{% expand "View `to_unixtime` query example" %}} + +```sql +SELECT to_unixtime('2024-01-01T01:01:59.123456789Z') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{% expand "View `to_unixtime` example with string format parsing" %}} + +```sql +SELECT + to_unixtime('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y') AS unixtime +``` + +| unixtime | +| :--------- | +| 1704070919 | + +{{% /expand %}} +{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/sql/operators/other.md b/content/influxdb/clustered/reference/sql/operators/other.md index 837f67cf1a..bd49e040e5 100644 --- a/content/influxdb/clustered/reference/sql/operators/other.md +++ b/content/influxdb/clustered/reference/sql/operators/other.md @@ -44,20 +44,42 @@ SELECT 'Hello' || ' world' AS "Concatenated" ## AT TIME ZONE -The `AT TIME ZONE` operator applies the offset of the specified time zone to a -timestamp type and returns an updated UTC timestamp. Time zone offsets are -provided by the the operating system time zone database. +The `AT TIME ZONE` operator takes the timestamp in the left operand and returns +an equivalent timestamp with the updated time and offset of the time zone +specified in the right operand. +If no time zone is included in the input timestamp's +[Arrow data type](/influxdb/clustered/reference/sql/data-types/#sql-and-arrow-data-types), +the operator assumes the time is in the time zone specified. +Time zone offsets are provided by the operating system time zone database. -{{% note %}} -Timestamp types in InfluxDB always represent a UTC time. The returned timestamp -is a UTC timestamp adjusted for the offset of the specified time zone. -{{% /note %}} +```sql +SELECT time AT TIME ZONE 'America/Los_Angeles' FROM home +``` + +{{< expand-wrapper >}} +{{% expand "Convert a UTC timestamp to a specified timezone" %}} + +```sql +SELECT + arrow_cast('2024-01-01 00:00:00', 'Timestamp(Nanosecond, Some("UTC"))') + AT TIME ZONE 'America/Los_Angeles' AS 'Time with TZ offset' +``` + +| Time with TZ offset | +| :------------------------ | +| 2023-12-31T16:00:00-08:00 | + +{{% /expand %}} +{{% expand "Add a time zone offset to a timestamp without a specified timezone" %}} ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'UTC with TZ offset' + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` -| UTC with TZ offset | -| :----------------------- | -| 2024-01-01T08:00:00.000Z | +| Local time with TZ offset | +| :------------------------ | +| 2024-01-01T00:00:00-08:00 | + +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file From 5d35018dc9637e97732ca6897e8cbc8bf8b09fa9 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 28 Aug 2024 15:27:18 -0600 Subject: [PATCH 2/6] updated deps --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index a9f404cd12..d69914fd1c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1050,9 +1050,9 @@ merge2@^1.3.0: integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg== micromatch@^4.0.4: - version "4.0.7" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.7.tgz#33e8190d9fe474a9895525f5618eee136d46c2e5" - integrity sha512-LPP/3KorzCwBxfeUuZmaR6bG2kdeHSbe0P2tY3FLRU4vYrjYz5hI4QZwV0njUx3jeuKe67YukQ1LSPZBKDqO/Q== + version "4.0.8" + resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202" + integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA== dependencies: braces "^3.0.3" picomatch "^2.3.1" From 72ff845310db484ddc45dcec0fb58f4e5fed61d3 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 29 Aug 2024 09:27:50 -0600 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Jason Stirnaman --- .../influxdb/cloud-dedicated/reference/sql/data-types.md | 2 +- .../reference/sql/functions/time-and-date.md | 6 +++--- .../reference/sql/functions/time-and-date.md | 4 ++-- content/influxdb/clustered/reference/sql/data-types.md | 2 +- .../clustered/reference/sql/functions/time-and-date.md | 4 ++-- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/sql/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index 7050893795..4d0a8eeafb 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/data-types.md +++ b/content/influxdb/cloud-dedicated/reference/sql/data-types.md @@ -26,7 +26,7 @@ A data type is an attribute that specifies the type of data that the object can DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). -Both SQL and Arrow data types play an important role is how data is operated on +Both SQL and Arrow data types play an important role in how data is operated on during query execution and returned in query results. {{% note %}} diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md index 8140925c7b..c8331f509b 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md @@ -44,7 +44,7 @@ Returns the current UTC date. To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-dedicated/query-data/sql/cast-types/). {{% /note %}} -The `current_date()` return value is determined at query time and will return +The `current_date()` return value is determined at query time and returns the same date, no matter when in the query plan the function executes. ``` @@ -127,7 +127,7 @@ Calculates time intervals and returns the start of the interval nearest to the s Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" and applying an aggregate or selector function to each window. -For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`. +For example, if you "bin" or "window" data into 15-minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15-minute bin it is in: `2023-01-01T18:15:00Z`. ```sql date_bin(interval, expression[, origin_timestamp]) @@ -1025,7 +1025,7 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: Converts a value to seconds since the [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). Supports strings, timestamps, and floats as input. -Strings are parsed as RFC3339nano timestamps if no +Strings are parsed as [RFC3339Nano timestamps](/influxdb/cloud-dedicated/reference/glossary/#rfc3339nano-timestamp) if no [Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided. diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md index 14449259c7..79624fad62 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md @@ -44,7 +44,7 @@ Returns the current UTC date. To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/cloud-serverless/query-data/sql/cast-types/). {{% /note %}} -The `current_date()` return value is determined at query time and will return +The `current_date()` return value is determined at query time and returns the same date, no matter when in the query plan the function executes. ``` @@ -1025,7 +1025,7 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: Converts a value to seconds since the [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). Supports strings, timestamps, and floats as input. -Strings are parsed as RFC3339nano timestamps if no +Strings are parsed as [RFC3339Nano timestamps](/influxdb/cloud-serverless/reference/glossary/#rfc3339nano-timestamp) if no [Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided. diff --git a/content/influxdb/clustered/reference/sql/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index ed21550cbf..451ddf43a5 100644 --- a/content/influxdb/clustered/reference/sql/data-types.md +++ b/content/influxdb/clustered/reference/sql/data-types.md @@ -26,7 +26,7 @@ A data type is an attribute that specifies the type of data that the object can DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). -Both SQL and Arrow data types play an important role is how data is operated on +Both SQL and Arrow data types play an important role in how data is operated on during query execution and returned in query results. {{% note %}} diff --git a/content/influxdb/clustered/reference/sql/functions/time-and-date.md b/content/influxdb/clustered/reference/sql/functions/time-and-date.md index 17b04a70f9..03c3287834 100644 --- a/content/influxdb/clustered/reference/sql/functions/time-and-date.md +++ b/content/influxdb/clustered/reference/sql/functions/time-and-date.md @@ -44,7 +44,7 @@ Returns the current UTC date. To use with InfluxDB, [cast the return value to a timestamp or string](/influxdb/clustered/query-data/sql/cast-types/). {{% /note %}} -The `current_date()` return value is determined at query time and will return +The `current_date()` return value is determined at query time and returns the same date, no matter when in the query plan the function executes. ``` @@ -1025,7 +1025,7 @@ SELECT to_timestamp_seconds('01:01:59.123456789 01-01-2024', '%c', '%+', '%H:%M: Converts a value to seconds since the [Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). Supports strings, timestamps, and floats as input. -Strings are parsed as RFC3339nano timestamps if no +Strings are parsed as [RFC3339Nano timestamps](/influxdb/clustered/reference/glossary/#rfc3339nano-timestamp) if no [Rust Chrono format strings](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided. From 3b6bc8b53d546149f589c1eaf1387152ddec231e Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 29 Aug 2024 13:13:12 -0600 Subject: [PATCH 4/6] updates to address PR feedback --- .../cloud-dedicated/reference/sql/data-types.md | 8 ++++---- .../reference/sql/functions/time-and-date.md | 6 +++--- .../cloud-serverless/reference/sql/data-types.md | 10 +++++----- .../reference/sql/functions/time-and-date.md | 6 +++--- content/influxdb/clustered/reference/sql/data-types.md | 8 ++++---- .../clustered/reference/sql/functions/time-and-date.md | 6 +++--- 6 files changed, 22 insertions(+), 22 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/sql/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index 4d0a8eeafb..df30af42e2 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/data-types.md +++ b/content/influxdb/cloud-dedicated/reference/sql/data-types.md @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :----------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md index c8331f509b..b89a471025 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md @@ -90,7 +90,7 @@ Returns the current UTC time. To use with InfluxDB, [cast the return value to a string](/influxdb/cloud-dedicated/query-data/sql/cast-types/#cast-to-a-string-type). {{% /note %}} -The `current_time()` return value is determined at query time and will return the same time, +The `current_time()` return value is determined at query time and returns the same time, no matter when in the query plan the function executes. ``` @@ -631,7 +631,7 @@ SELECT make_date(2024, 01, 01)::STRING AS date Returns the current UTC timestamp. -The `now()` return value is determined at query time and will return the same timestamp, +The `now()` return value is determined at query time and returns the same timestamp, no matter when in the query plan the function executes. ```sql @@ -697,7 +697,7 @@ SELECT Converts a value to a date (`YYYY-MM-DD`). Supports strings and numeric types as input. -Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. Numeric values are interpreted as days since the [Unix epoch](/influxdb/cloud-dedicated/reference/glossary/#unix-epoch). diff --git a/content/influxdb/cloud-serverless/reference/sql/data-types.md b/content/influxdb/cloud-serverless/reference/sql/data-types.md index cff4c51984..e922552a51 100644 --- a/content/influxdb/cloud-serverless/reference/sql/data-types.md +++ b/content/influxdb/cloud-serverless/reference/sql/data-types.md @@ -26,7 +26,7 @@ A data type is an attribute that specifies the type of data that the object can DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution. All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html). -Both SQL and Arrow data types play an important role is how data is operated on +Both SQL and Arrow data types play an important role in how data is operated on during query execution and returned in query results. {{% note %}} @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :----------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md index 79624fad62..8d515babe4 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md @@ -90,7 +90,7 @@ Returns the current UTC time. To use with InfluxDB, [cast the return value to a string](/influxdb/cloud-serverless/query-data/sql/cast-types/#cast-to-a-string-type). {{% /note %}} -The `current_time()` return value is determined at query time and will return the same time, +The `current_time()` return value is determined at query time and returns the same time, no matter when in the query plan the function executes. ``` @@ -631,7 +631,7 @@ SELECT make_date(2024, 01, 01)::STRING AS date Returns the current UTC timestamp. -The `now()` return value is determined at query time and will return the same timestamp, +The `now()` return value is determined at query time and returns the same timestamp, no matter when in the query plan the function executes. ```sql @@ -697,7 +697,7 @@ SELECT Converts a value to a date (`YYYY-MM-DD`). Supports strings and numeric types as input. -Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. Numeric values are interpreted as days since the [Unix epoch](/influxdb/cloud-serverless/reference/glossary/#unix-epoch). diff --git a/content/influxdb/clustered/reference/sql/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index 451ddf43a5..368808c9dc 100644 --- a/content/influxdb/clustered/reference/sql/data-types.md +++ b/content/influxdb/clustered/reference/sql/data-types.md @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :----------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/clustered/reference/sql/functions/time-and-date.md b/content/influxdb/clustered/reference/sql/functions/time-and-date.md index 03c3287834..e52c45a2bf 100644 --- a/content/influxdb/clustered/reference/sql/functions/time-and-date.md +++ b/content/influxdb/clustered/reference/sql/functions/time-and-date.md @@ -90,7 +90,7 @@ Returns the current UTC time. To use with InfluxDB, [cast the return value to a string](/influxdb/clustered/query-data/sql/cast-types/#cast-to-a-string-type). {{% /note %}} -The `current_time()` return value is determined at query time and will return the same time, +The `current_time()` return value is determined at query time and returns the same time, no matter when in the query plan the function executes. ``` @@ -631,7 +631,7 @@ SELECT make_date(2024, 01, 01)::STRING AS date Returns the current UTC timestamp. -The `now()` return value is determined at query time and will return the same timestamp, +The `now()` return value is determined at query time and returns the same timestamp, no matter when in the query plan the function executes. ```sql @@ -697,7 +697,7 @@ SELECT Converts a value to a date (`YYYY-MM-DD`). Supports strings and numeric types as input. -Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided. +Strings are parsed as `YYYY-MM-DD` unless another format is specified. Numeric values are interpreted as days since the [Unix epoch](/influxdb/clustered/reference/glossary/#unix-epoch). From 5897358d1ffb4cc643bd32160c7d7da65ba374ff Mon Sep 17 00:00:00 2001 From: Jeffrey Smith II Date: Thu, 12 Sep 2024 19:01:40 -0400 Subject: [PATCH 5/6] chore: remove unnecessary ::timestamp casts (#5596) --- .../influxdb/cloud-dedicated/get-started/query.md | 2 +- .../query-data/sql/aggregate-select.md | 12 ++++++------ .../client-libraries/flight/python-flight.md | 2 +- .../influxdb/cloud-dedicated/reference/sql/_index.md | 2 +- .../influxdb/cloud-dedicated/reference/sql/where.md | 2 +- .../influxdb/cloud-serverless/get-started/query.md | 2 +- .../query-data/sql/aggregate-select.md | 12 ++++++------ .../client-libraries/flight/python-flight.md | 4 ++-- .../cloud-serverless/reference/sql/_index.md | 2 +- .../influxdb/cloud-serverless/reference/sql/where.md | 2 +- .../client-libraries/flight/python-flight.md | 2 +- content/influxdb/clustered/reference/sql/_index.md | 2 +- content/influxdb/clustered/reference/sql/where.md | 2 +- 13 files changed, 24 insertions(+), 24 deletions(-) diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index 4b1ee4f91e..3775b1e693 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -162,7 +162,7 @@ WHERE {{% influxdb/custom-timestamps %}} ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time, room, selector_max(temp, time)['value'] AS 'max temp' FROM 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 9ce83c0633..3dde196546 100644 --- a/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md @@ -28,7 +28,7 @@ list_code_example: | ##### Aggregate by time-based intervals ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') AS time, mean(field1), sum(field2), tag1 @@ -206,7 +206,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time FROM home ... ``` @@ -225,7 +225,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time ... GROUP BY 1, room ... @@ -235,7 +235,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time FROM home ... GROUP BY _time, room @@ -247,7 +247,7 @@ The following example retrieves unique combinations of time intervals and rooms ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -288,7 +288,7 @@ If you want to reference a calculated time column by name, use an alias differen ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time, room, selector_max(temp, time)['value'] AS 'max temp', diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md index 23a0823c85..5b7b1bf6f3 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/cloud-dedicated/reference/sql/_index.md b/content/influxdb/cloud-dedicated/reference/sql/_index.md index 2a1389883e..da03de174d 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/sql/_index.md @@ -634,7 +634,7 @@ WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19 #### Examples ```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", +SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time", SUM(water_level) FROM "h2o_feet" GROUP BY "_time" diff --git a/content/influxdb/cloud-dedicated/reference/sql/where.md b/content/influxdb/cloud-dedicated/reference/sql/where.md index d0801b86cb..6d1585f796 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/where.md +++ b/content/influxdb/cloud-dedicated/reference/sql/where.md @@ -89,7 +89,7 @@ and a `level description` field value that equals `below 3 feet`. SELECT * FROM h2o_feet WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp +AND "time" >= '2019-08-19T12:00:00Z' AND "time" <= '2019-08-19T13:00:00Z' ``` {{< expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 823cd453a3..c600d22518 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -160,7 +160,7 @@ WHERE {{% influxdb/custom-timestamps %}} ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time, room, selector_max(temp, time)['value'] AS 'max temp' FROM 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 f63fd487fc..30aae448f7 100644 --- a/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md +++ b/content/influxdb/cloud-serverless/query-data/sql/aggregate-select.md @@ -28,7 +28,7 @@ list_code_example: | ##### Aggregate by time-based intervals ```sql SELECT - DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') AS time, mean(field1), sum(field2), tag1 @@ -206,7 +206,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time FROM home ... ``` @@ -224,7 +224,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time ... GROUP BY 1, room ... @@ -234,7 +234,7 @@ groups: ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time FROM home ... GROUP BY _time, room @@ -246,7 +246,7 @@ The following example retrieves unique combinations of time intervals and rooms ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -287,7 +287,7 @@ If you want to reference a calculated time column by name, use an alias differen ```sql SELECT - DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) + DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time, room, selector_max(temp, time)['value'] AS 'max temp', diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md b/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md index ac2ffbc89c..ca89ed1041 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', @@ -80,7 +80,7 @@ import tabulate sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/cloud-serverless/reference/sql/_index.md b/content/influxdb/cloud-serverless/reference/sql/_index.md index 790c0e0050..ff62551199 100644 --- a/content/influxdb/cloud-serverless/reference/sql/_index.md +++ b/content/influxdb/cloud-serverless/reference/sql/_index.md @@ -634,7 +634,7 @@ WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19 #### Examples ```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", +SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time", SUM(water_level) FROM "h2o_feet" GROUP BY "_time" diff --git a/content/influxdb/cloud-serverless/reference/sql/where.md b/content/influxdb/cloud-serverless/reference/sql/where.md index 0b5035baa9..3af8ebc156 100644 --- a/content/influxdb/cloud-serverless/reference/sql/where.md +++ b/content/influxdb/cloud-serverless/reference/sql/where.md @@ -88,7 +88,7 @@ and a `level description` field value that equals `below 3 feet`. SELECT * FROM h2o_feet WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp +AND "time" >= '2019-08-19T12:00:00Z' AND "time" <= '2019-08-19T13:00:00Z' ``` {{< expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md b/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md index 3b8de45613..d2f2640abc 100644 --- a/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md +++ b/content/influxdb/clustered/reference/client-libraries/flight/python-flight.md @@ -21,7 +21,7 @@ list_code_example: | sql=""" SELECT DATE_BIN(INTERVAL '2 hours', time, - '1970-01-01T00:00:00Z'::TIMESTAMP) AS time, + '1970-01-01T00:00:00Z') AS time, room, selector_max(temp, time)['value'] AS 'max temp', selector_min(temp, time)['value'] AS 'min temp', diff --git a/content/influxdb/clustered/reference/sql/_index.md b/content/influxdb/clustered/reference/sql/_index.md index 713a95ac67..0ffac5cb4f 100644 --- a/content/influxdb/clustered/reference/sql/_index.md +++ b/content/influxdb/clustered/reference/sql/_index.md @@ -637,7 +637,7 @@ WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19 #### Examples ```sql -SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time", +SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time", SUM(water_level) FROM "h2o_feet" GROUP BY "_time" diff --git a/content/influxdb/clustered/reference/sql/where.md b/content/influxdb/clustered/reference/sql/where.md index 403e27c484..e811c0aee6 100644 --- a/content/influxdb/clustered/reference/sql/where.md +++ b/content/influxdb/clustered/reference/sql/where.md @@ -89,7 +89,7 @@ and a `level description` field value that equals `below 3 feet`. SELECT * FROM h2o_feet WHERE "location" = 'santa_monica' -AND "time" >= '2019-08-19T12:00:00Z'::timestamp AND "time" <= '2019-08-19T13:00:00Z'::timestamp +AND "time" >= '2019-08-19T12:00:00Z' AND "time" <= '2019-08-19T13:00:00Z' ``` {{< expand-wrapper >}} From 4ef4aa5927f7bb711784bd11e3c98dce33b458a1 Mon Sep 17 00:00:00 2001 From: Jeffrey Smith II Date: Wed, 23 Oct 2024 13:18:21 -0400 Subject: [PATCH 6/6] feat: Update for latest SQL timezone behavior (#5657) * feat: Update for latest SQL timezone behavior * fix: cleanup and improve wording Co-authored-by: Scott Anderson --------- Co-authored-by: Scott Anderson --- .../reference/sql/data-types.md | 8 +- .../reference/sql/functions/time-and-date.md | 92 +++++++++++++++++++ .../reference/sql/operators/other.md | 4 +- .../reference/sql/data-types.md | 8 +- .../reference/sql/functions/time-and-date.md | 92 +++++++++++++++++++ .../reference/sql/operators/other.md | 4 +- .../clustered/reference/sql/data-types.md | 8 +- .../reference/sql/functions/time-and-date.md | 92 +++++++++++++++++++ .../reference/sql/operators/other.md | 2 +- 9 files changed, 293 insertions(+), 17 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/sql/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index df30af42e2..1bf904bce5 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/data-types.md +++ b/content/influxdb/cloud-dedicated/reference/sql/data-types.md @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :--------------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :-------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md index b89a471025..0df3a88ebd 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md @@ -34,6 +34,7 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) - [to_unixtime](#to_unixtime) +- [tz](#tz) ## current_date @@ -1072,3 +1073,94 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} + + +## tz + +Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC. + +```sql +tz(time_expression[, timezone]) +``` + +##### Arguments + +- **time_expression**: time to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) + to cast the value into. Default is `'UTC'`. + The function returns the timestamp cast to the specified timezone. + If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `tz` query example" %}} + +```sql +SELECT tz('2024-01-01T01:00:00Z', 'America/New_York') AS time_tz +``` + +| time_tz | +| :----------------------- | +| 2024-10-01T02:00:00-04:00| + +{{% /expand %}} +{{% expand "View `tz` query example from Getting Started data" %}} + +```sql +SELECT tz(time, 'Australia/Sydney') AS time_tz, time FROM home ORDER BY time LIMIT 3; +``` + +| time_tz | time | +| :---------------------------------- | ------------------------------ | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728982800+10:00 | 1970-01-01T00:00:01.728982800Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +##### Differences between tz and AT TIME ZONE +`tz` and [`AT TIME ZONE`](/influxdb/cloud-dedicated/reference/sql/operators/other/#at-time-zone) +differ when the input timestamp **does not** have a timezone. +- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the + `AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset + (also known as the "wall clock" time)--for example: + ```sql + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' + + -- Returns + 2024-01-01T00:00:00-08:00 + ``` +- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE` + operator return the timestamp converted to the time in the specified timezone--for example: + ```sql + '2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles' + tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles') + + -- Both return + 2023-12-31T16:00:00-08:00 + ``` +- `tz()` always converts the input timestamp to the specified time zone. + If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example: + ```sql + tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles') + -- Returns + 2023-12-31T16:00:00-08:00 + ``` + ```sql + tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles') + -- Returns + 2023-12-31T15:00:00-08:00 + ``` +{{< expand-wrapper >}} +{{% expand "View `tz` and `::timestamp` comparison" %}} +```sql +SELECT + '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp, + tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz; +``` +| time_timestamp | time_tz | +| :--------------------------- | :------------------------- | +| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 | +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md index d3b8a10639..e5e99ba2c5 100644 --- a/content/influxdb/cloud-dedicated/reference/sql/operators/other.md +++ b/content/influxdb/cloud-dedicated/reference/sql/operators/other.md @@ -75,7 +75,7 @@ SELECT ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' + '2024-01-01 00:00:00' AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` | Local time with TZ offset | @@ -83,4 +83,4 @@ SELECT | 2024-01-01T00:00:00-08:00 | {{% /expand %}} -{{< /expand-wrapper >}} \ No newline at end of file +{{< /expand-wrapper >}} diff --git a/content/influxdb/cloud-serverless/reference/sql/data-types.md b/content/influxdb/cloud-serverless/reference/sql/data-types.md index e922552a51..f2936ce620 100644 --- a/content/influxdb/cloud-serverless/reference/sql/data-types.md +++ b/content/influxdb/cloud-serverless/reference/sql/data-types.md @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :--------------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :-------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md index 4e4f7ab62b..a61bc78ddd 100644 --- a/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md +++ b/content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md @@ -34,6 +34,7 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) - [to_unixtime](#to_unixtime) +- [tz](#tz) ## current_date @@ -1072,3 +1073,94 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} + + +## tz + +Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC. + +```sql +tz(time_expression[, timezone]) +``` + +##### Arguments + +- **time_expression**: time to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) + to cast the value into. Default is `'UTC'`. + The function returns the timestamp cast to the specified timezone. + If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `tz` query example" %}} + +```sql +SELECT tz('2024-01-01T01:00:00Z', 'America/New_York') AS time_tz +``` + +| time_tz | +| :----------------------- | +| 2024-10-01T02:00:00-04:00| + +{{% /expand %}} +{{% expand "View `tz` query example from Getting Started data" %}} + +```sql +SELECT tz(time, 'Australia/Sydney') AS time_tz, time FROM home ORDER BY time LIMIT 3; +``` + +| time_tz | time | +| :---------------------------------- | ------------------------------ | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728982800+10:00 | 1970-01-01T00:00:01.728982800Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +##### Differences between tz and AT TIME ZONE +`tz` and [`AT TIME ZONE`](/influxdb/cloud-serverless/reference/sql/operators/other/#at-time-zone) +differ when the input timestamp **does not** have a timezone. +- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the + `AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset + (also known as the "wall clock" time)--for example: + ```sql + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' + + -- Returns + 2024-01-01T00:00:00-08:00 + ``` +- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE` + operator return the timestamp converted to the time in the specified timezone--for example: + ```sql + '2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles' + tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles') + + -- Both return + 2023-12-31T16:00:00-08:00 + ``` +- `tz()` always converts the input timestamp to the specified time zone. + If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example: + ```sql + tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles') + -- Returns + 2023-12-31T16:00:00-08:00 + ``` + ```sql + tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles') + -- Returns + 2023-12-31T15:00:00-08:00 + ``` +{{< expand-wrapper >}} +{{% expand "View `tz` and `::timestamp` comparison" %}} +```sql +SELECT + '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp, + tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz; +``` +| time_timestamp | time_tz | +| :--------------------------- | :------------------------- | +| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 | +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/sql/operators/other.md b/content/influxdb/cloud-serverless/reference/sql/operators/other.md index 1c9c7e6dd6..b0444f6e53 100644 --- a/content/influxdb/cloud-serverless/reference/sql/operators/other.md +++ b/content/influxdb/cloud-serverless/reference/sql/operators/other.md @@ -74,7 +74,7 @@ SELECT ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' + '2024-01-01 00:00:00' AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` | Local time with TZ offset | @@ -82,4 +82,4 @@ SELECT | 2024-01-01T00:00:00-08:00 | {{% /expand %}} -{{< /expand-wrapper >}} \ No newline at end of file +{{< /expand-wrapper >}} diff --git a/content/influxdb/clustered/reference/sql/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index 368808c9dc..5b924313de 100644 --- a/content/influxdb/clustered/reference/sql/data-types.md +++ b/content/influxdb/clustered/reference/sql/data-types.md @@ -132,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction. InfluxDB SQL supports the following DATE/TIME data types: -| SQL data type | Arrow data type | Description | -| :------------ | :--------------------------------- | :------------------------------------------- | -| TIMESTAMP | Timestamp(Nanosecond, Some("UTC")) | Nanosecond timestamp with a time zone offset | -| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | +| SQL data type | Arrow data type | Description | +| :------------ | :--------------------------------- | :-------------------------------------------- | +| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset | +| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration | ### Timestamp diff --git a/content/influxdb/clustered/reference/sql/functions/time-and-date.md b/content/influxdb/clustered/reference/sql/functions/time-and-date.md index e52c45a2bf..fdb363e812 100644 --- a/content/influxdb/clustered/reference/sql/functions/time-and-date.md +++ b/content/influxdb/clustered/reference/sql/functions/time-and-date.md @@ -34,6 +34,7 @@ InfluxDB's SQL implementation supports time and date functions that are useful w - [to_timestamp_nanos](#to_timestamp_nanos) - [to_timestamp_seconds](#to_timestamp_seconds) - [to_unixtime](#to_unixtime) +- [tz](#tz) ## current_date @@ -1072,3 +1073,94 @@ SELECT {{% /expand %}} {{< /expand-wrapper >}} + + +## tz + +Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC. + +```sql +tz(time_expression[, timezone]) +``` + +##### Arguments + +- **time_expression**: time to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) + to cast the value into. Default is `'UTC'`. + The function returns the timestamp cast to the specified timezone. + If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error. + +{{< expand-wrapper >}} +{{% expand "View `tz` query example" %}} + +```sql +SELECT tz('2024-01-01T01:00:00Z', 'America/New_York') AS time_tz +``` + +| time_tz | +| :----------------------- | +| 2024-10-01T02:00:00-04:00| + +{{% /expand %}} +{{% expand "View `tz` query example from Getting Started data" %}} + +```sql +SELECT tz(time, 'Australia/Sydney') AS time_tz, time FROM home ORDER BY time LIMIT 3; +``` + +| time_tz | time | +| :---------------------------------- | ------------------------------ | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728979200+10:00 | 1970-01-01T00:00:01.728979200Z | +| 1970-01-01T10:00:01.728982800+10:00 | 1970-01-01T00:00:01.728982800Z | + +{{% /expand %}} +{{< /expand-wrapper >}} + +##### Differences between tz and AT TIME ZONE +`tz` and [`AT TIME ZONE`](/influxdb/cloud-serverless/reference/sql/operators/other/#at-time-zone) +differ when the input timestamp **does not** have a timezone. +- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the + `AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset + (also known as the "wall clock" time)--for example: + ```sql + '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' + + -- Returns + 2024-01-01T00:00:00-08:00 + ``` +- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE` + operator return the timestamp converted to the time in the specified timezone--for example: + ```sql + '2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles' + tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles') + + -- Both return + 2023-12-31T16:00:00-08:00 + ``` +- `tz()` always converts the input timestamp to the specified time zone. + If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example: + ```sql + tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles') + -- Returns + 2023-12-31T16:00:00-08:00 + ``` + ```sql + tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles') + -- Returns + 2023-12-31T15:00:00-08:00 + ``` +{{< expand-wrapper >}} +{{% expand "View `tz` and `::timestamp` comparison" %}} +```sql +SELECT + '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp, + tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz; +``` +| time_timestamp | time_tz | +| :--------------------------- | :------------------------- | +| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 | +{{% /expand %}} +{{< /expand-wrapper >}} \ No newline at end of file diff --git a/content/influxdb/clustered/reference/sql/operators/other.md b/content/influxdb/clustered/reference/sql/operators/other.md index bd49e040e5..e7966a20e4 100644 --- a/content/influxdb/clustered/reference/sql/operators/other.md +++ b/content/influxdb/clustered/reference/sql/operators/other.md @@ -74,7 +74,7 @@ SELECT ```sql SELECT - '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' + '2024-01-01 00:00:00' AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset' ``` | Local time with TZ offset |