変更データの処理 (SQL Server)Work with Change Data (SQL Server)

適用対象: ○SQL Server ○Azure SQL Database (Managed Instance のみ) ×Azure SQL Data Warehouse ×Parallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database (Managed Instance only) noAzure SQL Data Warehouse noParallel Data Warehouse

変更データ キャプチャのコンシューマーは、テーブル値関数 (TVF) を使用することによって変更データを利用できるようになります。Change data is made available to change data capture consumers through table-valued functions (TVFs). これらの関数のすべてのクエリには、ログ シーケンス番号 (LSN) の範囲を定義する 2 つのパラメーターが必要です。これらのパラメーターは、返される結果セットを開発する際に検討の対象になります。All queries of these functions require two parameters to define the range of Log Sequence Numbers (LSNs) that are eligible for consideration when developing the returned result set. 期間の両端を示す LSN の上限値と下限値は、期間内に含まれると見なされます。Both the upper and lower LSN values that bound the interval are considered to be included within the interval.

TVF のクエリで使用する適切な LSN 値を特定するための関数がいくつか用意されています。Several functions are provided to help determine appropriate LSN values for use in querying a TVF. sys.fn_cdc_get_min_lsn 関数は、キャプチャ インスタンスの有効期間に関連付けられた最小の LSN を返します。The function sys.fn_cdc_get_min_lsn returns the smallest LSN that is associated with a capture instance validity interval. この有効期間は、現在キャプチャ インスタンスが変更データを利用できる期間です。The validity interval is the time interval for which change data is currently available for its capture instances. sys.fn_cdc_get_max_lsn 関数は、有効期間内の最大の LSN を返します。The function sys.fn_cdc_get_max_lsn returns the largest LSN in the validity interval. sys.fn_cdc_map_time_to_lsn 関数と sys.fn_cdc_map_lsn_to_time 関数は、LSN 値を従来のタイムラインに配置する場合に使用できます。The functions sys.fn_cdc_map_time_to_lsn and sys.fn_cdc_map_lsn_to_time are available to help place LSN values on a conventional timeline. 変更データ キャプチャでは両端の値を含む閉区間のクエリ範囲が使用されるため、連続したクエリ ウィンドウで変更が重複しないようにするためにシーケンス内の次の LSN 値を生成することが必要になる場合があります。Because change data capture uses closed query intervals, it is sometimes necessary to generate the next LSN value in a sequence to ensure that changes are not duplicated in consecutive query windows. sys.fn_cdc_increment_lsn 関数と sys.fn_cdc_decrement_lsn 関数は、LSN 値の増分の調整が必要な場合に役立ちます。The functions sys.fn_cdc_increment_lsn and sys.fn_cdc_decrement_lsn are useful when an incremental adjustment to an LSN value is required.

LSN の下限と上限の検証Validating LSN Boundaries

TVF クエリで使用する LSN の下限と上限は、使用前に検証することをお勧めします。We recommend validating the LSN boundaries that are to be used in a TVF query before their use. 下限または上限が Null の場合やキャプチャ インスタンスの有効期間から外れている場合、変更データ キャプチャの TVF からエラーが返されます。Null endpoints or endpoints that lie outside the validity interval for a capture instance will force an error to be returned by a change data capture TVF.

たとえば、すべての変更のクエリで、クエリ範囲の定義に使用されたパラメーターが無効または範囲外である場合や、行フィルター オプションが無効である場合は、次のエラーが返されます。For example, the following error is returned for a query for all changes when a parameter that is used to define the query interval is not valid, or is out of range, or the row filter option is invalid.

Msg 313, Level 16, State 3, Line 1

An insufficient number of arguments were supplied for the procedure or function cdc.fn_cdc_get_all_changes_ ...

net changes のクエリに対して返される対応するエラーは次のとおりです。The corresponding error returned for a net changes query is the following:

Msg 313, Level 16, State 3, Line 1

An insufficient number of arguments were supplied for the procedure or function cdc.fn_cdc_get_net_changes_ ...

注意

