feat(inspect): add base metadata table interface (#607)

This PR kicks off the implementation of table inspection support.

- Add `MetadataTable` class (without scan support for now).
- Add `SnapshotsTable` and `HistoryTable` as example impl.

Author: All-less

src/iceberg/CMakeLists.txt

@@ -41,6 +41,9 @@ set(ICEBERG_SOURCES
     file_io_registry.cc
     file_reader.cc
     file_writer.cc
+    inspect/history_table.cc
+    inspect/metadata_table.cc
+    inspect/snapshots_table.cc
     inheritable_metadata.cc
     json_serde.cc
     location_provider.cc
@@ -238,6 +241,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/CMakeLists.txt

@@ -0,0 +1,18 @@
+# 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.
+
+iceberg_install_all_headers(iceberg/inspect)

src/iceberg/inspect/history_table.cc

@@ -0,0 +1,62 @@
+/*
+ * 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/inspect/history_table.h"
+
+#include <memory>
+#include <utility>
+#include <vector>
+
+#include "iceberg/schema.h"
+#include "iceberg/schema_field.h"
+#include "iceberg/table.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/type.h"
+
+namespace iceberg {
+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 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) {
+  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

@@ -0,0 +1,44 @@
+/*
+ * 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
+
+#include <memory>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/inspect/metadata_table.h"
+#include "iceberg/result.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief History metadata table.
+class ICEBERG_EXPORT HistoryTable : public MetadataTable {
+ public:
+  static Result<std::unique_ptr<HistoryTable>> Make(std::shared_ptr<Table> table);
+
+  ~HistoryTable() override;
+
+  Kind kind() const noexcept override { return Kind::kHistory; }
+
+ private:
+  explicit HistoryTable(std::shared_ptr<Table> table);
+};
+
+}  // namespace iceberg

src/iceberg/inspect/meson.build

@@ -0,0 +1,21 @@
+# 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.
+
+install_headers(
+    ['history_table.h', 'metadata_table.h', 'snapshots_table.h'],
+    subdir: 'iceberg/inspect',
+)

src/iceberg/inspect/metadata_table.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/inspect/metadata_table.h"
+
+#include <memory>
+#include <utility>
+
+#include "iceberg/inspect/history_table.h"
+#include "iceberg/inspect/snapshots_table.h"
+
+namespace iceberg {
+
+MetadataTable::MetadataTable(std::shared_ptr<Table> source_table,
+                             TableIdentifier identifier, std::shared_ptr<Schema> schema)
+    : identifier_(std::move(identifier)),
+      schema_(std::move(schema)),
+      source_table_(std::move(source_table)) {}
+
+MetadataTable::~MetadataTable() = default;
+
+Result<std::unique_ptr<MetadataTable>> MetadataTable::Make(std::shared_ptr<Table> table,
+                                                           Kind kind) {
+  if (table == nullptr) [[unlikely]] {
+    return InvalidArgument("Table cannot be null");
+  }
+
+  switch (kind) {
+    case Kind::kSnapshots:
+      return SnapshotsTable::Make(table);
+    case Kind::kHistory:
+      return HistoryTable::Make(table);
+  }
+
+  return NotSupported("Unsupported metadata table type");
+}
+
+}  // namespace iceberg

src/iceberg/inspect/metadata_table.h

@@ -0,0 +1,62 @@
+/*
+ * 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
+
+#include <memory>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/result.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief Base class for Iceberg metadata tables.
+class ICEBERG_EXPORT MetadataTable {
+ public:
+  enum class Kind {
+    kSnapshots,
+    kHistory,
+  };
+
+  static Result<std::unique_ptr<MetadataTable>> Make(std::shared_ptr<Table> table,
+                                                     Kind kind);
+
+  virtual ~MetadataTable();
+
+  virtual Kind kind() const noexcept = 0;
+
+  const TableIdentifier& name() const { return identifier_; }
+
+  const std::shared_ptr<Schema>& schema() const { return schema_; }
+
+  const std::shared_ptr<Table>& source_table() const { return source_table_; }
+
+ protected:
+  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_;
+};
+
+}  // namespace iceberg

src/iceberg/inspect/snapshots_table.cc

@@ -0,0 +1,68 @@
+/*
+ * 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/inspect/snapshots_table.h"
+
+#include <memory>
+#include <utility>
+#include <vector>
+
+#include "iceberg/schema.h"
+#include "iceberg/schema_field.h"
+#include "iceberg/table.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/type.h"
+
+namespace iceberg {
+namespace {
+
+std::shared_ptr<Schema> MakeSnapshotsTableSchema() {
+  return std::make_shared<Schema>(std::vector<SchemaField>{
+      SchemaField::MakeRequired(1, "committed_at", timestamp_tz()),
+      SchemaField::MakeRequired(2, "snapshot_id", int64()),
+      SchemaField::MakeOptional(3, "parent_id", int64()),
+      SchemaField::MakeOptional(4, "operation", string()),
+      SchemaField::MakeOptional(5, "manifest_list", string()),
+      SchemaField::MakeOptional(6, "summary",
+                                std::make_shared<iceberg::MapType>(
+                                    SchemaField::MakeRequired(7, "key", string()),
+                                    SchemaField::MakeRequired(8, "value", string())))});
+}
+
+TableIdentifier MakeSnapshotsTableName(const TableIdentifier& source_name) {
+  return TableIdentifier{.ns = source_name.ns, .name = source_name.name + ".snapshots"};
+}
+
+}  // namespace
+
+SnapshotsTable::SnapshotsTable(std::shared_ptr<Table> table)
+    : MetadataTable(table, MakeSnapshotsTableName(table->name()),
+                    MakeSnapshotsTableSchema()) {}
+
+SnapshotsTable::~SnapshotsTable() = default;
+
+Result<std::unique_ptr<SnapshotsTable>> SnapshotsTable::Make(
+    std::shared_ptr<Table> table) {
+  if (table == nullptr) [[unlikely]] {
+    return InvalidArgument("Table cannot be null");
+  }
+  return std::unique_ptr<SnapshotsTable>(new SnapshotsTable(std::move(table)));
+}
+
+}  // namespace iceberg

src/iceberg/inspect/snapshots_table.h

@@ -0,0 +1,44 @@
+/*
+ * 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
+
+#include <memory>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/inspect/metadata_table.h"
+#include "iceberg/result.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief Snapshots metadata table.
+class ICEBERG_EXPORT SnapshotsTable : public MetadataTable {
+ public:
+  static Result<std::unique_ptr<SnapshotsTable>> Make(std::shared_ptr<Table> table);
+
+  ~SnapshotsTable() override;
+
+  Kind kind() const noexcept override { return Kind::kSnapshots; }
+
+ private:
+  explicit SnapshotsTable(std::shared_ptr<Table> table);
+};
+
+}  // namespace iceberg