<cdc.fn_cdc_get_net_changes_capture_instance> (Transact-SQL)

適用対象:SQL Server

指定したログ シーケンス番号 (LSN) 範囲内で変更されたソース行ごとに 1 つの純変更行を返します。

待って、LSN とは何ですか? SQL Serverトランザクション ログ内のすべてのレコードは、ログ シーケンス番号 (LSN) によって一意に識別されます。 LSN は、LSN2 が LSN1 より大きい場合、LSN2 によって参照されるログ レコードによって記述された変更が、ログ レコード LSN によって記述された変更 の後 に発生するように順序付けされます。

重要なイベントが発生したログ レコードの LSN は、正しい復元シーケンスを構築するのに役立ちます。 LSN は順序付けされているため、等値と不等値 (つまり、<>=、=、<=)>を比較できます。 このような比較は、復元シーケンスを構築するときに役立ちます。

LSN 範囲でソース行に複数の変更がある場合、行の最終的な内容を反映する 1 つの行が、以下で説明する列挙関数によって返されます。 たとえば、トランザクションがソース テーブルに行を挿入し、LSN 範囲内の後続のトランザクションがその行の 1 つ以上の列を更新した場合、関数は更新された列値を含む 1 つの 行のみを返します。

この列挙関数は、ソース テーブルで変更データ キャプチャが有効になっており、ネット トラッキングが指定されている場合に作成されます。 ネット トラッキングを有効にするには、ソース テーブルに主キーまたは一意のインデックスが必要です。 関数名は派生し、 形式 cdc.fn_cdc_get_net_changes_<capture_instance>を使用します。ここで <capture_instance> は、ソース テーブルが変更データ キャプチャに対して有効になったときにキャプチャ インスタンスに指定された値です。 詳細については、「sys.sp_cdc_enable_table (Transact-SQL)」を参照してください。

Transact-SQL 構文表記規則

構文

  
cdc.fn_cdc_get_net_changes_capture_instance ( from_lsn , to_lsn , '<row_filter_option>' )  
  
<row_filter_option> ::=  
{ all  
 | all with mask  
 | all with merge  
}  

引数

from_lsn

結果セットに含める LSN 範囲の低エンドポイントを表す LSN。 from_lsn は binary(10)です。

cdc.[ 内の行のみ capture_instance]_CT __$start_lsn以上の値を持つ変更テーブル が 結果セットに含from_lsn。

to_lsn

結果セットに含める LSN 範囲の上端を表す LSN を指定します。 to_lsn は binary(10)です。

cdc.[ 内の行のみcapture_instance]_CT__$start_lsnの値がfrom_lsn以下の値を持つテーブルを変更to_lsnが結果セットに含まれます。

<>row_filter_option ::= { all | all with mask | all with merge }

メタデータ列の内容と、結果セットで返される行を制御するオプション。 次のいずれかのオプションを指定できます。

all
行に対する最終的な変更の LSN と、その行に適用する操作が、メタデータ列 __$start_lsn および __$operation に返されます。 __$update_mask 列は常に NULL です。

すべてマスク付き
行に対する最終的な変更の LSN と、その行に適用する操作が、メタデータ列 __$start_lsn および __$operation に返されます。 また、更新操作から制御が返ると (__$operation = 4)、この操作で変更されたキャプチャ対象列が、__$update_mask の戻り値としてマークされます。

すべてマージあり
行に対する最終的な変更の LSN が、メタデータ列 __$start_lsn に返されます。 列 __$操作は、削除の場合は 1、変更を適用するために必要な操作が挿入または更新であることを示す 5 の 2 つの値のいずれかになります。 __$update_mask 列は常に NULL です。

特定の変更の正確な操作を決定するロジックはクエリの複雑さを増すので、このオプションは、変更データを適用するために必要な操作が挿入または更新のいずれかであることを示すために十分な場合にクエリのパフォーマンスを向上させるように設計されていますが、2 つを明示的に区別する必要はありません。 このオプションは、マージ操作を直接使用できるターゲット環境で最も魅力的です。

返されるテーブル

列名	データ型	説明
__$start_lsn	binary(10)	変更のコミット トランザクションに関連付けられた LSN。 同じトランザクションでコミットされたすべての変更は、同じコミット LSN を共有します。 たとえば、ソース テーブルに対する更新操作で 2 つの行の 2 つの列が変更された場合、変更テーブルには 4 つの行が含まれます。それぞれに同じ __$start_lsnvalueが含まれます。
__$operation	int	変更データの行をターゲット データ ソースに適用するために必要なデータ操作言語 (DML) 操作を識別します。 row_filter_option パラメーターの値が all または all with mask である場合、この列の値には、次のいずれかの値を指定できます。 1 = 削除 2 = 挿入 4 = 更新 row_filter_option パラメーターの値が all with merge である場合、この列の値には、次のいずれかの値を指定できます。 1 = 削除 5 = 挿入または更新
__$update_mask	varbinary (128)	キャプチャ インスタンスに対して指定された各キャプチャ対象列に対応するビットを持ったビット マスク。 この値は、__$operation = 1 または 2 の場合、定義されたすべてのビットを 1 に設定します。 __$operation が 3 または 4 の場合、変更された列に対応するビットだけが 1 に設定されます。
<キャプチャ対象のソース テーブルの列>	多様	この関数によって返されるその他の列は、ソース テーブルの列のうち、キャプチャ インスタンスの作成時にキャプチャ対象として指定された列です。 キャプチャ対象列リストで列が指定されなかった場合、ソース テーブルのすべての列が返されます。

