feat: transform human string for literal

src/iceberg/CMakeLists.txt

@@ -95,6 +95,7 @@ set(ICEBERG_SOURCES
     util/snapshot_util.cc
     util/temporal_util.cc
     util/timepoint.cc
+    util/transform_util.cc
     util/truncate_util.cc
     util/type_util.cc
     util/uuid.cc)

src/iceberg/meson.build

@@ -116,6 +116,7 @@ iceberg_sources = files(
     'util/snapshot_util.cc',
     'util/temporal_util.cc',
     'util/timepoint.cc',
+    'util/transform_util.cc',
     'util/truncate_util.cc',
     'util/type_util.cc',
     'util/uuid.cc',

src/iceberg/test/CMakeLists.txt

@@ -64,6 +64,7 @@ add_iceberg_test(schema_test
                  schema_util_test.cc
                  sort_field_test.cc
                  sort_order_test.cc
+                 transform_human_string_test.cc
                  transform_test.cc
                  type_test.cc)
 

src/iceberg/test/eval_expr_test.cc

@@ -161,7 +161,7 @@ TEST_F(BoundExpressionTest, YearTransform) {
   // Evaluate (2021)
   ICEBERG_UNWRAP_OR_FAIL(auto result, bound_transform->Evaluate(*struct_like));
   EXPECT_FALSE(result.IsNull());
-  EXPECT_EQ(std::get<int32_t>(result.value()), 2021);  // Year value
+  EXPECT_EQ(std::get<int32_t>(result.value()), 2021 - 1970);  // Year value
 }
 
 TEST_F(BoundExpressionTest, MonthTransform) {

src/iceberg/test/meson.build

@@ -40,6 +40,7 @@ iceberg_tests = {
             'schema_util_test.cc',
             'sort_field_test.cc',
             'sort_order_test.cc',
+            'transform_human_string_test.cc',
             'transform_test.cc',
             'type_test.cc',
         ),

src/iceberg/test/transform_human_string_test.cc

@@ -0,0 +1,187 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 <memory>
+#include <string>
+
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+#include "iceberg/expression/literal.h"
+#include "iceberg/test/matchers.h"
+#include "iceberg/transform.h"
+
+namespace iceberg {
+
+struct HumanStringTestParam {
+  std::string test_name;
+  std::shared_ptr<Type> source_type;
+  Literal literal;
+  std::vector<std::string> expecteds;
+};
+
+class IdentityTest : public ::testing::TestWithParam<HumanStringTestParam> {
+ protected:
+  std::vector<std::shared_ptr<Transform>> transforms_{{Transform::Identity()}};
+};
+
+TEST_P(IdentityTest, ToHumanString) {
+  const auto& param = GetParam();
+  for (int32_t i = 0; i < transforms_.size(); ++i) {
+    EXPECT_THAT(transforms_[i]->ToHumanString(param.literal),
+                HasValue(::testing::Eq(param.expecteds[i])));
+  }
+}
+
+INSTANTIATE_TEST_SUITE_P(
+    IdentityTestCases, IdentityTest,
+    ::testing::Values(
+        HumanStringTestParam{.test_name = "Null",
+                             .literal = Literal::Null(std::make_shared<IntType>()),
+                             .expecteds{"null"}},
+        HumanStringTestParam{.test_name = "Binary",
+                             .literal = Literal::Binary(std::vector<uint8_t>{1, 2, 3}),
+                             .expecteds{"AQID"}},
+        HumanStringTestParam{.test_name = "Fixed",
+                             .literal = Literal::Fixed(std::vector<uint8_t>{1, 2, 3}),
+                             .expecteds{"AQID"}},
+        HumanStringTestParam{.test_name = "Date",
+                             .literal = Literal::Date(17501),
+                             .expecteds{"2017-12-01"}},
+        HumanStringTestParam{.test_name = "Time",
+                             .literal = Literal::Time(36775038194),
+                             .expecteds{"10:12:55.038194"}},
+        HumanStringTestParam{.test_name = "TimestampWithZone",
+                             .literal = Literal::TimestampTz(1512151975038194),
+                             .expecteds{"2017-12-01T18:12:55.038194+00:00"}},
+        HumanStringTestParam{.test_name = "TimestampWithoutZone",
+                             .literal = Literal::Timestamp(1512123175038194),
+                             .expecteds{"2017-12-01T10:12:55.038194"}},
+        HumanStringTestParam{.test_name = "Long",
+                             .literal = Literal::Long(-1234567890000L),
+                             .expecteds{"-1234567890000"}},
+        HumanStringTestParam{.test_name = "String",
+                             .literal = Literal::String("a/b/c=d"),
+                             .expecteds{"a/b/c=d"}}),
+    [](const ::testing::TestParamInfo<HumanStringTestParam>& info) {
+      return info.param.test_name;
+    });
+
+class DateTest : public ::testing::TestWithParam<HumanStringTestParam> {
+ protected:
+  std::vector<std::shared_ptr<Transform>> transforms_{
+      Transform::Year(), Transform::Month(), Transform::Day()};
+};
+
+TEST_P(DateTest, ToHumanString) {
+  const auto& param = GetParam();
+
+  for (uint32_t i = 0; i < transforms_.size(); i++) {
+    ICEBERG_UNWRAP_OR_FAIL(auto trans_func,
+                           transforms_[i]->Bind(std::make_shared<DateType>()));
+    ICEBERG_UNWRAP_OR_FAIL(auto literal, trans_func->Transform(param.literal));
+    EXPECT_THAT(transforms_[i]->ToHumanString(literal),
+                HasValue(::testing::Eq(param.expecteds[i])));
+  }
+}
+
+INSTANTIATE_TEST_SUITE_P(
+    DateTestCases, DateTest,
+    ::testing::Values(
+        HumanStringTestParam{.test_name = "Date",
+                             .literal = Literal::Date(17501),
+                             .expecteds = {"2017", "2017-12", "2017-12-01"}},
+        HumanStringTestParam{.test_name = "NegativeDate",
+                             .literal = Literal::Date(-2),
+                             .expecteds = {"1969", "1969-12", "1969-12-30"}},
+        HumanStringTestParam{.test_name = "DateLowerBound",
+                             .literal = Literal::Date(0),
+                             .expecteds = {"1970", "1970-01", "1970-01-01"}},
+        HumanStringTestParam{.test_name = "NegativeDateLowerBound",
+                             .literal = Literal::Date(-365),
+                             .expecteds = {"1969", "1969-01", "1969-01-01"}},
+        HumanStringTestParam{.test_name = "NegativeDateUpperBound",
+                             .literal = Literal::Date(-1),
+                             .expecteds = {"1969", "1969-12", "1969-12-31"}},
+        HumanStringTestParam{.test_name = "Null",
+                             .literal = Literal::Null(std::make_shared<DateType>()),
+                             .expecteds = {"null", "null", "null"}}),
+    [](const ::testing::TestParamInfo<HumanStringTestParam>& info) {
+      return info.param.test_name;
+    });
+
+class TimestampTest : public ::testing::TestWithParam<HumanStringTestParam> {
+ protected:
+  std::vector<std::shared_ptr<Transform>> transforms_{
+      Transform::Year(), Transform::Month(), Transform::Day(), Transform::Hour()};
+};
+
+TEST_P(TimestampTest, ToHumanString) {
+  const auto& param = GetParam();
+  for (uint32_t i = 0; i < transforms_.size(); i++) {
+    ICEBERG_UNWRAP_OR_FAIL(auto trans_func, transforms_[i]->Bind(param.source_type));
+    ICEBERG_UNWRAP_OR_FAIL(auto literal, trans_func->Transform(param.literal));
+    EXPECT_THAT(transforms_[i]->ToHumanString(literal),
+                HasValue(::testing::Eq(param.expecteds[i])));
+  }
+}
+
+INSTANTIATE_TEST_SUITE_P(
+    TimestampTestCases, TimestampTest,
+    ::testing::Values(
+        HumanStringTestParam{
+            .test_name = "Timestamp",
+            .source_type = std::make_shared<TimestampType>(),
+            .literal = Literal::Timestamp(1512123175038194),
+            .expecteds = {"2017", "2017-12", "2017-12-01", "2017-12-01-10"}},
+        HumanStringTestParam{
+            .test_name = "NegativeTimestamp",
+            .source_type = std::make_shared<TimestampType>(),
+            .literal = Literal::Timestamp(-136024961806),
+            .expecteds = {"1969", "1969-12", "1969-12-30", "1969-12-30-10"}},
+        HumanStringTestParam{
+            .test_name = "TimestampLowerBound",
+            .source_type = std::make_shared<TimestampType>(),
+            .literal = Literal::Timestamp(0),
+            .expecteds = {"1970", "1970-01", "1970-01-01", "1970-01-01-00"}},
+        HumanStringTestParam{
+            .test_name = "NegativeTimestampLowerBound",
+            .source_type = std::make_shared<TimestampType>(),
+            .literal = Literal::Timestamp(-172800000000),
+            .expecteds = {"1969", "1969-12", "1969-12-30", "1969-12-30-00"},
+        },
+        HumanStringTestParam{
+            .test_name = "NegativeTimestampUpperBound",
+            .source_type = std::make_shared<TimestampType>(),
+            .literal = Literal::Timestamp(-1),
+            .expecteds = {"1969", "1969-12", "1969-12-31", "1969-12-31-23"}},
+        HumanStringTestParam{
+            .test_name = "TimestampTz",
+            .source_type = std::make_shared<TimestampTzType>(),
+            .literal = Literal::TimestampTz(1512151975038194),
+            .expecteds = {"2017", "2017-12", "2017-12-01", "2017-12-01-18"}},
+        HumanStringTestParam{.test_name = "Null",
+                             .source_type = std::make_shared<TimestampType>(),
+                             .literal = Literal::Null(std::make_shared<TimestampType>()),
+                             .expecteds = {"null", "null", "null", "null"}}),
+    [](const ::testing::TestParamInfo<HumanStringTestParam>& info) {
+      return info.param.test_name;
+    });
+
+}  // namespace iceberg

src/iceberg/test/transform_test.cc

@@ -459,7 +459,7 @@ INSTANTIATE_TEST_SUITE_P(
                                                                 .hour = 11,
                                                                 .minute = 43,
                                                                 .second = 20})),
