From 43836f80678b8923e15f6cf1f71d089e707a08f2 Mon Sep 17 00:00:00 2001 From: lidezhu Date: Thu, 13 Aug 2026 16:34:05 +0800 Subject: [PATCH 1/3] ticdc: document ignore-update-only-columns filter --- ticdc/ticdc-changefeed-config.md | 7 +++++++ ticdc/ticdc-filter.md | 9 +++++++++ ticdc/ticdc-open-api-v2.md | 12 +++++++++++- 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 09418f37bc50..140438248f10 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -144,6 +144,13 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - `ignore-update-new-value-expr = "gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 `UPDATE` DML。 +##### `ignore-update-only-columns` 从 v8.5.8 版本开始引入 + +- 该配置项是一个列名数组，仅适用于 Kafka 下游。 +- `ignore-update-only-columns = ["version", "updated_at"]` 表示当一条 `UPDATE` DML 仅变更 `version`、`updated_at` 中的一个或多个列时，过滤掉该事件。如果该事件还变更了列表之外的列，TiCDC 会将该事件发送到下游。 +- 如果发生值变更的列包含主键列或唯一键列，则无论该列是否在列表中，TiCDC 都不会过滤该事件。 +- 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。更多匹配规则和限制，请参考 [Changefeed 日志过滤器](/ticdc/ticdc-filter.md#event-filter-事件过滤器-从-v620-版本开始引入)。 + ### scheduler #### `enable-table-across-nodes` diff --git a/ticdc/ticdc-filter.md b/ticdc/ticdc-filter.md index 53681a58373d..dc892331d998 100644 --- a/ticdc/ticdc-filter.md +++ b/ticdc/ticdc-filter.md @@ -50,6 +50,7 @@ ignore-delete-value-expr = "name = 'john'" # 过滤掉包含 name = 'john' 条 ignore-insert-value-expr = "id >= 100" # 过滤掉包含 id >= 100 条件的 insert DML ignore-update-old-value-expr = "age < 18 or name = 'lili'" # 过滤掉旧值 age < 18 或 name = 'lili' 的 update DML ignore-update-new-value-expr = "gender = 'male' and age > 18" # 过滤掉新值 gender = 'male' 且 age > 18 的 update DML +ignore-update-only-columns = ["version", "updated_at"] # 当 update DML 仅变更 version 和 updated_at 列时，过滤掉该事件 ``` 配置参数说明： @@ -122,6 +123,14 @@ ignore-update-new-value-expr = "gender = 'male' and age > 18" # 过滤掉新值 - `ignore-insert-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定值的 INSERT 类型的 DML 事件。 - `ignore-update-old-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定旧值的 UPDATE 类型的 DML 事件。 - `ignore-update-new-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定新值的 UPDATE 类型的 DML 事件。 +- `ignore-update-only-columns` 从 v8.5.8 版本开始引入：指定一组列名。对于匹配 `matcher` 的表，如果一条 UPDATE 事件中发生值变更的列全部包含在该列表中，TiCDC 会过滤掉该事件；如果任意发生值变更的列不在该列表中，TiCDC 会将该事件发送到下游。该配置仅适用于 Kafka 下游，不影响 INSERT 和 DELETE 事件。 + + 使用该配置时，请注意以下事项： + + - 即使发生值变更的主键列或唯一键列已包含在列表中，TiCDC 也不会过滤该 UPDATE 事件。 + - 列名的大小写匹配规则由 Changefeed 配置项 `case-sensitive` 控制。 + - 如果列表中的列在匹配的表中不存在，TiCDC 会输出警告日志并忽略该列。列表中其他有效列仍会参与过滤判断。 + - 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。 > **注意：** > diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index b130a4a75fe4..8874c2a2d45e 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -167,6 +167,9 @@ curl -X GET http://127.0.0.1:8300/api/v2/health ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ] @@ -290,6 +293,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/health | `ignore_sql` | `STRING ARRAY` 类型，如 `["^drop", "add column"]` 表示过滤掉以 `DROP` 开头或者包含 `ADD COLUMN` 的 DDL。（非必选） | | `ignore_update_new_value_expr` | `STRING ARRAY` 类型，如 `"gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 UPDATE DML。（非必选） | | `ignore_update_old_value_expr` | `STRING ARRAY` 类型，如 `"age < 18"` 表示过滤掉旧值 `age < 18` 的 UPDATE DML。（非必选） | +| `ignore_update_only_columns` | `STRING ARRAY` 类型，从 v8.5.8 版本开始引入，仅适用于 Kafka 下游。如果 UPDATE 事件中发生值变更的列全部包含在该数组中，则过滤掉该事件，例如 `["version", "updated_at"]`。（非必选） | | `matcher` | `STRING ARRAY` 类型，是一个白名单，如 `["test.worker"]`，表示该过滤规则只应用于 `test` 库中的 `worker` 表。（非必选） | `mounter` 参数说明如下： @@ -413,6 +417,9 @@ curl -X POST -H "Content-type: application/json" http://127.0.0.1:8300/api/v2/ch ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ] @@ -598,6 +605,9 @@ curl -X DELETE http://127.0.0.1:8300/api/v2/changefeeds/test1 ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ] @@ -1066,4 +1076,4 @@ curl -X POST http://127.0.0.1:8300/api/v2/owner/resign curl -X POST -H "Content-type: application/json" http://127.0.0.1:8300/api/v2/log -d '{"log_level":"debug"}' ``` -如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 \ No newline at end of file +如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 From a54d85fc1ce10052fa88507c2fa9a05013480313 Mon Sep 17 00:00:00 2001 From: lidezhu Date: Thu, 13 Aug 2026 16:43:26 +0800 Subject: [PATCH 2/3] small fix --- ticdc/ticdc-changefeed-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 140438248f10..997817282aa7 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -149,7 +149,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 该配置项是一个列名数组，仅适用于 Kafka 下游。 - `ignore-update-only-columns = ["version", "updated_at"]` 表示当一条 `UPDATE` DML 仅变更 `version`、`updated_at` 中的一个或多个列时，过滤掉该事件。如果该事件还变更了列表之外的列，TiCDC 会将该事件发送到下游。 - 如果发生值变更的列包含主键列或唯一键列，则无论该列是否在列表中，TiCDC 都不会过滤该事件。 -- 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。更多匹配规则和限制，请参考 [Changefeed 日志过滤器](/ticdc/ticdc-filter.md#event-filter-事件过滤器-从-v620-版本开始引入)。 +- 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。 ### scheduler From f4a53e5102eaa5d13ba894520ce7f394543a9d29 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Tue, 18 Aug 2026 17:04:31 +0800 Subject: [PATCH 3/3] Update version info --- ticdc/ticdc-changefeed-config.md | 2 +- ticdc/ticdc-filter.md | 2 +- ticdc/ticdc-open-api-v2.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 997817282aa7..e1e5e5a784b6 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -144,7 +144,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - `ignore-update-new-value-expr = "gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 `UPDATE` DML。 -##### `ignore-update-only-columns` 从 v8.5.8 版本开始引入 +##### `ignore-update-only-columns` 从 v8.5.9 版本开始引入 - 该配置项是一个列名数组，仅适用于 Kafka 下游。 - `ignore-update-only-columns = ["version", "updated_at"]` 表示当一条 `UPDATE` DML 仅变更 `version`、`updated_at` 中的一个或多个列时，过滤掉该事件。如果该事件还变更了列表之外的列，TiCDC 会将该事件发送到下游。 diff --git a/ticdc/ticdc-filter.md b/ticdc/ticdc-filter.md index dc892331d998..3e53245a3c09 100644 --- a/ticdc/ticdc-filter.md +++ b/ticdc/ticdc-filter.md @@ -123,7 +123,7 @@ ignore-update-only-columns = ["version", "updated_at"] # 当 update DML 仅变 - `ignore-insert-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定值的 INSERT 类型的 DML 事件。 - `ignore-update-old-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定旧值的 UPDATE 类型的 DML 事件。 - `ignore-update-new-value-expr`：配置一个遵循默认 SQL Mode 的 SQL 表达式，用于过滤掉带有指定新值的 UPDATE 类型的 DML 事件。 -- `ignore-update-only-columns` 从 v8.5.8 版本开始引入：指定一组列名。对于匹配 `matcher` 的表，如果一条 UPDATE 事件中发生值变更的列全部包含在该列表中，TiCDC 会过滤掉该事件；如果任意发生值变更的列不在该列表中，TiCDC 会将该事件发送到下游。该配置仅适用于 Kafka 下游，不影响 INSERT 和 DELETE 事件。 +- `ignore-update-only-columns`：指定一组列名，从 v8.5.9 版本开始引入。对于匹配 `matcher` 的表，如果一条 UPDATE 事件中发生值变更的列全部包含在该列表中，TiCDC 会过滤掉该事件；如果任意发生值变更的列不在该列表中，TiCDC 会将该事件发送到下游。该配置仅适用于 Kafka 下游，不影响 INSERT 和 DELETE 事件。 使用该配置时，请注意以下事项： diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 8874c2a2d45e..eb5d231fa384 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -293,7 +293,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/health | `ignore_sql` | `STRING ARRAY` 类型，如 `["^drop", "add column"]` 表示过滤掉以 `DROP` 开头或者包含 `ADD COLUMN` 的 DDL。（非必选） | | `ignore_update_new_value_expr` | `STRING ARRAY` 类型，如 `"gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 UPDATE DML。（非必选） | | `ignore_update_old_value_expr` | `STRING ARRAY` 类型，如 `"age < 18"` 表示过滤掉旧值 `age < 18` 的 UPDATE DML。（非必选） | -| `ignore_update_only_columns` | `STRING ARRAY` 类型，从 v8.5.8 版本开始引入，仅适用于 Kafka 下游。如果 UPDATE 事件中发生值变更的列全部包含在该数组中，则过滤掉该事件，例如 `["version", "updated_at"]`。（非必选） | +| `ignore_update_only_columns` | `STRING ARRAY` 类型，从 v8.5.9 版本开始引入，仅适用于 Kafka 下游。如果 UPDATE 事件中发生值变更的列全部包含在该数组中，则过滤掉该事件，例如 `["version", "updated_at"]`。（非必选） | | `matcher` | `STRING ARRAY` 类型，是一个白名单，如 `["test.worker"]`，表示该过滤规则只应用于 `test` 库中的 `worker` 表。（非必选） | `mounter` 参数说明如下：