Skip to content

Commit 4045a6c

Browse files
sandersonjstirnamanjeffreyssmith2nd
authored
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 <jstirnaman@influxdata.com> * 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 <scott@influxdata.com> --------- Co-authored-by: Scott Anderson <scott@influxdata.com> --------- Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com> Co-authored-by: Jeffrey Smith II <jsmith@influxdata.com>
1 parent 91482e6 commit 4045a6c

File tree

27 files changed

+1370
-257
lines changed

27 files changed

+1370
-257
lines changed

‎.ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,7 @@ left
128128
level
129129
like
130130
local
131+
locf
131132
lower
132133
match
133134
max

‎.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ influxdata.com
7171
(iox|IOx)
7272
keep-url
7373
lat
74-
locf
74+
(locf|LOCF)
7575
logicalplan
7676
noaa|NOAA
7777
npm|NPM

‎content/influxdb/cloud-dedicated/get-started/query.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ WHERE
162162
{{% influxdb/custom-timestamps %}}
163163
```sql
164164
SELECT
165-
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time,
165+
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time,
166166
room,
167167
selector_max(temp, time)['value'] AS 'max temp'
168168
FROM

‎content/influxdb/cloud-dedicated/query-data/sql/aggregate-select.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ list_code_example: |
2828
##### Aggregate by time-based intervals
2929
```sql
3030
SELECT
31-
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) AS time,
31+
DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') AS time,
3232
mean(field1),
3333
sum(field2),
3434
tag1
@@ -206,7 +206,7 @@ groups:
206206

207207
```sql
208208
SELECT
209-
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time
209+
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time
210210
FROM home
211211
...
212212
```
@@ -225,7 +225,7 @@ groups:
225225
226226
```sql
227227
SELECT
228-
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time
228+
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time
229229
...
230230
GROUP BY 1, room
231231
...
@@ -235,7 +235,7 @@ groups:
235235
236236
```sql
237237
SELECT
238-
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time
238+
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS _time
239239
FROM home
240240
...
241241
GROUP BY _time, room
@@ -247,7 +247,7 @@ The following example retrieves unique combinations of time intervals and rooms
247247
248248
```sql
249249
SELECT
250-
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS time,
250+
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z') AS time,
251251
room,
252252
selector_max(temp, time)['value'] AS 'max temp',
253253
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
288288
289289
```sql
290290
SELECT
291-
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP)
291+
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z')
292292
AS _time,
293293
room,
294294
selector_max(temp, time)['value'] AS 'max temp',

