Skip to content

feat(inspect): capture scan inputs and open snapshot tasks - #1120

Open
manuzhang wants to merge 7 commits into
apache:mainfrom
manuzhang:codex/metadata-scan-support-20261115
Open

manuzhang wants to merge 7 commits into
apache:mainfrom
manuzhang:codex/metadata-scan-support-20261115

Conversation

@manuzhang

@manuzhang manuzhang commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Purpose

Regular data-table scans already support snapshot selection through UseSnapshot(), UseRef(), and AsOfTime(). MetadataScanBuilder also already exposes these selectors, but its implemented metadata tables (snapshots, history, and refs) use in-memory static tasks and reject time-travel selection.

This PR adds a generic snapshot-task execution path for the upcoming FilesTable (#876), ManifestsTable (#1121), and PartitionsTable (#1122) implementations. Those tables need to read metadata rows for a selected snapshot. The table implementations follow in their own PRs.

A source-table refresh after NewScan() must not change a builder's captured inputs. Built scans, tasks, and row streams retain their inputs for their own lifetimes. This PR supplies that ownership contract and builds directly on main.

Changes and rationale

  • Capture consistent inputs. The builder captures metadata and FileIO, then derives the schema through SchemaForScan(captured_metadata). FileIO is held separately from MetadataScanContext and passed to the table's MakeScan() hook, so snapshot tasks retain the captured IO even after a source refresh.
  • Share snapshot-task execution. Define SnapshotMetadataTask alongside StaticMetadataTask in metadata_scan_task.h/.cc. Its factory validates the context, FileIO, and row-reader callback. MetadataScanTaskReader opens it through that callback, allowing table-specific readers without a dispatch branch for every table.
  • Validate before reading. Centralize required metadata/schema checks in MetadataScanContext::Validate(), check whole-column projections, and resolve snapshot IDs, references, or timestamps against captured metadata. Reference lookup reuses SnapshotUtil::LatestSnapshot() after strict reference validation. Empty main selections return nullptr; dangling snapshot IDs remain errors. Main-branch detection is shared through SnapshotUtil::IsMainBranch().
  • Retain execution inputs. Tasks can be reopened with independent streams and configurable batch sizes. The builder, task, and active stream each retain the FileIO they need; static in-memory scans do not require FileIO.

Public API and ABI changes

The public virtual getter changes its return type:

- virtual const std::shared_ptr<Schema>& schema() const = 0;
+ virtual std::shared_ptr<Schema> schema() const = 0;

The member function remains const. Returning the pointer by value lets implementations copy it under their schema-cache lock, giving callers ownership that remains valid when the cache is replaced. This copies the shared_ptr, not the Schema.

Derived metadata tables must also update their protected MakeScan() override to accept the builder-captured std::shared_ptr<FileIO> as its second argument. The PR adds the protected SchemaForScan() hook, SnapshotMetadataTask, and TaskKind::kSnapshot. Existing binary consumers must be rebuilt.

Execution scope

The initial snapshot scan plans one task using an in-process row-reader callback. Splitting work into multiple tasks and providing serializable task descriptions are follow-up work for parallel and distributed execution.

Validation

  • All 62 metadata tests passed, including missing-input checks, repeated task opening, static scanning without FileIO, and the new FileIO-capture regression across source refresh and builder/scan/task destruction.
  • C++20 public-header compatibility passed.
  • Required pre-commit and changed-code clang-tidy 22.1.8 passed.

Local validation covers the standalone static Debug scan implementation and tests, rebuilt against this revision with unchanged cached static dependencies. Dependent table PRs must pass captured FileIO separately when adapting their MakeScan() overrides.

Copilot AI balanced review requested due to automatic review settings November 14, 2026 16:36

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Extract a focused piece from the metadata table implementation with its tests.

Co-authored-by: Codex <codex@openai.com>
@manuzhang
manuzhang force-pushed the codex/metadata-scan-support-20261115 branch from f11adff to 33c84fb Compare November 15, 2026 15:26
Copilot AI balanced review requested due to automatic review settings November 15, 2026 15:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@manuzhang manuzhang changed the title feat(inspect): add shared snapshot metadata scan support feat(inspect): capture scan inputs and open snapshot tasks Nov 15, 2026
Remove the private SnapshotAtRef helper. Validate explicit references and
handle an empty main snapshot before delegating to LatestSnapshot, so
missing references and dangling snapshot IDs still fail.

Cover empty tables, missing/null references, and dangling snapshot IDs.

Co-authored-by: Codex <codex@openai.com>
@manuzhang
manuzhang marked this pull request as draft November 16, 2026 15:18
manuzhang and others added 3 commits November 17, 2026 19:32
Extract SnapshotUtil::IsMainBranch and reuse it for metadata snapshot selection, schema lookup, and latest snapshot lookup.

Co-authored-by: Codex <codex@openai.com>
Document the retained snapshot task, deferred row-reader callback, and fresh task streams returned by repeated planning.

Co-authored-by: Codex <codex@openai.com>
Validate common metadata and schema inputs through MetadataScanContext::Validate at builder and scan factory boundaries. Keep FileIO validation specific to snapshot scans and cover direct factory input validation and static scans without FileIO.

Co-authored-by: Codex <codex@openai.com>
@manuzhang
manuzhang marked this pull request as ready for review November 17, 2026 15:22
@manuzhang
manuzhang requested review from wgtmac and zhjwpku November 17, 2026 15:22
Comment thread src/iceberg/CMakeLists.txt Resolved
Comment thread src/iceberg/inspect/metadata_scan.h Resolved
}

private:
const std::shared_ptr<MetadataScanTask> task_;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you plan to support multiple tasks in the future? I'm fine with the current implementation but we need to consider parallel task execution and serialization for better performance.

manuzhang and others added 2 commits November 20, 2026 11:21
Keep FileIO on the metadata scan builder and retained snapshot tasks instead of scan configuration. Colocate snapshot and static task implementations, label the callback parameters, rename the metadata utility source, and document future task splitting and serialization. Verify captured FileIO survives source refresh and the builder, scan, task, and active stream lifetimes.

Co-authored-by: Codex <codex@openai.com>
Exercise static metadata reads through StaticMetadataTask and MetadataScanTaskReader. The concrete SnapshotsScan was made private in apache#1139, so calling its factory prevents PR merge builds from compiling. Preserve the static-read FileIO regression through the public task API.

Co-authored-by: Codex <codex@openai.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants