cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)

Si applica a: SQL Server

Restituisce una riga di modifica netta per ogni riga di origine modificata nell'intervallo LSN (Log Sequence Numbers) specificato.

Aspetta, che cos'è un LSN? Ogni record nel log delle transazioni di SQL Server viene identificato in modo univoco da un numero di sequenza di log (LSN). I LSN vengono ordinati in modo che, se LSN2 è maggiore di LSN1, la modifica descritta dal record di log a cui fa riferimento LSN2 si è verificata dopo la modifica descritta dal record di log LSN.

LSN di un record di log in cui si è verificato un evento significativo può essere utile per costruire sequenze di ripristino corrette. Poiché i nomi LSN sono ordinati, è possibile confrontarli per verificarne l'uguaglianza e la disuguaglianza, ovvero , <, >=, <=, >=. Questi confronti sono utili nella creazione di sequenze di ripristino.

Quando una riga di origine presenta più modifiche durante l'intervallo LSN, una singola riga che riflette il contenuto finale della riga viene restituita dalla funzione di enumerazione descritta di seguito. Ad esempio, se una transazione inserisce una riga nella tabella di origine e una transazione successiva all'interno dell'intervallo LSN aggiorna una o più colonne in tale riga, la funzione restituisce una sola riga, che include i valori di colonna aggiornati.

Questa funzione di enumerazione viene creata nel momento in cui una tabella di origine è abilitata per l'acquisizione dei dati delle modifiche e quando viene specificato il rilevamento delle modifiche nette. Per abilitare il rilevamento delle modifiche nette, è necessario che la tabella di origine disponga di una chiave primaria o un indice univoco. Il nome della funzione è derivato e usa il formato cdc.fn_cdc_get_net_changes_<capture_instance>, dove <capture_instance> è il valore specificato per l'istanza di acquisizione quando la tabella di origine è stata abilitata per Change Data Capture. Per altre informazioni, vedere sys.sp_cdc_enable_table (Transact-SQL).

Convenzioni relative alla sintassi Transact-SQL

Sintassi

  
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  
}  

Argomenti

from_lsn

Il numero LSN che rappresenta l'endpoint inferiore dell'intervallo LSN da includere nel set di risultati. from_lsn è binary(10).

Solo le righe in cdc.[ capture_instance]_CT tabella delle modifiche con un valore in __$start_lsn maggiore o uguale a from_lsn sono inclusi nel set di risultati.

to_lsn

Il numero LSN che rappresenta l'endpoint superiore dell'intervallo LSN da includere nel set di risultati. to_lsn è binary(10).to_lsn is binary(10).

Solo le righe in cdc.[ capture_instance]_CT tabella delle modifiche con un valore in __$start_lsn minore o uguale a from_lsn o uguale a to_lsn sono inclusi nel set di risultati.

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

Opzione applicata al contenuto delle colonne dei metadati e alle righe restituite nel set di risultati. Le opzioni possibili sono le seguenti:

tutto
Restituisce l'LSN della modifica finale alla riga e l'operazione necessaria per applicare la riga nelle colonne di metadati __$start_lsn e __$operation. La colonna __$update_mask è sempre NULL.

all with mask
Restituisce l'LSN della modifica finale alla riga e l'operazione necessaria per applicare la riga nelle colonne di metadati __$start_lsn e __$operation. Inoltre, quando un'operazione di aggiornamento restituisce (__$operation = 4) le colonne acquisite modificate nell'aggiornamento vengono contrassegnate nel valore restituito in __$update_mask.

all with merge
Restituisce il numero LSN della modifica finale alla riga nelle colonne metadati __$start_lsn. La colonna __$operation sarà uno dei due valori seguenti: 1 per delete e 5 per indicare che l'operazione necessaria per applicare la modifica è un inserimento o un aggiornamento. La colonna __$update_mask è sempre NULL.

La logica necessaria a determinare l'operazione precisa per una determinata modifica aggiunge maggiore complessità alla query, pertanto questa opzione è progettata per migliorare le prestazioni di esecuzione delle query quando è sufficiente indicare che l'operazione necessaria ad applicare i dati di modifica è un inserimento o un aggiornamento, ma non è necessario distinguere in modo esplicito tra i due. Questa opzione è più interessante negli ambienti di destinazione in cui un'operazione di unione è disponibile direttamente.

Tabella restituita

Autorizzazioni

È richiesta l'appartenenza al ruolo predefinito del server sysadmin o al ruolo predefinito del database db_owner. Per tutti gli altri utenti, è richiesta l'autorizzazione SELECT su tutte le colonne acquisite nella tabella di origine e, se è stato definito un ruolo di controllo per l'istanza di acquisizione, l'appartenenza a tale ruolo del database. Quando il chiamante non dispone dell'autorizzazione per visualizzare i dati di origine, la funzione restituisce una riga con valori NULL per tutte le colonne.

Osservazioni:

Le modifiche apportate all'identificatore univoco di una riga causeranno fn_cdc_get_net_changes la visualizzazione del comando UPDATE iniziale con un comando DELETE e quindi un comando INSERT. Questo comportamento è necessario per tenere traccia della chiave prima e dopo la modifica.

L'errore 313 è previsto se l'intervallo LSN specificato non è appropriato quando si chiama cdc.fn_cdc_get_all_changes_<capture_instance> o cdc.fn_cdc_get_net_changes_<capture_instance>. Se il lsn_value parametro supera il tempo di LSN minimo o LSN più alto, l'esecuzione di queste funzioni restituirà l'errore 313: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or function. Questo errore deve essere gestito dallo sviluppatore.

Esempi

Nell'esempio seguente viene usata la funzione cdc.fn_cdc_get_net_changes_HR_Department per segnalare le modifiche nette apportate alla tabella HumanResources.Department di origine durante un intervallo di tempo specifico.

Innanzitutto, per contrassegnare l'inizio dell'intervallo di tempo viene utilizzata la funzione GETDATE. Dopo l'applicazione delle istruzioni DML alla tabella di origine, la funzione GETDATE viene chiamata nuovamente per identificare la fine dell'intervallo di tempo. La funzione sys.fn_cdc_map_time_to_lsn viene quindi usata per eseguire il mapping dell'intervallo di tempo a un intervallo di query change data capture delimitato dai valori LSN. Infine, la funzione cdc.fn_cdc_get_net_changes_HR_Department viene eseguita per ottenere tutte le modifiche alla tabella di origine per l'intervallo di tempo. La riga inserita ed eliminata non viene visualizzata nel set dei risultati restituito dalla funzione. Ciò avviene perché una riga aggiunta ed eliminata all'interno di una finestra di query non produce modifiche totali sulla tabella di origine per l'intervallo.

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

Vedi anche

• <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)
• Informazioni su Change Data Capture (SQL Server)