Skip to content

branch-4.2: [improvement](fe) Upgrade Paimon to 2.1.0 - #70103

Open
suxiaogang223 wants to merge 2 commits into
apache:branch-4.2from
suxiaogang223:codex/pick-69343-paimon-2.1-42
Open

suxiaogang223 wants to merge 2 commits into
apache:branch-4.2from
suxiaogang223:codex/pick-69343-paimon-2.1-42

Conversation

@suxiaogang223

@suxiaogang223 suxiaogang223 commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

What problem does this PR solve?

Issue Number: N/A

Related PR: #69343

Backport master commit 949a8061bfcabf51579f1892a5ffb18343aa42bf to branch-4.2. Upgrade the shared Paimon Java SDK from 1.4.2 to 2.1.0 for both FE and the BE JNI connector.

The release branch predates the connector/plugin split on master. Adapt the changes to its existing fe-core Paimon catalog, paimon-connector JNI module, and PaimonMergePlanner; do not introduce the master connector SPI or its module layout.

  • Upgrade hive-catalog-shade to 4.1.0, which still embeds Hive 3.1.3 but carries Paimon 2.1.0. The old shade bundle embeds Paimon 1.4.2 classes that would otherwise shadow the upgraded SDK.
  • Remove references and fixtures for the SDK's removed file-based privilege APIs, retaining catalog query authorization and existing fallback-branch coverage.
  • Preserve NULL-safe MERGE UPDATE/DELETE with nullable primary keys. MATCHED-only plans use INNER JOIN semantics; MERGE with INSERT uses a target-presence marker before the outer join. Keep user expression binding outside that private marker's scope.
  • Preserve deferred $file_indexes query authorization on FE, including each fallback branch. The existing 4.2 MVCC projection supplies the retained source snapshot to both system-table payloads.
  • Reject unsupported scan.mode=latest-delta OPTIONS instead of pinning it as a full snapshot; explicit @incr ranges remain available.
  • Mirror the existing Hadoop S3 configuration into catalog options for the 2.1 S3FileIO, while retaining explicit Paimon option precedence. Apply the shared mapping to filesystem, HMS, JDBC, and DLF catalog construction.
  • Adapt schema-manager and snapshot fixtures, cover default/checked integer overflow and pre-epoch timestamp-to-date behavior, and enable the existing BE java.nio access in JNI tests.
  • Carry over the original nullable-key/SDK regression suites and runner-generated expected outputs. New vector/full-text/ANN SQL features remain outside this backport.

The 4.2 MERGE command now shares MergeUtils.buildMergeJoin with the planner's target-left/source-right layout. Previously, the command put the source on the left, so the planner attached its target-presence marker to the preserved source. An unmatched row then selected MATCHED and wrote a NULL target key instead of INSERT.

Before: source LEFT OUTER JOIN target
          marker=1                 -> unmatched source is classified as MATCHED

After:  target RIGHT OUTER JOIN source
          marker=1                 -> missing target produces a NULL marker and selects INSERT

The compatibility regression keeps logical splits enabled when asserting Rust-reader execution, and nullable-key MERGE error expectations use the 4.2 implementation's Paimon diagnostics.

Release note

Upgrade the Paimon Java SDK to 2.1.0. Fix NULL-safe MERGE matched UPDATE/DELETE for nullable primary keys; preserve $file_indexes authorization and reject unsupported latest-delta OPTIONS reads. Paimon 2.1 supports opt-in checked integer aggregation and corrects pre-epoch timestamp-to-date casts. Its legacy file-based privilege APIs have been removed; users of that upstream authorization mechanism must migrate before upgrading.

FE and BE Java extensions must deploy the same SDK. Mixed 1.4.2/2.1.0 rolling-upgrade compatibility is not established.

