ticdc: document ignore-update-only-columns filter

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` <span class="version-mark">从 v8.5.9 版本开始引入</span>
+
+- 该配置项是一个列名数组，仅适用于 Kafka 下游。
+- `ignore-update-only-columns = ["version", "updated_at"]` 表示当一条 `UPDATE` DML 仅变更 `version`、`updated_at` 中的一个或多个列时，过滤掉该事件。如果该事件还变更了列表之外的列，TiCDC 会将该事件发送到下游。
+- 如果发生值变更的列包含主键列或唯一键列，则无论该列是否在列表中，TiCDC 都不会过滤该事件。
+- 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。
+
 ### scheduler
 
 #### `enable-table-across-nodes`

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.9 版本开始引入。对于匹配 `matcher` 的表，如果一条 UPDATE 事件中发生值变更的列全部包含在该列表中，TiCDC 会过滤掉该事件；如果任意发生值变更的列不在该列表中，TiCDC 会将该事件发送到下游。该配置仅适用于 Kafka 下游，不影响 INSERT 和 DELETE 事件。
+
+    使用该配置时，请注意以下事项：
+
+    - 即使发生值变更的主键列或唯一键列已包含在列表中，TiCDC 也不会过滤该 UPDATE 事件。
+    - 列名的大小写匹配规则由 Changefeed 配置项 `case-sensitive` 控制。
+    - 如果列表中的列在匹配的表中不存在，TiCDC 会输出警告日志并忽略该列。列表中其他有效列仍会参与过滤判断。
+    - 对于非 Kafka 下游，TiCDC 接受该配置，但不会根据该配置过滤事件。
 
 > **注意：**
 >

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.9 版本开始引入，仅适用于 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`。如果请求失败，则返回错误信息和错误码。
+如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。