From 999e668448eb29408eda952a6379faf8229156b3 Mon Sep 17 00:00:00 2001 From: lidezhu Date: Thu, 13 Aug 2026 17:40:06 +0800 Subject: [PATCH] ticdc: document ignore-update-only-columns filter --- ticdc/ticdc-changefeed-config.md | 7 +++++++ ticdc/ticdc-filter.md | 9 +++++++++ ticdc/ticdc-open-api-v2.md | 10 ++++++++++ 3 files changed, 26 insertions(+) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 4c1c419f33555..8d62fe16211cf 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -146,6 +146,13 @@ For more information, see [Event filter rules](/ticdc/ticdc-filter.md#event-filt - `ignore-update-new-value-expr = "gender = 'male'"` ignores `UPDATE` DMLs whose new value contains `gender = 'male'` +##### `ignore-update-only-columns` Introduced in v8.5.8 + +- This configuration item is an array of column names and applies only to Kafka downstreams. +- `ignore-update-only-columns = ["version", "updated_at"]` filters out an `UPDATE` DML event when the event changes only the `version` column, the `updated_at` column, or both. If the event also changes a column that is not in the list, TiCDC sends the event to the downstream. +- If the changed columns include a primary key or unique key column, TiCDC does not filter out the event, regardless of whether the column is in the list. +- For non-Kafka downstreams, TiCDC accepts this configuration but does not filter events based on it. + ### scheduler #### `enable-table-across-nodes` diff --git a/ticdc/ticdc-filter.md b/ticdc/ticdc-filter.md index 5a6a3d58f99bd..90eada67d46db 100644 --- a/ticdc/ticdc-filter.md +++ b/ticdc/ticdc-filter.md @@ -50,6 +50,7 @@ ignore-delete-value-expr = "name = 'john'" # Ignore delete DMLs that contain the ignore-insert-value-expr = "id >= 100" # Ignore insert DMLs that contain the condition "id >= 100". ignore-update-old-value-expr = "age < 18 or name = 'lili'" # Ignore update DMLs whose old value contains "age < 18" or "name = 'lili'". ignore-update-new-value-expr = "gender = 'male' and age > 18" # Ignore update DMLs whose new value contains "gender = 'male'" and "age > 18". +ignore-update-only-columns = ["version", "updated_at"] # Ignore update DMLs if every changed column is either version or updated_at. ``` Description of configuration parameters: @@ -122,6 +123,14 @@ Description of configuration parameters: - `ignore-insert-value-expr`: this parameter accepts a SQL expression that follows the default SQL mode, used to filter out the `INSERT` type of DML events with a specified value. - `ignore-update-old-value-expr`: this parameter accepts a SQL expression that follows the default SQL mode, used to filter out the `UPDATE` type of DML events with a specified old value. - `ignore-update-new-value-expr`: this parameter accepts a SQL expression that follows the default SQL mode, used to filter out the `UPDATE` DML events with a specified new value. +- `ignore-update-only-columns` Introduced in v8.5.8: specifies a set of column names. For tables matching `matcher`, if all columns whose values are changed in an `UPDATE` event are included in this list, TiCDC filters out the event. If any changed column is not included in the list, TiCDC sends the event to the downstream. This configuration applies only to Kafka downstreams and does not affect `INSERT` or `DELETE` events. + + When using this configuration, note the following: + + - TiCDC does not filter out an `UPDATE` event if it changes a primary key or unique key column, even if the column is included in the list. + - The `case-sensitive` changefeed configuration item controls whether column name matching is case-sensitive. + - If a column in the list does not exist in a matching table, TiCDC outputs a warning log and ignores the column. Other valid columns in the list are still used to determine whether to filter out the event. + - For non-Kafka downstreams, TiCDC accepts this configuration but does not filter events based on it. > **Note:** > diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 81846f0d3b333..c2f6a57e3dd64 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -169,6 +169,9 @@ This interface is used to submit a replication task to TiCDC. If the request is ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ] @@ -292,6 +295,7 @@ The `filter.event_filters` parameters are described as follows. For more informa | `ignore_sql` | `STRING ARRAY` type. For example, `["^drop", "add column"]` means to filter out DDL statements that start with `DROP` or contain `ADD COLUMN`. (Optional) | | `ignore_update_new_value_expr` | `STRING ARRAY` type. For example, `"gender = 'male'"` means to filter out the UPDATE DML statements with the new value `gender = 'male'`. (Optional) | | `ignore_update_old_value_expr` | `STRING ARRAY` type. For example, `"age < 18"` means to filter out the UPDATE DML statements with the old value `age < 18`. (Optional) | +| `ignore_update_only_columns` | `STRING ARRAY` type. Introduced in v8.5.8 and applicable only to Kafka downstreams. If all columns whose values are changed in an UPDATE event are included in this array, TiCDC filters out the event. For example, `["version", "updated_at"]`. (Optional) | | `matcher` | `STRING ARRAY` type. It works as an allowlist. For example, `["test.worker"]` means that the filter rule applies only to the `worker` table in the `test` database. (Optional) | The `mounter` parameter is described as follows: @@ -415,6 +419,9 @@ If the request is successful, `200 OK` is returned. If the request fails, an err ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ] @@ -600,6 +607,9 @@ To modify the changefeed configuration, follow the steps of `pause the replicati ], "ignore_update_new_value_expr": "string", "ignore_update_old_value_expr": "string", + "ignore_update_only_columns": [ + "string" + ], "matcher": [ "string" ]