Check List (For Author)

  • Build/style: FE and JNI packaging completed with build.sh using the latest Linux third-party prebuilt. Checkstyle and git diff --check passed.
  • FE unit tests: run-fe-ut.sh --run 'Paimon*Test,MergeIntoCommandTest' completed with 490 passed, 2 environment-gated catalog tests skipped, and no failures. Both new command-layout tests failed on the original implementation and passed after the fix.
  • Regression framework: rebuilt on branch-4.2; all 47 framework unit tests passed.
  • Local cluster regression: all six affected suites passed against their existing golden outputs:
    • test_paimon_nullable_key_merge
    • test_paimon_2_1_compatibility
    • test_paimon_write_boundary
    • test_paimon_write_row_level_dml
    • test_paimon_write_deletion_vector
    • test_paimon_write_merge_semantics
  • Runtime: locally built FE/JNI with the ASAN BE from this PR's successful compile job 1092066, MinIO, and the repository's Spark 4.0.0/Paimon 1.4.2 fixtures. FE/JNI use Paimon 2.1.0. The FE-only follow-up does not include a native C++ change.
  • Previous backport validation also covered 100 JNI connector unit tests.
  • Behavior changed: Yes, Paimon 2.1.0 SDK behavior and correct INSERT classification for unmatched MERGE source rows.
  • Does this need documentation: compatibility changes are recorded in the release note.

Self-review

  • Goal and scope: backport the SDK upgrade and directly affected behavior to the existing 4.2 layout. No master connector refactor or search feature is included.
  • Concurrency: no new threads, shared mutable state, or lock ordering. Existing cache/transaction locks are unchanged.
  • Lifecycle: no new resource owners or static initialization dependencies. Tests close local catalog, writer, commit, and reader resources.
  • Configuration: no new configuration key. Existing S3 settings now reach the SDK's catalog-option reader; explicit Paimon settings retain precedence.
  • Compatibility: the upstream legacy privilege API removal and same-SDK deployment requirement are documented. Mixed-SDK rolling upgrades are unverified.
  • Protocol: no Thrift/Protobuf schema or field IDs are changed. FE and BE dependency versions share one property.
  • Parallel paths: FE catalog and BE JNI dependencies move together. Shared S3 mapping covers all Hadoop-backed catalog constructors; fallback authorization checks both branches.
  • Conditions: Command and planner share the target-left/source-right join contract. The target marker distinguishes a real nullable-key row from an outer join's null-extension; both branch layouts have command-level tests. Unsupported delta mode fails explicitly.
  • Tests: SDK serialization/nullable-key behavior, MERGE branch selection and marker-name collisions, deferred authorization, S3 option precedence, and existing Paimon reader/cache tests are included. Cluster regression files and goldens are copied from the original PR, not hand-generated.
  • Results: see validation above; original master test totals are not represented as results for this backport.
  • Observability: unsupported delta mode returns an actionable diagnostic; existing scan error propagation is retained. No new metric is needed for this adaptation.
  • Persistence/transactions: no EditLog or recovery changes. Existing MERGE cardinality and transaction atomicity logic remains in place; nullable-key regression coverage includes duplicate-match rejection.
  • Writes: only MERGE target-presence classification changes. Writer commit/abort and storage ownership are unchanged.
  • FE/BE variables: none added.
  • Performance: no performance improvement is claimed; MERGE adds one constant target projection only when INSERT branches require an outer join. S3 options are copied at catalog construction.
  • Other concerns: the inspected OBS/S3 CI failures were connection timeouts and require rerunning CI against those endpoints. Mixed-SDK upgrades remain unverified.

Check List (For Reviewer who merge this PR)

  • Confirm the release note
  • Confirm test cases
  • Confirm document
  • Add branch pick label

### What problem does this PR solve?

Issue Number: N/A

Related PR: apache#69343

Backport master commit `949a8061bfcabf51579f1892a5ffb18343aa42bf` to branch-4.2. Upgrade the shared Paimon Java SDK from 1.4.2 to 2.1.0 for both FE and the BE JNI connector.

The release branch predates the connector/plugin split on master. Adapt the changes to its existing `fe-core` Paimon catalog, `paimon-connector` JNI module, and `PaimonMergePlanner`; do not introduce the master connector SPI or its module layout.

- Upgrade `hive-catalog-shade` to 4.1.0, which still embeds Hive 3.1.3 but carries Paimon 2.1.0. The old shade bundle embeds Paimon 1.4.2 classes that would otherwise shadow the upgraded SDK.
- Remove references and fixtures for the SDK's removed file-based privilege APIs, retaining catalog query authorization and existing fallback-branch coverage.
- Preserve NULL-safe MERGE UPDATE/DELETE with nullable primary keys. MATCHED-only plans use INNER JOIN semantics; MERGE with INSERT uses a target-presence marker before the outer join. Keep user expression binding outside that private marker's scope.
- Preserve deferred `$file_indexes` query authorization on FE, including each fallback branch. The existing 4.2 MVCC projection supplies the retained source snapshot to both system-table payloads.
- Reject unsupported `scan.mode=latest-delta` OPTIONS instead of pinning it as a full snapshot; explicit `@incr` ranges remain available.
- Mirror the existing Hadoop S3 configuration into catalog options for the 2.1 S3FileIO, while retaining explicit Paimon option precedence. Apply the shared mapping to filesystem, HMS, JDBC, and DLF catalog construction.
- Adapt schema-manager and snapshot fixtures, cover default/checked integer overflow and pre-epoch timestamp-to-date behavior, and enable the existing BE `java.nio` access in JNI tests.
- Carry over the original nullable-key/SDK regression suites and runner-generated expected outputs. New vector/full-text/ANN SQL features remain outside this backport.