‎content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ list_code_example: |
2121
sql="""
2222
SELECT DATE_BIN(INTERVAL '2 hours',
2323
time,
24-
'1970-01-01T00:00:00Z'::TIMESTAMP) AS time,
24+
'1970-01-01T00:00:00Z') AS time,
2525
room,
2626
selector_max(temp, time)['value'] AS 'max temp',
2727
selector_min(temp, time)['value'] AS 'min temp',

‎content/influxdb/cloud-dedicated/reference/sql/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -634,7 +634,7 @@ WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19
634634
#### Examples
635635

636636
```sql
637-
SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z'::timestamp) AS "_time",
637+
SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time",
638638
SUM(water_level)
639639
FROM "h2o_feet"
640640
GROUP BY "_time"

‎content/influxdb/cloud-dedicated/reference/sql/data-types.md

Lines changed: 31 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,26 @@ related:
1313
- /influxdb/cloud-dedicated/query-data/sql/cast-types/
1414
---
1515

16-
InfluxDB Cloud Dedicated uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/) implementation of SQL.
16+
{{< product-name >}} uses the [Apache Arrow DataFusion](https://arrow.apache.org/datafusion/)
17+
implementation of SQL.
1718
Data types define the type of values that can be stored in table columns.
1819
In InfluxDB's SQL implementation, a **measurement** is structured as a table,
1920
and **tags**, **fields** and **timestamps** are exposed as columns.
2021

22+
## SQL and Arrow data types
23+
24+
In SQL, each column, expression, and parameter has a data type.
25+
A data type is an attribute that specifies the type of data that the object can hold.
2126
DataFusion uses the [Arrow](https://arrow.apache.org/) type system for query execution.
22-
Data types stored in InfluxDB's storage engine are mapped to SQL data types at query time.
27+
All SQL types are mapped to [Arrow data types](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html).
28+
29+
Both SQL and Arrow data types play an important role in how data is operated on
30+
during query execution and returned in query results.
2331

2432
{{% note %}}
25-
When performing casting operations, cast to the **name** of the data type, not the actual data type.
33+
When performing casting operations, cast to the SQL data type unless you use
34+
[`arrow_cast()`](/influxdb/cloud-dedicated/reference/sql/functions/misc/#arrow_cast)
35+
to cast to a specific Arrow type.
2636
Names and identifiers in SQL are _case-insensitive_ by default. For example:
2737

2838
```sql
@@ -47,12 +57,12 @@ SELECT
4757

4858
## String types
4959

50-
| Name | Data type | Description |
51-
| :------ | :-------- | --------------------------------- |
52-
| STRING | UTF8 | Character string, variable-length |
53-
| CHAR | UTF8 | Character string, fixed-length |
54-
| VARCHAR | UTF8 | Character string, variable-length |
55-
| TEXT | UTF8 | Variable unlimited length |
60+
| SQL data type | Arrow data type | Description |
61+
| :------------ | :-------------- | --------------------------------- |
62+
| STRING | UTF8 | Character string, variable-length |
63+
| CHAR | UTF8 | Character string, fixed-length |
64+
| VARCHAR | UTF8 | Character string, variable-length |
65+
| TEXT | UTF8 | Variable unlimited length |
5666

5767
##### Example string literals
5868

@@ -66,11 +76,11 @@ SELECT
6676

6777
The following numeric types are supported:
6878

69-
| Name | Data type | Description |
70-
| :-------------- | :-------- | :--------------------------- |
71-
| BIGINT | INT64 | 64-bit signed integer |
72-
| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer |
73-
| DOUBLE | FLOAT64 | 64-bit floating-point number |
79+
| SQL data type | Arrow data type | Description |
80+
| :-------------- | :-------------- | :--------------------------- |
81+
| BIGINT | INT64 | 64-bit signed integer |
82+
| BIGINT UNSIGNED | UINT64 | 64-bit unsigned integer |
83+
| DOUBLE | FLOAT64 | 64-bit floating-point number |
7484

7585
### Integers
7686

@@ -122,10 +132,10 @@ Floats can be a decimal point, decimal integer, or decimal fraction.
122132

123133
InfluxDB SQL supports the following DATE/TIME data types:
124134

125-
| Name | Data type | Description |
126-
| :-------- | :-------- | :------------------------------------------------------------------- |
127-
| TIMESTAMP | TIMESTAMP | TimeUnit::Nanosecond, None |
128-
| INTERVAL | INTERVAL | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) |
135+
| SQL data type | Arrow data type | Description |
136+
| :------------ | :--------------------------------- | :-------------------------------------------- |
137+
| TIMESTAMP | Timestamp(Nanosecond, None) | Nanosecond timestamp with no time zone offset |
138+
| INTERVAL | Interval(IntervalMonthDayNano) | Interval of time with a specified duration |
129139

130140
### Timestamp
131141

@@ -180,9 +190,9 @@ INTERVAL '2 days 1 hour 31 minutes'
180190

181191
Booleans store TRUE or FALSE values.
182192

183-
| Name | Data type | Description |
184-
| :------ | :-------- | :------------------- |
185-
| BOOLEAN | BOOLEAN | True or false values |
193+
| SQL data type | Arrow data type | Description |
194+
| :------------ | :-------------- | :------------------- |
195+
| BOOLEAN | Boolean | True or false values |
186196

187197
##### Example boolean literals
188198

‎content/influxdb/cloud-dedicated/reference/sql/functions/misc.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ arrow_cast(expression, datatype)
3232
- **expression**: Expression to cast.
3333
Can be a constant, column, or function, and any combination of arithmetic or
3434
string operators.
35-
- **datatype**: [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html)
35+
- **datatype**: [Arrow data type](/influxdb/cloud-dedicated/reference/sql/data-types/#sql-and-arrow-data-types)
3636
to cast to.
3737

3838
{{< expand-wrapper >}}
@@ -60,7 +60,7 @@ LIMIT 1
6060
## arrow_typeof
6161

6262
Returns the underlying [Arrow data type](https://arrow.apache.org/datafusion/user-guide/sql/data_types.html)
63-
of the the expression:
63+
of the expression:
6464

6565
```sql
6666
arrow_typeof(expression)

0 commit comments

Comments
 (0)