Bewerken

Share via


cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL)

Applies to: SQL Server

Returns one row for each change applied to the source table within the specified log sequence number (LSN) range. If a source row had multiple changes during the interval, each change is represented in the returned result set. In addition to returning the change data, four metadata columns provide the information you need to apply the changes to another data source. Row filtering options govern the content of the metadata columns as well as the rows returned in the result set. When the 'all' row filter option is specified, each change has exactly one row to identify the change. When the 'all update old' option is specified, update operations are represented as two rows: one containing the values of the captured columns before the update and another containing the values of the captured columns after the update.

This enumeration function is created at the time that a source table is enabled for change data capture. The function name is derived and uses the format cdc.fn_cdc_get_all_changes_<capture_instance> where capture_instance is the value specified for the capture instance when the source table is enabled for change data capture.

Transact-SQL syntax conventions

Syntax

  
cdc.fn_cdc_get_all_changes_capture_instance ( from_lsn , to_lsn , '<row_filter_option>' )  
  
<row_filter_option> ::=  
{ all  
 | all update old  
}  

Arguments

from_lsn

The LSN value that represents the low endpoint of the LSN range to include in the result set. from_lsn is binary(10).

Only rows in the cdc.[capture_instance]_CT change table with a value in __$start_lsn greater than or equal to from_lsn are included in the result set.

to_lsn

The LSN value that represents the high endpoint of the LSN range to include in the result set. to_lsn is binary(10).

Only rows in the cdc.[capture_instance]_CT change table with a value in __$start_lsn greater than or equal to from_lsn and less than or equal to to_lsn are included in the result set.

<row_filter_option> ::= { all | all update old }

An option that governs the content of the metadata columns as well as the rows returned in the result set.

Can be one of the following options:

all
Returns all changes within the specified LSN range. For changes due to an update operation, this option only returns the row containing the new values after the update is applied.

all update old
Returns all changes within the specified LSN range. For changes due to an update operation, this option returns both the row containing the column values before the update and the row containing the column values after the update.

Table returned

Column name Data type Description
__$start_lsn binary(10) Commit LSN associated with the change that preserves the commit order of the change. Changes committed in the same transaction share the same commit LSN value.
__$seqval binary(10) Sequence value used to order changes to a row within a transaction.
__$operation int Identifies the data manipulation language (DML) operation needed to apply the row of change data to the target data source. Can be one of the following:

1 = delete

2 = insert

3 = update (captured column values are those before the update operation). This value applies only when the row filter option 'all update old' is specified.

4 = update (captured column values are those after the update operation)
__$update_mask varbinary(128) A bit mask with a bit corresponding to each captured column identified for the capture instance. This value has all defined bits set to 1 when __$operation = 1 or 2. When __$operation = 3 or 4, only those bits corresponding to columns that changed are set to 1.
<captured source table columns> varies The remaining columns returned by the function are the captured columns identified when the capture instance was created. If no columns were specified in the captured column list, all columns in the source table are returned.

Permissions

Requires membership in the sysadmin fixed server role or db_owner fixed database role. For all other users, requires SELECT permission on all captured columns in the source table and, if a gating role for the capture instance was defined, membership in that database role. When the caller does not have permission to view the source data, the function returns error 229 The SELECT permission was denied on the object 'fn_cdc_get_all_changes_...', database '\<DatabaseName>', schema 'cdc'.

Remarks

Columns of data type image, text, and ntext are always assigned a NULL value when __$operation = 1 or __$operation = 3. Columns of data type varbinary(max), varchar(max), or nvarchar(max) are assigned a NULL value when __$operation = 3 unless the column changed during the update. When __$operation = 1, these columns are assigned their value at the time of the delete. Computed columns that are included in a capture instance always have a value of NULL.

Error 313 is expected if LSN range supplied is not appropriate when calling cdc.fn_cdc_get_all_changes_<capture_instance> or cdc.fn_cdc_get_net_changes_<capture_instance>. If the lsn_value parameter is beyond the time of lowest LSN or highest LSN, then execution of these functions will return in error 313: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or function. This error should be handled by the developer.

Examples

Several SQL Server Management Studio templates are available that show how to use the change data capture query functions. These templates are available on the View menu in Management Studio. For more information, see Template Explorer.

This example shows the Enumerate All Changes for Valid Range Template. It uses the function cdc.fn_cdc_get_all_changes_HR_Department to report all the currently available changes for the capture instance HR_Department, which is defined for the source table HumanResources.Department in the AdventureWorks2022 database.

-- ========  
-- Enumerate All Changes for Valid Range Template  
-- ========  
USE AdventureWorks2022;  
GO  
  
DECLARE @from_lsn binary(10), @to_lsn binary(10);  
SET @from_lsn = sys.fn_cdc_get_min_lsn('HR_Department');  
SET @to_lsn   = sys.fn_cdc_get_max_lsn();  
SELECT * FROM cdc.fn_cdc_get_all_changes_HR_Department  
  (@from_lsn, @to_lsn, N'all');  
GO  

See Also