Skip to content

[FLINK-38960][doc] Clarify scope of state compatibility in "Upgrading… #27455

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
curcur merged 1 commit into from
Jan 23, 2026
+8 −0
Merged

[FLINK-38960][doc] Clarify scope of state compatibility in "Upgrading… #27455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/content.zh/docs/ops/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,9 @@ $ bin/flink run -s :savepointPath [:runArgs]

Savepoint 在 Flink 版本之间是兼容的，如下表所示：

***注意***：此处的“兼容”仅指 Savepoint 内部数据格式的兼容性，并不包含 SQL 算子或其他上层改动的兼容性。
在实践中，只要 Flink SQL 语义没有发生变化，这种状态格式的兼容性通常也能保证作业级别的兼容性。

<table class="table table-bordered" style="font-size:8pt">
<thead>
<tr>
Expand Down
5 changes: 5 additions & 0 deletions docs/content/docs/ops/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,11 @@ For more details, please take a look at the [savepoint documentation]({{< ref "d

Savepoints are compatible across Flink versions as indicated by the table below:

**Note**: "Compatible" here refers specifically to compatibility of the internal data format in
Copy link
Contributor

@davidradl davidradl Jan 22, 2026

Choose a reason for hiding this comment

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

The Jira indicates "This helps to avoid user confusion.". I am not sure how to action "cover compatibility of SQL operators or other Upper-level changes". It leads me to ask the questions

  • how do I check the compatibility of SQL operators
  • how can I check the other Upper-level changes

If I cannot do this, how will I know if my savepoint can be upgraded.
I wonder if we can as a minimum either:

  • ask the user to investigate the code base with some guidance around their save point. I think this would help as it would be a way forward for them. Ideally we would document the criteria when the savepoints are compatible and when they are not.
  • give an example of an incompatible savepoint in each of these cases where the internal data structure is compatible.

Copy link
Contributor Author

@AlexYinHan AlexYinHan Jan 23, 2026

Choose a reason for hiding this comment

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

Thanks for the comment. I have added lines as curcur suggested to prevent further confusion. I think we may later include more guidance if our users find it still hard to understand the statements in this document.

savepoints. It does not cover compatibility of SQL operators or other Upper-level changes. In
practice, provided there are no changes to Flink SQL semantics, this state format compatibility
typically also ensures job-level compatibility.

<table class="table table-bordered" style="font-size:8pt">
<thead>
<tr>
Expand Down