diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md index 3972ba05f26b..7ee29a00539c 100644 --- a/tidb-lightning/tidb-lightning-configuration.md +++ b/tidb-lightning/tidb-lightning-configuration.md @@ -114,21 +114,25 @@ driver = "file" # keep-after-success = false [conflict] -# 从 v7.3.0 开始引入的新版冲突数据处理策略。默认值为 ""。从 v8.0.0 开始,TiDB Lightning 优化了物理导入模式和逻辑导入模式的冲突策略。该优化为实验特性。 +# 从 v7.3.0 开始引入的新版冲突数据处理策略。默认值为 ""。从 v8.0.0 开始,TiDB Lightning 优化了物理导入模式和逻辑导入模式的冲突策略。 # - "":在物理导入模式下,不进行冲突数据检测和处理。如果源文件存在主键或唯一键冲突的记录,后续步骤会报错。在逻辑导入模式下,"" 策略将被转换为 "error" 策略处理。 # - "error":检测到导入的数据存在主键或唯一键冲突的数据时,终止导入并报错。 # - "replace":遇到主键或唯一键冲突的数据时,保留最新的数据,覆盖旧的数据。 # 冲突数据将被记录到目标 TiDB 集群中的 `lightning_task_info.conflict_error_v2` 表(该表用于记录物理导入模式下后置冲突检测到的冲突数据) # 和 `conflict_records` 表(该表用于记录逻辑导入模式和物理导入模式下前置冲突检测到的冲突数据)中。 +# 如果在物理导入模式下配置了 `conflict.strategy = "replace"`,可以在 `lightning_task_info.conflict_view` 视图中查看冲突数据。 # 你可以根据业务需求选择正确的记录重新手动写入到目标表中。注意,该方法要求目标 TiKV 的版本为 v5.2.0 或更新版本。 # - "ignore":遇到主键或唯一键冲突的数据时,保留旧的数据,忽略新的数据。仅当导入模式为逻辑导入模式时可以使用该选项。 strategy = "" -# 控制是否开启前置冲突检测,即导入数据到 TiDB 前,先检查所需导入的数据是否存在冲突。冲突记录比例大于或等于 1% 的场景建议开启前置冲突检测,可以提升冲突检测的性能,反之建议关闭。该参数默认值为 false,表示仅开启后置冲突检测。取值为 true 时,表示同时开启前置冲突检测和后置冲突检测。仅当导入模式为物理导入模式时可以使用该参数。该参数为实验特性。 +# 控制是否开启前置冲突检测,即导入数据到 TiDB 前,先检查所需导入的数据是否存在冲突。该参数默认值为 false,表示仅开启后置冲突检测。取值为 true 时,表示同时开启前置冲突检测和后置冲突检测。仅当导入模式为物理导入模式时可以使用该参数。冲突记录数量高于 1,000,000 的场景建议配置 `precheck-conflict-before-import = true`,可以提升冲突检测的性能,反之建议关闭。 # precheck-conflict-before-import = false -# 控制 strategy 为 "replace" 或 "ignore" 时,能处理的冲突错误数的上限。仅在 strategy 为 "replace" 或 "ignore" 时可配置。默认为 9223372036854775807,表示几乎可以容忍所有错误。 -# threshold = 9223372036854775807 -# 控制冲突数据记录表 (`conflict_records`) 中记录的冲突数据的条数上限,默认为 100。在物理导入模式下,当 strategy 为 "replace" 时会记录被覆盖的冲突记录。在逻辑导入模式下,当 strategy 为 "ignore" 时会记录被忽略写入的冲突记录,当 strategy 为 "replace" 时,不会记录冲突记录。 -# max-record-rows = 100 +# 控制 strategy 为 "replace" 或 "ignore" 时,能处理的冲突错误数的上限。仅在 strategy 为 "replace" 或 "ignore" 时可配置。默认为 10000。如果设置的值大于 10000,导入过程可能会出现性能下降的情况。 +# threshold = 10000 +# 控制冲突数据记录表 (`conflict_records`) 中记录的冲突数据的条数上限,默认为 10000。 +# 从 v8.1.0 开始,TiDB Lightning 会自动将 `max-record-rows` 的值设置为 `threshold` 的值,并忽略用户输入,因此无需再单独配置 `max-record-rows`。`max-record-rows` 将在未来版本中废弃。 +# 在物理导入模式下,当 strategy 为 "replace" 时会记录被覆盖的冲突记录。 +# 在逻辑导入模式下,当 strategy 为 "ignore" 时会记录被忽略写入的冲突记录,当 strategy 为 "replace" 时,不会记录冲突记录。 +# max-record-rows = 1000 [tikv-importer] # "local":物理导入模式(Physical Import Mode),默认使用。适用于 TB 级以上大数据量,但导入期间下游 TiDB 无法对外提供服务。 diff --git a/tidb-lightning/tidb-lightning-error-resolution.md b/tidb-lightning/tidb-lightning-error-resolution.md index 09af23266e64..26c39cf15eef 100644 --- a/tidb-lightning/tidb-lightning-error-resolution.md +++ b/tidb-lightning/tidb-lightning-error-resolution.md @@ -51,7 +51,7 @@ max-error = 0 ## 冲突错误 (Conflict error) -你可以通过修改配置项 [`conflict.threshold`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 来增加冲突错误相关的容错数量。如果设置为 *N*,那么 TiDB Lightning 允许数据源中出现 *N* 个冲突错误,而且会跳过这些错误继续导入,一旦超过这个错误数就会退出。在逻辑导入模式或者物理导入模式下,不同的场景会产生冲突错误,你可以参考对应导入模式的“冲突检测”文档。该配置项默认值为 `9223372036854775807`,意味着几乎能容忍全部错误。 +你可以通过修改配置项 [`conflict.threshold`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 来增加冲突错误相关的容错数量。如果设置为 *N*,那么 TiDB Lightning 允许数据源中出现 *N* 个冲突错误,而且会跳过这些错误继续导入,一旦超过这个错误数就会退出。在逻辑导入模式或者物理导入模式下,不同的场景会产生冲突错误,你可以参考对应导入模式的“冲突检测”文档。该配置项默认值为 `10000`,意味着能容忍 10000 个错误。 这些错误会被记录到数据库中。在导入完成后,你可以查看数据库中的数据,手动进行处理。请参见[错误报告](#错误报告)。 diff --git a/tidb-lightning/tidb-lightning-logical-import-mode-usage.md b/tidb-lightning/tidb-lightning-logical-import-mode-usage.md index 44a428946260..7b7cb4813745 100644 --- a/tidb-lightning/tidb-lightning-logical-import-mode-usage.md +++ b/tidb-lightning/tidb-lightning-logical-import-mode-usage.md @@ -56,9 +56,9 @@ TiDB Lightning 的完整配置文件可参考[完整配置及命令行参数](/t | `"error"` | 遇到冲突数据时终止导入 | `INSERT INTO ...` | | `""` | 会被转换为 `"error"`,遇到冲突数据时终止导入 | 无 | -配置为 `"error"` 时,由冲突数据引发的错误将直接导致导入任务终止。配置为 `"replace"` 或 `"ignore"` 时,可以通过进一步配置 [`conflict.threshold`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 控制冲突数据的上限。默认值为 `9223372036854775807`,意味着几乎能容忍全部错误。 +配置为 `"error"` 时,由冲突数据引发的错误将直接导致导入任务终止。配置为 `"replace"` 或 `"ignore"` 时,可以通过进一步配置 [`conflict.threshold`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 控制冲突数据的上限。默认值为 `10000`,意味着能容忍 10000 个错误。 -配置为 `"ignore"` 时,冲突数据可以被记录到下游的 `conflict_records` 表中,详见[可容忍错误](/tidb-lightning/tidb-lightning-error-resolution.md)功能介绍。此时可以通过配置 [`conflict.max-record-rows`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 控制记录上限,超出上限的冲突数据会被跳过导入而不再记录。默认值为 `100`。 +配置为 `"ignore"` 时,冲突数据可以被记录到下游的 `conflict_records` 表中,详见[可容忍错误](/tidb-lightning/tidb-lightning-error-resolution.md)功能介绍。在 v8.1.0 之前的版本中,可以通过配置 [`conflict.max-record-rows`](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置) 控制记录上限,超出上限的冲突数据会被跳过导入而不再记录。从 v8.1.0 版本开始,需要通过 [`conflict.threshold`](/tidb-lightning/tidb-lightning-configuration.md#配置文件) 配置,因为 TiDB Lightning 会自动将 `max-record-rows` 的值设置为 `threshold` 的值,并忽略用户输入。 ## 性能调优 diff --git a/tidb-lightning/tidb-lightning-physical-import-mode-usage.md b/tidb-lightning/tidb-lightning-physical-import-mode-usage.md index e076846c1c2a..9221f98d9b5e 100644 --- a/tidb-lightning/tidb-lightning-physical-import-mode-usage.md +++ b/tidb-lightning/tidb-lightning-physical-import-mode-usage.md @@ -30,18 +30,20 @@ check-requirements = true data-source-dir = "/data/my_database" [conflict] -# 从 v7.3.0 开始引入的新版冲突数据处理策略。默认值为 ""。从 v8.0.0 开始,TiDB Lightning 优化了物理导入模式和逻辑导入模式的冲突策略。该优化为实验特性。 +# 从 v7.3.0 开始引入的新版冲突数据处理策略。默认值为 ""。从 v8.0.0 开始,TiDB Lightning 优化了物理导入模式和逻辑导入模式的冲突策略。 # - "":不进行冲突数据检测和处理。如果源文件存在主键或唯一键冲突的记录,后续步骤会报错 # - "error":检测到导入的数据存在主键或唯一键冲突的数据时,终止导入并报错 # - "replace":遇到主键或唯一键冲突的数据时,保留最新的数据,覆盖旧的数据。 # 冲突数据将被记录到目标 TiDB 集群中的 `lightning_task_info.conflict_error_v2` 表(该表用于记录后置冲突检测到的冲突数据) # 和 `conflict_records` 表(该表用于记录前置冲突检测到的冲突数据)中。 +# 如果在物理导入模式下配置了 `conflict.strategy = "replace"`,可以在 `lightning_task_info.conflict_view` 视图中查看冲突数据。 # 你可以根据业务需求选择正确的记录重新手动写入到目标表中。注意,该方法要求目标 TiKV 的版本为 v5.2.0 或更新版本。 strategy = "" -# 控制是否开启前置冲突检测,即导入数据到 TiDB 前,先检查所需导入的数据是否存在冲突。冲突记录比例大于或等于 1% 的场景建议开启前置冲突检测,可以提升冲突检测的性能,反之建议关闭。该参数默认值为 false,表示仅开启后置冲突检测。取值为 true 时,表示同时开启前置冲突检测和后置冲突检测。该参数为实验特性。 +# 控制是否开启前置冲突检测,即导入数据到 TiDB 前,先检查所需导入的数据是否存在冲突。该参数默认值为 false,表示仅开启后置冲突检测。取值为 true 时,表示同时开启前置冲突检测和后置冲突检测。冲突记录数量高于 1,000,000 的场景建议配置 `precheck-conflict-before-import = true`,可以提升冲突检测的性能,反之建议关闭。 # precheck-conflict-before-import = false -# threshold = 9223372036854775807 -# max-record-rows = 100 +# threshold = 10000 +# 从 v8.1.0 开始,TiDB Lightning 会自动将 `max-record-rows` 的值设置为 `threshold` 的值,并忽略用户输入,因此无需再单独配置 `max-record-rows`。`max-record-rows` 将在未来版本中废弃。 +# max-record-rows = 10000 [tikv-importer] # 导入模式配置,设为 local 即使用物理导入模式