polish and simplify metadata table design

Author: wgtmac

src/iceberg/CMakeLists.txt

@@ -239,6 +239,7 @@ add_subdirectory(puffin)
 add_subdirectory(row)
 add_subdirectory(update)
 add_subdirectory(util)
+add_subdirectory(inspect)
 add_subdirectory(metrics)
 
 if(ICEBERG_BUILD_BUNDLE)

src/iceberg/inspect/history_table.cc

@@ -21,36 +21,42 @@
 
 #include <memory>
 #include <utility>
+#include <vector>
 
-#include "iceberg/inspect/metadata_table.h"
 #include "iceberg/schema.h"
 #include "iceberg/schema_field.h"
+#include "iceberg/table.h"
 #include "iceberg/table_identifier.h"
 #include "iceberg/type.h"
 
 namespace iceberg {
-
-HistoryTable::HistoryTable(std::shared_ptr<Table> table)
-    : MetadataTable(table, CreateName(table->name())) {}
-
-HistoryTable::~HistoryTable() = default;
-
-std::shared_ptr<Schema> HistoryTable::GetSchema() const {
-  return std::make_shared<Schema>(
-      std::vector<SchemaField>{
-          SchemaField::MakeRequired(1, "made_current_at", timestamp_tz()),
-          SchemaField::MakeRequired(2, "snapshot_id", int64()),
-          SchemaField::MakeOptional(3, "parent_id", int64()),
-          SchemaField::MakeRequired(4, "is_current_ancestor", boolean())},
-      1);
+namespace {
+
+std::shared_ptr<Schema> MakeHistoryTableSchema() {
+  return std::make_shared<Schema>(std::vector<SchemaField>{
+      SchemaField::MakeRequired(1, "made_current_at", timestamp_tz()),
+      SchemaField::MakeRequired(2, "snapshot_id", int64()),
+      SchemaField::MakeOptional(3, "parent_id", int64()),
+      SchemaField::MakeRequired(4, "is_current_ancestor", boolean())});
 }
 
-TableIdentifier HistoryTable::CreateName(const TableIdentifier& source_name) {
+TableIdentifier MakeHistoryTableName(const TableIdentifier& source_name) {
   return TableIdentifier{.ns = source_name.ns, .name = source_name.name + ".history"};
 }
 
+}  // namespace
+
+HistoryTable::HistoryTable(std::shared_ptr<Table> table)
+    : MetadataTable(table, MakeHistoryTableName(table->name()),
+                    MakeHistoryTableSchema()) {}
+
+HistoryTable::~HistoryTable() = default;
+
 Result<std::unique_ptr<HistoryTable>> HistoryTable::Make(std::shared_ptr<Table> table) {
-  return std::unique_ptr<HistoryTable>(new HistoryTable(table));
+  if (table == nullptr) [[unlikely]] {
+    return InvalidArgument("Table cannot be null");
+  }
+  return std::unique_ptr<HistoryTable>(new HistoryTable(std::move(table)));
 }
 
 }  // namespace iceberg

src/iceberg/inspect/history_table.h

@@ -24,36 +24,21 @@
 #include "iceberg/iceberg_export.h"
 #include "iceberg/inspect/metadata_table.h"
 #include "iceberg/result.h"
-#include "iceberg/table.h"
+#include "iceberg/type_fwd.h"
 
 namespace iceberg {
 
-/// \brief History metadata table
-///
-/// History is based on the table's snapshot log, which logs each update
-/// to the table's current snapshot. Each row has columns:
-/// - made_current_at (long, timestamp)
-/// - snapshot_id (long)
-/// - parent_id (long, optional)
-/// - is_current_ancestor (bool)
+/// \brief History metadata table.
 class ICEBERG_EXPORT HistoryTable : public MetadataTable {
  public:
-  /// \brief Create a HistoryTable from table metadata
-  ///
-  /// \param[in] table The source table
-  /// \return A HistoryTable instance or error status
   static Result<std::unique_ptr<HistoryTable>> Make(std::shared_ptr<Table> table);
 
   ~HistoryTable() override;
 
-  MetadataTableType type() const noexcept override { return MetadataTableType::kHistory; }
-
-  std::shared_ptr<Schema> GetSchema() const override;
+  Kind kind() const noexcept override { return Kind::kHistory; }
 
  private:
   explicit HistoryTable(std::shared_ptr<Table> table);
-
-  TableIdentifier CreateName(const TableIdentifier& source_name);
 };
 
 }  // namespace iceberg

src/iceberg/inspect/metadata_table.cc

@@ -20,76 +20,35 @@
 #include "iceberg/inspect/metadata_table.h"
 
 #include <memory>
-#include <string>
 #include <utility>
 
-#include "iceberg/file_io.h"
 #include "iceberg/inspect/history_table.h"
 #include "iceberg/inspect/snapshots_table.h"
-#include "iceberg/partition_spec.h"
-#include "iceberg/schema.h"
-#include "iceberg/schema_field.h"
-#include "iceberg/sort_order.h"
-#include "iceberg/table_identifier.h"
-#include "iceberg/table_metadata.h"
-#include "iceberg/table_properties.h"
-#include "iceberg/table_scan.h"
-#include "iceberg/type.h"
-#include "iceberg/type_fwd.h"
-#include "iceberg/util/uuid.h"
 
 namespace iceberg {
 
 MetadataTable::MetadataTable(std::shared_ptr<Table> source_table,
-                             TableIdentifier identifier)
-    : StaticTable(identifier, source_table->metadata(),
-                  std::string(source_table->metadata_file_location()), source_table->io(),
-                  source_table->catalog()),
-      source_table_(std::move(source_table)) {
-  auto schema = GetSchema();
-  if (!schema) {
-    schema = std::make_shared<Schema>(std::vector<SchemaField>{}, 1);
-  }
-
-  auto builder =
-      TableMetadataBuilder::BuildFromEmpty(TableMetadata::kDefaultTableFormatVersion);
-  auto result = builder->AssignUUID(Uuid::GenerateV4().ToString())
-                    .SetLocation(std::string(source_table_->location()))
-                    .SetCurrentSchema(schema, schema->schema_id())
-                    .SetDefaultSortOrder(SortOrder::Unsorted())
-                    .SetDefaultPartitionSpec(PartitionSpec::Unpartitioned())
-                    .SetProperties({})
-                    .Build();
-
-  if (!result.has_value()) {
-    // If metadata building fails, keep the original metadata from source_table
-    return;
-  }
-
-  std::shared_ptr<TableMetadata> built_metadata = std::move(result.value());
-
-  metadata_ = built_metadata;
-  metadata_cache_ = std::make_unique<TableMetadataCache>(metadata_.get());
-}
+                             TableIdentifier identifier, std::shared_ptr<Schema> schema)
+    : identifier_(std::move(identifier)),
+      schema_(std::move(schema)),
+      source_table_(std::move(source_table)) {}
 
 MetadataTable::~MetadataTable() = default;
 
-Status MetadataTable::Refresh() { return source_table_->Refresh(); }
-
-Result<std::unique_ptr<DataTableScanBuilder>> MetadataTable::NewScan() const {
-  return NotSupported("TODO: Scanning metadata tables is not yet supported");
-};
+Result<std::unique_ptr<MetadataTable>> MetadataTable::Make(std::shared_ptr<Table> table,
+                                                           Kind kind) {
+  if (table == nullptr) [[unlikely]] {
+    return InvalidArgument("Table cannot be null");
+  }
 
-Result<std::unique_ptr<MetadataTable>> MetadataTableFactory::CreateMetadataTable(
-    std::shared_ptr<Table> table, MetadataTableType type) {
-  switch (type) {
-    case MetadataTableType::kSnapshots:
+  switch (kind) {
+    case Kind::kSnapshots:
       return SnapshotsTable::Make(table);
-    case MetadataTableType::kHistory:
+    case Kind::kHistory:
       return HistoryTable::Make(table);
   }
 
-  return Invalid("Unsupported metadata table type");
+  return NotSupported("Unsupported metadata table type");
 }
 
 }  // namespace iceberg

src/iceberg/inspect/metadata_table.h

@@ -20,122 +20,43 @@
 #pragma once
 
 #include <memory>
-#include <string>
 
 #include "iceberg/iceberg_export.h"
-#include "iceberg/location_provider.h"
 #include "iceberg/result.h"
-#include "iceberg/sort_order.h"
-#include "iceberg/table.h"
-#include "iceberg/table_metadata.h"
-#include "iceberg/table_scan.h"
+#include "iceberg/table_identifier.h"
 #include "iceberg/type_fwd.h"
 
 namespace iceberg {
 
-/// \brief The type of metadata table
-enum class MetadataTableType {
-  kSnapshots,
-  kHistory,
-};
-
-/// \brief Base class for Iceberg metadata tables
-///
-/// Metadata tables expose table metadata as queryable tables with schemas and scan
-/// support. They provide read-only access to metadata.
-class ICEBERG_EXPORT MetadataTable : public StaticTable {
+/// \brief Base class for Iceberg metadata tables.
+class ICEBERG_EXPORT MetadataTable {
  public:
-  virtual MetadataTableType type() const noexcept = 0;
-
-  /// \brief Returns the table's metadata file location
-  std::string_view metadata_file_location() const {
-    return source_table_->metadata_file_location();
-  }
-
-  /// \brief Returns the table's base location
-  std::string_view location() const { return source_table_->location(); }
-
-  /// \brief Returns the time when this table was last updated
-  TimePointMs last_updated_ms() const { return source_table_->last_updated_ms(); }
-
-  /// \brief Returns the table's current snapshot, return NotFoundError if not found
-  Result<std::shared_ptr<Snapshot>> current_snapshot() const {
-    return source_table_->current_snapshot();
-  }
+  enum class Kind {
+    kSnapshots,
+    kHistory,
+  };
 
-  /// \brief Get the snapshot of this table with the given id
-  ///
-  /// \param snapshot_id the ID of the snapshot to get
-  /// \return the Snapshot with the given id, return NotFoundError if not found
-  Result<std::shared_ptr<Snapshot>> SnapshotById(int64_t snapshot_id) const {
-    return source_table_->SnapshotById(snapshot_id);
-  }
+  static Result<std::unique_ptr<MetadataTable>> Make(std::shared_ptr<Table> table,
+                                                     Kind kind);
 
-  /// \brief Get the snapshots of this table
-  const std::vector<std::shared_ptr<Snapshot>>& snapshots() const {
-    return source_table_->snapshots();
-  }
+  virtual ~MetadataTable();
 
-  /// \brief Get the snapshot history of this table
-  const std::vector<SnapshotLogEntry>& history() const {
-    return source_table_->history();
-  }
+  virtual Kind kind() const noexcept = 0;
 
-  /// \brief Returns the catalog that this table belongs to
-  const std::shared_ptr<Catalog>& catalog() const { return source_table_->catalog(); }
+  const TableIdentifier& name() const { return identifier_; }
 
-  /// \brief Returns a LocationProvider for this table
-  Result<std::unique_ptr<LocationProvider>> location_provider() const {
-    return source_table_->location_provider();
-  }
+  const std::shared_ptr<Schema>& schema() const { return schema_; }
 
-  /// \brief Refreshing is not supported in metadata tables.
-  Status Refresh() override;
-
-  /// \brief Create a new table scan builder for this table
-  ///
-  /// Once a table scan builder is created, it can be refined to project columns and
-  /// filter data.
-  Result<std::unique_ptr<DataTableScanBuilder>> NewScan() const override;
-
-  ~MetadataTable();
+  const std::shared_ptr<Table>& source_table() const { return source_table_; }
 
  protected:
-  explicit MetadataTable(std::shared_ptr<Table> source_table, TableIdentifier identifier);
-
-  /// \brief Returns the schema for this metadata table
-  ///
-  /// Subclasses override this method to provide their custom schema during
-  /// MetadataTable construction. The returned schema is used to initialize
-  /// the underlying TableMetadata.
-  ///
-  /// \return The schema for this metadata table, or nullptr for default schema
-  virtual std::shared_ptr<Schema> GetSchema() const { return nullptr; }
+  explicit MetadataTable(std::shared_ptr<Table> source_table, TableIdentifier identifier,
+                         std::shared_ptr<Schema> schema);
 
+ private:
+  TableIdentifier identifier_;
+  std::shared_ptr<Schema> schema_;
   std::shared_ptr<Table> source_table_;
 };
 
-/// \brief Metadata table factory and inspector
-///
-/// MetadataTable provides factory methods to create specific metadata tables for
-/// inspecting table metadata. Each metadata table exposes a different aspect of the
-/// table's metadata as a scannable Iceberg table.
-///
-/// Usage:
-///   auto metadata_table = ICEBERG_TRY(
-///       MetadataTableFactory::CreateMetadataTable(
-///           table, MetadataTableType::kSnapshots));
-///   auto scan = ICEBERG_TRY(metadata_table->NewScan());
-///   // ... scan and read metadata table data
-class ICEBERG_EXPORT MetadataTableFactory {
- public:
-  /// \brief Create a metadata table from a table
-  ///
-  /// \param table The source table
-  /// \param type The metadata table type to create
-  /// \return A MetadataTable instance or error status
-  static Result<std::unique_ptr<MetadataTable>> CreateMetadataTable(
-      std::shared_ptr<Table> table, MetadataTableType type);
-};
-
 }  // namespace iceberg