Add timezone support to v3 SQL docs (#5581)

* updated timezone-related functions and operators * updated deps * Apply suggestions from code review Co-authored-by: Jason Stirnaman <[email protected]> * updates to address PR feedback * chore: remove unnecessary ::timestamp casts (#5596) * feat: Update for latest SQL timezone behavior (#5657) * feat: Update for latest SQL timezone behavior * fix: cleanup and improve wording Co-authored-by: Scott Anderson <[email protected]> --------- Co-authored-by: Scott Anderson <[email protected]> --------- Co-authored-by: Jason Stirnaman <[email protected]> Co-authored-by: Jeffrey Smith II <[email protected]>
influxdata · Oct 30, 2024 · 4045a6c · 4045a6c
1 parent 91482e6
commit 4045a6c
Show file tree

Hide file tree

Showing 27 changed files with 1,370 additions and 257 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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/...ent/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md b/...ent/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
@@ -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
@@ -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
@@ -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)
-Original file line number
+Diff line change
@@ Expand Up / @@ -128,6 +128,7 @@ left @@
     level
     like
     local
+    locf
     lower
     match
     max
@@ Expand Down @@