refactor(table): split the table hierarchy and materialize the store a table serves

benchmark/benchmark_suite.cpp

@@ -368,7 +368,7 @@ Status EnsureTable(const std::string& root_path, const std::string& db_name,
                    const std::shared_ptr<arrow::Schema>& schema,
                    const std::vector<std::string>& primary_keys = {}) {
     PAIMON_ASSIGN_OR_RAISE(
-        std::unique_ptr<paimon::Catalog> catalog,
+        std::shared_ptr<paimon::Catalog> catalog,
         AddContext(paimon::Catalog::Create(root_path, options), "create catalog"));
     PAIMON_RETURN_NOT_OK(
         AddContext(catalog->CreateDatabase(db_name, options, true), "create database"));
@@ -434,25 +434,29 @@ Status WriteSourceDataToWriter(paimon::FileStoreWrite* writer, const SourceDataS
 Status WriteAndCommit(const std::string& table_path,
                       const std::map<std::string, std::string>& options,
                       const SourceDataSpec& source_spec) {
+    std::map<std::string, std::string> write_builder_options;
     paimon::WriteContextBuilder write_builder(table_path, "benchmark-writer");
+    write_builder_options = options;
+    PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<paimon::WriteContext> write_ctx,
+                           AddContext(write_builder.Finish(), "create write context"));
     PAIMON_ASSIGN_OR_RAISE(
-        std::unique_ptr<paimon::WriteContext> write_ctx,
-        AddContext(write_builder.SetOptions(options).Finish(), "create write context"));
-    PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<paimon::FileStoreWrite> writer,
-                           AddContext(paimon::FileStoreWrite::Create(std::move(write_ctx)),
-                                      "create file store writer"));
+        std::unique_ptr<paimon::FileStoreWrite> writer,
+        AddContext(paimon::FileStoreWrite::Create(std::move(write_ctx), write_builder_options),
+                   "create file store writer"));
 
     PAIMON_RETURN_NOT_OK(WriteSourceDataToWriter(writer.get(), source_spec));
     PAIMON_ASSIGN_OR_RAISE(std::vector<std::shared_ptr<paimon::CommitMessage>> messages,
                            AddContext(writer->PrepareCommit(), "prepare commit"));
 
+    std::map<std::string, std::string> commit_builder_options;
     paimon::CommitContextBuilder commit_builder(table_path, "benchmark-writer");
-    PAIMON_ASSIGN_OR_RAISE(
-        std::unique_ptr<paimon::CommitContext> commit_ctx,
-        AddContext(commit_builder.SetOptions(options).Finish(), "create commit context"));
+    commit_builder_options = options;
+    PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<paimon::CommitContext> commit_ctx,
+                           AddContext(commit_builder.Finish(), "create commit context"));
     PAIMON_ASSIGN_OR_RAISE(
         std::unique_ptr<paimon::FileStoreCommit> committer,
-        AddContext(paimon::FileStoreCommit::Create(std::move(commit_ctx)), "create committer"));
+        AddContext(paimon::FileStoreCommit::Create(std::move(commit_ctx), commit_builder_options),
+                   "create committer"));
     PAIMON_RETURN_NOT_OK(AddContext(committer->Commit(messages), "commit write"));
     return Status::OK();
 }
@@ -562,20 +566,23 @@ Result<const SharedReadTableCache*> GetOrCreateSharedReadTable(const std::string
 Result<int64_t> ReadRows(const std::string& table_path,
                          const std::map<std::string, std::string>& options,
                          int32_t prefetch_parallel_num) {
+    std::map<std::string, std::string> scan_builder_options;
     paimon::ScanContextBuilder scan_builder(table_path);
-    PAIMON_ASSIGN_OR_RAISE(
-        std::unique_ptr<paimon::ScanContext> scan_ctx,
-        AddContext(scan_builder.SetOptions(options).Finish(), "create scan context"));
+    scan_builder_options = options;
+    PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<paimon::ScanContext> scan_ctx,
+                           AddContext(scan_builder.Finish(), "create scan context"));
     PAIMON_ASSIGN_OR_RAISE(
         std::unique_ptr<paimon::TableScan> scanner,
-        AddContext(paimon::TableScan::Create(std::move(scan_ctx)), "create scanner"));
+        AddContext(paimon::TableScan::Create(std::move(scan_ctx), scan_builder_options),
+                   "create scanner"));
     PAIMON_ASSIGN_OR_RAISE(std::shared_ptr<paimon::Plan> plan,
                            AddContext(scanner->CreatePlan(), "create plan"));
 
+    std::map<std::string, std::string> read_builder_options;
     paimon::ReadContextBuilder read_builder(table_path);
     constexpr int32_t kPrefetchBatchCount = 600;