メッセージ 313 のメッセージは誤解を招き、エラーの実際の原因を伝えていないことが確認されています。It is recognized that the message for Msg 313 is misleading and does not convey the actual cause of the failure. このメッセージが不適切に使用されている原因は、TVF 内から明示的なエラーを返せないことから生じています。This awkward usage stems from the inability to raise an explicit error from within a TVF. ただし、不正確ではあっても認識可能なエラーを返す方が、空の結果セットを返すよりは役立つと考えられます。Nevertheless, the value of returning a recognizable, if inaccurate, error was deemed preferable to simply returning an empty result. 空の結果セットでは、有効なクエリが変更を返さなかった場合と区別できないためです。An empty result set would not be distinguishable from a valid query returning no changes.

すべての変更のクエリを実行したときに承認エラーが発生した場合は、次のような情報が返されます。Authorization failures will return failures when querying for all changes, as shown:

Msg 229, Level 14, State 5, Line 1

The SELECT permission was denied on the object 'fn_cdc_get_all_changes_...', database 'MyDB', schema 'cdc'.

これは、差分変更のクエリを実行した場合も同じです。The same is true when querying for net changes:

Msg 229, Level 14, State 5, Line 1

The SELECT permission was denied on the object fn_cdc_get_net_changes_...', database 'MyDB', schema 'cdc'.

これらの既知の TVF エラーを受け取り、そのエラーに関する有益情報を返す例については、"TRY CATCH を使用した差分変更の列挙" テンプレートを参照してください。See the template Enumerate Net Changes Using TRY CATCH for a demonstration of how to intercept these known TVF errors and return more meaningful information about the failure.

注意

SQL Server Management Studio で変更データ キャプチャ テンプレートを見つけるには、 [表示] メニューの [テンプレート エクスプローラー] をクリックし、 [SQL Server テンプレート] を展開し、 [変更データ キャプチャ] フォルダーを展開します。To locate change data capture templates in SQL Server Management Studio, on the View menu, click Template Explorer, expand SQL Server Templates and then expand the Change Data Capture folder.

クエリ関数Query Functions

