[fix](routineload) Persist the current load definition - #66634
Open
0AyanamiRei wants to merge 13 commits into
Open
[fix](routineload) Persist the current load definition#666340AyanamiRei wants to merge 13 commits into
0AyanamiRei wants to merge 13 commits into
Conversation
### What problem does this PR solve? Issue Number: N/A Related PR: apache#64878 Problem Summary: Routine Load image recovery reparsed the immutable original CREATE statement, so CREATE semantics changed by ALTER were not represented in the image. Persist the current load definition, retain the original statement as the legacy-image fallback, journal altered load clauses, and validate failure-prone Kafka and Kinesis changes before mutating runtime state. ### Release note Routine Load jobs now recover the current effective load definition after ALTER. ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.load.routineload.KafkaRoutineLoadJobTest,org.apache.doris.load.routineload.KinesisRoutineLoadJobTest,org.apache.doris.persist.AlterRoutineLoadOperationLogTest - Behavior changed: Yes. Image recovery uses the current effective Routine Load definition while legacy images continue to use origStmt. - Does this need documentation: No
0AyanamiRei
requested review from
gavinchou,
liaoxin01 and
mymeiyi
as code owners
August 11, 2026 02:21
Contributor
|
Thank you for your contribution to Apache Doris. Please clearly describe your PR:
|
### What problem does this PR solve? Issue Number: N/A Related PR: apache#64878 Problem Summary: Keep the original CREATE statement in new images so an older FE can ignore the new load definition field and use its existing recovery path. ALTERed load clauses are outside the downgrade compatibility guarantee and may not survive rollback. ### Release note Document that Routine Load ALTER semantics are not guaranteed after rolling back to an older FE. ### Check List (For Author) - Test: Not run (per request; compatibility coverage was added) - Behavior changed: No. This records and tests the intended rollback compatibility boundary. - Does this need documentation: Yes. The rollback limitation must be called out in the feature documentation.
0AyanamiRei
marked this pull request as draft
August 11, 2026 03:16
### What problem does this PR solve? Issue Number: N/A Related PR: apache#64878 Problem Summary: Routine Load now persists its effective load definition directly, but nested legacy Expr SQL-carrier fields also need stable serialization, legacy image/log fixtures must come from the merge base, and ALTER replay must not apply new leader-side CSV validation to historical journals. Complete those compatibility requirements and add three-FE failover coverage for leader journal write, follower replay, checkpoint, and restart recovery. ### Release note Routine Load jobs preserve effective load clauses across ALTER, follower replay, checkpoint, and FE restart. Legacy images continue to migrate from the original CREATE statement; rollback to an older FE remains structurally readable but does not preserve new ALTER semantics. ### Check List (For Author) - Test: Not run per requested handoff; FE unit and Docker regression coverage were added. - Behavior changed: Yes. Routine Load persistence and ALTER replay retain the current effective definition. - Does this need documentation: Yes. Document rolling-upgrade and rollback limitations.
0AyanamiRei
marked this pull request as ready for review
August 20, 2026 02:02
### What problem does this PR solve? Issue Number: N/A Related PR: apache#64878 Problem Summary: Directly persisting legacy Expr makes Routine Load metadata depend on complete Gson coverage for a broad and evolving expression graph. Keep origStmt as the durable load-definition carrier instead. ALTER logs persist the original ALTER SQL, leader and follower replay merge each delta into a canonical CREATE statement, and image recovery reparses that current effective statement. ### Release note Routine Load ALTER clauses are persisted by updating the stored CREATE statement and replaying ALTER SQL, avoiding a durable dependency on legacy Expr Gson serialization. ### Check List (For Author) - Test: Unit Test - RoutineLoadJobPersistenceTest and KafkaRoutineLoadJobTest: 16 tests passed. - AlterRoutineLoadOperationLogTest and KinesisRoutineLoadJobTest: 13 tests passed in the preceding targeted run. - Behavior changed: Yes. Routine Load load clauses use canonical origin SQL for image and journal recovery. - Does this need documentation: Yes. Document ALTER recovery and rolling-upgrade compatibility.
…d-definition-persistence
### What problem does this PR solve? Issue Number: close apache#66633 Related PR: apache#66634 Problem Summary: Routine Load cannot safely use the legacy Expr object graph as an image or journal compatibility surface. Keep the current effective load definition in origStmt, remove the duplicate execMemLimit JSON source, and cover all SQL-representable load clauses through CREATE image restore, ALTER merge, and a second image restore. ### Release note Routine Load now persists ALTERed load clauses in the effective origin SQL used during FE recovery. ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.load.routineload.RoutineLoadJobPersistenceTest - ./run-fe-ut.sh --run org.apache.doris.load.routineload.KafkaRoutineLoadJobTest,org.apache.doris.load.routineload.KinesisRoutineLoadJobTest,org.apache.doris.persist.AlterRoutineLoadOperationLogTest - Docker regression case added but not run locally - Behavior changed: Yes, ALTERed Routine Load definitions survive journal replay and image recovery - Does this need documentation: Yes, the existing design document and PR description must be updated
0AyanamiRei
requested review from
924060929,
englefly,
morrySnow and
starocean999
as code owners
August 20, 2026 06:04
### What problem does this PR solve? Issue Number: close apache#66633 Related PR: apache#66634 Problem Summary: Routine Load images already persist and replay origStmt. The persistence bug is that ALTER load clauses changed runtime fields without updating that statement. Keep the existing gsonPostProcess recovery path unchanged, persist the original ALTER SQL in the journal, and rewrite origStmt to a complete effective CREATE statement after leader and follower ALTER application. Remove direct-field persistence, cache hydration, CSV validation, and other adjacent changes from this PR. ### Release note Routine Load now preserves ALTERed load clauses across follower replay, checkpoints, and FE restart by maintaining the effective CREATE statement. ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.load.routineload.RoutineLoadJobPersistenceTest - ./run-fe-ut.sh --run org.apache.doris.load.routineload.KinesisRoutineLoadJobTest - KafkaRoutineLoadJobTest and AlterRoutineLoadOperationLogTest passed in the combined targeted run - Docker regression case added but not run locally - Behavior changed: Yes, ALTERed load clauses update the persisted origin statement - Does this need documentation: Yes, document mixed-version ALTER limitations
### What problem does this PR solve? Issue Number: close apache#66633 Related PR: apache#66634 Problem Summary: Treat the effective Routine Load fields as authoritative metadata instead of rewriting origStmt after ALTER. Persist the load-definition fields directly in images, persist RoutineLoadDesc deltas in ALTER journals, and use the original CREATE statement only when reading legacy images whose nullable effective fields are absent. Empty new definitions may also use the fallback safely because ALTER cannot unset all load clauses. ### Release note Routine Load now preserves ALTERed load clauses across journal replay and FE restart through direct metadata persistence. ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.load.routineload.RoutineLoadJobPersistenceTest,org.apache.doris.load.routineload.KafkaRoutineLoadJobTest,org.apache.doris.load.routineload.KinesisRoutineLoadJobTest,org.apache.doris.persist.AlterRoutineLoadOperationLogTest - Behavior changed: Yes, image and ALTER journal persist effective Routine Load definitions directly - Does this need documentation: Yes, document mixed-version ALTER limitations
### What problem does this PR solve? Issue Number: close apache#66633 Related PR: apache#66634 Problem Summary: Metadata consumers now persist legacy Expr objects directly, but the existing Expr Gson test only checked subtype and JSON idempotence. Add stable serialization for SQL-relevant fields that were silently dropped, persist function ORDER BY metadata, require every Expr instance field to be serialized or explicitly classified as non-durable, and verify SQL output with and without table names for every concrete registered subtype. Add an analysis review guide for future Expr changes. ### Release note None ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.analysis.ExprGsonSerializationTest - ./run-fe-ut.sh --run org.apache.doris.analysis.ExprGsonSerializationTest,org.apache.doris.load.routineload.RoutineLoadJobPersistenceTest,org.apache.doris.persist.AlterRoutineLoadOperationLogTest - Behavior changed: No user-facing SQL behavior; metadata Expr round trips now preserve SQL semantics - Does this need documentation: No, contributor guidance is included in analysis/AGENTS.md
### What problem does this PR solve? Issue Number: close apache#66633 Related PR: apache#66634 Problem Summary: The first restoration of direct Routine Load persistence omitted parts of the previously reviewed design. Restore the exact persistence implementation from commit 4394fa3, including execMemLimit and memtableOnSinkNode image fields, jobProperties cache hydration, CSV ALTER cache synchronization, leader-only validation, legacy image migration, and the original Kafka/Kinesis persistence tests. Keep the separate Expr serde hardening on top. ### Release note Routine Load persists its effective load definition and non-default task configuration directly across FE recovery. ### Check List (For Author) - Test: Unit Test - ./run-fe-ut.sh --run org.apache.doris.analysis.ExprGsonSerializationTest,org.apache.doris.load.routineload.RoutineLoadJobPersistenceTest,org.apache.doris.load.routineload.KafkaRoutineLoadJobTest,org.apache.doris.load.routineload.KinesisRoutineLoadJobTest,org.apache.doris.persist.AlterRoutineLoadOperationLogTest - Behavior changed: Yes, restore the complete direct-state image and ALTER journal persistence contract - Does this need documentation: Yes, document mixed-version ALTER limitations
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What problem does this PR solve?
Issue Number: N/A
Related PR: #64878
Problem Summary:
This is the persistence and recovery prerequisite for future Routine Load ALTER work. It does not add target-table ALTER syntax or behavior.
Routine Load historically persisted the original CREATE statement in
origStmtand reparsed it whenever an image was loaded. That statement is immutable, while ALTER ROUTINE LOAD changes the effective load clauses kept inRoutineLoadJob. After an ALTER followed by checkpoint/restart, reparsing the stale CREATE statement could therefore restore the original definition instead of the definition currently used to create tasks.There are two independent persistence paths that must retain the same effective state:
memtable_on_sink_node.RoutineLoadDescdelta inAlterRoutineLoadJobOperationLog, apply properties and the load-clause delta under the job write lock on the leader, and apply them in the same order during follower replay.The final design deliberately does not introduce a
LoadDefinitionwrapper or duplicate job/data-source property snapshots:RoutineLoadJobfields remain the effective state and receive stable Gson keys.jobPropertiesremains authoritative for properties whose runtime caches are rebuilt after deserialization.origStmtremains persisted for downgrade readability and for one-time migration of legacy images.origStmtonce, restores the load clauses andexec_mem_limit, and the next checkpoint naturally writes the direct-state format.memtable_on_sink_nodecannot be reconstructed and retains its historical post-restart value offalse.The ALTER log stores only the changed
RoutineLoadDescclauses. Nullable fields preserve clauses not modified by that ALTER. Old logs do not contain this field and therefore leave the current definition unchanged during replay.CSV ALTER properties are validated only on the leader before mutation. Replay trusts persisted journal values so that validation added by a newer FE cannot prevent replay of a journal written by an older FE. The cached
enclose,escape, andempty_field_as_nullvalues are kept in sync withjobProperties.Because Routine Load converts legacy expressions back to SQL before building each Nereids task, the persisted expression graph must retain every field that affects SQL generation. This PR adds stable serialization for the relevant
MatchPredicate,SlotRef, andTimeV2Literalfields and verifies SQL-equivalent Gson round trips.Compatibility boundary:
origStmtmigration. ALTER load clauses that were never recorded by the old image or old journal are not recoverable; the original CREATE semantics are restored.origStmtis still available, but semantic downgrade is not guaranteed. An old FE may restore the original CREATE clauses and ignore new ALTER deltas.Out of scope:
Tests added:
origStmtto prove new images do not fall back to SQL parsing.origStmtparsing.a8928245, including provenance and explicit assertions for unrecoverable legacy state.RoutineLoadDesc, and leader/replay checkpoint parity.Validation status for the final head:
git diff --check: passed.Release note
Routine Load jobs now preserve the effective load clauses after ALTER across follower replay, leader failover, checkpoint, and FE restart.
During a rolling upgrade, do not ALTER Routine Load load clauses until all FEs are running the new version. Rolling back after a new-version checkpoint can restore the original CREATE clauses instead of post-upgrade ALTER semantics.
Check List (For Author)
Test
Behavior changed:
origStmt.Does this need documentation?
Check List (For Reviewer who merge this PR)