static table metadata access support

Author: shuxu.li

src/iceberg/table.cc

@@ -40,7 +40,7 @@ BaseTable::BaseTable(std::string name, std::shared_ptr<TableMetadata> metadata)
 
 void BaseTable::InitSchema() const {
   for (const auto& schema : metadata_->schemas) {
-    if (schema->schema_id() != std::nullopt) {
+    if (schema->schema_id()) {
       schemas_map_.emplace(schema->schema_id().value(), schema);
       if (schema->schema_id().value() == metadata_->current_schema_id) {
         schema_ = schema;
@@ -83,10 +83,10 @@ void BaseTable::InitSnapshot() const {
 
 const std::string& BaseTable::uuid() const { return metadata_->table_uuid; }
 
-const std::shared_ptr<Schema>& BaseTable::schema() const {
+Result<std::shared_ptr<Schema>> BaseTable::schema() const {
   std::call_once(init_schema_once_, [this]() { InitSchema(); });
   if (!schema_) {
-    throw IcebergError("Current schema is not defined for this table");
+    return NotFound("Current schema is not defined for this table");
   }
   return schema_;
 }
@@ -96,8 +96,11 @@ const std::unordered_map<int32_t, std::shared_ptr<Schema>>& BaseTable::schemas()
   return schemas_map_;
 }
 
-const std::shared_ptr<PartitionSpec>& BaseTable::spec() const {
+Result<std::shared_ptr<PartitionSpec>> BaseTable::spec() const {
   std::call_once(init_partition_spec_once_, [this]() { InitPartitionSpec(); });
+  if (!partition_spec_) {
+    return NotFound("Default partition spec is not defined for this table");
+  }
   return partition_spec_;
 }
 
@@ -107,8 +110,11 @@ const std::unordered_map<int32_t, std::shared_ptr<PartitionSpec>>& BaseTable::sp
   return partition_spec_map_;
 }
 
-const std::shared_ptr<SortOrder>& BaseTable::sort_order() const {
+Result<std::shared_ptr<SortOrder>> BaseTable::sort_order() const {
   std::call_once(init_sort_order_once_, [this]() { InitSortOrder(); });
+  if (!sort_order_) {
+    return NotFound("Default sort order is not defined for this table");
+  }
   return sort_order_;
 }
 
@@ -124,10 +130,10 @@ const std::unordered_map<std::string, std::string>& BaseTable::properties() cons
 
 const std::string& BaseTable::location() const { return metadata_->location; }
 
-const std::shared_ptr<Snapshot>& BaseTable::current_snapshot() const {
+Result<std::shared_ptr<Snapshot>> BaseTable::current_snapshot() const {
   std::call_once(init_snapshot_once_, [this]() { InitSnapshot(); });
   if (!current_snapshot_) {
-    throw IcebergError("Current snapshot is not defined for this table");
+    return NotFound("Current snapshot is not defined for this table");
   }
   return current_snapshot_;
 }
@@ -147,27 +153,27 @@ const std::vector<std::shared_ptr<Snapshot>>& BaseTable::snapshots() const {
 
 const std::vector<std::shared_ptr<HistoryEntry>>& BaseTable::history() const {
   // TODO(lishuxu): Implement history retrieval
-  throw IcebergError("history is not supported for BaseTable now");
+  return history_;
 }
 
 Status StaticTable::Refresh() {
-  throw IcebergError("Refresh is not supported for StaticTable");
+  return NotSupported("Refresh is not supported for StaticTable");
 }
 
-std::unique_ptr<TableScan> StaticTable::NewScan() const {
-  throw IcebergError("NewScan is not supported for StaticTable");
+Result<std::unique_ptr<TableScan>> StaticTable::NewScan() const {
+  return NotSupported("NewScan is not supported for StaticTable");
 }
 
-std::shared_ptr<AppendFiles> StaticTable::NewAppend() {
-  throw IcebergError("NewAppend is not supported for StaticTable");
+Result<std::shared_ptr<AppendFiles>> StaticTable::NewAppend() {
+  return NotSupported("NewAppend is not supported for StaticTable");
 }
 
-std::unique_ptr<Transaction> StaticTable::NewTransaction() {
-  throw IcebergError("NewTransaction is not supported for StaticTable");
+Result<std::unique_ptr<Transaction>> StaticTable::NewTransaction() {
+  return NotSupported("NewTransaction is not supported for StaticTable");
 }
 
-std::unique_ptr<LocationProvider> StaticTable::location_provider() const {
-  throw IcebergError("location_provider is not supported for StaticTable");
+Result<std::unique_ptr<LocationProvider>> StaticTable::location_provider() const {
+  return NotSupported("location_provider is not supported for StaticTable");
 }
 
 }  // namespace iceberg

src/iceberg/table.h

@@ -26,7 +26,10 @@
 #include <vector>
 
 #include "iceberg/iceberg_export.h"
+#include "iceberg/location_provider.h"
 #include "iceberg/result.h"
+#include "iceberg/table_scan.h"
+#include "iceberg/transaction.h"
 #include "iceberg/type_fwd.h"
 
 namespace iceberg {
@@ -45,21 +48,21 @@ class ICEBERG_EXPORT Table {
   /// \brief Refresh the current table metadata
   virtual Status Refresh() = 0;
 
-  /// \brief Return the schema for this table
-  virtual const std::shared_ptr<Schema>& schema() const = 0;
+  /// \brief Return the schema for this table, return NotFoundError if not found
+  virtual Result<std::shared_ptr<Schema>> schema() const = 0;
 
   /// \brief Return a map of schema for this table
   virtual const std::unordered_map<int32_t, std::shared_ptr<Schema>>& schemas() const = 0;
 
-  /// \brief Return the partition spec for this table
-  virtual const std::shared_ptr<PartitionSpec>& spec() const = 0;
+  /// \brief Return the partition spec for this table, return NotFoundError if not found
+  virtual Result<std::shared_ptr<PartitionSpec>> spec() const = 0;
 
   /// \brief Return a map of partition specs for this table
   virtual const std::unordered_map<int32_t, std::shared_ptr<PartitionSpec>>& specs()
       const = 0;
 
-  /// \brief Return the sort order for this table
-  virtual const std::shared_ptr<SortOrder>& sort_order() const = 0;
+  /// \brief Return the sort order for this table, return NotFoundError if not found
+  virtual Result<std::shared_ptr<SortOrder>> sort_order() const = 0;
 
   /// \brief Return a map of sort order IDs to sort orders for this table
   virtual const std::unordered_map<int32_t, std::shared_ptr<SortOrder>>& sort_orders()
@@ -71,8 +74,8 @@ class ICEBERG_EXPORT Table {
   /// \brief Return the table's base location
   virtual const std::string& location() const = 0;
 
-  /// \brief Return the table's current snapshot
-  virtual const std::shared_ptr<Snapshot>& current_snapshot() const = 0;
+  /// \brief Return the table's current snapshot, or NotFoundError if not found
+  virtual Result<std::shared_ptr<Snapshot>> current_snapshot() const = 0;
 
   /// \brief Get the snapshot of this table with the given id, or null if there is no
   /// matching snapshot
@@ -92,42 +95,51 @@ class ICEBERG_EXPORT Table {
   /// \brief Create a new table scan for this table
   ///
   /// Once a table scan is created, it can be refined to project columns and filter data.
-  virtual std::unique_ptr<TableScan> NewScan() const = 0;
+  virtual Result<std::unique_ptr<TableScan>> NewScan() const = 0;
 
   /// \brief Create a new append API to add files to this table and commit
-  virtual std::shared_ptr<AppendFiles> NewAppend() = 0;
+  virtual Result<std::shared_ptr<AppendFiles>> NewAppend() = 0;
 
   /// \brief Create a new transaction API to commit multiple table operations at once
-  virtual std::unique_ptr<Transaction> NewTransaction() = 0;
+  virtual Result<std::unique_ptr<Transaction>> NewTransaction() = 0;
 
   /// TODO(wgtmac): design of FileIO is not finalized yet. We intend to use an
   /// IO-less design in the core library.
   // /// \brief Returns a FileIO to read and write table data and metadata files
   // virtual std::shared_ptr<FileIO> io() const = 0;
 
   /// \brief Returns a LocationProvider to provide locations for new data files
-  virtual std::unique_ptr<LocationProvider> location_provider() const = 0;
+  virtual Result<std::unique_ptr<LocationProvider>> location_provider() const = 0;
 };
 
+/// \brief An abstract base implementation of the Iceberg Table interface.
+///
+/// BaseTable provides common functionality for Iceberg table implementations,
+/// including lazy initialization of schema, partition specs, sort orders,
+/// and snapshot metadata.
+///
+/// This class is not intended to be used directly by users, but serves as a foundation
+/// for concrete implementations such as StaticTable or CatalogTable.
 class ICEBERG_EXPORT BaseTable : public Table {
  public:
   ~BaseTable() override = default;
+
   BaseTable(std::string name, std::shared_ptr<TableMetadata> metadata);
 
   const std::string& name() const override { return name_; }
 
   const std::string& uuid() const override;
 
-  const std::shared_ptr<Schema>& schema() const override;
+  Result<std::shared_ptr<Schema>> schema() const override;
 
   const std::unordered_map<int32_t, std::shared_ptr<Schema>>& schemas() const override;
 
-  const std::shared_ptr<PartitionSpec>& spec() const override;
+  Result<std::shared_ptr<PartitionSpec>> spec() const override;
 
   const std::unordered_map<int32_t, std::shared_ptr<PartitionSpec>>& specs()
       const override;
 
-  const std::shared_ptr<SortOrder>& sort_order() const override;
+  Result<std::shared_ptr<SortOrder>> sort_order() const override;
 
   const std::unordered_map<int32_t, std::shared_ptr<SortOrder>>& sort_orders()
       const override;
@@ -136,7 +148,7 @@ class ICEBERG_EXPORT BaseTable : public Table {
 
   const std::string& location() const override;
 
-  const std::shared_ptr<Snapshot>& current_snapshot() const override;
+  Result<std::shared_ptr<Snapshot>> current_snapshot() const override;
 
   Result<std::shared_ptr<Snapshot>> snapshot(int64_t snapshot_id) const override;
 
@@ -164,6 +176,8 @@ class ICEBERG_EXPORT BaseTable : public Table {
   mutable std::shared_ptr<Snapshot> current_snapshot_;
   mutable std::unordered_map<int64_t, std::shared_ptr<Snapshot>> snapshots_map_;
 
+  mutable std::vector<std::shared_ptr<HistoryEntry>> history_;
+
   std::shared_ptr<TableMetadata> metadata_;
 
   // once_flags
@@ -173,21 +187,25 @@ class ICEBERG_EXPORT BaseTable : public Table {
   mutable std::once_flag init_snapshot_once_;
 };
 
+/// \brief A read-only implementation of an Iceberg table.
+///
+/// StaticTable represents a snapshot of a table that does not support mutation.
 class ICEBERG_EXPORT StaticTable : public BaseTable {
  public:
   ~StaticTable() override = default;
+
   StaticTable(std::string name, std::shared_ptr<TableMetadata> metadata)
       : BaseTable(std::move(name), std::move(metadata)) {}
 
   Status Refresh() override;
 
-  std::unique_ptr<TableScan> NewScan() const override;
+  Result<std::unique_ptr<TableScan>> NewScan() const override;
 
-  std::shared_ptr<AppendFiles> NewAppend() override;
+  Result<std::shared_ptr<AppendFiles>> NewAppend() override;
 
-  std::unique_ptr<Transaction> NewTransaction() override;
+  Result<std::unique_ptr<Transaction>> NewTransaction() override;
 
-  std::unique_ptr<LocationProvider> location_provider() const override;
+  Result<std::unique_ptr<LocationProvider>> location_provider() const override;
 };
 
 }  // namespace iceberg

src/iceberg/table_metadata.cc

@@ -76,6 +76,19 @@ Result<std::shared_ptr<SortOrder>> TableMetadata::SortOrder() const {
   return *iter;
 }
 
+Result<std::shared_ptr<Snapshot>> TableMetadata::Snapshot() const {
+  if (current_snapshot_id == Snapshot::kInvalidSnapshotId) {
+    return NotFound("Current snapshot is not defined for this table");
+  }
+  auto iter = std::ranges::find_if(snapshots, [this](const auto& snapshot) {
+    return snapshot->snapshot_id == current_snapshot_id;
+  });
+  if (iter == snapshots.end()) {
+    return NotFound("Current snapshot with ID {} is not found", current_snapshot_id);
+  }
+  return *iter;
+}
+
 namespace {
 
 template <typename T>

src/iceberg/table_metadata.h

@@ -133,6 +133,8 @@ struct ICEBERG_EXPORT TableMetadata {
   Result<std::shared_ptr<PartitionSpec>> PartitionSpec() const;
   /// \brief Get the current sort order, return NotFoundError if not found
   Result<std::shared_ptr<SortOrder>> SortOrder() const;
+  /// \brief Get the current snapshot, return NotFoundError if not found
+  Result<std::shared_ptr<Snapshot>> Snapshot() const;
 
   friend bool operator==(const TableMetadata& lhs, const TableMetadata& rhs);
 

src/iceberg/table_scan.h

@@ -0,0 +1,27 @@
+/*
+ * 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
+
+namespace iceberg {
+
+/// \brief Represents a table scan operation
+class ICEBERG_EXPORT TableScan{};
+
+}  // namespace iceberg

test/CMakeLists.txt

@@ -46,8 +46,8 @@ add_test(NAME schema_test COMMAND schema_test)
 
 add_executable(table_test)
 target_include_directories(table_test PRIVATE "${CMAKE_BINARY_DIR}")
-target_sources(table_test PRIVATE table_test_helper.cc json_internal_test.cc
-                                  table_test.cc schema_json_test.cc)
+target_sources(table_test PRIVATE test_common.cc json_internal_test.cc table_test.cc
+                                  schema_json_test.cc)
 target_link_libraries(table_test PRIVATE iceberg_static GTest::gtest_main GTest::gmock)
 add_test(NAME table_test COMMAND table_test)
 
@@ -59,7 +59,7 @@ add_test(NAME expression_test COMMAND expression_test)
 
 add_executable(json_serde_test)
 target_include_directories(json_serde_test PRIVATE "${CMAKE_BINARY_DIR}")
-target_sources(json_serde_test PRIVATE table_test_helper.cc json_internal_test.cc
+target_sources(json_serde_test PRIVATE test_common.cc json_internal_test.cc
                                        metadata_serde_test.cc schema_json_test.cc)
 target_link_libraries(json_serde_test PRIVATE iceberg_static GTest::gtest_main
                                               GTest::gmock)

test/metadata_serde_test.cc

@@ -35,7 +35,7 @@
 #include "iceberg/table_metadata.h"
 #include "iceberg/transform.h"
 #include "iceberg/type.h"
-#include "table_test_helper.h"
+#include "test_common.h"
 
 namespace iceberg {
 
@@ -51,7 +51,7 @@ class MetadataSerdeTest : public ::testing::Test {
 TEST_F(MetadataSerdeTest, DeserializeV1Valid) {
   std::unique_ptr<TableMetadata> metadata;
   ASSERT_NO_FATAL_FAILURE(
-      TableTestHelper::ReadTableMetadata("TableMetadataV1Valid.json", &metadata));
+      test::ReadTableMetadata("TableMetadataV1Valid.json", &metadata));
 
   EXPECT_EQ(metadata->format_version, 1);
   EXPECT_EQ(metadata->table_uuid, "d20125c8-7284-442c-9aea-15fee620737c");
@@ -89,7 +89,7 @@ TEST_F(MetadataSerdeTest, DeserializeV1Valid) {
 TEST_F(MetadataSerdeTest, DeserializeV2Valid) {
   std::unique_ptr<TableMetadata> metadata;
   ASSERT_NO_FATAL_FAILURE(
-      TableTestHelper::ReadTableMetadata("TableMetadataV2Valid.json", &metadata));
+      test::ReadTableMetadata("TableMetadataV2Valid.json", &metadata));
 
   EXPECT_EQ(metadata->format_version, 2);
   EXPECT_EQ(metadata->table_uuid, "9c12d441-03fe-4693-9a96-a0705ddf69c1");