cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)

Articolo
02/18/2014

Restituisce una riga delle modifiche totali per ogni riga di origine modificata all'interno dell'intervallo LSN specificato. Pertanto, quando a una riga di origine vengono apportate più modifiche durante l'intervallo LSN, la funzione restituisce una sola riga che riflette il contenuto finale della riga. Ad esempio, se una transazione inserisce una riga nella tabella di origine ed una transazione successiva all'interno dell'intervallo LSN aggiorna uno o più colonne di quella riga, la funzione restituisce solo una riga che include i valori della 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 utilizza 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 ulteriori informazioni, vedere sys.sp_cdc_enable_table (Transact-SQL).

Icona di collegamento a un argomento Convenzioni della 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 è di tipo binary(10).

Solo le righe presenti nella tabella delle modifiche cdc.[capture_instance]_CT con valore in __$start_lsn maggiore o uguale a from_lsn vengono incluse 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 è di tipo binary(10).

Solo le righe della tabella delle modifiche cdc.[capture_instance]_CT con un valore in __$start_lsn minore o uguale a from_lsn oppure uguale a to_lsn sono incluse 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:
- all
  Restituisce il valore 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 a NULL.
- all with mask
  Restituisce il valore 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 le colonne acquisite modificate nell'aggiornamento vengono contrassegnate nel valore restituito in __$update_mask.
- all with merge
  Restituisce il valore LSN della modifica finale alla riga nelle colonne di metadati __$start_lsn. La colonna __$operation avrà uno dei due valori seguenti: 1 per un'operazione di eliminazione e 5 per indicare che l'operazione necessaria per applicare la modifica è un inserimento o un aggiornamento. La colonna __$update_mask è sempre a 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 è molto interessante negli ambienti di destinazione dove è direttamente disponibile un'operazione di unione, ad esempio un ambiente SQL Server 2012.

Tabella restituita

Nome colonna	Tipo di dati	Descrizione
__$start_lsn	binary(10)	Valore LSN associato al commit della transazione per la modifica. Tutte le modifiche di cui è stato eseguito il commit nella stessa transazione condividono lo stesso valore LSN di commit. Ad esempio, se un'operazione di aggiornamento nella tabella di origine modifica due colonne in due righe, la tabella di modifica conterrà quattro righe, ognuna con lo stesso valore __$start_lsn.
__$operation	int	Identifica l'operazione DML (Data Manipulation Language) necessaria per applicare la riga di dati di modifica all'origine dati di destinazione. Se il valore del parametro row_filter_option è all o all with mask, il valore in questa colonna può essere uno dei seguenti: 1 = eliminazione 2 = inserimento 4 = aggiornamento Se il valore del parametro row_filter_option è all with merge,, il valore in questa colonna può essere uno dei seguenti: 1 = eliminazione
__$update_mask	varbinary(128)	Maschera di bit in cui a ogni colonna acquisita identificata per l'istanza di acquisizione corrisponde un bit. Tutti i bit definiti per questo valore sono impostati su 1 se __$operation = 1 o 2. Quando __$operation = 3 o 4, solo i bit che corrispondono a colonne che sono state modificate sono impostati su 1.
<captured source table columns>	variabile	Le colonne rimanenti restituite dalla funzione sono le colonne della tabella di origine identificate come colonne acquisite durante la creazione dell'istanza di acquisizione. Se nessuna colonna è stata specificata nell'elenco delle colonne acquisite, vengono restituite tutte le colonne nella tabella di origine.

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. Se il chiamante non dispone delle autorizzazioni per visualizzare i dati di origine, la funzione restituisce un errore 208 (Il nome di oggetto non è valido).

Osservazioni

Se l'intervallo LSN specificato è esterno alla cronologia di rilevamento delle modifiche per l'istanza di acquisizione, la funzione restituisce un errore 208, in cui è indicato che il nome di oggetto non è valido.

Esempi

Nell'esempio seguente viene utilizzata la funzione cdc.fn_cdc_get_net_changes_HR_Department per segnalare tutte le modifiche apportate alla tabella di origine HumanResources.Department 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. Viene quindi utilizzata la funzione sys.fn_cdc_map_time_to_lsn per eseguire il mapping dell'intervallo di tempo a un intervallo di query di acquisizione di dati limitato da 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. Prima di eseguire questo esempio, è innanzitutto necessario eseguire l'esempio B in sys.sp_cdc_enable_table (Transact-SQL).

USE AdventureWorks2012;
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 = GETDATE() -1;
-- 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 @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');