<cdc.fn_cdc_get_net_changes_capture_instance> (Transact-SQL)

Artikel
05/30/2023

Gibt eine Nettoänderungszeile für jede Quellzeile zurück, die innerhalb des angegebenen LSN-Bereichs (Log Sequence Numbers) geändert wurde.

Warten Sie, was ist ein LSN? Jeder Datensatz im SQL Server Transaktionsprotokolls wird eindeutig durch eine Protokollsequenznummer (Log Sequence Number, LSN) identifiziert. LSNs sind so angeordnet, dass die durch den Protokolldatensatz beschriebene Änderung, auf die von LSN2 verwiesen wird, nach der im Protokolldatensatz LSN2 beschriebenen Änderung aufgetreten ist, wenn LSN2 größer als LSN1 ist.

Der LSN eines Protokolldatensatzes, in dem ein signifikantes Ereignis aufgetreten ist, kann nützlich sein, um richtige Wiederherstellungssequenzen zu erstellen. Da LSNs sortiert sind, können Sie sie auf Gleichheit und Ungleichheit vergleichen (d.a<. , >, =, <=, =). > Solche Vergleiche sind beim Erstellen von Wiederherstellungssequenzen hilfreich.

Wenn eine Quellzeile während des LSN-Bereichs mehrere Änderungen aufweist, wird eine einzelne Zeile, die den endgültigen Inhalt der Zeile widerspiegelt, von der unten beschriebenen Enumerationsfunktion zurückgegeben. Wenn beispielsweise eine Transaktion eine Zeile in die Quelltabelle einfügt und eine nachfolgende Transaktion innerhalb des LSN-Bereichs eine oder mehrere Spalten in dieser Zeile aktualisiert, gibt die Funktion nur eine Zeile zurück, die die aktualisierten Spaltenwerte enthält.

Diese Enumerationsfunktion wird erstellt, wenn eine Quelltabelle für Change Data Capture aktiviert wird und die Nettonachverfolgung angegeben ist. Um die Nettonachverfolgung zu aktivieren, muss die Quelltabelle einen Primärschlüssel oder einen eindeutigen Index aufweisen. Der Funktionsname wird abgeleitet und verwendet das Format cdc.fn_cdc_get_net_changes_<capture_instance>, wobei <capture_instance> der Wert ist, der für die Erfassung instance angegeben ist, als die Quelltabelle für die Änderungsdatenerfassung aktiviert wurde. Weitere Informationen finden Sie unter sys.sp_cdc_enable_table (Transact-SQL).

Transact-SQL-Syntaxkonventionen

Syntax

  
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  
}

Argumente

from_lsn

Der LSN, der den niedrigen Endpunkt des LSN-Bereichs darstellt, der in das Resultset aufgenommen werden soll. from_lsn ist binary(10).

Nur Zeilen in der cdc.[ capture_instance]_CT Änderungstabelle mit einem Wert in __$start_lsn größer als oder gleich from_lsn im Resultset enthalten sind.

to_lsn

Der LSN, der den hohen Endpunkt des LSN-Bereichs darstellt, der in das Resultset aufgenommen werden soll. to_lsn ist binary(10).

Nur Zeilen in der cdc.[ capture_instance]_CT Änderungstabelle mit einem Wert in __$start_lsn kleiner oder gleich from_lsn oder gleich to_lsn im Resultset enthalten sind.

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

Eine Option, die den Inhalt der Metadatenspalten sowie die im Resultset zurückgegebenen Zeilen steuert. Eine der folgenden Optionen ist möglich:

alle
Gibt die LSN der letzten Zeilenänderung sowie den Vorgang zurück, der erforderlich ist, um die Zeile in den Metadatenspalten __$start_lsn und __$operation anzuwenden. Die Spalte __$update_mask ist immer NULL.

all with mask
Gibt die LSN der letzten Zeilenänderung sowie den Vorgang zurück, der erforderlich ist, um die Zeile in den Metadatenspalten __$start_lsn und __$operation anzuwenden. Wenn ein Updatevorgang (__$operation = 4) zurückgibt, werden außerdem die im Update geänderten aufgezeichneten Spalten mit dem Wert gekennzeichnet, der in __$update_mask zurückgegeben wird.

all with merge
Gibt die LSN der letzten Zeilenänderung in den Metadatenspalten __$start_lsn zurück. Die Spalte __$operation ist auf einen von zwei Werten festgelegt: 1 für Löschen oder 5 als Hinweis dafür, dass der zur Änderungsanwendung benötigte Vorgang entweder ein Einfügevorgang oder ein Updatevorgang ist. Die Spalte __$update_mask ist immer NULL.

Da die Bestimmung des präzisen Vorgangs für eine bestimmte Änderung die Logik der Abfragekomplexität erhöht, soll diese Option die Abfrageleistung in den Fällen verbessern, in denen zur Angabe des für die Änderungsanwendung notwendigen Vorgangs nur darauf hingewiesen werden muss, dass es sich entweder um einen Einfügevorgang oder um einen Updatevorgang handelt, und die explizite Unterscheidung der beiden Vorgänge nicht notwendig ist. Diese Option ist am attraktivsten in Zielumgebungen, in denen ein Mergevorgang direkt verfügbar ist.

Zurückgegebene Tabelle

