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 6c0a4fb860..1ebaf7d462 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|IOx) keep-url lat -locf +(locf|LOCF) logicalplan noaa|NOAA npm|NPM 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/data-types.md b/content/influxdb/cloud-dedicated/reference/sql/data-types.md index ea4763ffc9..1bf904bce5 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 in 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 no 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..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 @@ -22,12 +22,19 @@ 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) +- [tz](#tz) ## current_date @@ -35,10 +42,10 @@ 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 +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. ``` @@ -84,7 +91,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. ``` @@ -121,8 +128,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 +469,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 +535,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 +573,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,11 +592,47 @@ 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. -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 @@ -608,6 +654,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. +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 +835,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 +945,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 +991,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 +1021,146 @@ 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](/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. + +```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 >}} + + +## 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 5fe800ec41..e5e99ba2c5 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' 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 >}} 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/data-types.md b/content/influxdb/cloud-serverless/reference/sql/data-types.md index 54dcc94bc8..f2936ce620 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 in 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 no 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 e54fc78603..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 @@ -22,11 +22,19 @@ 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) +- [tz](#tz) ## current_date @@ -34,10 +42,10 @@ 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 +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. ``` @@ -83,7 +91,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. ``` @@ -218,14 +226,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 +469,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 +535,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 +573,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,11 +592,47 @@ 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. -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 @@ -610,6 +654,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. +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 +835,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 +945,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 +991,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 +1021,146 @@ 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](/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. + +```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 >}} + + +## 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 cd4521194e..b0444f6e53 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' 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 >}} 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/data-types.md b/content/influxdb/clustered/reference/sql/data-types.md index bcd987f179..5b924313de 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 in 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 no 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..fdb363e812 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,19 @@ 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) +- [tz](#tz) ## current_date @@ -34,10 +42,10 @@ 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 +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. ``` @@ -83,7 +91,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. ``` @@ -461,7 +469,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 +535,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 +573,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,11 +592,47 @@ 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. -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 @@ -606,6 +654,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. +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 +835,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 +945,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 +991,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 +1021,146 @@ 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](/influxdb/clustered/reference/glossary/#rfc3339nano-timestamp) 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 >}} + + +## 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 837f67cf1a..e7966a20e4 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' 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/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 >}}