アクセス許可

sysadmin 固定サーバー ロールまたは固定データベース ロールdb_ownerメンバーシップが必要です。 他のすべてのユーザーには、ソース テーブル内のすべてのキャプチャ列に対する SELECT アクセス許可が必要です。また、キャプチャ インスタンスのゲーティング ロールが定義されている場合は、そのデータベース ロールのメンバーシップが必要です。 呼び出し元にソース データを表示する権限がない場合、関数はすべての列に NULL 値を持つ行を返します。

注釈

行の一意識別子を変更すると、最初の UPDATE コマンドが DELETE で表示され、代わりに INSERT コマンドが表示されます fn_cdc_get_net_changes 。 この動作は、変更の前後の両方でキーを追跡するために必要です。

または cdc.fn_cdc_get_net_changes_<capture_instance>を呼び出cdc.fn_cdc_get_all_changes_<capture_instance>すときに、指定された LSN 範囲が適切でない場合、エラー 313 が予期されます。 パラメーターが lsn_value 最も低い LSN または最大 LSN の時間を超えている場合、これらの関数の実行はエラー 313: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or functionで返されます。 このエラーは、開発者が処理する必要があります。 回避策の T-SQL のサンプルについては、 GitHub の ReplTalk を参照してください。

例

次の例では、 関数 cdc.fn_cdc_get_net_changes_HR_Department を使用して、特定の時間間隔中にソース テーブル HumanResources.Department に加えられた正味の変更を報告します。

最初に、関数を GETDATE 使用して時間間隔の開始をマークします。 ソース テーブルに対して複数の DML ステートメントを適用した後、再び GETDATE 関数を呼び出して期間の終わりを指定します。 その後 、関数sys.fn_cdc_map_time_to_lsn を使用して、LSN 値で囲まれた変更データ キャプチャ クエリ範囲に時間間隔をマップします。 最後に、cdc.fn_cdc_get_net_changes_HR_Department 関数を呼び出して、該当期間中に行われたソース テーブルへの差分変更を取得します。 挿入されて削除された行が、関数によって返される結果セットに表示されないことに注意してください。 たとえ行を追加しても、同じ期間内に削除されれば、その期間におけるソース テーブルへの差分変更とはならないためです。

注意

この例を実行する前に、テーブル で CDC を有効にするには、まず sys.sp_cdc_enable_table (Transact-SQL) で例 B を実行する HumanResources.Department必要があります。 次の例では、HR_Department は、 で指定されている CDC キャプチャ インスタンスの sys.sp_cdc_enable_table名前です。

USE AdventureWorks2022;  
GO  
DECLARE @begin_time datetime, @end_time datetime, @from_lsn binary(10), @to_lsn binary(10);  
-- Obtain the beginning of the time interval.  
SET @begin_time = DATEADD(day, -1, GETDATE()) ;  
-- DML statements to produce changes in the HumanResources.Department table.  
INSERT INTO HumanResources.Department (Name, GroupName)  
VALUES (N'MyDept', N'MyNewGroup');  
  
UPDATE HumanResources.Department  
SET GroupName = N'Resource Control'  
WHERE GroupName = N'Inventory Management';  
  
DELETE FROM HumanResources.Department  
WHERE Name = N'MyDept';  
  
-- Obtain the end of the time interval.  
SET @end_time = GETDATE();  
-- Map the time interval to a change data capture query range.  
SET @from_lsn = sys.fn_cdc_map_time_to_lsn('smallest greater than or equal', @begin_time);  
SET @from_lsn = ISNULL(sys.fn_cdc_map_time_to_lsn('smallest greater than or equal', @begin_time), [sys].[fn_cdc_get_min_lsn]('HR_Department') );
SET @to_lsn = sys.fn_cdc_map_time_to_lsn('largest less than or equal', @end_time);  
  
-- Return the net changes occurring within the query window.  
SELECT * FROM cdc.fn_cdc_get_net_changes_HR_Department(@from_lsn, @to_lsn, 'all');  

参照

• <cdc.fn_cdc_get_all_changes_capture_instance> (Transact-SQL)
• sys.fn_cdc_map_time_to_lsn (Transact-SQL)
• sys.sp_cdc_enable_table (Transact-SQL)
• sys.sp_cdc_help_change_data_capture (Transact-SQL)
• 変更データ キャプチャについて (SQL Server)