sys.sp_cdc_cleanup_change_table (Transact-SQL)

项目
12/22/2023

根据指定的 @low_water_mark 值从当前数据库中的更改表中删除行。此存储过程是为需要直接管理更改表清除进程的用户提供的。但是，由于此过程会影响更改表中数据的所有使用者，因而应多加小心。

语法

sys.sp_cdc_cleanup_change_table [ @capture_instance = ] 'capture_instance'
    , [ @low_water_mark = ] low_water_mark
    , [ @threshold = ] 'delete threshold'
    , [ @fCleanupFailed = ] 'cleanup failed' OUTPUT
[ ; ]

参数

[ @capture_instance = ] 'capture_instance'

与更改表关联的捕获实例的名称。 @capture_instance 为 sysname，无默认值，不能为 NULL。

capture_instance必须命名当前数据库中存在的捕获实例。

[ @low_water_mark = ] low_water_mark

要用作@capture实例的新低水印的日志序列号（LSN）。 @low_water_mark 为 binary（10），没有默认值。

如果该值为非 null，则它必须显示为cdc.lsn_time_mapping表中当前项的start_lsn 值。如果与其他条目 cdc.lsn_time_mapping 共享的提交时间与新低水印标识的条目相同，则与该组条目关联的最小 LSN 被选为低水印。

如果该值显式设置为 NULL，则@capture实例的当前@low水印用于定义清理操作的上限。

[ @threshold = ] 'delete threshold'

清理时可以使用单个语句删除的最大删除条目数。 @threshold 为 bigint，默认值为 5000。

[ @fCleanupFailed = ] 'cleanup failed' OUTPUT

指示清理操作是否失败的 OUTPUT 参数。 @fCleanupFailed为位，默认值为 0.

结果集

无，除非使用可选的 @fCleanupFailed OUTPUT 参数。

返回代码值

0（成功）或 1（失败）。

示例

-- Declaring a variable and Setting to zero first
SELECT @cleanup_failed_bit = 0;

-- Execute cleanup and obtain output bit
EXEC @retcode = sys.sp_cdc_cleanup_change_table
    @capture_instance = '<CaptureInstance>',
    @low_water_mark = @LSN, --== LSN to be used for new low watermark for capture instance
    @threshold = 1,
    @fCleanupFailed = @cleanup_failed_bit OUTPUT;

-- Leverage @cleanup_failed_bit output to check the status.
SELECT IIF(@cleanup_failed_bit > 0, 'CLEANUP FAILURE', 'CLEANUP SUCCESS');

CLEANUP SUCCESS

注解

sys.sp_cdc_cleanup_change_table 执行以下操作：

如果 @low_water_mark 参数为 NULL，则@capture实例的start_lsn值保持不变。但是，如果当前低水印大于使用 过程@low_water_mark 参数指定的低水印值，则会引发错误 22957 。错误 22957 的错误消息为 LSN %s, specified as the new low endpoint for the change table associated with capture instance '%s', isn't within the Change Data Capture timeline [%s, %s].

注意

新的低水印可能不是在存储过程调用中指定的低水印。如果表中的其他条目 cdc.lsn_time_mapping 共享相同的提交时间，则选择在条目组中表示的最小start_lsn作为调整后的低水印。 如果 @low_water_mark 参数为 NULL 或当前低水印大于新的低水印，start_lsn则捕获实例的值保持不变。
然后删除值小于低水印的表条目 __$start_lsn 。删除阈值用于限制在单个事务中删除的行数。报告无法成功删除条目，但不会影响捕获实例的低水印的任何更改，这些更改可能基于调用进行。
sys.sp_cdc_cleanup_change_table如果存储过程在更新捕获实例的start_lsn后超时，但不删除更改表数据，则在下一次执行sys.sp_cdc_cleanup_change_table存储过程之前，使用存储过程sys.sp_cdc_change_job增加数据保留值不会保留指定保留期的数据。 cdc.change_tables中的start_lsn值应被视为新的低水印。 sys.sp_cdc_cleanup_change_table存储过程不设置start_lsn值以匹配新指定的数据保留期。该过程始终基于低水印执行清理。为@low_water_mark参数指定一个值，该参数等于或高于start_lsncdc.change_tables中的值，可避免生成错误 22957。

如果使用 sys.sp_cdc_cleanup_change_table 管理清理表进程，并在调用 CDC 扫描和 CDC 清理之间 sys.sp_cdc_cleanup_change_table 发生死锁，则错误 22852 记录严重性为 10（信息性消息）。错误 22852 的消息如下所示：

Could not delete change table entries made obsolete by a change in one or more low water marks for capture instances of database <DatabaseName>. The failure occurred when executing the command <CommandName>. The error returned was <ErrorInfo>. Use the action and error to determine the cause of the failure and resubmit the request.

在以下情况下使用 sys.sp_cdc_cleanup_change_table ：

清理代理作业报告删除失败。

管理员可以运行此存储过程以显式重试失败的操作。若要重试给定捕获实例的清理，请为@low_water_mark参数执行sys.sp_cdc_cleanup_change_table并指定 NULL。
清理代理作业使用的基于保留的简单策略是不够的。

由于此存储过程对单个捕获实例执行清理，因此可用于生成自定义清理策略，以定制用于清理单个捕获实例的规则。

权限

要求具有 db_owner 固定数据库角色中的成员资格。