feat: add partition field/partition spec (#54)

- Implement the API for partition spec/field.
- add pure virtual classes for transform

Author: gty404

src/iceberg/CMakeLists.txt

@@ -23,6 +23,9 @@ set(ICEBERG_SOURCES
     schema.cc
     schema_field.cc
     schema_internal.cc
+    partition_field.cc
+    partition_spec.cc
+    transform.cc
     type.cc)
 
 set(ICEBERG_STATIC_BUILD_INTERFACE_LIBS)

src/iceberg/error.h

@@ -34,6 +34,7 @@ enum class ErrorKind {
   kCommitStateUnknown,
   kInvalidSchema,
   kInvalidArgument,
+  kNotSupported,
 };
 
 /// \brief Error with a kind and a message.

src/iceberg/exception.h

@@ -38,4 +38,11 @@ class ICEBERG_EXPORT IcebergError : public std::runtime_error {
   explicit IcebergError(const std::string& what) : std::runtime_error(what) {}
 };
 
+#define ICEBERG_CHECK(condition, ...)                        \
+  do {                                                       \
+    if (!(condition)) [[unlikely]] {                         \
+      throw iceberg::IcebergError(std::format(__VA_ARGS__)); \
+    }                                                        \
+  } while (0)
+
 }  // namespace iceberg

src/iceberg/partition_field.cc

@@ -0,0 +1,56 @@
+/*
+ * 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 "iceberg/partition_field.h"
+
+#include <format>
+
+#include "iceberg/transform.h"
+#include "iceberg/type.h"
+#include "iceberg/util/formatter.h"
+
+namespace iceberg {
+
+PartitionField::PartitionField(int32_t source_id, int32_t field_id, std::string name,
+                               std::shared_ptr<TransformFunction> transform)
+    : source_id_(source_id),
+      field_id_(field_id),
+      name_(std::move(name)),
+      transform_(std::move(transform)) {}
+
+int32_t PartitionField::source_id() const { return source_id_; }
+
+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::string PartitionField::ToString() const {
+  return std::format("{} ({} {}({}))", name_, field_id_, *transform_, source_id_);
+}
+
+bool PartitionField::Equals(const PartitionField& other) const {
+  return source_id_ == other.source_id_ && field_id_ == other.field_id_ &&
+         name_ == other.name_ && *transform_ == *other.transform_;
+}
+
+}  // namespace iceberg

src/iceberg/partition_field.h

@@ -0,0 +1,80 @@
+/*
+ * 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.
+ */
+
+#pragma once
+
+/// \file iceberg/partition_field.h
+/// A partition field in a partition spec
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/type_fwd.h"
+#include "iceberg/util/formattable.h"
+
+namespace iceberg {
+
+/// \brief a field with its transform.
+class ICEBERG_EXPORT PartitionField : public util::Formattable {
+ public:
+  /// \brief Construct a field.
+  /// \param[in] source_id The source field ID.
+  /// \param[in] field_id The partition field ID.
+  /// \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);
+
+  /// \brief Get the source field ID.
+  int32_t source_id() const;
+
+  /// \brief Get the partition field ID.
+  int32_t field_id() const;
+
+  /// \brief Get the partition field name.
+  std::string_view name() const;
+
+  /// \brief Get the transform type.
+  std::shared_ptr<TransformFunction> const& transform() const;
+
+  std::string ToString() const override;
+
+  friend bool operator==(const PartitionField& lhs, const PartitionField& rhs) {
+    return lhs.Equals(rhs);
+  }
+
+  friend bool operator!=(const PartitionField& lhs, const PartitionField& rhs) {
+    return !(lhs == rhs);
+  }
+
+ private:
+  /// \brief Compare two fields for equality.
+  [[nodiscard]] bool Equals(const PartitionField& other) const;
+
+  int32_t source_id_;
+  int32_t field_id_;
+  std::string name_;
+  std::shared_ptr<TransformFunction> transform_;
+};
+
+}  // namespace iceberg

