cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)

  • Artículo

Se aplica a:SQL Server

Devuelve una fila de cambio neto para cada fila de origen cambiada dentro del intervalo de números de secuencia de registro (LSN) especificado.

Espera, ¿qué es un LSN? Cada registro del SQL Server registro de transacciones se identifica de forma única mediante un número de secuencia de registro (LSN). Los LSN se ordenan de forma que, si LSN2 es mayor que LSN1, el cambio descrito por el registro de registro al que hace referencia LSN2 se produjo después del cambio descrito por el LSN del registro.

El LSN de un registro donde se produjo un evento significativo puede ser útil para construir secuencias de restauración correctas. Dado que los LSN están ordenados, puede compararlos por igualdad y desigualdad (es decir, , <, = , <=, =, >>=). Estas comparaciones son útiles para generar secuencias de restauración.

Cuando una fila de origen tiene varios cambios durante el intervalo LSN, se devuelve una sola fila que refleja el contenido final de la fila mediante la función de enumeración descrita a continuación. Por ejemplo, si una transacción inserta una fila en la tabla de origen y una transacción posterior dentro del intervalo LSN actualiza una o varias columnas de esa fila, la función devuelve solo una fila, que incluye los valores de columna actualizados.

Esta función de enumeración se crea cuando se habilita una tabla de origen para la captura de datos modificados y se especifica seguimientos de cambios en la red. Para habilitar el seguimiento de cambios netos, la tabla de origen debe tener una clave principal o índice único. El nombre de la función se deriva y usa el formato cdc.fn_cdc_get_net_changes_<capture_instance>, donde <capture_instance> es el valor especificado para la instancia de captura cuando se habilitó la tabla de origen para la captura de datos modificados. Para obtener más información, consulte sys.sp_cdc_enable_table (Transact-SQL).

Convenciones de sintaxis de Transact-SQL

Sintaxis

  
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  
}

Argumentos

from_lsn

El LSN que representa el extremo inferior del rango de LSN que se va a incluir en el conjunto de resultados. from_lsn es binary(10).

Solo las filas del cdc.[ capture_instance]_CT tabla de cambios con un valor en __$start_lsn mayor o igual que from_lsn se incluyen en el conjunto de resultados.

to_lsn

El LSN que representa el extremo superior del rango de LSN que se va a incluir en el conjunto de resultados. to_lsn es binary(10).

Solo las filas del cdc.[ capture_instance]_CT tabla de cambios con un valor en __$start_lsn menor o igual que from_lsn o igual que to_lsn se incluyen en el conjunto de resultados.

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

Una opción que rige el contenido de las columnas de metadatos y las filas devueltas en el conjunto de resultados. Puede ser una de las siguientes opciones:

todo
Devuelve el LSN del último cambio de la fila y la operación necesaria para aplicar la fila en las columnas de metadatos __$start_lsn y __$operation. La columna __$update_mask tiene siempre el valor NULL.

all with mask
Devuelve el LSN del último cambio de la fila y la operación necesaria para aplicar la fila en las columnas de metadatos __$start_lsn y __$operation. Además, cuando una operación de actualización devuelve (__$operation = 4) las columnas capturadas modificadas en la actualización se marcan en el valor devuelto en __$update_mask.

todos con combinación
Devuelve el LSN del último cambio realizado en la fila en las columnas de metadatos __$start_lsn. La columna __$operation tendrá uno de estos dos valores: 1 para eliminar y 5 indicar que la operación necesaria para aplicar el cambio es una inserción o una actualización. La columna __$update_mask tiene siempre el valor NULL.

Debido a que la lógica para determinar la operación precisa de un cambio determinado agrega mayor complejidad a la consulta, esta opción se ha diseñado para mejorar el rendimiento de las consultas cuando es suficiente indicar que la operación necesaria para aplicar los datos de cambio es una inserción o una actualización, pero no es necesario distinguir explícitamente entre las dos. Esta opción es más atractiva en entornos de destino en los que una operación de combinación está disponible directamente.

Tabla devuelta

Nombre de la columna Tipo de datos Descripción
__$start_lsn binary(10) Número de secuencia de registro (LSN) asociado con la transacción de confirmación para el cambio.

