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) です。 low_water_mark は binary(10)で、既定値はありません。

値が null 以外の場合は、cdc.lsn_time_mapping テーブルの現在のエントリの start_lsn 値として表示する必要があります。 cdc.lsn_time_mapping の他のエントリが、新しい低レベルのウォーターマークで識別されたエントリと同じコミット時間を共有する場合、そのグループのエントリに関連付けられた最小 LSN が低レベルのウォーターマークとして選択されます。

値が明示的に NULL に設定されている場合、キャプチャ インスタンスの現在の低基準値を使用して、クリーンアップ操作の上限が定義されます。

[ @threshold= ] 'delete threshold'
クリーンアップ時に 1 つのステートメントを使用して削除できる削除エントリの最大数です。 delete_threshold は bigint で、既定値は 5000 です。

[ @fCleanupFailed = ] 'cleanup failed' OUTPUT クリーンアップ操作が失敗したかどうかを示す OUTPUT パラメーターです。 cleanup failed は 少しで、既定値は 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');

Result
--------
CLEANUP SUCCESS

解説

sys.sp_cdc_cleanup_change_table は、次の操作を実行します。

  1. @low_water_mark パラメーターが NULL の場合、キャプチャ インスタンスのstart_lsn値は変更されません。 ただし、現在の低基準値がプロシージャの @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 の値が低レベルのウォーターマークより小さい場合は、その変更テーブル エントリが削除されます。 削除しきい値は、1 つのトランザクションで削除された行の数を制限するために使用されます。 エントリを正常に削除できなかったことが報告されますが、呼び出しに基づいて行われた可能性のある低基準値のキャプチャ インスタンスに対する変更には影響しません。

  3. キャプチャ インスタンス のstart_lsn を更新した後、変更テーブル データを削除せずにsys.sp_cdc_cleanup_change_table ストアド プロシージャがタイムアウトした場合、ストアド プロシージャの次回の実行前 にストアド プロシージャ sys.sp_cdc_change_job を使用してデータ保持値を増やす sys.sp_cdc_cleanup_change_table は、指定された保持期間のデータを保持しません。 cdc.change_tables のstart_lsn 値は、新しい低基準値として扱う必要があります。 sys.sp_cdc_cleanup_change_table ストアド プロシージャは、新しく指定されたデータ保持期間に一致するようにstart_lsn値を設定しません。 プロシージャは常に、低基準値に基づいてクリーンアップを実行します。 cdc.change_tablesでstart_lsn値以上の@low_water_mark パラメーターの値を指定すると、エラー 22957 が生成されなくなります。

  4. sys.sp_cdc_cleanup_change_tableを使用してクリーンアップ テーブル プロセスを管理し、sys.sp_cdc_cleanup_change_tableが呼び出されたときに CDC スキャンと CDC クリーンアップの間にデッドロックが発生した場合、エラー 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を実行し、 @low_water_mark パラメーターに NULL を指定します。

  • クリーンアップ エージェント ジョブで使用される単純な保持ベースのポリシーが適切ではありません。

    このストアド プロシージャは 1 つのキャプチャ インスタンスに対してクリーンアップを行うため、個々のキャプチャ インスタンスに対してクリーンアップのルールを調整するカスタム クリーンアップ戦略を構築するために使用できます。

アクセス許可

db_owner 固定データベース ロールのメンバーシップが必要です。

参照

<cdc.fn_cdc_get_all_changes_capture_instance> (Transact-SQL)
sys.fn_cdc_get_min_lsn (Transact-SQL)
sys.fn_cdc_increment_lsn (Transact-SQL)