fix(scan): restore parameter order and document cache refresh

Author: gripleaf

docs/source/api/scan.rst

@@ -72,7 +72,7 @@ are rejected. The physical table path must match, including when scanning its ``
 ``$audit_log`` system table. Format tables and global system tables do not use these resources.
 ``Finish()`` resets the builder's resource setting, like ``WithCache()`` and ``WithExecutor()``.
 
-Every new scan still checks for the latest schema. Previously loaded schema versions, Arrow
+Every new scan still checks for the latest schema ID. Previously loaded schema versions, Arrow
 schemas, partition and primary-key field information, and statistics evolution objects are
 reused. Existing scans retain their original schema. Snapshot selection, filters, streaming
 progress, executors and scan metrics remain independent. ``SetTableSchema()`` keeps its existing
@@ -81,9 +81,14 @@ behavior: on main it bypasses the shared schema cache; on other branches it is i
 The resources can be shared by concurrent scans when the supplied file system and metadata
 memory pool support concurrent use. The resource object retains its metadata pool independently
 of each scan's memory pool. Cached schema versions are retained for the resource object's lifetime;
-there is no automatic eviction or background refresh. Recreate the resources after deleting and
-recreating a table or branch, or changing file system access configuration. A metadata cache does
-not pin snapshots or prevent their data files from expiring.
+there is no automatic eviction or background refresh. The caller must recreate the resources after
+fast-forward, deleting and recreating a table or branch, or changing file system access configuration.
+Fast-forward can replace schema contents under existing IDs, so discovering the latest ID does not
+refresh a cached schema. After fast-forward completes, create a new ``TableScanResources`` and use it
+for subsequent scans; existing resources and scans retain their cached metadata. This follows
+Paimon's `fast-forward cache refresh requirement
+<https://paimon.apache.org/docs/1.3/maintenance/manage-branches/#fast-forward>`_.
+A metadata cache does not pin snapshots or prevent their data files from expiring.
 
 Interface
 =========

include/paimon/scan_context.h

@@ -51,14 +51,14 @@ class PAIMON_EXPORT ScanContext {
                 const std::shared_ptr<ScanFilter>& scan_filter,
                 const std::shared_ptr<GlobalIndexResult>& global_index_result,
                 const std::shared_ptr<RealtimeContext>& realtime_context,
+                const std::shared_ptr<MemoryPool>& memory_pool,
                 const std::shared_ptr<Executor>& executor,
                 const std::shared_ptr<FileSystem>& specific_file_system,
                 const std::optional<std::string>& table_schema,
                 const std::map<std::string, std::string>& options,
                 const std::shared_ptr<Cache>& cache,
                 const std::shared_ptr<FormatTable>& format_table,
-                const std::shared_ptr<TableScanResources>& table_resources,
-                const std::shared_ptr<MemoryPool>& memory_pool);
+                const std::shared_ptr<TableScanResources>& table_resources);
 
     ~ScanContext();
 

include/paimon/table/source/table_scan_resources.h

@@ -33,9 +33,11 @@ class TableScanResourcesAccess;
 /// Metadata resources shared by scans of one managed table and branch.
 ///
 /// Share this object through ScanContextBuilder::WithTableResources(). Each scan still discovers
-/// the latest schema and chooses its own snapshot. Schema versions and their derived metadata
-/// remain cached for the lifetime of this object. Recreate it after dropping and recreating a
-/// table or branch, or changing the file system's access configuration.
+/// the latest schema ID and chooses its own snapshot. Schema versions and their derived metadata
+/// remain cached for the lifetime of this object. The caller must recreate it after fast-forward,
+/// dropping and recreating a table or branch, or changing the file system's access configuration.
+/// Fast-forward can replace schema contents under existing IDs; cached versions are not refreshed
+/// automatically. Use the new resources for subsequent scans.
 ///
 /// Concurrent scans may share these resources. The supplied file system and metadata memory pool
 /// must support concurrent use. Filters, executors, scan progress and scan metrics are not shared.

src/paimon/core/operation/scan_context.cpp

@@ -36,14 +36,14 @@ ScanContext::ScanContext(const std::string& path, bool is_streaming_mode,
                          const std::shared_ptr<ScanFilter>& scan_filter,
                          const std::shared_ptr<GlobalIndexResult>& global_index_result,
                          const std::shared_ptr<RealtimeContext>& realtime_context,
+                         const std::shared_ptr<MemoryPool>& memory_pool,
                          const std::shared_ptr<Executor>& executor,
                          const std::shared_ptr<FileSystem>& specific_file_system,
                          const std::optional<std::string>& table_schema,
                          const std::map<std::string, std::string>& options,
                          const std::shared_ptr<Cache>& cache,
                          const std::shared_ptr<FormatTable>& format_table,
-                         const std::shared_ptr<TableScanResources>& table_resources,
-                         const std::shared_ptr<MemoryPool>& memory_pool)
+                         const std::shared_ptr<TableScanResources>& table_resources)
     : path_(path),
       is_streaming_mode_(is_streaming_mode),
       limit_(limit),
@@ -249,9 +249,9 @@ Result<std::unique_ptr<ScanContext>> ScanContextBuilder::Finish() {
         impl_->path_, impl_->is_streaming_mode_, impl_->limit_,
         std::make_shared<ScanFilter>(impl_->predicates_, impl_->partition_filters_,
                                      impl_->bucket_filter_),
-        impl_->global_index_result_, impl_->realtime_context_, executor,
+        impl_->global_index_result_, impl_->realtime_context_, impl_->memory_pool_, executor,
         impl_->specific_file_system_, impl_->table_schema_, options, impl_->cache_,
-        impl_->format_table_, impl_->table_resources_, impl_->memory_pool_);
+        impl_->format_table_, impl_->table_resources_);
     impl_->Reset();
     return ctx;
 }