Skip to content

[core][spark] Support managed Format Table partition operations#8713

Draft
sundapeng wants to merge 4 commits into
apache:masterfrom
sundapeng:format-table-partition-operations
Draft

[core][spark] Support managed Format Table partition operations#8713
sundapeng wants to merge 4 commits into
apache:masterfrom
sundapeng:format-table-partition-operations

Conversation

@sundapeng

@sundapeng sundapeng commented Jul 18, 2026

Copy link
Copy Markdown
Member

Summary

Follow-up to #8707. This PR makes the catalog the source of truth for opt-in managed Format Table partitions and wires the complete partition lifecycle through Core and Spark SQL.

Changes

  • Add catalog capability checks and REST-catalog partition gateways, while keeping existing unsupported configurations readable as unmanaged so operators can reset the option safely.
  • Read managed partitions from paged catalog metadata with safe predicate-prefix pushdown. Registered partitions without directories read as empty, while unregistered filesystem data remains invisible until repaired.
  • Register partitions after successful writes and preserve committed files when registration fails so metadata can be reconciled without data loss.
  • Harden physical paths: validate untrusted partition metadata, keep resolved paths under the table root, preserve keyed-layout compatibility for . and .., and prevent managed table copies from switching partition-path layouts dynamically.
  • Support managed Format Table ADD/DROP PARTITION, SHOW PARTITIONS, and MSCK REPAIR TABLE ... [ADD|DROP|SYNC] PARTITIONS in Spark. Partial DROP specs use bounded catalog paging and deduplicated scans.
  • Make DROP failure states explicit: ambiguous catalog responses never trigger data deletion or registration recreation; directory-deletion failures remain unregistered so partial data is not exposed.
  • Add sys.list_format_table_partitions with bounded filtered pagination. Continuation tokens are bound to the original where predicate and fail closed if a replayed raw catalog page changes.
  • Add sys.sync_format_table_metadata with dry-run support, scoped filesystem/catalog reconciliation, raw partition-value preservation, paged catalog traversal, and bounded mutation batches.
  • Document the managed option, Spark DDL, repair commands, procedures, limits, and migration path.

Testing

  • Core managed scan, commit, compatibility, path-safety, and catalog tests (125 tests)
  • FormatTableMetadataProcedureTest (36 tests)
  • Spark DDL planning, partition management, and MSCK suites (59 tests)
  • Spark 3 / Scala 2.13 compile on JDK 11
  • Spark 4 / Scala 2.13 compile on JDK 17
  • Spotless and Checkstyle for the affected Core and Spark modules
  • GitHub Actions matrix

Notes

  • Managed Format Table partitions remain opt-in through metastore.partitioned-table=true and require a catalog that advertises the capability (currently REST catalog).
  • Filtered procedure page tokens are opaque and must be resumed with the same where expression.
  • DROP errors identify whether catalog state is ambiguous or which unregistered paths need manual reconciliation.

Relates to #8707.

@sundapeng sundapeng changed the title [core][spark] Support managed Format Table partition operations 【WIP】[core][spark] Support managed Format Table partition operations Jul 18, 2026
@sundapeng
sundapeng force-pushed the format-table-partition-operations branch from f2a9b50 to df367a3 Compare July 18, 2026 06:24
@sundapeng sundapeng changed the title 【WIP】[core][spark] Support managed Format Table partition operations [WIP][core][spark] Support managed Format Table partition operations Jul 18, 2026
@sundapeng sundapeng changed the title [WIP][core][spark] Support managed Format Table partition operations [core][spark] Support managed Format Table partition operations Jul 18, 2026
@sundapeng

Copy link
Copy Markdown
Member Author

To make this easier to review, I have split it into three stacked PRs with identical content (the tip of the stack is byte-identical to this branch):

Converting this PR to draft and keeping it open as the full-feature view; review can start with #8728. I will close this one once the split PRs are merged.

@sundapeng
sundapeng marked this pull request as draft July 19, 2026 07:46
Route managed Format Table partition discovery through the catalog so
scans read exactly the registered partitions and an empty registration
reads as empty instead of falling back to directory listing. Validate
partition locations against the table path before any read or delete.
Register written partitions at commit time in bounded batches, keep
IF NOT EXISTS registration idempotent for concurrent writers, and fall
back to unmanaged directory discovery when no catalog manages the
table.
Route ALTER TABLE ADD/DROP PARTITION for catalog-managed Format Tables
through a Spark-side partition gateway. ADD forwards the whole batch
with the IF NOT EXISTS flag so the catalog can apply it atomically and
creates partition directories; strict batch atomicity stays with the
catalog service. DROP unregisters partitions before deleting their
directories, expands partial specs through bounded catalog pagination,
and never touches data that is not registered. Session-level overrides
of the managed flag are ignored when classifying tables, and unmanaged
Format Tables fail with an explicit unsupported error.
Add list_format_table_partitions and sync_format_table_metadata
procedures for catalog-managed Format Tables. Listing pages through the
catalog and embeds a filter fingerprint in page tokens so stale cursors
are rejected. The sync procedure diffs the filesystem against the
catalog registration, defaults to dry-run, and applies repair diffs in
bounded batches. MSCK REPAIR TABLE reuses the same sync engine through
an interception ahead of Spark's v2 rejection, and SHOW PARTITIONS runs
through a bounded, paginated executor.
Identify the Paimon REST client and its version by default (standard
HTTP practice) so servers can audit callers and detect clients that
predate newer table semantics. An explicit header.User-Agent option
always wins, and the header is outside the DLF signature set.
@sundapeng
sundapeng force-pushed the format-table-partition-operations branch from 2b6e714 to be718a8 Compare July 19, 2026 11:43
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.

1 participant