summaryrefslogtreecommitdiffstats
path: root/yql/essentials/docs/en
diff options
context:
space:
mode:
authorrobot-piglet <[email protected]>2025-03-19 21:03:41 +0300
committerrobot-piglet <[email protected]>2025-03-19 21:14:44 +0300
commitcaffeefdf18bc9e13499ab6ae4024208561bd627 (patch)
tree8ca98b509dd82637b176927f4cf3d441a4c7816f /yql/essentials/docs/en
parent4a5e8d99c610850d8aa35506f332b9898fa2e3bc (diff)
Intermediate changes
commit_hash:b16f3e48e8ace97fa7d4b3d172f16bb0e784fd8b
Diffstat (limited to 'yql/essentials/docs/en')
-rw-r--r--yql/essentials/docs/en/types/json.md52
-rw-r--r--yql/essentials/docs/en/types/primitive.md183
-rw-r--r--yql/essentials/docs/en/udf/list/datetime.md163
3 files changed, 307 insertions, 91 deletions
diff --git a/yql/essentials/docs/en/types/json.md b/yql/essentials/docs/en/types/json.md
index 115dc7c0d51..868b33a48ea 100644
--- a/yql/essentials/docs/en/types/json.md
+++ b/yql/essentials/docs/en/types/json.md
@@ -87,7 +87,7 @@ String types in UTF-8. Such strings are represented in JSON as strings with JSON
## Date {#date}
-Date. Uint64, unix time days.
+Date. Uint16, unix time days.
* Type in JSON: `string`.
* Value example: `18367`.
@@ -111,12 +111,60 @@ Date and time. Uint64, unix time microseconds.
## Interval {#interval}
-Time interval. Int64, precision to the microsecond, the interval values must not exceed 24 hours.
+Time interval. Int64, precision to the microsecond.
* Type in JSON: `number`.
* Value example: `123456`, `-123456`.
* Sample JSON value: `123456`, `-123456`.
+### TzDate, TzDateTime, TzTimestamp {#tzdate}
+
+Datetime types with time zone label.
+
+* Type in JSON: `string`.
+* Value is represented as string with the date/time value and the time zone label separated by a comma.
+* Sample JSON value: `"2023-06-29,Europe/Moscow"`, `""2023-06-29T17:14:11,Europe/Moscow""`, `""2023-06-29T17:15:36.645735,Europe/Moscow""` for TzDate, TzDateTime and TzTimestamp respectively..
+
+## Date32 {#date32}
+
+Date. Int32, unix time days.
+
+* Type in JSON: `string`.
+* Value example: `"-8722"`.
+* Sample JSON value: `1946-02-14`.
+
+## Datetime64 {#datetime64}
+
+Date and time. Int64, unix time seconds.
+
+* Type in JSON: `string`.
+* Value example: `"-753511371"`.
+* Sample JSON value: `1946-02-14T19:17:09Z`.
+
+## Timestamp64 {#timestamp64}
+
+Date and time. Int64, unix time microseconds.
+
+* Type in JSON: `string`.
+* Value example: `"-753511370765432"`.
+* Sample JSON value: `1946-02-14T19:17:09.234568Z`.
+
+## Interval64 {#interval64}
+
+Time interval. Int64, precision to the microsecond.
+
+* Type in JSON: `number`.
+* Value example: `"-9223339708799000000"`, `"9223339708799000000"`.
+* Sample JSON value: `-9223339708799000000`, `9223339708799000000`.
+
+### TzDate32, TzDateTime64, TzTimestamp64 {#tzdate32}
+
+Datetime types with time zone label.
+
+* Type in JSON: `string`.
+* Value is represented as string with the date/time value and the time zone label separated by a comma.
+* Sample JSON value: `"1946-02-14,Europe/Moscow"`, `"1946-02-14T19:17:09,Europe/Moscow"`, `"1946-02-14T19:17:09.234568,Europe/Moscow"` for TzDate32, TzDateTime64 и TzTimestamp64 respectively.
+
## Optional {#optional}
Means that the value can be `null`. If the value is `null`, then in JSON it's also `null`. If the value is not `null`, then the JSON value is expressed as if the type isn't `Optional`.
diff --git a/yql/essentials/docs/en/types/primitive.md b/yql/essentials/docs/en/types/primitive.md
index 24857a2f643..2d80ad4f057 100644
--- a/yql/essentials/docs/en/types/primitive.md
+++ b/yql/essentials/docs/en/types/primitive.md
@@ -51,17 +51,39 @@ To store numbers (JSON Number) in `JsonDocument`, as well as for arithmetic oper
## Date and time {#datetime}
+### Basic types
+
+Value range for all basic datetime types: From midnight<sup>1</sup> 01.01.1970 to midnight<sup>1</sup> 01.01.2106.
+Value range for basic interval type: from -136 years to +136 years.
+
| Type | Description | Notes |
-| ----- | ----- | ----- |
-| `Date` | Date, precision to the day | Range of values for all time types except `Interval`: From 00:00 01.01.1970 to 00:00 01.01.2106. Internal `Date` representation: Unsigned 16-bit integer |
-| `Datetime` | Date/time, precision to the second | Internal representation: Unsigned 32-bit integer |
-| `Timestamp` | Date/time, precision to the microsecond | Internal representation: Unsigned 64-bit integer |
-| `Interval` | Time interval (signed), precision to microseconds | Value range: From -136 years to +136 years. Internal representation: Signed 64-bit integer. |
-| `TzDate` | Date with time zone label, precision to the day | Not supported in table columns |
-| `TzDateTime` | Date/time with time zone label, precision to the second | Not supported in table columns |
-| `TzTimestamp` | Date/time with time zone label, precision to the microsecond | Not supported in table columns |
+|----- | ----- | ----- |
+| `Date` | Time moment, representing the UTC midnight<sup>1</sup>, precision to the day | Internal representation: unsigned 16-bit integer |
+| `Datetime` | UTC time moment, precision to second | Internal representation: unsigned 32-bit integer |
+| `Timestamp` | UTC time moment, precision to microsecond | Internal representation: unsigned 64-bit integer |
+| `Interval` | Time interval, precision to microseconds | Internal representation: signed 64-bit integer |
+| `TzDate` | UTC time moment, representing the local midnight<sup>1</sup>, precision to the day | Internal representation: unsigned 16-bit integer with time zone id |
+| `TzDateTime` | UTC time moment with time zone label, precision to second | Internal representation: unsigned 32-bit integer with time zone id |
+| `TzTimestamp` | UTC time moment with time zone label, precision to microsecond | Internal representation: unsigned 64-bit integer with time zone id |
+
+<sup>1</sup> Midnight is the particular time moment with all _time_ components being zero.
+### Extended types
+
+Value range for all basic datetime types: From midnight<sup>1</sup> 01.01.144169 BC to midnight<sup>1</sup> 01.01.148107.
+Value range for basic interval type: from -292277 years to +292277 years.
+
+| Type | Description | Notes |
+|----- | ----- | ----- |
+| `Date32` | Time moment, representing the UTC midnight<sup>1</sup>, precision to the day | Internal representation: signed 32-bit integer |
+| `Datetime64` | UTC time moment, precision to second | Internal representation: signed 64-bit integer |
+| `Timestamp64` | UTC time moment, precision to microsecond | Internal representation: signed 64-bit integer |
+| `Interval64` | Time interval, precision to microseconds | Internal representation: signed 64-bit integer |
+| `TzDate32` | UTC time moment, representing the local midnight<sup>1</sup>, precision to the day | Internal representation: signed 32-bit integer with time zone id |
+| `TzDateTime64` | UTC time moment with time zone label, precision to second | Internal representation: signed 64-bit integer with time zone id |
+| `TzTimestamp64` | UTC time moment with time zone label, precision to microsecond | Internal representation: signed 64-bit integer with time zone id |
+<sup>1</sup> Midnight is the particular time moment with all _time_ components being zero.
### Supporting types with a time zone label
@@ -80,9 +102,6 @@ SELECT -- these expressions are always true for any timezones: the timezone does
AddTimezone(CurrentUtcDatetime(), "America/New_York");
```
-Keep in mind that when converting between `TzDate` and `TzDatetime`, or `TzTimestamp` the date's midnight doesn't follow the local time zone, but midnight in UTC for the date in UTC.
-
-
## Casting between data types {#cast}
@@ -92,36 +111,55 @@ Explicit casting using [CAST](../syntax/expressions.md#cast):
#### Casting to numeric types
-| Type | Bool | Int | Uint | Float | Double | Decimal |
-| --- | --- | --- | --- | --- | --- | --- |
-| **Bool** | — | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | No | Yes | No |
-| **INT** | Yes<sup>2</sup> | — | Yes<sup>3</sup> | Yes | Yes | Yes |
-| **Uint** | Yes<sup>2</sup> | Yes | — | Yes | Yes | Yes |
-| **Float** | Yes<sup>2</sup> | Yes | Yes | — | Yes | No |
-| **Double** | Yes<sup>2</sup> | Yes | Yes | Yes | — | No |
-| **Decimal** | No | Yes | Yes | Yes | Yes | — |
-| **String** | Yes | Yes | Yes | Yes | Yes | Yes |
-| **Utf8** | Yes | Yes | Yes | Yes | Yes | Yes |
-| **Json** | No | No | No | No | No | No |
-| **Yson** | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> |
-| **Uuid** | No | No | No | No | No | No |
-| **Date** | No | Yes | Yes | Yes | Yes | No | Yes |
-| **Datetime** | No | Yes | Yes | Yes | Yes | No |
-| **Timestamp** | No | Yes | Yes | Yes | Yes | No |
-| **Interval** | No | Yes | Yes | Yes | Yes | No |
+| Type | Bool | Int8 | Int16 | Int32 | Int64 | Uint8 | Uint16 | Uint32 | Uint64 | Float | Double | Decimal |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **Bool** | — | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | Yes<sup>1</sup> | No |
+| **Int8** | Yes<sup>2</sup> | — | Yes | Yes | Yes | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes | Yes | Yes | |
+| **Int16** | Yes<sup>2</sup> | Yes<sup>4</sup> | — | Yes | Yes | Yes<sup>3,4</sup> | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes | Yes | Yes |
+| **Int32** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | — | Yes | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3</sup> | Yes<sup>3</sup> | Yes | Yes | Yes |
+| **Int64** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | — | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3</sup> | Yes | Yes | Yes |
+| **Uint8** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes | Yes | Yes | — | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Uint16** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes<sup>4</sup> | — | Yes | Yes | Yes | Yes | Yes |
+| **Uint32** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes<sup>4</sup> | Yes<sup>4</sup> | — | Yes | Yes | Yes | Yes |
+| **Uint64** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | — | Yes | Yes | Yes |
+| **Float** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | — | Yes | No |
+| **Double** | Yes<sup>2</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes | — | No |
+| **Decimal** | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | — |
+| **String** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Utf8** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Json** | No | No | No | No | No | No | No | No | No | No | No | No |
+| **Yson** | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | Yes<sup>5</sup> | No |
+| **Uuid** | No | No | No | No | No | No | No | No | No | No | No | No |
+| **Date** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes<sup>4</sup> | Yes | Yes | Yes | Yes | Yes | Yes | No |
+| **Datetime** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes | Yes | No |
+| **Timestamp** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes | No |
+| **Interval** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3</sup> | Yes | Yes | No |
+| **Date32** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes<sup>4</sup> | Yes | Yes | Yes | Yes | Yes | Yes | No |
+| **Datetime64** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes | Yes | No |
+| **Timestamp64** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes | Yes | No |
+| **Interval64** | No | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes<sup>4</sup> | Yes | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3,4</sup> | Yes<sup>3</sup> | Yes | Yes | No |
<sup>1</sup> `True` is converted to `1` and `False` to `0`.
<sup>2</sup> Any value other than `0` is converted to `True`, `0` is converted to `False`.
<sup>3</sup> Possible only in the case of a non-negative value.
-<sup>4</sup> Using the built-in function [Yson::ConvertTo](../udf/list/yson.md#ysonconvertto).
+<sup>4</sup> Possible only for the values from the target type value range.
+<sup>5</sup> Using the built-in function [Yson::ConvertTo](../udf/list/yson.md#ysonconvertto).
#### Converting to date and time data types
+##### Basic types
+
| Type | Date | Datetime | Timestamp | Interval |
| --- | --- | --- | --- | --- |
| **Bool** | No | No | No | No |
-| **INT** | Yes | Yes | Yes | Yes |
-| **Uint** | Yes | Yes | Yes | Yes |
+| **Int8** | Yes | Yes | Yes | Yes |
+| **Int16** | Yes | Yes | Yes | Yes |
+| **Int32** | Yes | Yes | Yes | Yes |
+| **Int64** | Yes | Yes | Yes | Yes |
+| **Uint8** | Yes | Yes | Yes | Yes |
+| **Uint16** | Yes | Yes | Yes | Yes |
+| **Uint32** | Yes | Yes | Yes | Yes |
+| **Uint64** | Yes | Yes | Yes | Yes |
| **Float** | No | No | No | No |
| **Double** | No | No | No | No |
| **Decimal** | No | No | No | No |
@@ -133,7 +171,41 @@ Explicit casting using [CAST](../syntax/expressions.md#cast):
| **Date** | — | Yes | Yes | No |
| **Datetime** | Yes | — | Yes | No |
| **Timestamp** | Yes | Yes | — | No |
-| **Interval** | No | No | No | — | — |
+| **Interval** | No | No | No | — |
+| **Date32** | Yes | Yes | Yes | No |
+| **Datetime64** | Yes | Yes | Yes | No |
+| **Timestamp64** | Yes | Yes | Yes | No |
+| **Interval64** | No | No | No | Yes |
+
+##### Extended types
+
+| Type | Date32 | Datetime64 | Timestamp64 | Interval64 |
+| --- | --- | --- | --- | --- |
+| **Bool** | No | No | No | No |
+| **Int8** | Yes | Yes | Yes | Yes |
+| **Int16** | Yes | Yes | Yes | Yes |
+| **Int32** | Yes | Yes | Yes | Yes |
+| **Int64** | Yes | Yes | Yes | Yes |
+| **Uint8** | Yes | Yes | Yes | Yes |
+| **Uint16** | Yes | Yes | Yes | Yes |
+| **Uint32** | Yes | Yes | Yes | Yes |
+| **Uint64** | Yes | Yes | Yes | Yes |
+| **Float** | No | No | No | No |
+| **Double** | No | No | No | No |
+| **Decimal** | No | No | No | No |
+| **String** | Yes | Yes | Yes | Yes |
+| **Utf8** | Yes | Yes | Yes | Yes |
+| **Json** | No | No | No | No |
+| **Yson** | No | No | No | No |
+| **Uuid** | No | No | No | No |
+| **Date** | Yes | Yes | Yes | No |
+| **Datetime** | Yes | Yes | Yes | No |
+| **Timestamp** | Yes | Yes | Yes | No |
+| **Interval** | No | No | No | Yes |
+| **Date32** | — | Yes | Yes | No |
+| **Datetime64** | Yes | — | Yes | No |
+| **Timestamp64** | Yes | Yes | — | No |
+| **Interval64** | No | No | No | — |
#### Conversion to other data types
@@ -154,6 +226,10 @@ Explicit casting using [CAST](../syntax/expressions.md#cast):
| **Datetime** | Yes | Yes | No | No | No |
| **Timestamp** | Yes | Yes | No | No | No |
| **Interval** | Yes | Yes | No | No | No |
+| **Date32** | Yes | Yes | No | No | No |
+| **Datetime64** | Yes | Yes | No | No | No |
+| **Timestamp64** | Yes | Yes | No | No | No |
+| **Interval64** | Yes | Yes | No | No | No |
<sup>4</sup> Using the built-in function [Yson::ConvertTo](../udf/list/yson.md#ysonconvertto).
@@ -176,13 +252,40 @@ Implicit type casting that occurs in basic operations ( +-\*/) between different
#### Date and time types
+##### Basic types
+
| Type | Date | Datetime | Timestamp | Interval | TzDate | TzDatetime | TzTimestamp |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| **Date** | — | — | — | `Date` | — | — | — |
-| **Datetime** | — | — | — | `Datetime` | — | — | — |
-| **Timestamp** | — | — | — | `Timestamp` | — | — | — |
-| **Interval** | `Date` | `Datetime` | `Timestamp` | — | `TzDate` | `TzDatetime` | `TzTimestamp` |
-| **TzDate** | — | — | — | `TzDate` | — | — | — |
-| **TzDatetime** | — | — | — | `TzDatetime` | — | — | — |
-| **TzTimestamp** | — | — | — | `TzTimestamp` | — | — | — |
-
+| **Date** | — | `DateTime` | `Timestamp` | — | `TzDate` | `TzDatetime` | `TzTimestamp` |
+| **Datetime** | — | — | `Timestamp` | — | — | `TzDatetime` | `TzTimestamp` |
+| **Timestamp** | — | — | — | — | — | — | `TzTimestamp` |
+| **Interval** | — | — | — | — | — | — | — |
+| **TzDate** | — | — | — | — | — | `TzDatetime` | `TzTimestamp` |
+| **TzDatetime** | — | — | — | — | — | — | `TzTimestamp` |
+| **TzTimestamp** | — | — | — | — | — | — | — |
+| **Date32** | — | — | — | — | — | — | — |
+| **Datetime64** | — | — | — | — | — | — | — |
+| **Timestamp64** | — | — | — | — | — | — | — |
+| **Interval64** | — | — | — | — | — | — | — |
+| **TzDate32** | — | — | — | — | — | — | — |
+| **TzDatetime64** | — | — | — | — | — | — | — |
+| **TzTimestamp64** | — | — | — | — | — | — | — |
+
+##### Extended types
+
+| Type | Date32 | Datetime64 | Timestamp64 | Interval64 | TzDate32 | TzDatetime64 | TzTimestamp64 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| **Date** | `Date32` | `DateTime64` | `Timestamp64` | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
+| **Datetime** | — | `Datetime64` | `Timestamp64` | — | — | `TzDatetime64` | `TzTimestamp64` |
+| **Timestamp** | — | — | `Timestamp64` | — | — | — | `TzTimestamp64` |
+| **Interval** | — | — | — | — | — | — | — |
+| **TzDate** | — | — | — | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
+| **TzDatetime** | — | — | — | — | — | `TzDatetime64` | `TzTimestamp64` |
+| **TzTimestamp** | — | — | — | — | — | — | `TzTimestamp64` |
+| **Date32** | — | `DateTime64` | `Timestamp64` | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
+| **Datetime64** | — | — | `Timestamp64` | — | — | `TzDatetime64` | `TzTimestamp64` |
+| **Timestamp64** | — | — | — | — | — | — | `TzTimestamp64` |
+| **Interval64** | — | — | — | — | — | — | — |
+| **TzDate32** | — | — | — | — | — | `TzDatetime64` | `TzTimestamp64` |
+| **TzDatetime64** | — | — | — | — | — | — | `TzTimestamp64` |
+| **TzTimestamp64** | — | — | — | — | — | — | — |
diff --git a/yql/essentials/docs/en/udf/list/datetime.md b/yql/essentials/docs/en/udf/list/datetime.md
index dbd6f137350..9f2b967f023 100644
--- a/yql/essentials/docs/en/udf/list/datetime.md
+++ b/yql/essentials/docs/en/udf/list/datetime.md
@@ -1,8 +1,9 @@
# DateTime
-In the DateTime module, the main internal representation format is `Resource<TM>`, which stores the following date components:
+In the DateTime module, there are two internal representation formats: `Resource<TM>` for basic types and `Resource<TM64>` for extended ones.
-* Year (12 bits).
+`Resource<TM>` and `Resource<TM64>` store the following date components:
+* Year (12 bits, unsigned for `Resource<TM>`; 19 bits, signed for `Resource<TM64>`).
* Month (4 bits).
* Day (5 bits).
* Hour (5 bits).
@@ -23,14 +24,10 @@ Conversion from a primitive type to an internal representation. It's always succ
#### List of functions
-* `DateTime::Split(Date{Flags:AutoMap}) -> Resource<TM>`
-* `DateTime::Split(Datetime{Flags:AutoMap}) -> Resource<TM>`
-* `DateTime::Split(Timestamp{Flags:AutoMap}) -> Resource<TM>`
-* `DateTime::Split(TzDate{Flags:AutoMap}) -> Resource<TM>`
-* `DateTime::Split(TzDatetime{Flags:AutoMap}) -> Resource<TM>`
-* `DateTime::Split(TzTimestamp{Flags:AutoMap}) -> Resource<TM>`
+* `DateTime::Split(Date/TzDate/DateTime/TzDateTime/Timestamp/TzTimestamp{Flags:AutoMap}) -> Resource<TM>`
+* `DateTime::Split(Date32/TzDate32/DateTime64/TzDatetime64/Timestamp64/TzTimestamp64{Flags:AutoMap}) -> Resource<TM64>`
-Functions that accept `Resource<TM>` as input, can be called directly from the primitive date/time type. An implicit conversion will be made in this case by calling a relevant `Split` function.
+Functions that accept `Resource<TM>` or `Resource<TM64>` as input, can be called directly from the primitive date/time type. An implicit conversion will be made in this case by calling a relevant `Split` function.
## Make... {#make}
@@ -39,11 +36,17 @@ Making a primitive type from an internal representation. It's always successful
#### List of functions
* `DateTime::MakeDate(Resource<TM>{Flags:AutoMap}) -> Date`
-* `DateTime::MakeDatetime(Resource<TM>{Flags:AutoMap}) -> Datetime`
-* `DateTime::MakeTimestamp(Resource<TM>{Flags:AutoMap}) -> Timestamp`
* `DateTime::MakeTzDate(Resource<TM>{Flags:AutoMap}) -> TzDate`
+* `DateTime::MakeDate32(Resource<TM>{Flags:AutoMap}) -> Date32`
+* `DateTime::MakeTzDate32(Resource<TM>{Flags:AutoMap}) -> TzDate32`
+* `DateTime::MakeDatetime(Resource<TM>{Flags:AutoMap}) -> Datetime`
* `DateTime::MakeTzDatetime(Resource<TM>{Flags:AutoMap}) -> TzDatetime`
+* `DateTime::MakeDatetime64(Resource<TM>{Flags:AutoMap}) -> Datetime64`
+* `DateTime::MakeTzDatetime64(Resource<TM>{Flags:AutoMap}) -> TzDatetime64`
+* `DateTime::MakeTimestamp(Resource<TM>{Flags:AutoMap}) -> Timestamp`
* `DateTime::MakeTzTimestamp(Resource<TM>{Flags:AutoMap}) -> TzTimestamp`
+* `DateTime::MakeTimestamp64(Resource<TM>{Flags:AutoMap}) -> Timestamp64`
+* `DateTime::MakeTzTimestamp64(Resource<TM>{Flags:AutoMap}) -> TzTimestamp64`
#### Examples
@@ -66,21 +69,22 @@ Extracting a component from an internal representation.
#### List of functions
* `DateTime::GetYear(Resource<TM>{Flags:AutoMap}) -> Uint16`
-* `DateTime::GetDayOfYear(Resource<TM>{Flags:AutoMap}) -> Uint16`
-* `DateTime::GetMonth(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetMonthName(Resource<TM>{Flags:AutoMap}) -> String`
-* `DateTime::GetWeekOfYear(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetWeekOfYearIso8601(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetDayOfMonth(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetDayOfWeek(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetDayOfWeekName(Resource<TM>{Flags:AutoMap}) -> String`
-* `DateTime::GetHour(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetMinute(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetSecond(Resource<TM>{Flags:AutoMap}) -> Uint8`
-* `DateTime::GetMillisecondOfSecond(Resource<TM>{Flags:AutoMap}) -> Uint32`
-* `DateTime::GetMicrosecondOfSecond(Resource<TM>{Flags:AutoMap}) -> Uint32`
-* `DateTime::GetTimezoneId(Resource<TM>{Flags:AutoMap}) -> Uint16`
-* `DateTime::GetTimezoneName(Resource<TM>{Flags:AutoMap}) -> String`
+* `DateTime::GetYear(Resource<TM64>{Flags:AutoMap}) -> Int32`
+* `DateTime::GetDayOfYear(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint16`
+* `DateTime::GetMonth(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetMonthName(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> String`
+* `DateTime::GetWeekOfYear(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetWeekOfYearIso8601(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetDayOfMonth(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetDayOfWeek(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetDayOfWeekName(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> String`
+* `DateTime::GetHour(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetMinute(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetSecond(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint8`
+* `DateTime::GetMillisecondOfSecond(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint32`
+* `DateTime::GetMicrosecondOfSecond(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint32`
+* `DateTime::GetTimezoneId(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> Uint16`
+* `DateTime::GetTimezoneName(Resource<TM>/Resource<TM64>{Flags:AutoMap}) -> String`
#### Examples
@@ -102,7 +106,8 @@ Updating one or more components in the internal representation. Returns either a
#### List of functions
```yql
-DateTime::Update( Resource<TM>{Flags:AutoMap}, [ Year:Uint16?, Month:Uint8?, Day:Uint8?, Hour:Uint8?, Minute:Uint8?, Second:Uint8?, Microsecond:Uint32?, Timezone:String? ]) -> Resource<TM>?
+DateTime::Update(Resource<TM>{Flags:AutoMap}, [ Year:Uint16?, Month:Uint8?, Day:Uint8?, Hour:Uint8?, Minute:Uint8?, Second:Uint8?, Microsecond:Uint32?, Timezone:String? ]) -> Resource<TM>?
+DateTime::Update(Resource<TM64>{Flags:AutoMap}, [ Year:Int32?, Month:Uint8?, Day:Uint8?, Hour:Uint8?, Minute:Uint8?, Second:Uint8?, Microsecond:Uint32?, Timezone:String? ]) -> Resource<TM64>?
```
#### Examples
@@ -128,8 +133,11 @@ Getting a Timestamp from the number of seconds/milliseconds/microseconds since t
#### List of functions
* `DateTime::FromSeconds(Uint32{Flags:AutoMap}) -> Timestamp`
+* `DateTime::FromSeconds64(Int64{Flags:AutoMap}) -> Timestamp64`
* `DateTime::FromMilliseconds(Uint64{Flags:AutoMap}) -> Timestamp`
+* `DateTime::FromMilliseconds64(Int64{Flags:AutoMap}) -> Timestamp64`
* `DateTime::FromMicroseconds(Uint64{Flags:AutoMap}) -> Timestamp`
+* `DateTime::FromMicroseconds64(Int64{Flags:AutoMap}) -> Timestamp64`
## To... {#to}
@@ -138,8 +146,11 @@ Getting a number of seconds/milliseconds/microseconds since the UTC Epoch from a
#### List of functions
* `DateTime::ToSeconds(Date/DateTime/Timestamp/TzDate/TzDatetime/TzTimestamp{Flags:AutoMap}) -> Uint32`
+* `DateTime::ToSeconds(Date32/DateTime64/Timestamp64/TzDate32/TzDatetime64/TzTimestamp64{Flags:AutoMap}) -> Int64`
* `DateTime::ToMilliseconds(Date/DateTime/Timestamp/TzDate/TzDatetime/TzTimestamp{Flags:AutoMap}) -> Uint64`
+* `DateTime::ToMilliseconds(Date32/DateTime64/Timestamp64/TzDate32/TzDatetime64/TzTimestamp64{Flags:AutoMap}) -> Int64`
* `DateTime::ToMicroseconds(Date/DateTime/Timestamp/TzDate/TzDatetime/TzTimestamp{Flags:AutoMap}) -> Uint64`
+* `DateTime::ToMicroseconds(Date32/DateTime64/Timestamp64/TzDate32/TzDatetime64/TzTimestamp64{Flags:AutoMap}) -> Int64`
#### Examples
@@ -155,23 +166,41 @@ Conversions between `Interval` and various time units.
#### List of functions
-* `DateTime::ToDays(Interval{Flags:AutoMap}) -> Int16`
+* `DateTime::ToDays(Interval{Flags:AutoMap}) -> Int32`
+* `DateTime::ToDays(Interval64{Flags:AutoMap}) -> Int32`
* `DateTime::ToHours(Interval{Flags:AutoMap}) -> Int32`
+* `DateTime::ToHours(Interval64{Flags:AutoMap}) -> Int64`
* `DateTime::ToMinutes(Interval{Flags:AutoMap}) -> Int32`
+* `DateTime::ToMinutes(Interval64{Flags:AutoMap}) -> Int64`
* `DateTime::ToSeconds(Interval{Flags:AutoMap}) -> Int32`
+* `DateTime::ToSeconds(Interval64{Flags:AutoMap}) -> Int64`
* `DateTime::ToMilliseconds(Interval{Flags:AutoMap}) -> Int64`
+* `DateTime::ToMilliseconds(Interval64{Flags:AutoMap}) -> Int64`
* `DateTime::ToMicroseconds(Interval{Flags:AutoMap}) -> Int64`
-* `DateTime::IntervalFromDays(Int16{Flags:AutoMap}) -> Interval`
+* `DateTime::ToMicroseconds(Interval64{Flags:AutoMap}) -> Int64`
+* `DateTime::IntervalFromDays(Int32{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromDays(Int32{Flags:AutoMap}) -> Interval64`
* `DateTime::IntervalFromHours(Int32{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromHours(Int64{Flags:AutoMap}) -> Interval64`
* `DateTime::IntervalFromMinutes(Int32{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromMinutes(Int64{Flags:AutoMap}) -> Interval64`
* `DateTime::IntervalFromSeconds(Int32{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromSeconds(Int64{Flags:AutoMap}) -> Interval64`
* `DateTime::IntervalFromMilliseconds(Int64{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromMilliseconds(Int64{Flags:AutoMap}) -> Interval64`
* `DateTime::IntervalFromMicroseconds(Int64{Flags:AutoMap}) -> Interval`
+* `DateTime::Interval64FromMicroseconds(Int64{Flags:AutoMap}) -> Interval64`
AddTimezone doesn't affect the output of ToSeconds() in any way, because ToSeconds() always returns GMT time.
You can also create an Interval from a string literal in the format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601%23Durations).
+{% note warning %}
+
+At the moment, only literals for deterministic intervals are supported. All components greater than week -- M (month) and Y (year) -- are not fixed, since the interval can be defined only considering the particular context (month, year).
+
+{% endnote %}
+
#### Examples
```yql
@@ -188,17 +217,30 @@ Get the start (end) of the period including the date/time. If the result is inva
#### List of functions
* `DateTime::StartOfYear(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOfYear(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOfYear(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOfYear(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::StartOfQuarter(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOfQuarter(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOfQuarter(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOfQuarter(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::StartOfMonth(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOfMonth(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOfMonth(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOfMonth(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::StartOfWeek(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOfWeek(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOfWeek(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOfWeek(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::StartOfDay(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOfDay(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOfDay(Resource<TM>{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOfDay(Resource<TM64>{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::StartOf(Resource<TM>{Flags:AutoMap}, Interval{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::StartOf(Resource<TM64>{Flags:AutoMap}, Interval64{Flags:AutoMap}) -> Resource<TM64>?`
* `DateTime::EndOf(Resource<TM>{Flags:AutoMap}, Interval{Flags:AutoMap}) -> Resource<TM>?`
+* `DateTime::EndOf(Resource<TM64>{Flags:AutoMap}, Interval64{Flags:AutoMap}) -> Resource<TM64>?`
+
The `StartOf`/`EndOf` functions are intended for grouping by an arbitrary period within a day. The result differs from the input value only by time components. A period exceeding one day is treated as a day (an equivalent of `StartOfDay`/`EndOfDay`). If a day doesn't include an integer number of periods, the number is rounded to the nearest time from the beginning of the day that is a multiple of the specified period. When the interval is zero, the output is same as the input. A negative interval is treated as a positive one.
@@ -207,6 +249,7 @@ The `EndOf...` functions are intended for obtaining the latest moment in the sam
The functions treat periods longer than one day in a different manner than the same-name functions in the old library. The time components are always reset to zero (this makes sense, because these functions are mainly used for grouping by the period). You can also specify a time period within a day:
* `DateTime::TimeOfDay(Resource<TM>{Flags:AutoMap}) -> Interval`
+* `DateTime::TimeOfDay(Resource<TM64>{Flags:AutoMap}) -> Interval64`
#### Examples
@@ -244,8 +287,11 @@ Returns either an updated copy or NULL, if an update produces an invalid date or
#### List of functions
* `DateTime::ShiftYears(Resource<TM>{Flags:AutoMap}, Int32) -> Resource<TM>?`
+* `DateTime::ShiftYears(Resource<TM64>{Flags:AutoMap}, Int32) -> Resource<TM64>?`
* `DateTime::ShiftQuarters(Resource<TM>{Flags:AutoMap}, Int32) -> Resource<TM>?`
+* `DateTime::ShiftQuarters(Resource<TM64>{Flags:AutoMap}, Int32) -> Resource<TM64>?`
* `DateTime::ShiftMonths(Resource<TM>{Flags:AutoMap}, Int32) -> Resource<TM>?`
+* `DateTime::ShiftMonths(Resource<TM64>{Flags:AutoMap}, Int32) -> Resource<TM64>?`
If the resulting number of the day in the month exceeds the maximum allowed, then the `Day` field will accept the last day of the month without changing the time (see examples).
@@ -270,20 +316,20 @@ Get a string representation of a time using an arbitrary formatting string.
#### List of functions
-* `DateTime::Format(String, alwaysWriteFractionalSeconds:Bool?) -> (Resource<TM>{Flags:AutoMap}) -> String`
+* `DateTime::Format(String, alwaysWriteFractionalSeconds:Bool?) -> (Resource<TM64>{Flags:AutoMap}) -> String`
A set of specifiers is implemented for the formatting string:
-* `%%`: % character.
-* `%Y`: 4-digit year.
-* `%m`: 2-digit month.
-* `%d`: 2-digit day.
-* `%H`: 2-digit hour.
-* `%M`: 2-digit minutes.
-* `%S`: 2-digit seconds -- or xx.xxxxxx in the case of non-empty microseconds (only if `alwaysWriteFractionalSeconds` is not set to `True`).
-* `%z`: +hhmm or -hhmm.
-* `%Z`: IANA name of the timezone.
-* `%b`: A short three-letter English name of the month (Jan).
+* `%%`: % character;
+* `%Y`: Variable length (1-6 digits) year with minus for the dates BC;
+* `%m`: 2-digit month;
+* `%d`: 2-digit day;
+* `%H`: 2-digit hour;
+* `%M`: 2-digit minutes;
+* `%S`: 2-digit seconds or `XX.XXXXXX` in the case of non-empty microseconds (only if `alwaysWriteFractionalSeconds` is not set to `True`);
+* `%z`: +hhmm or -hhmm;
+* `%Z`: IANA name of the timezone (GMT);
+* `%b`: A short three-letter English name of the month (Jan);
* `%B`: A full English name of the month (January).
All other characters in the format string are passed on without changes.
@@ -308,15 +354,15 @@ Parse a string into an internal representation using an arbitrary formatting str
Implemented specifiers:
-* `%%`: the % character.
-* `%Y`: 4-digit year (1970).
-* `%m`: 2-digit month (1).
-* `%d`: 2-digit day (1).
-* `%H`: 2-digit hour (0).
-* `%M`: 2-digit minutes (0).
-* `%S`: Seconds (0), can also accept microseconds in the formats from xx. up to xx.xxxxxx
-* `%Z`: The IANA name of the timezone (GMT).
-* `%b`: A short three-letter case-insensitive English name of the month (Jan).
+* `%%`: the % character;
+* `%Y`: 4-digit year;
+* `%m`: 2-digit month;
+* `%d`: 2-digit day;
+* `%H`: 2-digit hour;
+* `%M`: 2-digit minutes;
+* `%S`: Seconds, can also accept microseconds in the formats from `XX` up to `XX.XXXXXX`;
+* `%Z`: The IANA name of the timezone (GMT);
+* `%b`: A short three-letter case-insensitive English name of the month (Jan);
* `%B`: A full case-insensitive English name of the month (January).
#### Examples
@@ -359,6 +405,25 @@ SELECT
-- 2009-10-14T16:55:33Z
```
+## Parse64 {#parse64}
+
+Parse a string into a wide internal representation using an arbitrary formatting string. Default values are used for empty fields. If errors are raised, NULL is returned.
+
+* `DateTime::Parse64(String) -> (String{Flags:AutoMap}) -> Resource<TM64>?`
+
+Implemented specifiers:
+
+* `%%`: the % character;
+* `%Y`: Variable length (1-6 digits) year with minus for the dates BC;
+* `%m`: 2-digit month;
+* `%d`: 2-digit day;
+* `%H`: 2-digit hour;
+* `%M`: 2-digit minutes;
+* `%S`: Seconds, can also accept microseconds in the formats from `XX` up to `XX.XXXXXX`;
+* `%Z`: The IANA name of the timezone (GMT);
+* `%b`: A short three-letter case-insensitive English name of the month (Jan);
+* `%B`: A full case-insensitive English name of the month (January).
+
## Standard scenarios
### Conversions between strings and seconds