Skip to content

Add timezone support to v3 SQL docs #5581

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Oct 30, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .ci/vale/styles/InfluxDataDocs/Terms/query-functions.txt
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ left
level
like
local
locf
lower
match
max
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ influxdata.com
(iox|IOx)
keep-url
lat
locf
(locf|LOCF)
logicalplan
noaa|NOAA
npm|NPM
Expand Down
2 changes: 1 addition & 1 deletion content/influxdb/cloud-dedicated/get-started/query.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
...
```
Expand All @@ -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
...
Expand All @@ -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
Expand All @@ -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',
Expand Down Expand Up @@ -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',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
2 changes: 1 addition & 1 deletion content/influxdb/cloud-dedicated/reference/sql/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
52 changes: 31 additions & 21 deletions content/influxdb/cloud-dedicated/reference/sql/data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
Expand Down Expand Up @@ -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)
Expand Down
Loading