### Release note

Upgrade the Paimon Java SDK to 2.1.0. Fix NULL-safe MERGE matched UPDATE/DELETE for nullable primary keys; preserve `$file_indexes` authorization and reject unsupported `latest-delta` OPTIONS reads. Paimon 2.1 supports opt-in checked integer aggregation and corrects pre-epoch timestamp-to-date casts. Its legacy file-based privilege APIs have been removed; users of that upstream authorization mechanism must migrate before upgrading.

FE and BE Java extensions must deploy the same SDK. Mixed 1.4.2/2.1.0 rolling-upgrade compatibility is not established.

### Check List (For Author)

- Unit tests: `EXTRA_FE_MODULES=paimon=be-java-extensions/paimon-connector ./run-fe-ut.sh --run 'Paimon*Test,AbstractPaimonPropertiesTest,DorisIOManagerTest,GlobalIndexAssignerTest'` passed.
  - FE: 480 scheduled, 478 passed, 2 pre-existing environment-gated catalog tests skipped (`PaimonCatalogTest`, `PaimonDlfRestCatalogTest`).
  - BE Java/JNI connector: 100 passed, no failures or skips.
  - Includes SDK serialization with nullable keys, MERGE target-presence/name collisions, deferred file-index authorization, S3 configuration precedence, cache governance and scan planning.
