You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@fluss.apache.org by "gstamatakis95 (via GitHub)" <gi...@apache.org> on 2026/08/28 09:04:21 UTC
[PR] [docs] Document Paimon tiering issue with externally evolved schema [fluss]
gstamatakis95 opened a new pull request, #4140:
URL: https://github.com/apache/fluss/pull/4140
### Purpose
Linked issue: close #4138
Documents the known issue reported in #4038. When the schema of a Paimon lake table managed by Fluss is evolved by an external engine (for example Spark or Doris adding a column directly on the Paimon table), the tiering job fails to write subsequent records and restarts in a loop until the schemas match again. There is no code fix for this yet, so this PR documents the failure, its blast radius, the safety guarantees, and the recovery steps, and states the operational rule that lake table schemas must only be evolved through Fluss. The issue report describes the failure as an endless retry of the same split, while this documentation describes the verified behavior of the shipped code, where the write failure restarts the whole tiering job in a loop because `FlussLakeTiering` configures full-restart failover with an indefinite exponential-delay restart strategy. This PR touches a different section of `paimon.md` than the open #4112, so the two changes do not conflict.
### Brief change log
- **`website/docs/streaming-lakehouse/datalake-formats/paimon.md`**: adds a Schema Evolution section describing the supported evolution path (`ALTER TABLE ... ADD` on the Fluss table, which applies the same change to the Paimon table as part of the statement) and a warning covering the external evolution failure: the exact error signature, the job-level restart loop visible in the Flink UI, the impact on the other tables served by the same tiering job, the paused log retention and growing storage while tiering is stalled, and the recovery steps (run the matching `ALTER TABLE ... ADD` on the Fluss table to keep the column, or drop the externally added column when Fluss cannot reconcile the schemas). Links #4038 for tracking.
- **`website/docs/streaming-lakehouse/tiering-service.md`**: adds a warning in the Overview that the schema of a lake table managed by the Tiering Service must never be changed through an external engine, notes that only Paimon and Iceberg support schema evolution through Fluss, and links the Paimon Schema Evolution section for symptoms and recovery.
- **`website/docs/engine-flink/ddl.md`**: adds a note in the Add Columns section that datalake-enabled tables on a Paimon or Iceberg lakehouse propagate added columns to the corresponding lake table, that adding columns to datalake-enabled Hudi and Lance tables is not yet supported, and that the lake table must not be altered externally, linking the Paimon Schema Evolution section.
### Tests
Documentation-only change, no tests. Every statement was verified against the current code: the error strings in `FlussRecordAsPaimonRow` and `PaimonLakeWriter`, the full-restart failover strategy and the indefinite exponential-delay restart strategy configured in `FlussLakeTiering`, the lake-first schema sync applied by the coordinator in `MetadataManager.alterTableSchema`, the schema compatibility check in `PaimonLakeCatalog.alterTable` and `PaimonTableValidation.isPaimonSchemaCompatible`, and the unsupported `alterTable` in the Hudi and Lance lake catalogs. All internal links and anchors were checked to resolve.
### API and Format
No API or storage format changes. Documentation only.
### Documentation
This PR is the documentation task itself. It updates the Paimon lake format page, the Tiering Service page, and the Flink DDL Add Columns section of the `next` docs version.
🤖 AI-assisted changes - reviewed by human developer
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [docs] Document Paimon tiering issue with externally evolved schema [fluss]
Posted by "fresh-borzoni (via GitHub)" <gi...@apache.org>.
fresh-borzoni merged PR #4140:
URL: https://github.com/apache/fluss/pull/4140
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org