Merge pull request ClickHouse#75735 from yariks5s/time/time64_v2

Implement Time and Time64 data types, ClickHouse#71943

Author: yakov-olkhovskiy

base/base/Decimal.h

@@ -10,6 +10,7 @@ namespace DB
 {
 template <class> struct Decimal;
 class DateTime64;
+class Time64;
 
 #define FOR_EACH_UNDERLYING_DECIMAL_TYPE(M) \
     M(Int32) \
@@ -142,6 +143,16 @@ class DateTime64 : public Decimal64
 
     constexpr DateTime64(const Base & v): Base(v) {} // NOLINT(google-explicit-constructor)
 };
+
+class Time64 : public Decimal64
+{
+public:
+    using Base = Decimal64;
+    using Base::Base;
+    using NativeType = Base::NativeType;
+
+    constexpr Time64(const Base & v): Base(v) {} // NOLINT(google-explicit-constructor)
+};
 }
 
 constexpr UInt64 max_uint_mask = std::numeric_limits<UInt64>::max();
@@ -173,6 +184,15 @@ namespace std
         }
     };
 
+    template <>
+    struct hash<DB::Time64>
+    {
+        size_t operator()(const DB::Time64 & x) const
+        {
+            return std::hash<DB::Time64::NativeType>()(x);
+        }
+    };
+
     template <>
     struct hash<DB::Decimal256>
     {

base/base/Decimal_fwd.h

@@ -27,14 +27,16 @@ using Decimal128 = Decimal<Int128>;
 using Decimal256 = Decimal<Int256>;
 
 class DateTime64;
+class Time64;
 
 template <class T>
 concept is_decimal =
     std::is_same_v<T, Decimal32>
     || std::is_same_v<T, Decimal64>
     || std::is_same_v<T, Decimal128>
     || std::is_same_v<T, Decimal256>
-    || std::is_same_v<T, DateTime64>;
+    || std::is_same_v<T, DateTime64>
+    || std::is_same_v<T, Time64>;
 
 template <class T>
 concept is_over_big_int =

base/base/TypeName.h

@@ -44,6 +44,7 @@ TN_MAP(Decimal64)
 TN_MAP(Decimal128)
 TN_MAP(Decimal256)
 TN_MAP(DateTime64)
+TN_MAP(Time64)
 TN_MAP(Array)
 TN_MAP(Tuple)
 TN_MAP(Map)

base/base/extended_types.h

@@ -74,6 +74,7 @@ template <typename T> concept is_floating_point =
     M(DataTypeDate) \
     M(DataTypeDate32) \
     M(DataTypeDateTime) \
+    M(DataTypeTime) \
     M(DataTypeInt8) \
     M(DataTypeUInt8) \
     M(DataTypeInt16) \
@@ -94,6 +95,7 @@ template <typename T> concept is_floating_point =
     M(DataTypeDate, X) \
     M(DataTypeDate32, X) \
     M(DataTypeDateTime, X) \
+    M(DataTypeTime, X) \
     M(DataTypeInt8, X) \
     M(DataTypeUInt8, X) \
     M(DataTypeInt16, X) \

ci/jobs/scripts/check_style/aspell-ignore/en/aspell-dict.txt

@@ -3045,6 +3045,7 @@ toStartOfYear
 toString
 toStringCutToZero
 toTime
+toTimeWithFixedDate
 toTimeZone
 toType
 toTypeName

docs/en/sql-reference/data-types/datetime.md

@@ -23,7 +23,7 @@ Resolution: 1 second.
 
 ## Speed {#speed}
 
-The `Date` datatype is faster than `DateTime` under _most_ conditions.
+The `Date` data type is faster than `DateTime` under _most_ conditions.
 
 The `Date` type requires 2 bytes of storage, while `DateTime` requires 4. However, when the database compresses the database, this difference is amplified. This amplification is due to the minutes and seconds in `DateTime` being less compressible. Filtering and aggregating `Date` instead of `DateTime` is also faster.
 

docs/en/sql-reference/data-types/time.md

@@ -0,0 +1,112 @@
+---
+description: 'Documentation for the Time data type in ClickHouse, which stores
+  the time range with second precision'
+slug: /sql-reference/data-types/time
+sidebar_position: 15
+sidebar_label: 'Time'
+title: 'Time'
+---
+
+# Time
+
+The `Time` data type is used to store a time value independent of any calendar date. It is ideal for representing daily schedules, event times, or any situation where only the time component (hours, minutes, seconds) is important.
+
+Syntax:
+
+``` sql
+Time()
+```
+
+Supported range of values: \[-999:59:59, 999:59:59\].
+
+Resolution: 1 second.
+
+## Speed {#speed}
+
+The `Date` data type is faster than `Time` under _most_ conditions. But the `Time` data type is around the same as `DateTime` data type.
+
+Due to the implementation details, the `Time` and `DateTime` type requires 4 bytes of storage, while `Date` requires 2 bytes. However, when the database compresses the database, this difference is amplified.
+
+## Usage Remarks {#usage-remarks}
+
+The point in time is saved as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time), regardless of the time zone or daylight saving time.
+
+**Note:** The Time data type does not observe time zones. It represents a time‐of‐day value on its own, without any date or regional offset context. Attempting to apply or change a time zone on Time columns has no effect and is not supported.
+
+## Examples {#examples}
+
+**1.** Creating a table with a `Time`-type column and inserting data into it:
+
+``` sql
+CREATE TABLE dt
+(
+    `time` Time,
+    `event_id` UInt8
+)
+ENGINE = TinyLog;
+```
+
+``` sql
+-- Parse Time
+-- - from string,
+-- - from integer interpreted as number of seconds since 1970-01-01.
+INSERT INTO dt VALUES ('100:00:00', 1), (12453, 3);
+
+SELECT * FROM dt;
+```
+
+``` text
+   ┌──────time─┬─event_id─┐
+1. │ 100:00:00 │        1 │
+2. │ 003:27:33 │        3 │
+   └───────────┴──────────┘
+```
+
+**2.** Filtering on `Time` values
+
+``` sql
+SELECT * FROM dt WHERE time = toTime('100:00:00')
+```
+
+``` text
+   ┌──────time─┬─event_id─┐
+1. │ 100:00:00 │        1 │
+   └───────────┴──────────┘
+```
+
+`Time` column values can be filtered using a string value in `WHERE` predicate. It will be converted to `Time` automatically:
+
+``` sql
+SELECT * FROM dt WHERE time = '100:00:00'
+```
+
+``` text
+   ┌──────time─┬─event_id─┐
+1. │ 100:00:00 │        1 │
+   └───────────┴──────────┘
+```
+
+**3.** Getting a time zone for a `Time`-type column:
+
+``` sql
+SELECT toTime(now()) AS column, toTypeName(column) AS x
+```
+
+``` text
+   ┌────column─┬─x────┐
+1. │ 018:55:15 │ Time │
+   └───────────┴──────┘
+```
+
+
+## See Also {#see-also}
+
+- [Type conversion functions](../functions/type-conversion-functions.md)
+- [Functions for working with dates and times](../functions/date-time-functions.md)
+- [Functions for working with arrays](../functions/array-functions.md)
+- [The `date_time_input_format` setting](../../operations/settings/settings-formats.md#date_time_input_format)
+- [The `date_time_output_format` setting](../../operations/settings/settings-formats.md#date_time_output_format)
+- [The `timezone` server configuration parameter](../../operations/server-configuration-parameters/settings.md#timezone)
+- [The `session_timezone` setting](../../operations/settings/settings.md#session_timezone)
+- [The `DateTime` data type](datetime.md)
+- [The `Date` data type](date.md)

docs/en/sql-reference/data-types/time64.md

@@ -0,0 +1,110 @@
+---
+description: 'Documentation for the Time64 data type in ClickHouse, which stores
+  the time range with sub-second precision'
+slug: /sql-reference/data-types/time64
+sidebar_position: 17
+sidebar_label: 'Time64'
+title: 'Time64'
+---
+
+# Time64
+
+The Time64 data type allows storing time values with sub-second precision. Unlike DateTime64, it does not include a calendar date, but only represents time. The precision defines the resolution of stored values in fractional seconds.
+
+Tick size (precision): 10<sup>-precision</sup> seconds. Valid range: [ 0 : 9 ].
+Typically, are used - 3 (milliseconds), 6 (microseconds), 9 (nanoseconds).
+
+**Syntax:**
+
+``` sql
+Time64(precision)
+```
+
+Internally, Time64 stores data as an Int64 number of ticks since the start of the day (000:00:00.000000000). The tick resolution is determined by the precision parameter. Optionally, a time zone can be specified at the column level, which affects how time values are interpreted and displayed in text format.
+
+Unlike DateTime64, Time64 does not store a date component, meaning that it only represents time. See details in [Time](../../sql-reference/data-types/time.md).
+
+Supported range of values: \[000:00:00, 999:59:59.99999999\]
+
+## Examples {#examples}
+
+1. Creating a table with `Time64`-type column and inserting data into it:
+
+``` sql
+CREATE TABLE t64
+(
+    `timestamp` Time64(3),
+    `event_id` UInt8
+)
+ENGINE = TinyLog;
+```
+
+``` sql
+-- Parse Time
+-- - from integer interpreted as number of seconds since 1970-01-01.
+-- - from string,
+INSERT INTO t64 VALUES (15463123, 1), (154600.123, 2), ('100:00:00', 3);
+
+SELECT * FROM t64;
+```
+
+``` text
+   ┌─────timestamp─┬─event_id─┐
+1. │ 004:17:43.123 │        1 │
+2. │ 042:56:40.123 │        2 │
+3. │ 100:00:00.000 │        3 │
+   └───────────────┴──────────┘
+```
+
+2. Filtering on `Time64` values
+
+``` sql
+SELECT * FROM t64 WHERE timestamp = toTime64('100:00:00', 3);
+```
+
+``` text
+   ┌─────timestamp─┬─event_id─┐
+1. │ 100:00:00.000 │        3 │
+   └───────────────┴──────────┘
+```
+
+Unlike `Time`, `Time64` values are not converted from `String` automatically.
+
+``` sql
+SELECT * FROM t64 WHERE timestamp = toTime64(154600.123, 3);
+```
+
+``` text
+   ┌─────timestamp─┬─event_id─┐
+1. │ 042:56:40.123 │        2 │
+   └───────────────┴──────────┘
+```
+
+Contrary to inserting, the `toTime64` function will treat all values as the decimal variant, so precision needs to
+be given after the decimal point.
+
+3. Getting a time zone for a `Time64`-type value:
+
+``` sql
+SELECT toTime64(now(), 3) AS column, toTypeName(column) AS x;
+```
+
+``` text
+   ┌────────column─┬─x─────────┐
+1. │ 019:14:16.000 │ Time64(3) │
+   └───────────────┴───────────┘
+```
+
+
+**See Also**
+
+- [Type conversion functions](../../sql-reference/functions/type-conversion-functions.md)
+- [Functions for working with dates and times](../../sql-reference/functions/date-time-functions.md)
+- [The `date_time_input_format` setting](../../operations/settings/settings-formats.md#date_time_input_format)
+- [The `date_time_output_format` setting](../../operations/settings/settings-formats.md#date_time_output_format)
+- [The `timezone` server configuration parameter](../../operations/server-configuration-parameters/settings.md#timezone)
+- [The `session_timezone` setting](../../operations/settings/settings.md#session_timezone)
+- [Operators for working with dates and times](../../sql-reference/operators/index.md#operators-for-working-with-dates-and-times)
+- [`Date` data type](../../sql-reference/data-types/date.md)
+- [`Time` data type](../../sql-reference/data-types/time.md)
+- [`DateTime` data type](../../sql-reference/data-types/datetime.md)

docs/en/sql-reference/functions/date-time-functions.md

@@ -1644,16 +1644,18 @@ Result:
 **See Also**
 - [date_trunc](#date_trunc)
 
-## toTime {#totime}
+## toTimeWithFixedDate {#totimewithfixeddate}
 
 Converts a date with time to a certain fixed date, while preserving the time.
 
 **Syntax**
 
 ```sql
-toTime(date[,timezone])
+toTimeWithFixedDate(date[,timezone])
 ```
 
+Alias: `toTime` - can be used only when the `use_legacy_to_time` setting is enabled.
+
 **Arguments**
 
 - `date` — Date to convert to a time. [Date](../data-types/date.md)/[DateTime](../data-types/datetime.md)/[DateTime64](../data-types/datetime64.md).

src/Columns/ColumnDecimal.cpp

@@ -533,5 +533,6 @@ template class ColumnDecimal<Decimal64>;
 template class ColumnDecimal<Decimal128>;
 template class ColumnDecimal<Decimal256>;
 template class ColumnDecimal<DateTime64>;
+template class ColumnDecimal<Time64>;
 
 }