feat: transform function

Author: gty404

src/iceberg/CMakeLists.txt

@@ -31,6 +31,7 @@ set(ICEBERG_SOURCES
     statistics_file.cc
     table_metadata.cc
     transform.cc
+    transform_function.cc
     type.cc)
 
 set(ICEBERG_STATIC_BUILD_INTERFACE_LIBS)

src/iceberg/json_internal.cc

@@ -85,7 +85,7 @@ nlohmann::json ToJson(const SortOrder& sort_order) {
 expected<std::unique_ptr<SortField>, Error> SortFieldFromJson(
     const nlohmann::json& json) {
   TRY_ASSIGN(transform_str, GetJsonValue<std::string>(json, kTransform));
-  TRY_ASSIGN(transform, TransformFunctionFromString(transform_str));
+  TRY_ASSIGN(transform, TransformFromString(transform_str));
   TRY_ASSIGN(source_id, GetJsonValue<int32_t>(json, kSourceId));
   TRY_ASSIGN(direction_str, GetJsonValue<std::string>(json, kDirection));
   TRY_ASSIGN(direction, SortDirectionFromString(direction_str));

src/iceberg/partition_field.cc

@@ -28,7 +28,7 @@
 namespace iceberg {
 
 PartitionField::PartitionField(int32_t source_id, int32_t field_id, std::string name,
-                               std::shared_ptr<TransformFunction> transform)
+                               std::shared_ptr<Transform> transform)
     : source_id_(source_id),
       field_id_(field_id),
       name_(std::move(name)),
@@ -40,9 +40,7 @@ int32_t PartitionField::field_id() const { return field_id_; }
 
 std::string_view PartitionField::name() const { return name_; }
 
-std::shared_ptr<TransformFunction> const& PartitionField::transform() const {
-  return transform_;
-}
+std::shared_ptr<Transform> const& PartitionField::transform() const { return transform_; }
 
 std::string PartitionField::ToString() const {
   return std::format("{} ({} {}({}))", name_, field_id_, *transform_, source_id_);

src/iceberg/partition_field.h

@@ -43,7 +43,7 @@ class ICEBERG_EXPORT PartitionField : public util::Formattable {
   /// \param[in] name The partition field name.
   /// \param[in] transform The transform function.
   PartitionField(int32_t source_id, int32_t field_id, std::string name,
-                 std::shared_ptr<TransformFunction> transform);
+                 std::shared_ptr<Transform> transform);
 
   /// \brief Get the source field ID.
   int32_t source_id() const;
@@ -55,7 +55,7 @@ class ICEBERG_EXPORT PartitionField : public util::Formattable {
   std::string_view name() const;
 
   /// \brief Get the transform type.
-  std::shared_ptr<TransformFunction> const& transform() const;
+  std::shared_ptr<Transform> const& transform() const;
 
   std::string ToString() const override;
 
@@ -74,7 +74,7 @@ class ICEBERG_EXPORT PartitionField : public util::Formattable {
   int32_t source_id_;
   int32_t field_id_;
   std::string name_;
-  std::shared_ptr<TransformFunction> transform_;
+  std::shared_ptr<Transform> transform_;
 };
 
 }  // namespace iceberg

src/iceberg/sort_field.cc

@@ -27,7 +27,7 @@
 
 namespace iceberg {
 
-SortField::SortField(int32_t source_id, std::shared_ptr<TransformFunction> transform,
+SortField::SortField(int32_t source_id, std::shared_ptr<Transform> transform,
                      SortDirection direction, NullOrder null_order)
     : source_id_(source_id),
       transform_(std::move(transform)),
@@ -36,9 +36,7 @@ SortField::SortField(int32_t source_id, std::shared_ptr<TransformFunction> trans
 
 int32_t SortField::source_id() const { return source_id_; }
 
-std::shared_ptr<TransformFunction> const& SortField::transform() const {
-  return transform_;
-}
+std::shared_ptr<Transform> const& SortField::transform() const { return transform_; }
 
 SortDirection SortField::direction() const { return direction_; }
 

src/iceberg/sort_field.h

@@ -98,14 +98,14 @@ class ICEBERG_EXPORT SortField : public util::Formattable {
   /// \param[in] transform The transform function.
   /// \param[in] direction The sort direction.
   /// \param[in] null_order The null order.
-  SortField(int32_t source_id, std::shared_ptr<TransformFunction> transform,
+  SortField(int32_t source_id, std::shared_ptr<Transform> transform,
             SortDirection direction, NullOrder null_order);
 
   /// \brief Get the source field ID.
   int32_t source_id() const;
 
   /// \brief Get the transform type.
-  const std::shared_ptr<TransformFunction>& transform() const;
+  const std::shared_ptr<Transform>& transform() const;
 
   /// \brief Get the sort direction.
   SortDirection direction() const;
@@ -128,7 +128,7 @@ class ICEBERG_EXPORT SortField : public util::Formattable {
   [[nodiscard]] bool Equals(const SortField& other) const;
 
   int32_t source_id_;
-  std::shared_ptr<TransformFunction> transform_;
+  std::shared_ptr<Transform> transform_;
   SortDirection direction_;
   NullOrder null_order_;
 };

src/iceberg/transform.cc

@@ -21,65 +21,113 @@
 
 #include <format>
 
+#include "iceberg/transform_function.h"
+#include "iceberg/type.h"
+
 namespace iceberg {
 
-namespace {
-/// \brief Get the relative transform name
-constexpr std::string_view ToString(TransformType type) {
-  switch (type) {
-    case TransformType::kUnknown:
-      return "unknown";
+std::shared_ptr<Transform> Transform::Identity() {
+  static auto instance = std::make_shared<Transform>(TransformType::kIdentity);
+  return instance;
+}
+
+Transform::Transform(TransformType transform_type) : transform_type_(transform_type) {}
+
+Transform::Transform(TransformType transform_type, int32_t param)
+    : transform_type_(transform_type), param_(param) {}
+
+TransformType Transform::transform_type() const { return transform_type_; }
+
+expected<std::unique_ptr<TransformFunction>, Error> Transform::Bind(
+    const std::shared_ptr<Type>& source_type) const {
+  auto type_str = TransformTypeToString(transform_type_);
+
+  switch (transform_type_) {
     case TransformType::kIdentity:
-      return "identity";
-    case TransformType::kBucket:
-      return "bucket";
-    case TransformType::kTruncate:
-      return "truncate";
+      return std::make_unique<IdentityTransform>(source_type);
+
+    case TransformType::kBucket: {
+      if (auto param = std::get_if<int32_t>(&param_)) {
+        return std::make_unique<BucketTransform>(source_type, *param);
+      }
+      return unexpected<Error>({
+          .kind = ErrorKind::kInvalidArgument,
+          .message = std::format(
+              "Bucket requires int32 param, none found in transform '{}'", type_str),
+      });
+    }
+
+    case TransformType::kTruncate: {
+      if (auto param = std::get_if<int32_t>(&param_)) {
+        return std::make_unique<TruncateTransform>(source_type, *param);
+      }
+      return unexpected<Error>({
+          .kind = ErrorKind::kInvalidArgument,
+          .message = std::format(
+              "Truncate requires int32 param, none found in transform '{}'", type_str),
+      });
+    }
+
     case TransformType::kYear:
-      return "year";
+      return std::make_unique<YearTransform>(source_type);
     case TransformType::kMonth:
-      return "month";
+      return std::make_unique<MonthTransform>(source_type);
     case TransformType::kDay:
-      return "day";
+      return std::make_unique<DayTransform>(source_type);
     case TransformType::kHour:
-      return "hour";
+      return std::make_unique<HourTransform>(source_type);
     case TransformType::kVoid:
-      return "void";
+      return std::make_unique<VoidTransform>(source_type);
+
     default:
-      return "invalid";
+      return unexpected<Error>({
+          .kind = ErrorKind::kNotSupported,
+          .message = std::format("Unsupported transform type: '{}'", type_str),
+      });
   }
 }
-}  // namespace
-
-TransformFunction::TransformFunction(TransformType type) : transform_type_(type) {}
-
-TransformType TransformFunction::transform_type() const { return transform_type_; }
 
-std::string TransformFunction::ToString() const {
-  return std::format("{}", iceberg::ToString(transform_type_));
+bool TransformFunction::Equals(const TransformFunction& other) const {
+  return transform_type_ == other.transform_type_ && *source_type_ == *other.source_type_;
 }
 
-bool TransformFunction::Equals(const TransformFunction& other) const {
-  return transform_type_ == other.transform_type_;
+std::string Transform::ToString() const {
+  switch (transform_type_) {
+    case TransformType::kIdentity:
+    case TransformType::kYear:
+    case TransformType::kMonth:
+    case TransformType::kDay:
+    case TransformType::kHour:
+    case TransformType::kVoid:
+    case TransformType::kUnknown:
+      return std::format("{}", TransformTypeToString(transform_type_));
+    case TransformType::kBucket:
+    case TransformType::kTruncate:
+      return std::format("{}[{}]", TransformTypeToString(transform_type_),
+                         std::get<int32_t>(param_));
+  }
 }
 
-IdentityTransformFunction::IdentityTransformFunction()
-    : TransformFunction(TransformType::kIdentity) {}
+TransformFunction::TransformFunction(TransformType transform_type,
+                                     std::shared_ptr<Type> source_type)
+    : transform_type_(transform_type), source_type_(std::move(source_type)) {}
+
+TransformType TransformFunction::transform_type() const { return transform_type_; }
+
+std::shared_ptr<Type> const& TransformFunction::source_type() const {
+  return source_type_;
+}
 
-expected<ArrowArray, Error> IdentityTransformFunction::Transform(
-    const ArrowArray& input) {
-  return unexpected<Error>({.kind = ErrorKind::kNotSupported,
-                            .message = "IdentityTransformFunction::Transform"});
+bool Transform::Equals(const Transform& other) const {
+  return transform_type_ == other.transform_type_ && param_ == other.param_;
 }
 
-expected<std::unique_ptr<TransformFunction>, Error> TransformFunctionFromString(
-    std::string_view str) {
+expected<std::unique_ptr<Transform>, Error> TransformFromString(std::string_view str) {
   if (str == "identity") {
-    return std::make_unique<IdentityTransformFunction>();
+    return std::make_unique<Transform>(TransformType::kIdentity);
   }
-  return unexpected<Error>(
-      {.kind = ErrorKind::kInvalidArgument,
-       .message = "Invalid TransformFunction string: " + std::string(str)});
+  return unexpected<Error>({.kind = ErrorKind::kInvalidArgument,
+                            .message = std::format("Invalid Transform string: {}", str)});
 }
 
 }  // namespace iceberg

src/iceberg/transform.h

@@ -23,6 +23,7 @@
 
 #include <cstdint>
 #include <memory>
+#include <variant>
 
 #include "iceberg/arrow_c_data.h"
 #include "iceberg/error.h"
@@ -56,16 +57,98 @@ enum class TransformType {
   kVoid,
 };
 
+/// \brief Get the relative transform name
+constexpr std::string_view TransformTypeToString(TransformType type) {
+  switch (type) {
+    case TransformType::kUnknown:
+      return "unknown";
+    case TransformType::kIdentity:
+      return "identity";
+    case TransformType::kBucket:
+      return "bucket";
+    case TransformType::kTruncate:
+      return "truncate";
+    case TransformType::kYear:
+      return "year";
+    case TransformType::kMonth:
+      return "month";
+    case TransformType::kDay:
+      return "day";
+    case TransformType::kHour:
+      return "hour";
+    case TransformType::kVoid:
+      return "void";
+  }
+}
+
+/// \brief Represents a transform used in partitioning or sorting in Iceberg.
+///
+/// This class supports binding to a source type and instantiating the corresponding
+/// TransformFunction, as well as serialization-friendly introspection.
+class ICEBERG_EXPORT Transform : public util::Formattable {
+ public:
+  /// \brief Returns a shared singleton instance of the Identity transform.
+  ///
+  /// This transform leaves values unchanged and is commonly used for direct partitioning.
+  /// \return A shared pointer to the Identity transform.
+  static std::shared_ptr<Transform> Identity();
+
+  /// \brief Constructs a Transform of the specified type (for non-parametric types).
+  /// \param transform_type The transform type (e.g., identity, year, day).
+  explicit Transform(TransformType transform_type);
+
+  /// \brief Constructs a parameterized Transform (e.g., bucket(16), truncate(4)).
+  /// \param transform_type The transform type.
+  /// \param param The integer parameter associated with the transform.
+  Transform(TransformType transform_type, int32_t param);
+
+  /// \brief Returns the transform type.
+  TransformType transform_type() const;
+
+  /// \brief Binds this transform to a source type, returning a typed TransformFunction.
+  ///
+  /// This creates a concrete transform implementation based on the transform type and
+  /// parameter.
+  /// \param source_type The source column type to bind to.
+  /// \return A TransformFunction instance wrapped in `expected`, or an error on failure.
+  expected<std::unique_ptr<TransformFunction>, Error> Bind(
+      const std::shared_ptr<Type>& source_type) const;
+
+  /// \brief Returns a string representation of this transform (e.g., "bucket[16]").
+  std::string ToString() const override;
+
+  /// \brief Equality comparison.
+  friend bool operator==(const Transform& lhs, const Transform& rhs) {
+    return lhs.Equals(rhs);
+  }
+
+  /// \brief Inequality comparison.
+  friend bool operator!=(const Transform& lhs, const Transform& rhs) {
+    return !(lhs == rhs);
+  }
+
+ private:
+  /// \brief Checks equality with another Transform instance.
+  [[nodiscard]] virtual bool Equals(const Transform& other) const;
+
+  TransformType transform_type_;
+  ///< Optional parameter (e.g., num_buckets, width)
+  std::variant<std::monostate, int32_t> param_;
+};
+
 /// \brief A transform function used for partitioning.
-class ICEBERG_EXPORT TransformFunction : public util::Formattable {
+class ICEBERG_EXPORT TransformFunction {
  public:
-  explicit TransformFunction(TransformType type);
+  virtual ~TransformFunction() = default;
+  TransformFunction(TransformType transform_type, std::shared_ptr<Type> source_type);
   /// \brief Transform an input array to a new array
   virtual expected<ArrowArray, Error> Transform(const ArrowArray& data) = 0;
   /// \brief Get the transform type
-  virtual TransformType transform_type() const;
-
-  std::string ToString() const override;
+  TransformType transform_type() const;
+  /// \brief Get the source type of transform function
+  const std::shared_ptr<Type>& source_type() const;
+  /// \brief Get the result type of transform function
+  virtual expected<std::shared_ptr<Type>, Error> ResultType() const = 0;
 
   friend bool operator==(const TransformFunction& lhs, const TransformFunction& rhs) {
     return lhs.Equals(rhs);
@@ -80,16 +163,10 @@ class ICEBERG_EXPORT TransformFunction : public util::Formattable {
   [[nodiscard]] virtual bool Equals(const TransformFunction& other) const;
 
   TransformType transform_type_;
+  std::shared_ptr<Type> source_type_;
 };
 
-ICEBERG_EXPORT expected<std::unique_ptr<TransformFunction>, Error>
-TransformFunctionFromString(std::string_view str);
-
-class ICEBERG_EXPORT IdentityTransformFunction : public TransformFunction {
- public:
-  IdentityTransformFunction();
-  /// \brief Transform will take an input array and transform it into a new array.
-  expected<ArrowArray, Error> Transform(const ArrowArray& input) override;
-};
+ICEBERG_EXPORT expected<std::unique_ptr<Transform>, Error> TransformFromString(
+    std::string_view str);
 
 }  // namespace iceberg