From e168cd4d1c383ec5e9b21496dd2ccca6d78d2ac1 Mon Sep 17 00:00:00 2001
From: Hangxiang Yu <masteryhx@gmail.com>
Date: Wed, 28 Feb 2024 10:01:39 +0800
Subject: [PATCH] [FLINK-34352][doc] Improve the documentation of
 allowNonRestoredState

---
 docs/content.zh/docs/ops/state/savepoints.md | 10 +++++++++-
 docs/content/docs/ops/state/savepoints.md    |  8 +++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/content.zh/docs/ops/state/savepoints.md b/docs/content.zh/docs/ops/state/savepoints.md
index 9916f1080cca2..25ae077a88a3c 100644
--- a/docs/content.zh/docs/ops/state/savepoints.md
+++ b/docs/content.zh/docs/ops/state/savepoints.md
@@ -180,7 +180,15 @@ $ bin/flink run -s :savepointPath [:runArgs]
 
 #### 跳过无法映射的状态恢复
 
-默认情况下，resume 操作将尝试将 Savepoint 的所有状态映射回你要还原的程序。 如果删除了运算符，则可以通过 `--allowNonRestoredState`（short：`-n`）选项跳过无法映射到新程序的状态：
+默认情况下，resume 操作将尝试将 Savepoint 的所有状态映射回你要还原的程序。 如果删除了运算符，则可以通过 `--allowNonRestoredState`（short：`-n`）选项跳过无法映射到新程序的状态。
+
+{{< hint warning  >}}
+错误使用这个功能可能会导致应用程序出现严重的正确性问题。其中最重要的是确认剩余的状态是否能够准确地映射到相应的运算符上。
+
+需要注意在默认情况下，运算符的 UID 是根据拓扑顺序重新分配的，这会导致状态与运算符无法正确关联，最终造成状态未能按照预期正确恢复。
+
+为了防止这种不匹配，建议在 DataStream 作业中显式地为所有操作符[指定 UID ]({{< ref "docs/ops/production_ready" >}}/#set-uuids-for-all-operators)。
+{{< /hint >}}
 
 #### Claim 模式
 
diff --git a/docs/content/docs/ops/state/savepoints.md b/docs/content/docs/ops/state/savepoints.md
index 82a9649dc5101..cf08141bad8f1 100644
--- a/docs/content/docs/ops/state/savepoints.md
+++ b/docs/content/docs/ops/state/savepoints.md
@@ -208,7 +208,13 @@ This submits a job and specifies a savepoint to resume from. You may give a path
 
 #### Allowing Non-Restored State
 
-By default, the resume operation will try to map all state of the savepoint back to the program you are restoring with. If you dropped an operator, you can allow to skip state that cannot be mapped to the new program via `--allowNonRestoredState` (short: `-n`) option:
+By default, the resume operation will try to map all state of the savepoint back to the program you are restoring with. If you dropped an operator, you can allow to skip state that cannot be mapped to the new program via `--allowNonRestoredState` (short: `-n`) option.
+
+{{< hint warning  >}}
+Improper usage of this feature could result in significant issues with the correctness of the application. It is crucial to verify that any remaining states can be accurately mapped to the appropriate operators.
+It is worth noting that operator UIDs are reassigned based on topological order by default, which may lead to incorrect associations between states and operators, thus consequently states are not correctly restored as wished.
+To prevent such mismatches, it is advisable to explicitly [assign UIDs] ({{< ref "docs/ops/production_ready" >}}/#set-uuids-for-all-operators) to all operators in a DataStream job. 
+{{< /hint >}}
 
 #### Claim mode