Spaltenname	Datentyp	BESCHREIBUNG
__$start_lsn	binary(10)	LSN, die dem Commit für die Änderung zugeordnet wurde. Alle Änderungen, für die ein Commit in derselben Transaktion ausgeführt wurde, verwenden dieselbe Commit-LSN. Wenn beispielsweise ein Aktualisierungsvorgang für die Quelltabelle zwei Spalten in zwei Zeilen ändert, enthält die Änderungstabelle vier Zeilen mit jeweils demselben __$start_lsnvalue.
__$operation	int	Identifiziert den Vorgang der Datenbearbeitungssprache (Data Manipulation Language, DML), der erforderlich ist, um die Zeile der Änderungsdaten auf die Zieldatenquelle anzuwenden. Wenn der Wert des row_filter_option-Parameters 'all' oder 'all with mask' ist, kann der Wert in dieser Spalte einen der folgenden Werte annehmen: 1 = Löschen 2 = Einfügen 4 = Aktualisieren Wenn der Wert des row_filter_option-Parameters 'all with merge' ist, kann der Wert in dieser Spalte einen der folgenden Werte annehmen: 1 = Löschen 5 = Einfügen oder Aktualisieren
__$update_mask	varbinary(128)	Eine Bitmaske mit einem Bit, das den einzelnen aufgezeichneten Spalten entspricht, die für die Aufzeichnungsinstanz identifiziert wurden. Für diesen Wert sind alle definierten Bits auf 1 festgelegt, wenn __$operation = 1 oder 2 ist. Wenn __$operation = 3 oder 4, werden nur die Bits auf 1 gesetzt, die geänderten Spalten entsprechen.
<erfasste Quelltabellenspalten>	Variiert	Bei den von der Funktion zurückgegebenen verbleibenden Spalten handelt es sich um die Spalten aus der Quelltabelle, die beim Erstellen der Aufzeichnungsinstanz als aufgezeichnete Spalten identifiziert wurden. Wenn in der Liste der aufgezeichneten Spalten keine Spalten angegeben wurden, werden alle Spalten in der Quelltabelle zurückgegeben.

Berechtigungen

Erfordert die Mitgliedschaft in der festen Serverrolle sysadmin oder in der festen Datenbankrolle db_owner. Für alle anderen Benutzer ist die SELECT-Berechtigung für alle aufgezeichneten Spalten in der Quelltabelle und, wenn eine Gatingrolle für die Aufzeichnungsinstanz definiert wurde, eine Mitgliedschaft in dieser Datenbankrolle erforderlich. Wenn der Aufrufer nicht über die Berechtigung zum Anzeigen der Quelldaten verfügt, gibt die Funktion eine Zeile mit NULL-Werten für alle Spalten zurück.

Bemerkungen

Änderungen am eindeutigen Bezeichner einer Zeile führen fn_cdc_get_net_changes dazu, dass stattdessen der anfängliche UPDATE-Befehl mit einem DELETE- und dann dem INSERT-Befehl angezeigt wird. Dieses Verhalten ist erforderlich, um den Schlüssel sowohl vor als auch nach der Änderung nachzuverfolgen.

Fehler 313 wird erwartet, wenn der angegebene LSN-Bereich beim Aufrufen cdc.fn_cdc_get_all_changes_<capture_instance> von oder cdc.fn_cdc_get_net_changes_<capture_instance>nicht geeignet ist. Wenn der lsn_value Parameter über die Zeit des niedrigsten LSN oder höchsten LSN hinaus liegt, wird die Ausführung dieser Funktionen im Fehler 313 zurückgegeben: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or function. Der Entwickler sollte sich um diesen Fehler kümmern. Beispiel für eine Problemumgehung finden Sie unter ReplTalk auf GitHub.

Beispiele

Im folgenden Beispiel wird die -Funktion cdc.fn_cdc_get_net_changes_HR_Department verwendet, um die Nettoänderungen zu melden, die in einem bestimmten Zeitintervall an der Quelltabelle HumanResources.Department vorgenommen wurden.

Zuerst wird die GETDATE-Funktion verwendet, um den Anfang des Zeitintervalls zu markieren. Nachdem mehrere DML-Anweisungen auf die Quelltabelle angewendet wurden, wird die GETDATE-Funktion erneut aufgerufen, um das Ende des Zeitintervalls zu identifizieren. Die Funktion sys.fn_cdc_map_time_to_lsn wird dann verwendet, um das Zeitintervall einem Änderungsdatenerfassungsabfragebereich zuzuordnen, der durch LSN-Werte begrenzt ist. Schließlich wird die cdc.fn_cdc_get_net_changes_HR_Department-Funktion abgefragt, um die Nettoänderungen an der Quelltabelle für das Zeitintervall zu erhalten. Beachten Sie, dass die eingefügte und anschließend gelöschte Zeile nicht in dem von der Funktion zurückgegebenen Resultset aufgeführt wird. Der Grund dafür ist, dass eine in einem Abfragefenster zuerst hinzugefügte und dann gelöschte Zeile keine Nettoänderung in der Quelltabelle für das Intervall erzeugt.

Hinweis

Bevor Sie dieses Beispiel ausführen, müssen Sie zuerst Beispiel B in sys.sp_cdc_enable_table (Transact-SQL) ausführen, um CDC für die Tabelle HumanResources.Departmentzu aktivieren. Im folgenden Beispiel ist HR_Department der Name des CDC-Erfassungs-instance, wie in sys.sp_cdc_enable_tableangegeben.

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');