- FE and JNI Checkstyle: zero violations. `git -c core.whitespace=-blank-at-eof diff --check` passed (retain the runner-generated golden files' final blank separators).
- FE and JNI production/test Java compiled through the test runner against Paimon 2.1.0 and hive-catalog-shade 4.1.0.
- Full `build.sh --fe` packaging was not completed: the local third-party installation lacks the native Paimon/Lance archives, and that entry point starts rebuilding the whole third-party set. No native C++ code is changed.
- Cluster regression and native BE runtime tests were not run locally. Regression suites and golden outputs are carried from apache#69343; its master validation totals are not claimed here.

- Behavior changed: Yes, Paimon 2.1.0 SDK behavior and the adaptations described above.
- Does this need documentation: No separate documentation change; compatibility changes are recorded in the release note.

### Self-review

- Goal and scope: backport the SDK upgrade and directly affected behavior to the existing 4.2 layout. No master connector refactor or search feature is included.
- Concurrency: no new threads, shared mutable state, or lock ordering. Existing cache/transaction locks are unchanged.
- Lifecycle: no new resource owners or static initialization dependencies. Tests close local catalog, writer, commit, and reader resources.
- Configuration: no new configuration key. Existing S3 settings now reach the SDK's catalog-option reader; explicit Paimon settings retain precedence.
- Compatibility: the upstream legacy privilege API removal and same-SDK deployment requirement are documented. Mixed-SDK rolling upgrades are unverified.
- Protocol: no Thrift/Protobuf schema or field IDs are changed. FE and BE dependency versions share one property.
- Parallel paths: FE catalog and BE JNI dependencies move together. Shared S3 mapping covers all Hadoop-backed catalog constructors; fallback authorization checks both branches.
- Conditions: the target marker distinguishes a real nullable-key row from an outer join's null-extension. Unsupported delta mode fails explicitly.
- Tests: SDK serialization/nullable-key behavior, MERGE branch selection and marker-name collisions, deferred authorization, S3 option precedence, and existing Paimon reader/cache tests are included. Cluster regression files and goldens are copied from the original PR, not hand-generated.
- Results: see validation above; original master test totals are not represented as results for this backport.
- Observability: unsupported delta mode returns an actionable diagnostic; existing scan error propagation is retained. No new metric is needed for this adaptation.
- Persistence/transactions: no EditLog or recovery changes. Existing MERGE cardinality and transaction atomicity logic remains in place; nullable-key regression coverage includes duplicate-match rejection.
- Writes: only MERGE target-presence classification changes. Writer commit/abort and storage ownership are unchanged.
- FE/BE variables: none added.
- Performance: no performance improvement is claimed; MERGE adds one constant target projection only when INSERT branches require an outer join. S3 options are copied at catalog construction.
- Other concerns: full cluster/native regression validation and mixed-SDK upgrades remain outside local verification.

### Check List (For Reviewer who merge this PR)

- [ ] Confirm the release note
- [ ] Confirm test cases
- [ ] Confirm document
- [ ] Add branch pick label

(cherry picked from commit 949a806)
@hello-stephen

Copy link
Copy Markdown
Contributor

Thank you for your contribution to Apache Doris.
Don't know what should be done next? See How to process your PR.

Please clearly describe your PR:

  1. What problem was fixed (it's best to include specific error reporting information). How it was fixed.
  2. Which behaviors were modified. What was the previous behavior, what is it now, why was it modified, and what possible impacts might there be.
  3. What features were added. Why was this function added?
  4. Which code was refactored and why was this part of the code refactored?
  5. Which functions were optimized and what is the difference before and after the optimization?

@suxiaogang223 suxiaogang223 changed the title [improvement](fe) Upgrade Paimon to 2.1.0 (branch-4.2) branch-4.2: [improvement](fe) Upgrade Paimon to 2.1.0 Nov 3, 2026
@suxiaogang223

Copy link
Copy Markdown
Member Author

run buildall

@suxiaogang223

Copy link
Copy Markdown
Member Author

/review

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Codex automated review failed and did not complete.

Error: Selected model is at capacity. Please try a different model.
Workflow run: https://github.com/apache/doris/actions/runs/41614088069

Please inspect the workflow logs and rerun the review after the underlying issue is resolved.

@zhangstar333

Copy link
Copy Markdown
Contributor

run buildall

### What problem does this PR solve?

Issue Number: N/A

Related PR: apache#70103, apache#69343

Problem Summary: The backported Paimon merge planner adds its target-presence
marker to the left join input, but PaimonMergeCommand still places the source
on the left. Unmatched source rows therefore select MATCHED and write NULL
target keys instead of inserting. Reuse MergeUtils to keep the target on the
left and preserve the source with RIGHT OUTER JOIN when INSERT is present.
Add command-level tests for both join layouts. Keep logical splits when the
compatibility case asserts Rust execution and use the 4.2 MERGE diagnostics
in nullable-key error expectations.

### Release note

Fix Paimon MERGE INTO incorrectly classifying unmatched source rows as matched
on branch-4.2, including NULL key writes to non-nullable primary keys.

### Check List (For Author)

- Test: FE/JNI build and Checkstyle; 490 FE unit tests passed, 2 environment-gated
  tests skipped; 47 regression framework unit tests passed; all 6 affected
  Paimon regression suites passed against existing golden outputs using the
  PR's successful CI ASAN BE and the repository's Spark/Paimon fixtures.
- Behavior changed: Yes, unmatched Paimon MERGE source rows select INSERT.
- Does this need documentation: No, restores the intended MERGE semantics.
@suxiaogang223

Copy link
Copy Markdown
Member Author

run buildall

@suxiaogang223

Copy link
Copy Markdown
Member Author

Local code review completed for 94fb806 against branch-4.2 base 3767131. Reviewed the complete 34-file PR diff and the affected FE planning, snapshot, catalog-construction, and BE JNI read/write call chains using the local code-review skill.

Result: PASS. No actionable findings in the reviewed diff. This is a review of the current revision, including the MERGE input-layout fix.

Critical checkpoint conclusions:

Checkpoint Conclusion
Goal and proof The shared SDK and embedded shade move to Paimon 2.1.0. Nullable-key serialization, MERGE branch selection, integer overflow, and pre-epoch date semantics have targeted tests.
Scope and reuse Changes stay within the 4.2 SDK adaptation and affected tests. PaimonMergeCommand reuses MergeUtils.buildMergeJoin; no connector/plugin-layout backport is introduced.
Concurrency and locks No new threads, shared mutable state, or lock-order change. S3 mirroring runs during catalog initialization, before the options map is published through the existing initialization path.
Lifecycle No new resource owner or static-initialization dependency. SDK catalog authorization retains its existing catalog close boundary; local writer/commit/reader test resources are closed.
Configuration No new Doris FE/BE configuration. Hadoop S3 settings are copied into the SDK catalog options, preserving explicit Paimon values.
Compatibility FE/JNI dependency management uses the same version. The shade's embedded Paimon is aligned; embedded Hive/Iceberg class contents are unchanged. Removal of upstream file-based privilege APIs is documented. Mixed 1.4.2/2.1.0 rolling-upgrade compatibility remains unverified and is explicitly disclosed.
Thrift/Protobuf No schema, field ID, or enum change.
Parallel paths The shared S3 mapping is reached by filesystem, HMS, JDBC, and DLF initialization. Deferred system-table checks traverse both fallback branches. FE and JNI dependency versions change together.
Conditions and planner invariants MATCHED-only MERGE uses INNER JOIN. MERGE with INSERT uses target-left RIGHT OUTER JOIN source; the target-side constant becomes NULL only for a missing target. Marker lookup uses ExprId, and user binding retains the original scope. Unsupported latest-delta OPTIONS fail explicitly.
Test coverage Command-layout and planner tests cover both join shapes, nullable keys, null-extension, and marker-name collisions. Regression covers UPDATE/DELETE/INSERT, branch priority, duplicate rejection, JNI/Rust reads, file indexes, and checked overflow.
Expected results Both new golden files passed local regression comparison. The modified snapshots golden adds exactly the SDK's nullable operation and writer_version columns; legacy fixture snapshots lack both fields. The full static-fixture system-table suite was not rerun locally.
Observability Existing exception propagation is retained; unsupported delta mode gives an actionable error. No new execution subsystem requiring metrics is introduced.
Transactions and persistence No EditLog/replay or failover-protocol change. Existing cardinality checks and commit/abort paths remain in use.
Writes and atomicity Nullable-key branch classification is corrected without changing writer ownership or commit sequencing. Duplicate matches/inserts are rejected; the transaction regression confirms a failed oversized write publishes neither rows nor a new snapshot.
FE/BE variables No new protocol variable or sending path. Serialized SDK objects require the FE/JNI version alignment noted above.
Performance The target marker is one constant projection, added only for INSERT-capable MERGE. S3 mirroring is one configuration traversal at catalog creation. No new per-row allocation or unbounded planning work was found in the diff.
Other concerns Environment-gated HMS/DLF tests and mixed-SDK deployment remain outside completed local coverage. External-service CI still needs its own successful run.

Validation on this head in the current worktree:

  • FE and JNI packaging through build.sh, including Checkstyle: passed.
  • FE tests via run-fe-ut.sh --run 'Paimon*Test,MergeIntoCommandTest': 490 passed, 2 environment-gated skips, 0 failures. The two command-layout tests fail before the fix and pass afterward.
  • Regression framework build: 47 unit tests passed.
  • Regression through run-regression-test.sh, comparing committed expected outputs: 7 suites passed, 0 failures/skips: test_paimon_nullable_key_merge, test_paimon_2_1_compatibility, test_paimon_write_boundary, test_paimon_write_row_level_dml, test_paimon_write_deletion_vector, test_paimon_write_merge_semantics, and the additionally checked test_paimon_write_transaction.
  • Runtime: locally built FE/JNI using Paimon 2.1.0, this PR's successful CI ASAN BE artifact (compile job 1092066), MinIO, and the repository's Spark 4.0.0/Paimon 1.4.2 fixtures. No new native C++ change is present.
schema: doris-repo-review/v1
status: PASS
pr: apache/doris#70103
commit: 94fb806bd61dcab775c8906694efd8236d2f2523
base: 37671319cdefc44dd8e5b85a0584a4826460f03d
reviewed_at: 2026-11-05T07:37:50+00:00
reviewer: suxiaogang223
model: gpt-6.1-sol
effort: xhigh
findings: {blocker: 0, major: 0, minor: 0, nit: 0}
rounds: 1
converged: true

@suxiaogang223

Copy link
Copy Markdown
Member Author

/review

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Codex automated review failed and did not complete.

Error: Review context preparation failed before Codex ran; inspect the 'Prepare authoritative PR context and required AGENTS guides' step.
Workflow run: https://github.com/apache/doris/actions/runs/41988992056

Please inspect the workflow logs and rerun the review after the underlying issue is resolved.

@hello-stephen

Copy link
Copy Markdown
Contributor

FE Regression Coverage Report

Increment line coverage 15.57% (26/167) 🎉
Increment coverage report
Complete coverage report

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