Todos los cambios confirmados en la misma transacción comparten el mismo LSN de confirmación. Por ejemplo, si una operación de actualización de la tabla de origen modifica dos columnas en dos filas, la tabla de cambios contendrá cuatro filas, cada una con la misma __$start_lsnvalue.
__$operation int Identifica la operación del lenguaje de manipulación de datos (DML) necesaria para aplicar la fila de datos modificados al origen de datos de destino.

Si el valor del parámetro row_filter_option es todos o todos con máscara, el valor de esta columna puede ser uno de los siguientes:

1 = eliminar

2 = insertar

4 = actualizar

Si el valor del parámetro row_filter_option es todos con combinación, el valor de esta columna puede ser uno de los siguientes:

1 = eliminar

5 = insertar o actualizar
__$update_mask varbinary(128) Máscara de bits con un bit que corresponde a cada columna capturada identificada para la instancia de captura. Este valor tiene todos los bits definidos establecidos en 1 si __$operation = 1 o 2. Si __$operation = 3 o 4, solo los bits que corresponden a columnas que han cambiado se establecen en 1.
<columnas de la tabla de origen capturadas> Varía Las columnas restantes devueltas por la función son las columnas de la tabla de origen que se identificaron como columnas capturadas cuando se creó la instancia de captura. Si no se especificó ninguna columna en la lista de columnas capturadas, se devuelven todas las columnas de la tabla de origen.

Permisos

Debe pertenecer al rol fijo de servidor sysadmin o al rol fijo de base de datos db_owner. Para el resto de usuarios, requiere el permiso SELECT en todas las columnas capturadas en la tabla de origen y, si se ha definido un rol de acceso para la instancia de captura, la pertenencia a ese rol de base de datos. Cuando el autor de la llamada no tiene permiso para ver los datos de origen, la función devuelve una fila con valores NULL para todas las columnas.

Comentarios

Las modificaciones en el identificador único de una fila harán fn_cdc_get_net_changes que se muestre el comando UPDATE inicial con un comando DELETE y, a continuación, INSERT en su lugar. Este comportamiento es necesario para realizar un seguimiento de la clave tanto antes como después del cambio.

Se espera el error 313 si el intervalo LSN proporcionado no es adecuado al llamar a cdc.fn_cdc_get_all_changes_<capture_instance> o cdc.fn_cdc_get_net_changes_<capture_instance>. Si el lsn_value parámetro está fuera del tiempo de LSN más bajo o LSN más alto, la ejecución de estas funciones devolverá el error 313: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or function. El desarrollador debe controlar este error. Puede encontrar un ejemplo de T-SQL para una solución alternativa en ReplTalk en GitHub.

Ejemplos

En el ejemplo siguiente se usa la función cdc.fn_cdc_get_net_changes_HR_Department para notificar los cambios netos realizados en la tabla HumanResources.Department de origen durante un intervalo de tiempo específico.

En primer lugar, se usa la función GETDATE para marcar el inicio del intervalo de tiempo. Después de aplicar varias instrucciones DML a la tabla de origen, se llama de nuevo a la función GETDATE para identificar el final del intervalo de tiempo. A continuación, la función sys.fn_cdc_map_time_to_lsn se usa para asignar el intervalo de tiempo a un intervalo de consultas de captura de datos modificados enlazado por valores LSN. Por último, se consulta la función cdc.fn_cdc_get_net_changes_HR_Department para obtener los cambios de la red realizados en la tabla de origen durante el intervalo de tiempo. Observe que la fila que se inserta y, a continuación, se elimina no aparece en el conjunto de resultados devuelto por la función. Esto se debe a que una fila que primero se agrega y luego se elimina dentro de una ventana de consulta no genera ningún cambio de la red en la tabla de origen para el intervalo.

Nota:

Antes de ejecutar este ejemplo, primero debe ejecutar el ejemplo B en sys.sp_cdc_enable_table (Transact-SQL) para habilitar CDC en la tabla HumanResources.Department. En el ejemplo siguiente, HR_Department es el nombre de la instancia de captura CDC, como se especifica en 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');

Consulte también