-                       .expected = Literal::Int(2021)},
+                       .expected = Literal::Int(2021 - 1970)},
         TransformParam{
             .str = "TimestampTz",
             // 2021-01-01T07:43:20+08:00, which is 2020-12-31T23:43:20Z
@@ -472,12 +472,12 @@ INSTANTIATE_TEST_SUITE_P(
                                                        .minute = 43,
                                                        .second = 20,
                                                        .tz_offset_minutes = 480})),
-            .expected = Literal::Int(2020)},
+            .expected = Literal::Int(2020 - 1970)},
         TransformParam{.str = "Date",
                        .source_type = iceberg::date(),
                        .source = Literal::Date(TemporalTestHelper::CreateDate(
                            {.year = 2052, .month = 2, .day = 20})),
-                       .expected = Literal::Int(2052)}),
+                       .expected = Literal::Int(2052 - 1970)}),
     [](const ::testing::TestParamInfo<TransformParam>& info) { return info.param.str; });
 
 class MonthTransformTest : public ::testing::TestWithParam<TransformParam> {};
@@ -2061,7 +2061,8 @@ TEST_F(TransformProjectStrictTest, YearStrictLessThan) {
           std::move(projected));
   EXPECT_EQ(unbound_projected->op(), Expression::Operation::kLt);
   EXPECT_EQ(unbound_projected->literals().size(), 1);
