sys.sp_cdc_cleanup_change_table (Transact-SQL)

适用范围:SQL Server

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

Transact-SQL 语法约定

语法

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

日志序列号(LSN),用作@capture_instance的新低水印@low_water_markbinary(10),没有默认值。

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

如果显式设置为NULL该值,则@capture_instance的当前@low_water_mark用于定义清理操作的上限。

注意

@low_water_mark为 LSN 阈值。 处理任何 LSN 值低于提供的值的事务,并且排除了有关值。

[ @threshold = ] 'delete threshold'

清理时可以使用单个语句删除的最大删除条目数。 @thresholdbigint,默认值为 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 执行以下操作:

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

    注意

    新的低水印可能不是在存储过程调用中指定的低水印。 如果表中的其他条目 cdc.lsn_time_mapping 共享相同的提交时间,则选择在条目组中表示的最小 start_lsn 项作为调整后的低水印。 如果 @low_water_mark 参数NULL或当前低水印大于新的低水印,start_lsn则捕获实例的值保持不变。

  2. 然后删除值小于低水印的表条目 __$start_lsn 。 删除阈值用于限制在单个事务中删除的行数。 报告无法成功删除条目,但不会影响捕获实例的低水印的任何更改,这些更改可能基于调用进行。

  3. sys.sp_cdc_cleanup_change_table如果存储过程在更新start_lsn捕获实例后超时,但不删除更改表数据,则在下一次执行sys.sp_cdc_cleanup_change_table存储过程之前使用存储过程sys.sp_cdc_change_job增加数据保留值不会保留指定的保留期的数据。 start_lsn cdc.change_tables中的值应被视为新的低水印。 sys.sp_cdc_cleanup_change_table存储过程不设置start_lsn值以匹配新指定的数据保留期。 该过程始终基于低水印执行清理。 为@low_water_mark参数指定一个值,该参数等于或高于start_lsncdc.change_tables中的值,可避免生成错误 22957。

  4. 如果使用 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

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

    管理员可以运行此存储过程以显式重试失败的操作。 若要重试给定捕获实例的清理,请执行sys.sp_cdc_cleanup_change_table并指定NULL@low_water_mark参数。

  • 清理代理作业使用的基于保留的简单策略是不够的。

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

权限

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