-    read_builder.SetOptions(options)
-        .EnablePrefetch(true)
+    read_builder_options = options;
+    read_builder.EnablePrefetch(true)
         .SetPrefetchBatchCount(kPrefetchBatchCount)
         .SetPrefetchMaxParallelNum(prefetch_parallel_num)
         .EnableMultiThreadRowToBatch(GetRowToBatchThreadNumber() > 1)
@@ -584,7 +591,8 @@ Result<int64_t> ReadRows(const std::string& table_path,
                            AddContext(read_builder.Finish(), "create read context"));
     PAIMON_ASSIGN_OR_RAISE(
         std::unique_ptr<paimon::TableRead> reader,
-        AddContext(paimon::TableRead::Create(std::move(read_ctx)), "create table reader"));
+        AddContext(paimon::TableRead::Create(std::move(read_ctx), read_builder_options),
+                   "create table reader"));
     PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<paimon::BatchReader> batch_reader,
                            AddContext(reader->CreateReader(plan->Splits()), "create batch reader"));
 

cmake_modules/SetupCxxFlags.cmake

@@ -106,7 +106,6 @@ if("${BUILD_WARNING_LEVEL}" STREQUAL "CHECKIN")
     elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
         set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wall")
         set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wno-conversion")
-        set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wno-deprecated-declarations")
         set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wno-sign-conversion")
         set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wno-unused-variable")
     else()
@@ -163,6 +162,11 @@ if(MSVC)
     # (required for protobuf, see https://github.com/protocolbuffers/protobuf/issues/6885)
     set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} /wd4065")
 elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    # Paimon's own deprecated entry points stay exercised by its tests until they are removed, so
+    # deprecation warnings stay off for every GCC build, as they already are for every Clang build
+    # below. Downstream consumers compiling the public headers with their own flags see them.
+    set(CXX_COMMON_FLAGS "${CXX_COMMON_FLAGS} -Wno-deprecated-declarations")
+
     if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL "7.0" OR CMAKE_CXX_COMPILER_VERSION
                                                          VERSION_GREATER "7.0")
         # Without this, gcc >= 7 warns related to changes in C++17

docs/code-style.md

@@ -168,10 +168,10 @@ All fallible functions return `Status` (no value) or `Result<T>` (with value). *
 ```cpp
 // ✅ Good — explicit type
 PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<TableScan> scan,
-                       TableScan::Create(std::move(ctx)));
+                       table->NewScan(std::move(ctx)));
 
 // ❌ Bad — auto
-PAIMON_ASSIGN_OR_RAISE(auto scan, TableScan::Create(std::move(ctx)));
+PAIMON_ASSIGN_OR_RAISE(auto scan, table->NewScan(std::move(ctx)));
 ```
 
 If you need a `shared_ptr` from a function returning `unique_ptr`, write the target type directly — the macro already moves:

docs/source/api/format_table.rst

@@ -35,18 +35,16 @@ and :cpp:class:`paimon::FileStoreCommit`. See :doc:`../user_guide/format_table`.
 Contexts
 ========
 
-Each of those entry points builds its context from a table path, and the schema under that path
-says what kind of table it is. A caller that already holds a ``FormatTable`` hands it over instead,
-through the constructor each context builder has for one:
-
-* :cpp:class:`paimon::ScanContextBuilder`\ ``(const std::shared_ptr<FormatTable>&)``
-* :cpp:class:`paimon::ReadContextBuilder`\ ``(const std::shared_ptr<FormatTable>&)``
-* :cpp:class:`paimon::WriteContextBuilder`\ ``(const std::shared_ptr<FormatTable>&)``
-* :cpp:class:`paimon::CommitContextBuilder`\ ``(const std::shared_ptr<FormatTable>&)``
-
-This is the only way to reach a format table whose schema does not live under its own location,
-such as one a REST catalog serves: nothing under the location says that it is a format table, nor
-that what sits below it is data rather than metadata. The table knows both, so a setting that would
-answer either question again - ``SetTableSchema()``, ``WithFileSystem()`` and a branch among them -
-is refused by these builders rather than quietly ignored. Options given at the call still win over
-the ones the table carries, as they do everywhere else.
+Each of those entry points builds its context the way it does for a data table: from the table's
+location, through the builder's usual constructor:
+
+* :cpp:class:`paimon::ScanContextBuilder`\ ``(const std::string&)``
+* :cpp:class:`paimon::ReadContextBuilder`\ ``(const std::string&)``
+* :cpp:class:`paimon::WriteContextBuilder`\ ``(const std::string& root_path, const std::string& commit_user)``
+* :cpp:class:`paimon::CommitContextBuilder`\ ``(const std::string& root_path, const std::string& commit_user)``
+
+The context then goes to the table's own operator - ``NewScan()``, ``NewRead()``, ``NewWrite()`` or
+``NewCommit()`` - which serves a table whose schema does not live under its own location as well,
+such as one a REST catalog serves: the table carries its schema and the file system it was loaded
+through, so nothing under the location has to answer for them. Options given at the call still win
+over the ones the table carries, as they do everywhere else.