追跡されているソース テーブルの特性とそのキャプチャ インスタンスの構成方法に応じて、変更データのクエリのための TVF が 1 つまたは 2 つ生成されます。Depending on the characteristics of the source table being tracked and the way in which its capture instance is configured, either one or two TVFs for querying change data are generated.

  • cdc.fn_cdc_get_all_changes_<capture_instance> 関数は、指定した期間に発生したすべての変更を返します。The function cdc.fn_cdc_get_all_changes_<capture_instance> returns all changes that occurred for the specified interval. この関数は常に生成されます。This function is always generated. エントリは、必ず並べ替えて返されます。まず変更のトランザクション コミット LSN で並べ替えられ、次にそのトランザクション内の変更のシーケンス値で並べ替えられます。Entries are always returned sorted, first by the transaction commit LSN of the change, and then by a value that sequences the change within its transaction. 選択した行フィルター オプションに応じて、更新について最後の行が返される (行フィルター オプションが "all" の場合) か、新しい値と古い値の両方が返されます (行フィルター オプションが "all update old" の場合)。Depending on the row filter option chosen, either the final row is returned on update (row filter option "all") or both the new and old values are returned on update (row filter option "all update old"').

  • cdc.fn_cdc_get_net_changes_<capture_instance> 関数は、ソース テーブルが有効である場合に @supports_net_changes パラメーターが 1 に設定されていると生成されます。The function cdc.fn_cdc_get_net_changes_<capture_instance> is generated when the parameter @supports_net_changes is set to 1 when the source table is enabled.

    注意

    このオプションは、ソース テーブルで主キーが定義されている場合、または @index_name パラメーターを使用して一意のインデックスが特定されている場合にのみサポートされます。This option is only supported if the source table has a defined primary key or if the parameter @index_name has been used to identify a unique index.

    netchanges 関数は、ソース テーブルの変更された各行につき 1 つの変更を返します。The netchanges function returns one change per modified source table row. 指定した期間に複数の変更が行に対して記録されていた場合は、列の値には行の最終的な内容が反映されます。If more than one change is logged for the row during the specified interval, the column values will reflect the final contents of the row. ターゲット環境の更新に必要な操作を正しく特定するには、その期間に行に対して行われた最初の操作と最後の操作の両方を TVF で考慮する必要があります。To correctly identify the operation that is necessary to update the target environment, the TVF must consider both the initial operation on the row during the interval and the final operation on the row. 行フィルター オプション 'all' を指定した場合、 net changes のクエリで返される操作は、挿入、削除、または更新 (新しい値) になります。When the row filter option 'all' is specified, the operations that are returned by a net changes query will either be insert, delete, or update (new values). このオプションでは、更新マスクは常に null として返されます。これは、集計マスクの計算に関連するコストのためです。This option always returns the update mask as null because there is a cost associated with computing an aggregate mask. 行に対するすべての変更が反映された集計マスクが必要な場合は、'all with mask' オプションを使用します。If you require an aggregate mask that reflects all changes to a row, use the 'all with mask' option. 下流の処理で挿入と更新を区別する必要がない場合は、"all with merge" オプションを使用します。If downstream processing does not require inserts and updates to be distinguished, use the 'all with merge' option. この場合、操作の値に指定される値は 2 つのみです。削除を表す 1 と、挿入または更新の操作を表す 5 です。In this case, the operation value will only take on two values: 1 for delete and 5 for an operation that could be either an insert or an update. このオプションを使用すると、挿入と更新のどちらの操作を派生させるかを特定する追加処理が不要になるので、この区別が不要な場合にクエリのパフォーマンスが向上します。This option eliminates the additional processing needed to determine whether the derived operation should be an insert or an update, and can improve the performance of the query when this differentiation is not necessary.

クエリ関数から返される更新マスクは、変更データの行で変更されたすべての列を特定できるように簡潔に表現したものです。The update mask that is returned from a query function is a compact representation that identifies all columns that changed in a row of change data. 通常、この情報が必要とされるのは、キャプチャ対象列の小さなサブセットを使用する場合のみです。Typically, this information is only required for a small subset of the captured columns. アプリケーションでより直接的に使用できる形式の情報をこのマスクから抽出するための関数も用意されています。Functions are available to assist in extracting information from the mask in a form that is more directly usable by applications. sys.fn_cdc_get_column_ordinal 関数は、特定のキャプチャ インスタンスの指定した列の位置を表す序数を返します。一方、 sys.fn_cdc_is_bit_set 関数は、関数呼び出しで指定した序数に基づいて、指定したマスクのビットのパリティを返します。The function sys.fn_cdc_get_column_ordinal returns the ordinal position of a named column for a given capture instance, whereas the function sys.fn_cdc_is_bit_set returns the parity of the bit in the provided mask based on the ordinal that was passed in the function call. この 2 つの関数により、更新マスクから情報を効率的に抽出し、変更データの要求と共に返すことができます。Together, these two functions allow information from the update mask to be efficiently extracted and returned with the request for change data. これらの関数の使用例については、"All With Mask を使用した差分変更の列挙" テンプレートを参照してください。See the template Enumerate Net Changes Using All With Mask for a demonstration of how these functions are used.

クエリ関数のシナリオQuery Function Scenarios

以降のセクションでは、クエリ関数の cdc.fn_cdc_get_all_changes_<capture_instance> および cdc.fn_cdc_get_net_changes_<capture_instance> を使用して変更データ キャプチャ データのクエリを実行するための一般的なシナリオについて説明します。The following sections describe common scenarios for querying change data capture data by using the query functions cdc.fn_cdc_get_all_changes_<capture_instance> and cdc.fn_cdc_get_net_changes_<capture_instance>.

キャプチャ インスタンスの有効期間内のすべての変更のクエリQuerying for All Changes Within the Capture Instance Validity Interval

変更データに対する最も単純な要求は、キャプチャ インスタンスの有効期間内の現在の変更データをすべて返す要求です。The most straightforward request for change data is one that returns all of the current change data in a capture instance's validity interval. このクエリを実行するには、まず、有効期間の LSN の下限と上限を求めます。To make this request, first determine the lower and upper LSN boundaries of the validity interval. 次に、それらの値を使用して、クエリ関数 cdc.fn_cdc_get_all_changes_<capture_instance> または cdc.fn_cdc_get_net_changes_<capture_instance> に渡すパラメーター @from_lsn および @to_lsn を特定します。Then, use these values to identify the parameters @from_lsn and @to_lsn passed to the query function cdc.fn_cdc_get_all_changes_<capture_instance> or cdc.fn_cdc_get_net_changes_<capture_instance>. 下限を取得するには sys.fn_cdc_get_min_lsn 関数を使用し、上限を取得するには sys.fn_cdc_get_max_lsn 関数を使用します。Use the function sys.fn_cdc_get_min_lsn to obtain the lower bound, and sys.fn_cdc_get_max_lsn to obtain the upper bound. クエリ関数 cdc.fn_cdc_get_all_changes_<capture_instance> を使用して現在のすべての有効な変更のクエリを実行するためのサンプル コードについては、"有効な範囲のすべての変更の列挙" テンプレートを参照してください。See the template Enumerate All Changes for the Valid Range for sample code to query for all current valid changes by using the query function cdc.fn_cdc_get_all_changes_<capture_instance>. cdc.fn_cdc_get_net_changes_<capture_instance> 関数を使用した類似の例については、"有効な範囲の差分変更の列挙" テンプレートを参照してください。See the template Enumerate Net Changes for the Valid Range for a similar example of using the function cdc.fn_cdc_get_net_changes_<capture_instance>.

前回の変更セット以降に発生したすべての新しい変更のクエリQuerying for All New Changes Since the Last Set of Changes

一般的なアプリケーションの場合、変更データのクエリは継続的なプロセスであり、前回の要求以降に発生したすべての変更の要求が定期的に行われます。For typical applications, querying for change data will be an ongoing process, making periodic requests for all of the changes that occurred since the last request. そのようなクエリでは、 sys.fn_cdc_increment_lsn 関数を使用して、前回のクエリの上限から現在のクエリの下限を求めることができます。For such queries, you can use the function sys.fn_cdc_increment_lsn to derive the lower bound of the current query from the upper bound of the previous query. この方法では、クエリ範囲が常に両端の値を含む閉区間として扱われるため、行の重複が起こらないことが保証されます。This method ensures that no rows are repeated because the query interval is always treated as a closed interval where both end-points are included in the interval. 次に、 sys.fn_cdc_get_max_lsn 関数を使用して、新しい要求期間の上限を取得します。Then, use the function sys.fn_cdc_get_max_lsn to obtain the high end-point for the new request interval. クエリ期間を体系的に移動させて前回の要求以降に発生したすべての変更を取得するためのサンプル コードについては、"前回の要求以降に発生したすべての変更の列挙" テンプレートを参照してください。See the template Enumerate All Changes Since Previous Request for sample code to systematically move the query window to obtain all changes since the last request.

現在までのすべての新しい変更のクエリQuerying for all New Changes Up Until Now

クエリ関数から返される変更に対しては、前回の要求から現在の日時までの間に発生した変更のみを含める制約がよく適用されます。A typical constraint that is placed on the changes returned by a query function is to include only the changes that occurred between the previous request until the current date and time. この場合はまず、前回の要求で使用された @from_lsn 値に sys.fn_cdc_increment_lsn 関数を適用して下限を求めます。For this query, apply the function sys.fn_cdc_increment_lsn to the @from_lsn value that was used in the previous request to determine the lower bound. 期間の上限は特定の時点として表されるため、クエリ関数で使用するには先に LSN 値に変換する必要があります。Because the upper bound on the time interval is expressed as a specific point in time, it must be converted to an LSN value before it can be used by a query function. datetime 値を対応する LSN 値に変換するには、まず、指定した上限までの間にコミットされたすべての変更が既にキャプチャ プロセスによって処理されていることを確認する必要があります。Before the datetime value can be converted to a corresponding LSN value, you must ensure that the capture process has processed all changes that were committed through the specified upper bound. この確認は、該当するすべての変更が変更テーブルに反映されているようにするために必要です。This is required to ensure that all the qualifying changes have been propagated to the change table. これを確認するには、wait ループを構成して、任意のデータベース変更テーブルに記録されたコミット LSN の現在の最大値が目的の要求期間の終了時間を超えているかどうかを定期的に確認する方法があります。One way to do this is to structure a wait loop that periodically checks to see if the current maximum commit lsn recorded for any database change table exceeds the desired end time of the request interval.

関連するすべてのログ エントリが既にキャプチャ プロセスによって処理されていることを遅延ループで確認したら、 sys.fn_cdc_map_time_to_lsn 関数を使用して、LSN 値として表された新しい上限を求めます。After the delay loop verifies that the capture process has already processed all the relevant log entries, use the function sys.fn_cdc_map_time_to_lsn to determine the new high end-point expressed as an LSN value. 指定した時刻までの間にコミットされたエントリがすべて取得されるようにするには、sys.fn_cdc_map_time_to_lsn 関数を呼び出してオプション 'largest less than or equal' を使用します。To ensure that all entries that were committed through the specified time are retrieved, call the function sys.fn_cdc_map_time_to_lsn, and use the option 'largest less than or equal'.

注意

変更が発生していない期間には、cdc.lsn_time_mapping テーブルにダミー エントリが追加されて、特定のコミット時間までの変更が既にキャプチャ プロセスによって処理されていることが示されます。In periods of inactivity, a dummy entry is added to the table cdc.lsn_time_mapping to mark the fact that the capture process has processed the changes up to a given commit time. これは、処理する新しい変更がない場合にキャプチャ プロセスの処理が遅れているように見えるのを防ぐためです。This prevents it from appearing that the capture process has fallen behind when there are simply no recent changes to process.

"現在までのすべての変更の列挙" テンプレートは、上の方法を使用して変更データのクエリを実行する方法を示しています。The template Enumerate All Changes Up Until Now demonstrates how to use the previous strategy to query for change data.

すべての変更結果セットへのコミット時間の追加Adding a Commit Time to an All Changes Result Set

データベース変更テーブルの各エントリに対応するトランザクションのコミット時間は、 cdc.lsn_time_mappingテーブルから取得できます。The commit time of each transaction with an associated entry in a database change table is available in the table cdc.lsn_time_mapping. すべての変更の要求で返された __$start_lsn 値を cdc.lsn_time_mapping テーブルのエントリの start_lsn 値と結合することにより、変更データと共に tran_end_time を返して、ソースにおけるトランザクションのコミット時間を使用して変更にタイム スタンプを付けることができます。By joining the __$start_lsn value returned in a request for all changes with the start_lsn value of a cdc.lsn_time_mapping table entry, you can return the tran_end_time along with the change data to stamp the change with the commit time of the transaction at the source. "すべての変更結果セットへのコミット時間の添付" テンプレートは、この結合の実行方法を示しています。The template Append Commit Time to All Changes Result Set demonstrates how to perform this join.

同じトランザクションの他のデータと変更データとの結合Joining Change Data with Other Data from the Same Transaction

変更データを、トランザクションがソースでコミットされたときに収集されたその他の情報と結合すると便利な場合があります。Occasionally, it is useful to join change data with other information gathered about the transaction when it committed at the source. cdc.lsn_time_mapping テーブルの tran_begin_lsn 列には、そのような結合を実行するために必要な情報が含まれています。The tran_begin_lsn column in the table cdc.lsn_time_mapping provides the information needed to perform such a join. ソースの更新が発生したら、システム動的ビュー sys.dm_tran_database_transactions の database_transaction_begin_lsn の値を、変更データと結合するその他の情報と共に保存する必要があります。When the update of the source occurs, the value for database_transaction_begin_lsn from the system dynamic view sys.dm_tran_database_transactions must be saved along with any other information to be joined with the change data. その後、fn_convertnumericlsntobinary 関数を使用して、database_transaction_begin_lsn の値と tran_begin_lsn の値を比較します。Use the function fn_convertnumericlsntobinary to compare the database_transaction_begin_lsn and tran_begin_lsn values. この関数を作成するためのコードは、"fn_convertnumericlsntobinary 関数の作成" テンプレートに含まれています。The code to create this function is available in the template Create Function fn_convertnumericlsntobinary. "特定の tran_begin_lsn を持つすべての変更の取得" テンプレートは、この結合の実行方法を示しています。The template Return All Changes with a Given tran_begin_lsn demonstrates how to effect the join.

datetime ラッパー関数を使用したクエリQuerying Using Datetime Wrapper Functions

変更データのクエリの一般的なアプリケーション シナリオの 1 つに、datetime 値で範囲指定されたスライディング ウィンドウを使用して変更データを定期的に要求するというものがあります。A typical application scenario for querying for change data is to periodically request change data by using a sliding window bounded by datetime values. この種のコンシューマーのために、ストアド プロシージャ sys.sp_cdc_generate_wrapper_function が用意されています。このストアド プロシージャは、変更データ キャプチャ クエリ関数のカスタム ラッパー関数を作成するためのスクリプトを生成します。For this class of consumers, change data capture provides the stored procedure sys.sp_cdc_generate_wrapper_function that generates scripts to create custom wrapper functions for the change data capture query functions. これらのカスタム ラッパーを使用すると、クエリ範囲を datetime のペアとして表すことができます。These custom wrappers allow the query interval to be expressed as a datetime pair.

このストアド プロシージャでは、呼び出しオプションを使用することにより、呼び出し元がアクセスできるすべてのキャプチャ インスタンスに対してラッパーを生成することも、指定したキャプチャ インスタンスに対してのみ生成することもできます。Calling options for the stored procedure allow for wrappers to be generated for all capture instances that the caller has access to, or only a specified capture instance. そのほか、キャプチャ間隔の上限が開いているか閉じているかを指定したり、使用可能なキャプチャ対象列のうちのどれを結果セットに含めるかを指定したり、結果セットに含める列のうちのどれに更新フラグを関連付けるかを指定したりすることもできます。Supported options also include the ability to specify whether the high end-point of the capture interval should be open or closed, which of the available captured columns should be included in the result set and which of the included columns should have associated update flags. このプロシージャが返す結果セットには 2 つの列があります。1 つは、生成される関数の名前 (キャプチャ インスタンス名から派生する名前)、もう 1 つは、ラッパー ストアド プロシージャの作成ステートメントです。The procedure returns a result set with two columns: the generated function name, which is derivable from the capture instance name, and the create statement for the wrapper stored procedure. すべての変更クエリをラップする関数は常に生成されます。The function to wrap the all changes query is always generated. キャプチャ インスタンスの作成時に @supports_net_changes パラメーターが設定されていた場合は、差分変更追跡の関数をラップする関数も生成されます。If the @supports_net_changes parameter was set when the capture instance was created, the function to wrap the net changes function is also generated.

スクリプト生成ストアド プロシージャを呼び出してラッパー ストアド プロシージャの作成ステートメントを生成し、その結果の作成スクリプトを実行して関数を作成するのは、アプリケーション デザイナーの仕事です。It is the responsibility of the application designer to call the script generation stored procedure to generate the create statements for the wrapper stored procedures, and to execute the resulting create scripts to create the functions. キャプチャ インスタンスの作成時に自動的には行われません。This does not occur automatically when a capture instance is created.

datetime ラッパーはユーザーが所有します。呼び出し元の既定のスキーマには作成されません。Datetime wrappers are owned by the user, and not are created in the default schema of the caller. 生成される関数はほとんどのユーザーがそのまま使用できますが、The generated function is suitable without modification for most users. 関数を作成する前に、生成されたスクリプトをさらにカスタマイズすることもできます。However, further customization can always be applied to the generated script prior to creating the function.

すべての変更クエリをラップする関数の名前は、fn_all_changes_ の後にキャプチャ インスタンスの名前を付けた名前になります。The name of the function to wrap the all changes query is fn_all_changes_ followed by the capture instance name. 差分変更追跡のラッパーに使用されるプレフィックスは fn_net_changes です。The prefix that is used for the net changes wrapper is fn_net_changes_. どちらの関数も、関連する変更データ キャプチャ TVF と同じように 3 つの引数を受け取ります。Both functions take three arguments, just as their associated change data capture TVFs do. ただし、ラッパーのクエリ範囲は、2 つの LSN 値ではなく 2 つの datetime 値で範囲指定されます。However, the query interval for the wrappers is bounded by two datetime values instead of than by two LSN values. @row_filter_option パラメーターはどちらの場合も同じです。The @row_filter_option parameter for both sets of functions are the same.

生成されるラッパー関数は、変更データ キャプチャ タイムラインを体系的に進めるための規則をサポートしているため、前の期間の @end_time パラメーターは、次の期間の @start_time パラメーターとして使用されるものと見なされます。The generated wrapper functions support the following convention for systematically walking the change data capture timeline: It is expected that the @end_time parameter of the previous interval be used as the @start_time parameter of the subsequent interval. またラッパー関数は、datetime 値を LSN 値にマップし、この規則に従った場合にデータの欠落や重複が発生しないようにします。The wrapper function takes care of mapping the datetime values to LSN values and ensuring that no data is lost or repeated if this convention is followed.

ラッパーは、指定のクエリ期間で閉じた上限をサポートするように生成することも、開いた上限をサポートするように生成することもできます。The wrappers can be generated to support either a closed upper bound or an open upper bound on the specified query window. つまり、抽出期間の上限とコミット時間が等しいエントリを、その期間に含めるかどうかを呼び出し元が指定できます。That is, the caller can specify whether entries having a commit time equal to the upper bound of the extraction interval are to be included within the interval. 既定では、上限が含まれます。By default, the upper bound is included.

生成されるクエリ TVF では、@from_lsn 値または @to_lsn 値に NULL 値を渡すと失敗しますが、datetime ラッパー関数では、NULL を使用すると現在のすべての変更を取得できます。While the generated query TVFs fail if supplied a null value for either the @from_lsn value or the @to_lsn value, the datetime wrapper functions use null to allow the datetime wrappers to return all current changes. つまり、datetime ラッパーにクエリ期間の下限として NULL を渡すと、クエリ TVF に適用される基になる SELECT ステートメントでキャプチャ インスタンスの有効期間の下限が使用されます。That is, if null is passed as the low end-point of the query window to the datetime wrapper, the low end point of the capture instance validity interval is used in the underlying SELECT statement that is applied to the query TVF. 同様に、クエリ期間の上限として NULL を渡すと、クエリ TVF に適用される SELECT ステートメントでキャプチャ インスタンスの有効期間の上限が使用されます。Similarly, if null is passed as the high end-point of the query window, the high end-point of the capture instance validity interval is used when selecting from the query TVF.

ラッパー関数から返される結果セットには、要求したすべての列と、それに続いて、行に関連付けられている操作を示す 1 つまたは 2 つの文字として記録される操作列が含まれます。The result set returned by a wrapper function includes all the requested columns followed by an operation column, recoded as one or two characters to identify the operation that is associated with the row. 更新フラグを要求した場合は、操作コードの後に、@update_flag_list パラメーターで指定した順にビット列として表示されます。If update flags have been requested, they appear as bit columns after the operation code, in the order specified in the @update_flag_list parameter. 生成される datetime ラッパーをカスタマイズするための呼び出しオプションについては、「sys.sp_cdc_generate_wrapper_function (Transact-SQL)」を参照してください。For information about the calling options for customizing the generated datetime wrappers, see sys.sp_cdc_generate_wrapper_function (Transact-SQL).

"更新フラグを含むラッパー TVF のインスタンス化" テンプレートは、生成されるラッパー関数をカスタマイズして、差分変更のクエリから返される結果セットに指定した列の更新フラグを追加する方法を示しています。The template Instantiate a Wrapper TVF With Update Flag shows how to customize a generated wrapper function to append an update flag for a specified column to the result set returned by a net changes query. "スキーマの CDC ラッパー TVF のインスタンス化" テンプレートは、特定のデータベース スキーマのソース テーブルに対して作成されたすべてのキャプチャ インスタンスのクエリ TVF の datetime ラッパーをインスタンス化する方法を示しています。The template Instantiate CDC Wrapper TVFs for a Schema shows how to instantiate the Datetime Wrappers for the Query TVFs for all of the capture instances created for the source tables in a given database schema.

datetime ラッパーを使用して変更データのクエリを実行する例については、"更新フラグを含むラッパーを使用した差分変更の取得" テンプレートを参照してください。For an example that uses a datetime wrapper to query for change data, see the template Get Net Changes Using Wrapper With Update Flags. このテンプレートは、更新フラグを返すように構成されたラッパー関数を使用して差分変更のクエリを実行する方法を示しています。This template demonstrates how to query for net changes with a wrapper function when the wrapper is configured to return update flags. 基になるクエリ関数で更新時に NULL でない更新マスクを返すには、行フィルター オプション "all with mask" を使用する必要があります。Note that the row filter option 'all with mask' is required for the underlying query function to return a non-null update mask on update. datetime の期間の下限と上限の両方に対して NULL 値を渡して、基になる LSN に基づくクエリの実行時にキャプチャ インスタンスの有効期間の下限と上限が使用されるようにします。Null values are passed for both the lower and upper datetime interval boundaries to signal the function to use the low end point and the high end point of the validity interval for the capture instance when performing the underlying LSN based query. このクエリでは、キャプチャ インスタンスの有効期間内に発生したソース行の各変更ごとに 1 行のデータが返されます。The query returns one row for each modification to a source row that occurred within the valid range for the capture instance.

datetime ラッパー関数を使用したキャプチャ インスタンスの切り替えUsing the Datetime Wrapper Functions to Transition Between Capture Instances

変更データ キャプチャでは、追跡するソース テーブル 1 つに対してキャプチャ インスタンスを 2 つまで使用できます。Change data capture supports up to two capture instances for a single tracked source table. この機能は主に、ソース テーブルに対するデータ定義言語 (DDL) の変更によって追跡可能な列が増えた場合に、キャプチャ インスタンスを切り替えることができるようにするために使用されます。The principal use of this capability is to accommodate a transition between multiple capture instances when data definition language (DDL) changes to the source table expand the set of available columns for tracking. 新しいキャプチャ インスタンスに切り替える際に、基になるクエリ関数の名前の変更から上のアプリケーション レベルを保護するには、基になる呼び出しをラッパー関数でラップして、When transitioning to a new capture instance, one way to protect higher application levels from changes in the names of the underlying query functions is to use a wrapper function to wrap the underlying call. ラッパー関数の名前が元の名前と同じになるようにする方法があります。Then, ensure that the name of the wrapper function remains the same. インスタンスの切り替えが行われるときに、古いラッパー関数を削除して、新しいクエリ関数を参照する同じ名前の新しいラッパー関数を作成できます。When the switch is to occur, the old wrapper function can be dropped, and a new one with the same name created that references the new query functions. 生成されるスクリプトを事前に変更して同じ名前のラッパー関数が作成されるようにすることで、上のアプリケーション層に影響を与えずに新しいキャプチャ インスタンスに切り替えることができます。By first modifying the generated script to create a wrapper function of the same name, you can make the switch to a new capture instance without affecting higher application layers.

参照See Also

データ変更の追跡 (SQL Server) Track Data Changes (SQL Server)
変更データ キャプチャについて (SQL Server) About Change Data Capture (SQL Server)
変更データ キャプチャの有効化と無効化 (SQL Server) Enable and Disable Change Data Capture (SQL Server)
変更データ キャプチャの管理と監視 (SQL Server)Administer and Monitor Change Data Capture (SQL Server)