src/iceberg/partition_spec.cc

@@ -0,0 +1,54 @@
+/*
+ * 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 "iceberg/partition_spec.h"
+
+#include <format>
+
+#include "iceberg/schema.h"
+#include "iceberg/type.h"
+#include "iceberg/util/formatter.h"
+
+namespace iceberg {
+
+PartitionSpec::PartitionSpec(std::shared_ptr<Schema> schema, int32_t spec_id,
+                             std::vector<PartitionField> fields)
+    : schema_(std::move(schema)), spec_id_(spec_id), fields_(std::move(fields)) {}
+
+const std::shared_ptr<Schema>& PartitionSpec::schema() const { return schema_; }
+
+int32_t PartitionSpec::spec_id() const { return spec_id_; }
+
+std::span<const PartitionField> PartitionSpec::fields() const { return fields_; }
+
+std::string PartitionSpec::ToString() const {
+  std::string repr = std::format("partition_spec[spec_id<{}>,\n", spec_id_);
+  for (const auto& field : fields_) {
+    std::format_to(std::back_inserter(repr), "  {}\n", field);
+  }
+  repr += "]";
+  return repr;
+}
+
+bool PartitionSpec::Equals(const PartitionSpec& other) const {
+  return *schema_ == *other.schema_ && spec_id_ == other.spec_id_ &&
+         fields_ == other.fields_;
+}
+
+}  // namespace iceberg

src/iceberg/partition_spec.h

@@ -0,0 +1,71 @@
+/*
+ * 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.
+ */
+
+#pragma once
+
+/// \file iceberg/partition_spec.h
+/// Partition specs for Iceberg tables.
+
+#include <cstdint>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/partition_field.h"
+#include "iceberg/util/formattable.h"
+
+namespace iceberg {
+
+/// \brief A partition spec for a Table.
+///
+/// A partition spec is a list of partition fields, along with a unique integer ID.  A
+/// Table may have different partition specs over its lifetime due to partition spec
+/// evolution.
+class ICEBERG_EXPORT PartitionSpec : public util::Formattable {
+ public:
+  PartitionSpec(std::shared_ptr<Schema> schema, int32_t spec_id,
+                std::vector<PartitionField> fields);
+  /// \brief Get the table schema
+  const std::shared_ptr<Schema>& schema() const;
+  /// \brief Get the spec ID.
+  int32_t spec_id() const;
+  /// \brief Get a view of the partition fields.
+  std::span<const PartitionField> fields() const;
+
+  std::string ToString() const override;
+
+  friend bool operator==(const PartitionSpec& lhs, const PartitionSpec& rhs) {
+    return lhs.Equals(rhs);
+  }
+
+  friend bool operator!=(const PartitionSpec& lhs, const PartitionSpec& rhs) {
+    return !(lhs == rhs);
+  }
+
+ private:
+  /// \brief Compare two partition specs for equality.
+  [[nodiscard]] bool Equals(const PartitionSpec& other) const;
+
+  std::shared_ptr<Schema> schema_;
+  const int32_t spec_id_;
+  std::vector<PartitionField> fields_;
+};
+
+}  // namespace iceberg

src/iceberg/transform.cc

@@ -0,0 +1,75 @@
+/*
+ * 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 "iceberg/transform.h"
+
+#include <format>
+
+namespace iceberg {
+
+namespace {
+/// \brief Get the relative transform name
+constexpr std::string_view ToString(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";
+    default:
+      return "invalid";
+  }
+}
+}  // 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_;
+}
+
+IdentityTransformFunction::IdentityTransformFunction()
+    : TransformFunction(TransformType::kIdentity) {}
+
+expected<ArrowArray, Error> IdentityTransformFunction::Transform(
+    const ArrowArray& input) {
+  return unexpected<Error>({.kind = ErrorKind::kNotSupported,
+                            .message = "IdentityTransformFunction::Transform"});
+}
+
+}  // namespace iceberg