diff options
| author | robot-piglet <[email protected]> | 2025-03-19 21:03:41 +0300 |
|---|---|---|
| committer | robot-piglet <[email protected]> | 2025-03-19 21:14:44 +0300 |
| commit | caffeefdf18bc9e13499ab6ae4024208561bd627 (patch) | |
| tree | 8ca98b509dd82637b176927f4cf3d441a4c7816f /yql/essentials/docs | |
| parent | 4a5e8d99c610850d8aa35506f332b9898fa2e3bc (diff) | |
Intermediate changes
commit_hash:b16f3e48e8ace97fa7d4b3d172f16bb0e784fd8b
Diffstat (limited to 'yql/essentials/docs')
| -rw-r--r-- | yql/essentials/docs/en/types/json.md | 52 | ||||
| -rw-r--r-- | yql/essentials/docs/en/types/primitive.md | 183 | ||||
| -rw-r--r-- | yql/essentials/docs/en/udf/list/datetime.md | 163 | ||||
| -rw-r--r-- | yql/essentials/docs/ru/types/json.md | 36 | ||||
| -rw-r--r-- | yql/essentials/docs/ru/types/primitive.md | 130 | ||||
| -rw-r--r-- | yql/essentials/docs/ru/udf/list/datetime.md | 142 |
6 files changed, 557 insertions, 149 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 diff --git a/yql/essentials/docs/ru/types/json.md b/yql/essentials/docs/ru/types/json.md index a257773ab7c..70667148670 100644 --- a/yql/essentials/docs/ru/types/json.md +++ b/yql/essentials/docs/ru/types/json.md @@ -128,6 +128,42 @@ YQL позволяет задавать параметры с помощью [DE * Значение представляется как строковое представление времени и временная зона через запятую. * Пример значения JSON — `"2023-06-29,Europe/Moscow"`, `""2023-06-29T17:14:11,Europe/Moscow""`, `""2023-06-29T17:15:36.645735,Europe/Moscow""` для TzDate, TzDateTime и TzTimestamp соответственно. +### Date32 {#date32} + +Дата, внутреннее представление — Int32, количество дней относительно unix epoch. + +* Тип в JSON — `string`. +* Пример значения JSON — `"-8722"` для даты `1946-02-14`. + +### Datetime64 {#datetime64} + +Дата и время, внутреннее представление — Int64, количество секунд относительно unix epoch. + +* Тип в JSON — `string`. +* Пример значения JSON — `"-753511371"`для даты `1946-02-14T19:17:09Z`. + +### Timestamp64 {#timestamp64} + +Дата и время, внутреннее представление — Int64, количество микросекунд c unix epoch. + +* Тип в JSON — `string`. +* Пример значения JSON — `"-753511370765432"` для `1946-02-14T19:17:09.234568Z`. + +### Interval64 {#interval64} + +Временной интервал, внутреннее представление — Int64, точность до микросекунд. + +* Тип в JSON — `string`. +* Пример значения JSON — `"9223339708799000000"`. + +### TzDate32, TzDateTime64, TzTimestamp64 {#tzdate32} + +Временные типы с меткой временной зоны. + +* Тип в JSON — `string`. +* Значение представляется как строковое представление времени и временная зона через запятую. +* Пример значения JSON — `"1946-02-14,Europe/Moscow"`, `"1946-02-14T19:17:09,Europe/Moscow"`, `"1946-02-14T19:17:09.234568,Europe/Moscow"` для TzDate32, TzDateTime64 и TzTimestamp64 соответственно. + ## Контейнеры В контейнерах все элементы кодируются согласно их типу. diff --git a/yql/essentials/docs/ru/types/primitive.md b/yql/essentials/docs/ru/types/primitive.md index 7cd07db98f6..05c6158cfb6 100644 --- a/yql/essentials/docs/ru/types/primitive.md +++ b/yql/essentials/docs/ru/types/primitive.md @@ -48,15 +48,39 @@ ## Дата и время {#datetime} +### Базовые типы + +Диапазон значений всех базовых временных типов – от полуночи<sup>1</sup> 01.01.1970 до полуночи<sup>1</sup> 01.01.2106. +Диапазон значений базового типа интевала – от -136 лет до +136 лет. + Тип | Описание | Примечания ----- | ----- | ----- -`Date` | Дата, точность до дней | Диапазон значений для всех временных типов кроме `Interval` - от нуля часов 01.01.1970 до нуля часов 01.01.2106. Внутреннее представление `Date` – беззнаковое целое 16 бит | -`Datetime` | Дата/время, точность до секунд | Внутреннее представление – беззнаковое целое 32 бит | -`Timestamp` | Дата/время, точность до микросекунд | Внутреннее представление – беззнаковое целое 64 бит | -`Interval` | Интервал времени (знаковый), точность до микросекунд | Диапазон значений – от -136 лет до +136 лет. Внутреннее представление – знаковое целое 64 бит. -`TzDate` | Дата с меткой временной зоны, точность до дней | Не поддерживается в столбцах таблиц -`TzDateTime` | Дата/время с меткой временной зоны, точность до секунд | Не поддерживается в столбцах таблиц -`TzTimestamp` | Дата/время с меткой временной зоны, точность до микросекунд | Не поддерживается в столбцах таблиц +`Date` | Момент времени, в который происходит полночь<sup>1</sup> по UTC, точность до дней | Внутреннее представление – беззнаковое целое 16 бит +`Datetime` | Момент времени по UTC, точность до секунд | Внутреннее представление – беззнаковое целое 32 бит +`Timestamp` | Момент времени по UTC, точность до микросекунд | Внутреннее представление – беззнаковое целое 64 бит +`Interval` | Интервал времени, точность до микросекунд | Диапазон значений – от -136 лет до +136 лет. Внутреннее представление – знаковое целое 64 бит. +`TzDate` | Момент времени по UTC, в который происходит полночь в заданной таймзоне | Внутреннее представление – беззнаковое целое 16 бит и метка таймзоны +`TzDateTime` | Момент времени по UTC с меткой временной зоны, точность до секунд | Внутреннее представление – беззнаковое целое 32 бит и метка таймзоны +`TzTimestamp` | Момент времени по UTC с меткой временной зоны, точность до микросекунд | Внутреннее представление – беззнаковое целое 64 бит и метка таймзоны + +<sup>1</sup> Полночью считаем такой момент времени, в которой все компоненты _времени_ равны нулю. + +### Расширенные типы + +Диапазон значений всех расширенных временных типов – от полуночи<sup>1</sup> 01.01.144169 до н.э. до полуночи<sup>1</sup> 01.01.148107. +Диапазон значений расширенного типа интевала – от -292277 лет до +292277 лет. + +Тип | Описание | Примечания +----- | ----- | ----- +`Date32` | Момент времени, в который происходит полночь<sup>1</sup> по UTC, точность до дней | Внутреннее представление `Date32` – знаковое целое 32 бит +`Datetime64` | Момент времени по UTC, точность до секунд | Внутреннее представление – знаковое целое 64 бит +`Timestamp64` | Момент времени по UTC, точность до микросекунд | Внутреннее представление – знаковое целое 64 бит +`Interval64` | Интервал времени, точность до микросекунд | Внутреннее представление – знаковое целое 64 бит +`TzDate32` | Момент времени по UTC, в который происходит полночь в заданной таймзоне | Внутреннее представление – знаковое целое 32 бит и метка таймзоны +`TzDateTime64` | Момент времени по UTC с меткой временной зоны, точность до секунд | Внутреннее представление – знаковое целое 64 бит и метка таймзоны +`TzTimestamp64` | Момент времени по UTC с меткой временной зоны, точность до микросекунд | Внутреннее представление – знаковое целое 64 бит и метка таймзоны + +<sup>1</sup> Полночью считаем такой момент времени, в которой все компоненты _времени_ равны нулю. ### Особенности поддержки типов с меткой временной зоны @@ -75,9 +99,6 @@ SELECT --эти выражения всегда true для любых тайм� AddTimezone(CurrentUtcDatetime(), "America/New_York"); ``` -Важно понимать, что при преобразованиях между `TzDate` и `TzDatetime` или `TzTimestamp` дате соответствует не полночь по локальному времени таймзоны, а полночь по UTC для даты в UTC. - - ## Приведение простых типов данных {#cast} ### Явное приведение {#explicit-cast} @@ -109,6 +130,10 @@ SELECT --эти выражения всегда true для любых тайм� **Datetime** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да | Да | Да | Нет **Timestamp** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да | Да | Нет **Interval** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да<sup>3,4</sup> | Да<sup>3,4</sup> | Да<sup>3,4</sup> | Да<sup>3</sup> | Да | Да | Нет +**Date32** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да | Да<sup>4</sup> | Да | Да | Да | Да | Да | Да | Нет +**Datetime64** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да | Да | Да | Нет +**Timestamp64** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да | Да | Нет +**Interval64** | Нет | Да<sup>4</sup> | Да<sup>4</sup> | Да<sup>4</sup> | Да | Да<sup>3,4</sup> | Да<sup>3,4</sup> | Да<sup>3,4</sup> | Да<sup>3</sup> | Да | Да | Нет <sup>1</sup> `True` преобразуется в `1`, `False` преобразуется в `0`. <sup>2</sup> Любое значение кроме `0` преобразуется в `True`, `0` преобразуется в `False`. @@ -118,6 +143,8 @@ SELECT --эти выражения всегда true для любых тайм� #### Приведение к типам данных даты и времени +##### Базовые типы + Тип | Date | Datetime | Timestamp | Interval --- | --- | --- | --- | --- **Bool** | Нет | Нет | Нет | Нет @@ -140,7 +167,41 @@ SELECT --эти выражения всегда true для любых тайм� **Date** | — | Да | Да | Нет **Datetime** | Да | — | Да | Нет **Timestamp** | Да | Да | — | Нет -**Interval** | Нет | Нет | Нет | — | — +**Interval** | Нет | Нет | Нет | — +**Date32** | Да | Да | Да | Нет +**Datetime64** | Да | Да | Да | Нет +**Timestamp64** | Да | Да | Да | Нет +**Interval64** | Нет | Нет | Нет | Да + +##### Расширенные типы + +Тип | Date32 | Datetime64 | Timestamp64 | Interval64 +--- | --- | --- | --- | --- +**Bool** | Нет | Нет | Нет | Нет +**Int8** | Да | Да | Да | Да +**Int16** | Да | Да | Да | Да +**Int32** | Да | Да | Да | Да +**Int64** | Да | Да | Да | Да +**Uint8** | Да | Да | Да | Да +**Uint16** | Да | Да | Да | Да +**Uint32** | Да | Да | Да | Да +**Uint64** | Да | Да | Да | Да +**Float** | Нет | Нет | Нет | Нет +**Double** | Нет | Нет | Нет | Нет +**Decimal** | Нет | Нет | Нет | Нет +**String** | Да | Да | Да | Да +**Utf8** | Да | Да | Да | Да +**Json** | Нет | Нет | Нет | Нет +**Yson** | Нет | Нет | Нет | Нет +**Uuid** | Нет | Нет | Нет | Нет +**Date** | Да | Да | Да | Нет +**Datetime** | Да | Да | Да | Нет +**Timestamp** | Да | Да | Да | Нет +**Interval** | Нет | Нет | Нет | Да +**Date32** | — | Да | Да | Нет +**Datetime64** | Да | — | Да | Нет +**Timestamp64** Да | Да | — | Нет +**Interval64** | Нет | Нет | Нет | — #### Приведение к другим типам данных @@ -167,6 +228,10 @@ SELECT --эти выражения всегда true для любых тайм� **Datetime** | Да | Да | Нет | Нет | Нет **Timestamp** | Да | Да | Нет | Нет | Нет **Interval** | Да | Да | Нет | Нет | Нет +**Date32** | Да | Да | Нет | Нет | Нет +**Datetime64** | Да | Да | Нет | Нет | Нет +**Timestamp64** | Да | Да | Нет | Нет | Нет +**Interval64** | Да | Да | Нет | Нет | Нет <sup>1</sup> При помощи встроенной функции [Yson::ConvertTo](../udf/list/yson.md#ysonconvertto). @@ -195,15 +260,42 @@ SELECT --эти выражения всегда true для любых тайм� **Float** | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | — | `Double` **Double** | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | — - #### Типы даты и времени +##### Базовые типы + Тип | 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** | — | — | — | — | — | — | — + +##### Расширенные типы + +Тип | 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/ru/udf/list/datetime.md b/yql/essentials/docs/ru/udf/list/datetime.md index aee9628c405..03afa6a6103 100644 --- a/yql/essentials/docs/ru/udf/list/datetime.md +++ b/yql/essentials/docs/ru/udf/list/datetime.md @@ -1,8 +1,9 @@ # DateTime -В модуле DateTime основным внутренним форматом представления является `Resource<TM>`, хранящий следующие компоненты даты: +В модуле DateTime существует два внутренних формата представления: `Resource<TM>` для базовых типов дат и `Resource<TM64>` для расширенных. -* Year (12 бит); +`Resource<TM>` и `Resource<TM64>` хранят следующие компоненты дат: +* Year (для `Resource<TM>` 12 бит, беззнаковый; для `Resource<TM64> 19 бит, знаковый); * Month (4 бита); * Day (5 бит); * Hour (5 бит); @@ -23,14 +24,10 @@ #### Список функций -* `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>` -Функции, принимающие на вход `Resource<TM>`, могут быть вызваны непосредственно от простого типа даты/времени. В этом случае будет сделано неявное преобразование через вызов соответствующей функции `Split`. +Функции, принимающие на вход `Resource<TM>` или `Resource<TM64>`, могут быть вызваны непосредственно от простого типа даты/времени. В этом случае будет сделано неявное преобразование через вызов соответствующей функции `Split`. ## Make... {#make} @@ -39,11 +36,17 @@ #### Список функций * `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` #### Примеры @@ -66,21 +69,22 @@ SELECT #### Список функций * `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` #### Примеры @@ -102,7 +106,8 @@ SELECT #### Список функций ```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>? ``` #### Примеры @@ -128,8 +133,11 @@ SELECT #### Список функций * `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 @@ SELECT #### Список функций * `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` #### Примеры @@ -155,18 +166,30 @@ SELECT #### Список функций -* `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` {% note warning %} @@ -178,6 +201,12 @@ AddTimezone никак не влияет на вывод ToSeconds(), поско Interval также можно создавать из строкового литерала в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601%23Durations). +{% note warning %} + +На данный момент поддержаны только литералы для детерминированных интервалов. Все размерности больше недели -- M (месяц) и Y (год) -- не фиксированы, поскольку интервал может быть определен только с помощью внешнего контекста (месяц, год). + +{% endnote %} + #### Примеры ```yql @@ -194,17 +223,29 @@ SELECT #### Список функций * `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>?` Функции `StartOf`/`EndOf` предназначены для группировки в пределах суток по произвольному периоду. Результат отличается от входного значения только компонентами времени. Период более суток трактуется как сутки (эквивалентно `StartOfDay`/`EndOfDay`). Если в сутках не содержится целого числа периодов, производится округление к ближайшему времени от начала суток, кратному указанному периоду. При нулевом интервале выход совпадает со входом. Отрицательный интервал трактуется как положительный. @@ -213,6 +254,7 @@ SELECT Поведение функций с периодами больше дня отличается от поведения одноимённых функций в старой библиотеке. Компоненты времени всегда обнуляются (это логично, поскольку эти функции в основном используются для группировки по периоду). Отдельно существует возможность выделить время в пределах суток: * `DateTime::TimeOfDay(Resource<TM>{Flags:AutoMap}) -> Interval` +* `DateTime::TimeOfDay(Resource<TM64>{Flags:AutoMap}) -> Interval64` #### Примеры @@ -250,8 +292,11 @@ SELECT #### Список функций * `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>?` Если в результате номер дня в месяце превышает максимально возможный, то в поле `Day` будет записан последний день месяца, время при этом не изменится (см. примеры). @@ -277,17 +322,17 @@ SELECT #### Список функций -* `DateTime::Format(String, alwaysWriteFractionalSeconds:Bool?) -> (Resource<TM>{Flags:AutoMap}) -> String` +* `DateTime::Format(String, alwaysWriteFractionalSeconds:Bool?) -> (Resource<TM64>{Flags:AutoMap}) -> String` Для строки форматирования реализовано множество спецификаторов: * `%%` - символ %; -* `%Y` - год 4 цифры; +* `%Y` - год 1-6 цифр и знак, для дат до н.э.; * `%m` - месяц 2 цифры; * `%d` - день 2 цифры; * `%H` - час 2 цифры; * `%M` - минуты 2 цифры; -* `%S` - секунды 2 цифры -- или xx.xxxxxx в случае непустых микросекунд (и только если флаг `alwaysWriteFractionalSeconds` не выставлен в `True`); +* `%S` - секунды 2 цифры или `XX.XXXXXX` в случае непустых микросекунд (и только если флаг `alwaysWriteFractionalSeconds` не выставлен в `True`); * `%z` - +hhmm or -hhmm; * `%Z` - IANA имя таймзоны; * `%b` - короткое трехбуквенное английское название месяца (Jan); @@ -316,13 +361,13 @@ SELECT Реализованные спецификаторы: * `%%` - символ %; -* `%Y` - год 4 цифры (1970); -* `%m` - месяц 2 цифры (1); -* `%d` - день 2 цифры (1); -* `%H` - час 2 цифры (0); -* `%M` - минуты 2 цифры (0); -* `%S` - секунды (0), может принимать и микросекунды в форматах от xx. до xx.xxxxxx -* `%Z` - IANA имя таймзоны (GMT). +* `%Y` - год 4 цифры; +* `%m` - месяц 2 цифры; +* `%d` - день 2 цифры; +* `%H` - час 2 цифры; +* `%M` - минуты 2 цифры; +* `%S` - секунды, может принимать и микросекунды в форматах от `XX` до `XX.XXXXXX`; +* `%Z` - IANA имя таймзоны (GMT); * `%b` - короткое трехбуквенное регистронезависимое английское название месяца (Jan); * `%B` - полное регистронезависимое английское название месяца (January). @@ -366,6 +411,25 @@ SELECT -- 2009-10-14T16:55:33Z ``` +## Parse64 {#parse64} + +Распарсить строку в широкое внутреннее представление, используя произвольную строку форматирования. Для незаполненных полей используются значения по умолчанию. При возникновении ошибок возвращается NULL. + +* `DateTime::Parse64(String) -> (String{Flags:AutoMap}) -> Resource<TM64>?` + +Реализованные спецификаторы: + +* `%%` - символ %; +* `%Y` - год 1-6 цифр и знак, для дат до н.э.; +* `%m` - месяц 2 цифры; +* `%d` - день 2 цифры; +* `%H` - час 2 цифры; +* `%M` - минуты 2 цифры; +* `%S` - секунды, может принимать и микросекунды в форматах от `XX` до `XX.XXXXXX`; +* `%Z` - IANA имя таймзоны (GMT); +* `%b` - короткое трехбуквенное регистронезависимое английское название месяца (Jan); +* `%B` - полное регистронезависимое английское название месяца (January). + ## Типовые сценарии ### Преобразования между строками и секундами |