-  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()), 2021);
+  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()),
+            2021 - 1970);
 }
 
 TEST_F(TransformProjectStrictTest, YearStrictGreaterThanOrEqual) {
@@ -2085,7 +2086,8 @@ TEST_F(TransformProjectStrictTest, YearStrictGreaterThanOrEqual) {
           std::move(projected));
   EXPECT_EQ(unbound_projected->op(), Expression::Operation::kGt);
   EXPECT_EQ(unbound_projected->literals().size(), 1);
-  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()), 2020);
+  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()),
+            2020 - 1970);
 }
 
 TEST_F(TransformProjectStrictTest, YearStrictNotEqual) {
@@ -2109,7 +2111,8 @@ TEST_F(TransformProjectStrictTest, YearStrictNotEqual) {
           std::move(projected));
   EXPECT_EQ(unbound_projected->op(), Expression::Operation::kNotEq);
   EXPECT_EQ(unbound_projected->literals().size(), 1);
-  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()), 2021);
+  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()),
+            2021 - 1970);
 }
 
 TEST_F(TransformProjectStrictTest, MonthStrictLessThan) {
@@ -2218,7 +2221,8 @@ TEST_F(TransformProjectStrictTest, YearStrictUpperBound) {
           std::move(projected));
   EXPECT_EQ(unbound_projected->op(), Expression::Operation::kLt);
   EXPECT_EQ(unbound_projected->literals().size(), 1);
-  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()), 2018);
+  EXPECT_EQ(std::get<int32_t>(unbound_projected->literals().front().value()),
+            2018 - 1970);
 }
 
 TEST_F(TransformProjectStrictTest, VoidStrictReturnsNull) {

src/iceberg/transform.cc

@@ -31,6 +31,7 @@
 #include "iceberg/util/checked_cast.h"
 #include "iceberg/util/macros.h"
 #include "iceberg/util/projection_util_internal.h"
+#include "iceberg/util/transform_util.h"
 
 namespace iceberg {
 namespace {
@@ -366,6 +367,50 @@ Result<std::unique_ptr<UnboundPredicate>> Transform::ProjectStrict(
   std::unreachable();
 }
 
+Result<std::string> Transform::ToHumanString(const Literal& value) {
+  if (value.IsNull()) {
+    return "null";
+  }
+
+  switch (transform_type_) {
+    case TransformType::kYear:
+      return TransformUtil::HumanYear(std::get<int32_t>(value.value()));
+    case TransformType::kMonth:
+      return TransformUtil::HumanMonth(std::get<int32_t>(value.value()));
+    case TransformType::kDay:
+      return TransformUtil::HumanDay(std::get<int32_t>(value.value()));
+    case TransformType::kHour:
+      return TransformUtil::HumanHour(std::get<int32_t>(value.value()));
+    default: {
+      switch (value.type()->type_id()) {
+        case TypeId::kDate:
+          return TransformUtil::HumanDay(std::get<int32_t>(value.value()));
+        case TypeId::kTime:
+          return TransformUtil::HumanTime(std::get<int64_t>(value.value()));
+        case TypeId::kTimestamp:
+          return TransformUtil::HumanTimestamp(std::get<int64_t>(value.value()));
+        case TypeId::kTimestampTz:
+          return TransformUtil::HumanTimestampWithZone(std::get<int64_t>(value.value()));
+        case TypeId::kFixed:
+        case TypeId::kBinary: {
+          const auto& binary_data = std::get<std::vector<uint8_t>>(value.value());
+          return TransformUtil::Base64Encode(
+              {reinterpret_cast<const char*>(binary_data.data()), binary_data.size()});
+        }
+        case TypeId::kDecimal: {
+          const auto& decimal_type = internal::checked_cast<DecimalType&>(*value.type());
+          const auto& decimal = std::get<::iceberg::Decimal>(value.value());
+          return decimal.ToString(decimal_type.scale());
+        }
+        case TypeId::kString:
+          return std::get<std::string>(value.value());
+        default:
+          return value.ToString();
+      }
+    }
+  }
+}
+
 bool TransformFunction::Equals(const TransformFunction& other) const {
   return transform_type_ == other.transform_type_ && *source_type_ == *other.source_type_;
 }

src/iceberg/transform.h

@@ -194,6 +194,12 @@ class ICEBERG_EXPORT Transform : public util::Formattable {
   Result<std::unique_ptr<UnboundPredicate>> ProjectStrict(
       std::string_view name, const std::shared_ptr<BoundPredicate>& predicate);
 
+  /// \brief Returns a human-readable String representation of a transformed value.
+  ///
+  /// \param value The literal value to be transformed.
+  /// @return a human-readable String representation of the value
+  Result<std::string> ToHumanString(const Literal& value);
+
   /// \brief Returns a string representation of this transform (e.g., "bucket[16]").
   std::string ToString() const override;
 

src/iceberg/util/meson.build

@@ -36,6 +36,7 @@ install_headers(
         'string_util.h',
         'temporal_util.h',
         'timepoint.h',
+        'transform_util.h',
         'truncate_util.h',
         'type_util.h',
         'uuid.h',

src/iceberg/util/temporal_util.cc

@@ -68,14 +68,14 @@ template <>
 Result<Literal> ExtractYearImpl<TypeId::kDate>(const Literal& literal) {
   auto value = std::get<int32_t>(literal.value());
   auto ymd = DateToYmd(value);
-  return Literal::Int(static_cast<int32_t>(ymd.year()));
+  return Literal::Int((ymd.year() - kEpochYmd.year()).count());
 }
 
 template <>
 Result<Literal> ExtractYearImpl<TypeId::kTimestamp>(const Literal& literal) {
   auto value = std::get<int64_t>(literal.value());
   auto ymd = TimestampToYmd(value);
-  return Literal::Int(static_cast<int32_t>(ymd.year()));
+  return Literal::Int((ymd.year() - kEpochYmd.year()).count());
 }
 
 template <>