feat: Add support for Time with Timezone type (facebookincubator#14999)

Summary:

Add support for TIME WITH TIME ZONE Type. TIME WITH TIME ZONE represents time from midnight in milliseconds precision at a particular timezone. Its physical type is BIGINT. The high 52 bits of bigint store signed integer for milliseconds in UTC.
The lower 12 bits store the time zone offsets minutes. This allows the time to be converted at any point of
time without ambiguity of daylight savings time. Time zone offsets range from -14:00 hours to +14:00 hours.

When converting to string we encode the offset hours instead of the timezone name as per [issue](prestodb/presto#25957).

NOTE:
I will be adding support for CastOperator, CustomComparator , InputGenerator in subsequent PR's/Diffs.

Reviewed By: kevinwilfong

Differential Revision: D83195237

Author: Krishna Pai

velox/docs/develop/types.rst

@@ -182,6 +182,7 @@ TDIGEST                   VARBINARY
 QDIGEST                   VARBINARY
 BIGINT_ENUM               BIGINT
 VARCHAR_ENUM              VARCHAR
+TIME WITH TIME ZONE       BIGINT
 ========================  =====================
 
 TIMESTAMP WITH TIME ZONE represents a time point in milliseconds precision
@@ -247,6 +248,12 @@ VarcharEnumParameter as the key.
 Casting is only permitted to and from VARCHAR type, and is case-sensitive. Casting between different enum types is not permitted.
 Comparison operations are only allowed between values of the same enum type.
 
+TIME WITH TIME ZONE represents time from midnight in milliseconds precision at a particular timezone.
+Its physical type is BIGINT. The high 52 bits of bigint store signed integer for milliseconds in UTC.
+The lower 12 bits store the time zone offsets minutes. This allows the time to be converted at any point of
+time without ambiguity of daylight savings time. Time zone offsets range from -14:00 hours to +14:00 hours.
+
+
 Spark Types
 ~~~~~~~~~~~~
 The `data types <https://spark.apache.org/docs/latest/sql-ref-datatypes.html>`_ in Spark have some semantic differences compared to those in

velox/expression/fuzzer/ExpressionFuzzerTest.cpp

@@ -257,6 +257,7 @@ std::unordered_set<std::string> skipFunctions = {
     "geometry_to_bing_tiles",
     "geometry_to_dissolved_bing_tiles",
     "geometry_union",
+    "localtime",
 };
 
 std::unordered_set<std::string> skipFunctionsSOT = {

velox/functions/prestosql/types/CMakeLists.txt

@@ -30,6 +30,7 @@ velox_add_library(
   SfmSketchRegistration.cpp
   TDigestRegistration.cpp
   TimestampWithTimeZoneRegistration.cpp
+  TimeWithTimezoneRegistration.cpp
   UuidRegistration.cpp
   VarcharEnumRegistration.cpp
   VarcharEnumType.cpp

velox/functions/prestosql/types/TimeWithTimezoneRegistration.cpp

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "velox/functions/prestosql/types/TimeWithTimezoneType.h"
+#include "velox/functions/prestosql/types/TimestampWithTimeZoneType.h"
+#include "velox/type/Type.h"
+
+namespace facebook::velox {
+
+folly::dynamic TimeWithTimezoneType::serialize() const {
+  folly::dynamic obj = folly::dynamic::object;
+  obj["name"] = "Type";
+  obj["type"] = name();
+  return obj;
+}
+
+std::string TimeWithTimezoneType::valueToString(int64_t value) const {
+  // TIME WITH TIME ZONE is encoded similarly to TIMESTAMP WITH TIME ZONE
+  // with the most significnat 52 bits representing the time component and the
+  // least 12 bits representing the timezone minutes. This is different from
+  // TIMESTAMP WITH TIMEZONE where the last 12 bits represent the timezone
+  // offset. The timezone offset minutes are stored by value, encoded in the
+  // type itself. This allows the type to be used in a timezone-agnostic manner.
+  //
+  // The time component is a 52 bit value representing the number of
+  // milliseconds since midnight in UTC.
+
+  int64_t timeComponent = unpackMillisUtc(value);
+
+  // Ensure time component is within valid range
+  VELOX_CHECK_GE(timeComponent, 0, "Time component is negative");
+  VELOX_CHECK_LE(timeComponent, kMillisInDay, "Time component is too large");
+
+  int64_t hours = timeComponent / kMillisInHour;
+  int64_t remainingMs = timeComponent % kMillisInHour;
+  int64_t minutes = remainingMs / kMillisInMinute;
+  remainingMs = remainingMs % kMillisInMinute;
+  int64_t seconds = remainingMs / kMillisInSecond;
+  int64_t millis = remainingMs % kMillisInSecond;
+
+  // TimeZone's are encoded as a 12 bit value.
+  // This represents a range of -14:00 to +14:00, with 0 representing UTC.
+  // The range is from -840 to 840 minutes, we thus encode by doing bias
+  // encoding and taking 840 as the bias.
+  auto timezoneMinutes = unpackZoneKeyId(value);
+
+  VELOX_CHECK_GE(timezoneMinutes, 0, "Timezone offset is less than -14:00");
+  VELOX_CHECK_LE(
+      timezoneMinutes, 1680, "Timezone offset is greater than +14:00");
+
+  auto decodedMinutes = timezoneMinutes >= kTimeZoneBias
+      ? timezoneMinutes - kTimeZoneBias
+      : kTimeZoneBias - timezoneMinutes;
+
+  const auto isBehindUTCString = timezoneMinutes >= kTimeZoneBias ? "+" : "-";
+
+  int16_t offsetHours = decodedMinutes / kMinutesInHour;
+  int16_t remainingOffsetMinutes = decodedMinutes % kMinutesInHour;
+
+  return fmt::format(
+      "{:02d}:{:02d}:{:02d}.{:03d}{}{:02d}:{:02d}",
+      hours,
+      minutes,
+      seconds,
+      millis,
+      isBehindUTCString,
+      offsetHours,
+      remainingOffsetMinutes);
+}
+
+namespace {
+
+class TimeWithTimezoneTypeFactory : public CustomTypeFactory {
+ public:
+  TimeWithTimezoneTypeFactory() = default;
+
+  TypePtr getType(const std::vector<TypeParameter>& parameters) const override {
+    VELOX_CHECK(parameters.empty());
+    return TIME_WITH_TIME_ZONE();
+  }
+
+  // Type casting from and to TimestampWithTimezone is not supported yet.
+  exec::CastOperatorPtr getCastOperator() const override {
+    return nullptr;
+  }
+
+  AbstractInputGeneratorPtr getInputGenerator(
+      const InputGeneratorConfig& config) const override {
+    return nullptr;
+  }
+};
+} // namespace
+
+void registerTimeWithTimezoneType() {
+  registerCustomType(
+      "time with time zone",
+      std::make_unique<const TimeWithTimezoneTypeFactory>());
+}
+
+} // namespace facebook::velox

velox/functions/prestosql/types/TimeWithTimezoneRegistration.h

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+namespace facebook::velox {
+void registerTimeWithTimezoneType();
+}

velox/functions/prestosql/types/TimeWithTimezoneType.h

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "velox/type/Type.h"
+
+namespace facebook::velox {
+
+/// Represents TIME WITH TIME ZONE as a bigint.
+/// This type stores time with timezone information, typically encoded as:
+/// - Most significant bits: milliseconds since midnight UTC (similar to TIME)
+/// - Least significant bits : timezone information
+class TimeWithTimezoneType final : public BigintType {
+  TimeWithTimezoneType() = default;
+
+ public:
+  static constexpr int16_t kTimeZoneBias = 840;
+  static constexpr int16_t kMinutesInHour = 60;
+
+  static std::shared_ptr<const TimeWithTimezoneType> get() {
+    VELOX_CONSTEXPR_SINGLETON TimeWithTimezoneType kInstance;
+    return {std::shared_ptr<const TimeWithTimezoneType>{}, &kInstance};
+  }
+
+  bool equivalent(const Type& other) const override {
+    // Pointer comparison works since this type is a singleton.
+    return this == &other;
+  }
+
+  const char* name() const override {
+    return "TIME WITH TIME ZONE";
+  }
+
+  std::string toString() const override {
+    return name();
+  }
+
+  /// Returns the time with timezone 'value' formatted as HH:MM:SS.mmmZZ
+  /// where the timezone offset is included in the representation.
+  std::string valueToString(int64_t value) const;
+
+  folly::dynamic serialize() const override;
+
+  static TypePtr deserialize(const folly::dynamic& /*obj*/) {
+    return TimeWithTimezoneType::get();
+  }
+
+  bool isOrderable() const override {
+    return true;
+  }
+
+  bool isComparable() const override {
+    return true;
+  }
+
+  /// Encodes the timezone offset in the upper bits of the bigint.
+  /// The timezone offset is encoded as an integer in the range [-840, 840]
+  /// representing the number of minutes from UTC. The bias is added to the
+  /// timezone offset to ensure that the timezone offset is positive.
+  /// Typically called before a call to pack which will encode the timezone
+  /// offset along with the time value.
+  static inline int16_t biasEncode(int16_t timeZoneOffsetMinutes) {
+    VELOX_CHECK(
+        -kTimeZoneBias <= timeZoneOffsetMinutes &&
+            timeZoneOffsetMinutes <= kTimeZoneBias,
+        "Timezone offset must be between -840 and 840 minutes. Got: ",
+        timeZoneOffsetMinutes);
+    return timeZoneOffsetMinutes + kTimeZoneBias;
+  }
+};
+
+inline bool isTimeWithTimeZone(const TypePtr& other) {
+  return TimeWithTimezoneType::get() == other;
+}
+
+using TimeWithTimezoneTypePtr = std::shared_ptr<const TimeWithTimezoneType>;
+
+FOLLY_ALWAYS_INLINE TimeWithTimezoneTypePtr TIME_WITH_TIME_ZONE() {
+  return TimeWithTimezoneType::get();
+}
+
+} // namespace facebook::velox

velox/functions/prestosql/types/parser/tests/TypeParserTest.cpp

@@ -46,6 +46,11 @@ static const TypePtr& TIMESTAMP_WITH_TIME_ZONE() {
   return instance;
 }
 
+static const TypePtr& TIME_WITH_TIME_ZONE() {
+  static const TypePtr instance{new CustomType()};
+  return instance;
+}
+
 class TypeFactory : public CustomTypeFactory {
  public:
   TypeFactory(const TypePtr& type) : type_(type) {}
@@ -76,6 +81,9 @@ class TypeParserTest : public ::testing::Test {
     registerCustomType(
         "timestamp with time zone",
         std::make_unique<const TypeFactory>(TIMESTAMP_WITH_TIME_ZONE()));
+    registerCustomType(
+        "time with time zone",
+        std::make_unique<const TypeFactory>(TIME_WITH_TIME_ZONE()));
   }
 };
 
@@ -106,6 +114,10 @@ TEST_F(TypeParserTest, time) {
   ASSERT_EQ(*parseType("time"), *TIME());
 }
 
+TEST_F(TypeParserTest, timeWithTimeZoneType) {
+  ASSERT_EQ(*parseType("time with time zone"), *TIME_WITH_TIME_ZONE());
+}
+
 TEST_F(TypeParserTest, arrayType) {
   ASSERT_EQ(*parseType("array(bigint)"), *ARRAY(BIGINT()));
 
@@ -269,11 +281,6 @@ TEST_F(TypeParserTest, rowType) {
 }
 
 TEST_F(TypeParserTest, typesWithSpaces) {
-  // Type is not registered.
-  VELOX_ASSERT_UNSUPPORTED_THROW(
-      parseType("row(time time with time zone)"),
-      "Failed to parse type [time with time zone]. Type not registered.");
-
   ASSERT_EQ(
       *parseType("timestamp with time zone"), *TIMESTAMP_WITH_TIME_ZONE());
 
@@ -285,10 +292,6 @@ TEST_F(TypeParserTest, typesWithSpaces) {
   ASSERT_EQ(
       *parseType("row(double double precision)"), *ROW({"double"}, {DOUBLE()}));
 
-  VELOX_ASSERT_THROW(
-      parseType("row(time with time zone)"),
-      "Failed to parse type [with time zone]");
-
   ASSERT_EQ(*parseType("row(double precision)"), *ROW({DOUBLE()}));
 
   ASSERT_EQ(

velox/functions/prestosql/types/tests/CMakeLists.txt

@@ -18,6 +18,7 @@ add_executable(
   HyperLogLogTypeTest.cpp
   JsonTypeTest.cpp
   TimestampWithTimeZoneTypeTest.cpp
+  TimeWithTimezoneTypeTest.cpp
   TDigestTypeTest.cpp
   QDigestTypeTest.cpp
   TypeTestBase.cpp