Utilizzare i dati delle modifiche (SQL Server)Work with Change Data (SQL Server)

I dati delle modifiche vengono resi disponibili ai consumer della funzionalità Change Data Capture tramite funzioni con valori di tabella.Change data is made available to change data capture consumers through table-valued functions (TVFs). Per tutte le query di queste funzioni sono necessari due parametri che definiscono l'intervallo di numeri di sequenza del file di log (LSN) idonei durante lo sviluppo del set di risultati restituito.All queries of these functions require two parameters to define the range of Log Sequence Numbers (LSNs) that are eligible for consideration when developing the returned result set. Entrambi i valori LSN che rappresentano il limite inferiore e quello superiore dell'intervallo sono inclusi nell'intervallo stesso.Both the upper and lower LSN values that bound the interval are considered to be included within the interval.

Per stabilire i valori LSN appropriati da utilizzare per l'esecuzione di query su una funzione con valori di tabella, sono disponibili numerose funzioni.Several functions are provided to help determine appropriate LSN values for use in querying a TVF. La funzione sys.fn_cdc_get_min_lsn restituisce il valore LSN meno elevato associato a un intervallo di validità di un'istanza di acquisizione,The function sys.fn_cdc_get_min_lsn returns the smallest LSN that is associated with a capture instance validity interval. ovvero all'intervallo di tempo durante il quale i dati delle modifiche rimangono disponibili per le relative istanze di acquisizione.The validity interval is the time interval for which change data is currently available for its capture instances. La funzione sys.fn_cdc_get_max_lsn restituisce il valore LSN più elevato nell'intervallo di validità.The function sys.fn_cdc_get_max_lsn returns the largest LSN in the validity interval. Le funzioni sys.fn_cdc_map_time_to_lsn e sys.fn_cdc_map_lsn_to_time possono essere usate per includere i valori LSN in una cronologia convenzionale.The functions sys.fn_cdc_map_time_to_lsn and sys.fn_cdc_map_lsn_to_time are available to help place LSN values on a conventional timeline. Poiché in Change Data Capture vengono utilizzati intervalli di query chiusi, talvolta risulta necessario generare il valore LSN successivo in una sequenza per garantire che le modifiche non vengano duplicate in finestre di query consecutive.Because change data capture uses closed query intervals, it is sometimes necessary to generate the next LSN value in a sequence to ensure that changes are not duplicated in consecutive query windows. Le funzioni sys.fn_cdc_increment_lsn e sys.fn_cdc_decrement_lsn sono utili quando è necessario modificare in modo incrementale un valore LSN.The functions sys.fn_cdc_increment_lsn and sys.fn_cdc_decrement_lsn are useful when an incremental adjustment to an LSN value is required.

Convalida dei limiti LSN Validating LSN Boundaries

È consigliabile convalidare i limiti LSN da utilizzare in una query con funzione con valori di tabella prima dell'utilizzo.We recommend validating the LSN boundaries that are to be used in a TVF query before their use. Endpoint con valore Null oppure endpoint esterni all'intervallo di validità per un'istanza di acquisizione provocheranno la restituzione di un errore da parte di una funzione con valori di tabella relativa a Change Data Capture.Null endpoints or endpoints that lie outside the validity interval for a capture instance will force an error to be returned by a change data capture TVF.

L'errore seguente viene ad esempio restituito per una query per tutte le modifiche quando un parametro utilizzato per definire l'intervallo di query non è valido, non è compreso nell'intervallo oppure l'opzione del filtro di riga non è valida.For example, the following error is returned for a query for all changes when a parameter that is used to define the query interval is not valid, or is out of range, or the row filter option is invalid.

Msg 313, Level 16, State 3, Line 1

An insufficient number of arguments were supplied for the procedure or function cdc.fn_cdc_get_all_changes_ ...

L'errore corrispondente restituito per una query net changes è il seguente:The corresponding error returned for a net changes query is the following:

Msg 313, Level 16, State 3, Line 1

An insufficient number of arguments were supplied for the procedure or function cdc.fn_cdc_get_net_changes_ ...

Nota

È noto che il messaggio 313 è fuorviante e non indica la causa effettiva dell'errore.It is recognized that the message for Msg 313 is misleading and does not convey the actual cause of the failure. Questo utilizzo non opportuno del messaggio deriva dall'impossibilità di generare un errore esplicito dall'interno di una funzione con valori di tabella.This awkward usage stems from the inability to raise an explicit error from within a TVF. Si è tuttavia ritenuto preferibile restituire un errore riconoscibile, sebbene inaccurato, rispetto a non restituire alcun risultato.Nevertheless, the value of returning a recognizable, if inaccurate, error was deemed preferable to simply returning an empty result. Un set di risultati vuoto non sarebbe infatti distinguibile da una query valida che non restituisce alcuna modifica.An empty result set would not be distinguishable from a valid query returning no changes.

Quando viene eseguita una query per tutte le modifiche, gli errori di autorizzazione negata restituiranno altri errori, come illustrato di seguito:Authorization failures will return failures when querying for all changes, as shown:

Msg 229, Level 14, State 5, Line 1

The SELECT permission was denied on the object 'fn_cdc_get_all_changes_...', database 'MyDB', schema 'cdc'.

Lo stesso messaggio è valido in caso di esecuzione di una query per le modifiche totali:The same is true when querying for net changes:

Msg 229, Level 14, State 5, Line 1

The SELECT permission was denied on the object fn_cdc_get_net_changes_...', database 'MyDB', schema 'cdc'.

Vedere il modello Enumerate Net Changes Using TRY CATCH per una dimostrazione di come vengono intercettati questi errori noti relativi alle funzioni con valori di tabella e come vengono restituite informazioni più significative relative all'errore.See the template Enumerate Net Changes Using TRY CATCH for a demonstration of how to intercept these known TVF errors and return more meaningful information about the failure.

Nota

Per trovare i modelli di Change Data Capture in SQL Server Management Studio, scegliere Esplora modelli dal menu Visualizza, espandere Modelli di SQL Server , quindi espandere la cartella Change Data Capture .To locate change data capture templates in SQL Server Management Studio, on the View menu, click Template Explorer, expand SQL Server Templates and then expand the Change Data Capture folder.

Funzioni di query Query Functions

A seconda delle caratteristiche della tabella di origine per cui viene eseguito il rilevamento delle modifiche e del modo in cui la relativa istanza di acquisizione viene configurata, vengono generate una o due funzioni con valori di tabella per l'esecuzione di query sui dati delle modifiche.Depending on the characteristics of the source table being tracked and the way in which its capture instance is configured, either one or two TVFs for querying change data are generated.

  • La funzione cdc.fn_cdc_get_all_changes_ restituisce tutte le modifiche che si sono verificate per l'intervallo specificato.The function cdc.fn_cdc_get_all_changes_ returns all changes that occurred for the specified interval. Questa funzione viene sempre generata.This function is always generated. Le voci vengono restituite sempre in modo ordinato, prima in base al valore LSN del commit della transazione e successivamente in base a un valore che ordina in sequenza la modifica all'interno della transazione.Entries are always returned sorted, first by the transaction commit LSN of the change, and then by a value that sequences the change within its transaction. A seconda dell'opzione del filtro di riga scelta, un aggiornamento può comportare la restituzione della riga finale (opzione del filtro di riga "all") o dei valori nuovi e precedenti (opzione del filtro di riga "all update old").Depending on the row filter option chosen, either the final row is returned on update (row filter option "all") or both the new and old values are returned on update (row filter option "all update old"').

  • La funzione cdc.fn_cdc_get_net_changes_ viene generata quando il parametro @supports_net_changes è impostato su 1 e la tabella di origine è abilitata.The function cdc.fn_cdc_get_net_changes_ is generated when the parameter @supports_net_changes is set to 1 when the source table is enabled.

    Nota

    Questa opzione è supportata solo se la tabella di origine contiene una chiave primaria definita o se il parametro @index_name è stato usato per identificare un indice univoco.This option is only supported if the source table has a defined primary key or if the parameter @index_name has been used to identify a unique index.

    La funzione netchanges restituisce una modifica per ogni riga della tabella di origine modificata.The netchanges function returns one change per modified source table row. Se durante l'intervallo specificato viene registrata più di una modifica relativa alla riga, i valori della colonna rifletteranno i contenuti finali della riga.If more than one change is logged for the row during the specified interval, the column values will reflect the final contents of the row. Per identificare correttamente l'operazione necessaria all'aggiornamento dell'ambiente di destinazione, è necessario che nella funzione con valori di tabella vengano considerate sia l'operazione iniziale sulla riga durante l'intervallo sia l'operazione finale sulla riga stessa.To correctly identify the operation that is necessary to update the target environment, the TVF must consider both the initial operation on the row during the interval and the final operation on the row. Quando viene specificata l'opzione del filtro di riga 'all', le operazioni restituite da una query net changes vengono inserite, eliminate o aggiornate con valori nuovi.When the row filter option 'all' is specified, the operations that are returned by a net changes query will either be insert, delete, or update (new values). Questa opzione restituisce sempre un valore Null per la maschera di aggiornamento perché al calcolo di una maschera di aggregazione è associato un costo.This option always returns the update mask as null because there is a cost associated with computing an aggregate mask. Se è necessaria una maschera di aggregazione che rifletta tutte le modifiche apportate a una riga, utilizzare l'opzione 'all with mask'.If you require an aggregate mask that reflects all changes to a row, use the 'all with mask' option. Se l'elaborazione a valle non richiede la distinzione tra operazioni di inserimento e di aggiornamento, utilizzare l'opzione 'all with merge'.If downstream processing does not require inserts and updates to be distinguished, use the 'all with merge' option. In questo caso, il valore dell'operazione accetterà solo due valori, 1 per l'eliminazione e 5 per un'operazione che potrebbe essere un inserimento o un aggiornamento.In this case, the operation value will only take on two values: 1 for delete and 5 for an operation that could be either an insert or an update. Questa opzione elimina le operazioni di elaborazione aggiuntive necessarie per determinare se l'operazione derivata deve essere un inserimento o un aggiornamento e può migliorare le prestazioni della query quando questa differenziazione non è necessaria.This option eliminates the additional processing needed to determine whether the derived operation should be an insert or an update, and can improve the performance of the query when this differentiation is not necessary.

    La maschera di aggiornamento restituita da una funzione della query è una rappresentazione compatta che identifica tutte le colonne modificate in una riga di dati delle modifiche.The update mask that is returned from a query function is a compact representation that identifies all columns that changed in a row of change data. Generalmente, queste informazioni sono necessarie solo per un subset delle colonne acquisite di dimensioni ridotte.Typically, this information is only required for a small subset of the captured columns. Le funzioni sono disponibili per consentire l'estrazione delle informazioni dalla maschera in una forma utilizzabile dalle applicazioni in modo più diretto.Functions are available to assist in extracting information from the mask in a form that is more directly usable by applications. La funzione sys.fn_cdc_get_column_ordinal restituisce la posizione ordinale di una colonna denominata per una determinata istanza di acquisizione, mentre la funzione sys.fn_cdc_is_bit_set restituisce la parità del bit nella maschera fornita in base al numero ordinale passato nella chiamata alla funzione.The function sys.fn_cdc_get_column_ordinal returns the ordinal position of a named column for a given capture instance, whereas the function sys.fn_cdc_is_bit_set returns the parity of the bit in the provided mask based on the ordinal that was passed in the function call. Se utilizzate insieme, queste due funzioni consentono l'estrazione e la restituzione efficienti delle informazioni dalla maschera di aggiornamento con la richiesta dei dati delle modifiche.Together, these two functions allow information from the update mask to be efficiently extracted and returned with the request for change data. Vedere il modello Enumerate Net Changes Using All With Mask per una dimostrazione di come utilizzare queste funzioni.See the template Enumerate Net Changes Using All With Mask for a demonstration of how these functions are used.

Scenari di funzioni di query Query Function Scenarios

Nelle sezioni seguenti vengono descritti scenari comuni per l'esecuzione di query sui dati di Change Data Capture tramite le funzioni di query cdc.fn_cdc_get_all_changes_ e cdc.fn_cdc_get_net_changes_.The following sections describe common scenarios for querying change data capture data by using the query functions cdc.fn_cdc_get_all_changes_ and cdc.fn_cdc_get_net_changes_.

Esecuzione di query per tutte le modifiche comprese nell'intervallo di validità dell'istanza di acquisizioneQuerying for All Changes Within the Capture Instance Validity Interval

La richiesta più diretta di dati delle modifiche consiste nella restituzione di tutti i dati delle modifiche correnti compresi nell'intervallo di validità di un'istanza di acquisizione.The most straightforward request for change data is one that returns all of the current change data in a capture instance’s validity interval. Per eseguire questa richiesta, determinare innanzitutto i limiti LSN superiore e inferiore dell'intervallo di validità.To make this request, first determine the lower and upper LSN boundaries of the validity interval. Usare quindi questi valori per identificare i parametri @from_lsn e@to_lsn passati alla funzione di query cdc.fn_cdc_get_all_changes_ o cdc.fn_cdc_get_net_changes_.Then, use these values to identify the parameters @from_lsn and @to_lsn passed to the query function cdc.fn_cdc_get_all_changes_ or cdc.fn_cdc_get_net_changes_. Usare la funzione sys.fn_cdc_get_min_lsn per ottenere il limite inferiore e sys.fn_cdc_get_max_lsn per ottenere il limite superiore.Use the function sys.fn_cdc_get_min_lsn to obtain the lower bound, and sys.fn_cdc_get_max_lsn to obtain the upper bound. Vedere il modello Enumerate All Changes for the Valid Range affinché nel codice di esempio venga eseguita una query per tutte le modifiche valide correnti tramite la funzione di query cdc.fn_cdc_get_all_changes_.See the template Enumerate All Changes for the Valid Range for sample code to query for all current valid changes by using the query function cdc.fn_cdc_get_all_changes_. Vedere il modello Enumerate Net Changes for the Valid Range per un esempio simile relativo all'utilizzo della funzione cdc.fn_cdc_get_net_changes_.See the template Enumerate Net Changes for the Valid Range for a similar example of using the function cdc.fn_cdc_get_net_changes_.

Esecuzione di query per tutte le nuove modifiche successive all'ultimo set di modificheQuerying for All New Changes Since the Last Set of Changes

Per applicazioni tipiche, il processo di esecuzione di query per i dati delle modifiche è continuo, con richieste periodiche di tutte le modifiche apportate dopo l'ultima richiesta.For typical applications, querying for change data will be an ongoing process, making periodic requests for all of the changes that occurred since the last request. Per query di questo tipo, è possibile usare la funzione sys.fn_cdc_increment_lsn per dedurre il limite inferiore della query corrente dal limite superiore della query precedente.For such queries, you can use the function sys.fn_cdc_increment_lsn to derive the lower bound of the current query from the upper bound of the previous query. Tramite questo metodo è possibile garantire che nessuna riga venga ripetuta perché l'intervallo di query viene sempre considerato come un intervallo chiuso dove entrambi gli endpoint sono inclusi nell'intervallo.This method ensures that no rows are repeated because the query interval is always treated as a closed interval where both end-points are included in the interval. Usare la funzione sys.fn_cdc_get_max_lsn per ottenere l'endpoint alto per il nuovo intervallo della richiesta.Then, use the function sys.fn_cdc_get_max_lsn to obtain the high end-point for the new request interval. Vedere il modello Enumerate All Changes Since Previous Request affinché nel codice di esempio la finestra Query venga spostata sistematicamente per ottenere tutte le modifiche apportate dopo l'ultima richiesta.See the template Enumerate All Changes Since Previous Request for sample code to systematically move the query window to obtain all changes since the last request.

Esecuzione di query per tutte le nuove modifiche apportate finoraQuerying for all New Changes Up Until Now

Un vincolo tipico posto sulle modifiche restituite da una funzione di query consiste nella necessità di dover includere solo le modifiche che si sono verificate tra la richiesta precedente e la data e l'ora correnti.A typical constraint that is placed on the changes returned by a query function is to include only the changes that occurred between the previous request until the current date and time. Per questa query, applicare la funzione sys.fn_cdc_increment_lsn al valore @from_lsn usato nella richiesta precedente per determinare il limite inferiore.For this query, apply the function sys.fn_cdc_increment_lsn to the @from_lsn value that was used in the previous request to determine the lower bound. Poiché il limite superiore dell'intervallo di tempo viene espresso come momento specifico nel tempo, è necessario convertirlo in un valore LSN prima che possa essere utilizzato da una funzione di query.Because the upper bound on the time interval is expressed as a specific point in time, it must be converted to an LSN value before it can be used by a query function. Prima di poter convertire il valore datetime in un valore LSN corrispondente, è necessario assicurarsi che il processo di acquisizione abbia elaborato tutte le modifiche di cui è stato eseguito il commit attraverso il limite superiore specificato.Before the datetime value can be converted to a corresponding LSN value, you must ensure that the capture process has processed all changes that were committed through the specified upper bound. Solo così è possibile assicurarsi che tutte le modifiche valide siano state propagate alla tabella delle modifiche.This is required to ensure that all the qualifying changes have been propagated to the change table. Un modo possibile per eseguire questa operazione consiste nel strutturare un ciclo di attesa che controlli periodicamente se il valore LSN di commit massimo corrente registrato per qualsiasi tabella delle modifiche del database supera l'ora di fine desiderata dell'intervallo della richiesta.One way to do this is to structure a wait loop that periodically checks to see if the current maximum commit lsn recorded for any database change table exceeds the desired end time of the request interval.

Dopo che il ciclo di ritardo verifica se il processo di acquisizione abbia già elaborato tutte le voci di log rilevanti, usare la funzione sys.fn_cdc_map_time_to_lsn per determinare il nuovo endpoint alto espresso come un valore LSN.After the delay loop verifies that the capture process has already processed all the relevant log entries, use the function sys.fn_cdc_map_time_to_lsn to determine the new high end-point expressed as an LSN value. Per assicurarsi che tutte le voci di cui è stato eseguito il commit nel periodo di tempo specificato siano state recuperate, chiamare la funzione sys.fn_cdc_map_time_to_lsn e utilizzare l'opzione 'largest less than or equal'.To ensure that all entries that were committed through the specified time are retrieved, call the function sys.fn_cdc_map_time_to_lsn, and use the option 'largest less than or equal'.

Nota

In periodi di inattività, viene aggiunta una voce fittizia alla tabella cdc.lsn_time_mapping per contrassegnare il fatto che il processo di acquisizione ha elaborato le modifiche entro un periodo di commit specificato.In periods of inactivity, a dummy entry is added to the table cdc.lsn_time_mapping to mark the fact that the capture process has processed the changes up to a given commit time. Ciò evita che il processo sembri in ritardo con l'acquisizione, quando invece semplicemente non esistono modifiche recenti da elaborare.This prevents it from appearing that the capture process has fallen behind when there are simply no recent changes to process.

Il modello Enumerate All Changes Up Until Now è una dimostrazione di come utilizzare la strategia precedente per eseguire query per i dati delle modifiche.The template Enumerate All Changes Up Until Now demonstrates how to use the previous strategy to query for change data.

Aggiunta di un'ora di commit a un set di risultati di tutte le modificheAdding a Commit Time to an All Changes Result Set

L'ora di commit di ogni transazione con una voce associata in una tabella delle modifiche del database è disponibile nella tabella cdc.lsn_time_mapping.The commit time of each transaction with an associated entry in a database change table is available in the table cdc.lsn_time_mapping. Unendo in join il valore $start_lsn restituito in una richiesta di tutte le modifiche al valore start_lsn di una voce della tabella cdc.lsn_time_mapping, è possibile restituire il valore tran_end_time insieme ai dati delle modifiche per contrassegnare la modifica con l'ora di commit della transazione all'origine.By joining the $start_lsn value returned in a request for all changes with the start_lsn value of a cdc.lsn_time_mapping table entry, you can return the tran_end_time along with the change data to stamp the change with the commit time of the transaction at the source. Il modello Append Commit Time to All Changes Result Set è una dimostrazione di come eseguire questo join.The template Append Commit Time to All Changes Result Set demonstrates how to perform this join.

Join dei dati delle modifiche con altri dati della stessa transazioneJoining Change Data with Other Data from the Same Transaction

È talvolta utile creare un join dei dati delle modifiche con altre informazioni raccolte sulla transazione quando il relativo commit viene eseguito all'origine.Occasionally, it is useful to join change data with other information gathered about the transaction when it committed at the source. Nella colonna tran_begin_lsn della tabella cdc.lsn_time_mapping sono contenute le informazioni necessarie per eseguire questo join.The tran_begin_lsn column in the table cdc.lsn_time_mapping provides the information needed to perform such a join. Quando si verifica l'aggiornamento dell'origine, il valore di database_transaction_begin_lsn della vista dinamica del sistema sys.dm_tran_database_transactions deve essere salvato insieme a qualsiasi altra informazione da unire con i dati delle modifiche.When the update of the source occurs, the value for database_transaction_begin_lsn from the system dynamic view sys.dm_tran_database_transactions must be saved along with any other information to be joined with the change data. Utilizzare la funzione fn_convertnumericlsntobinary per confrontare i valori database_transaction_begin_lsn e tran_begin_lsn.Use the function fn_convertnumericlsntobinary to compare the database_transaction_begin_lsn and tran_begin_lsn values. Il codice per creare questa funzione è disponibile nel modello Create Function fn_convertnumericlsntobinary.The code to create this function is available in the template Create Function fn_convertnumericlsntobinary. Il modello Return All Changes with a Given tran_begin_lsn è una dimostrazione di come attuare il join.The template Return All Changes with a Given tran_begin_lsn demonstrates how to effect the join.

Esecuzione di query utilizzando le funzioni del wrapper datetimeQuerying Using Datetime Wrapper Functions

Un tipico scenario dell'applicazione relativo all'esecuzione di query per i dati delle modifiche consiste nel richiedere periodicamente i dati delle modifiche tramite una finestra temporale scorrevole delimitata da valori datetime.A typical application scenario for querying for change data is to periodically request change data by using a sliding window bounded by datetime values. Per questa classe di consumer, Change Data Capture fornisce la stored procedure sys.sp_cdc_generate_wrapper_function che consente di generare script per creare funzioni wrapper personalizzate per le funzioni di query di Change Data Capture.For this class of consumers, change data capture provides the stored procedure sys.sp_cdc_generate_wrapper_function that generates scripts to create custom wrapper functions for the change data capture query functions. Questi wrapper personalizzati consentono di esprimere l'intervallo di query come coppia datetime.These custom wrappers allow the query interval to be expressed as a datetime pair.

Le opzioni di chiamata per la stored procedure consentono di generare wrapper per tutte le istanze di acquisizione a cui può accedere il chiamante o per una sola istanza di acquisizione specificata.Calling options for the stored procedure allow for wrappers to be generated for all capture instances that the caller has access to, or only a specified capture instance. Le opzioni supportate includono inoltre la possibilità di specificare se l'endpoint alto dell'intervallo di acquisizione deve essere aperto o chiuso, quale colonna acquisita disponibile deve essere inclusa nel set di risultati e a quali colonne incluse è necessario associare flag di aggiornamento.Supported options also include the ability to specify whether the high end-point of the capture interval should be open or closed, which of the available captured columns should be included in the result set and which of the included columns should have associated update flags. La procedura restituisce un set di risultati con due colonne: il nome della funzione generata, derivabile dal nome dell'istanza di acquisizione, e l'istruzione CREATE per la stored procedure del wrapper.The procedure returns a result set with two columns: the generated function name, which is derivable from the capture instance name, and the create statement for the wrapper stored procedure. La funzione per eseguire il wrapping della query di tutte le modifiche viene sempre generata.The function to wrap the all changes query is always generated. Se il parametro @supports_net_changes è stato impostato in fase di creazione dell'istanza di acquisizione, viene anche generata la funzione di wrapping della query per le modifiche delta.If the @supports_net_changes parameter was set when the capture instance was created, the function to wrap the net changes function is also generated.

È responsabilità del progettista dell'applicazione chiamare la stored procedure per la generazione dello script per generare le istruzioni CREATE per le stored procedure del wrapper ed eseguire gli script di creazione risultanti per creare le funzioni.It is the responsibility of the application designer to call the script generation stored procedure to generate the create statements for the wrapper stored procedures, and to execute the resulting create scripts to create the functions. Questo processo non viene eseguito automaticamente alla creazione di un'istanza di acquisizione.This does not occur automatically when a capture instance is created.

I wrapper datetime sono di proprietà dell'utente e non vengono creati nello schema predefinito del chiamante.Datetime wrappers are owned by the user, and not are created in the default schema of the caller. La funzione generata è utilizzabile dalla maggior parte degli utenti senza necessità di apportare modifiche.The generated function is suitable without modification for most users. Lo script generato può comunque essere ulteriormente personalizzato prima di creare la funzione.However, further customization can always be applied to the generated script prior to creating the function.

Il nome della funzione di wrapping della query per tutte le modifiche è fn_all_changes_ seguito dal nome dell'istanza di acquisizione.The name of the function to wrap the all changes query is fn_all_changes_ followed by the capture instance name. Il prefisso utilizzato per il wrapper delle modifiche delta è fn_net_changes_.The prefix that is used for the net changes wrapper is fn_net_changes_. Entrambe le funzioni accettano tre argomenti, proprio come le funzioni con valori di tabella di Change Data Capture associate.Both functions take three arguments, just as their associated change data capture TVFs do. Tuttavia, l'intervallo di query per i wrapper è limitato da due valori datetime e non da due valori LSN.However, the query interval for the wrappers is bounded by two datetime values instead of than by two LSN values. Il parametro @row_filter_option è identico per entrambi i set di funzioni.The @row_filter_option parameter for both sets of functions are the same.

Le funzioni wrapper generate supportano la convenzione seguente per l'esame sistematico della cronologia di Change Data Capture: si prevede che il parametro @end_time dell'intervallo precedente venga usato come parametro @start_time dell'intervallo successivo.The generated wrapper functions support the following convention for systematically walking the change data capture timeline: It is expected that the @end_time parameter of the previous interval be used as the @start_time parameter of the subsequent interval. La funzione wrapper esegue il mapping dei valori datetime ai valori LSN e si assicura che nessun dato venga perso o ripetuto se viene seguita questa convenzione.The wrapper function takes care of mapping the datetime values to LSN values and ensuring that no data is lost or repeated if this convention is followed.

È possibile generare i wrapper affinché supportino un limite superiore chiuso o un limite superiore aperto nella finestra di query specificata.The wrappers can be generated to support either a closed upper bound or an open upper bound on the specified query window. Il chiamante può quindi specificare se le voci con un'ora di commit corrispondente al limite superiore dell'intervallo di estrazione debbano essere incluse nell'intervallo.That is, the caller can specify whether entries having a commit time equal to the upper bound of the extraction interval are to be included within the interval. Per impostazione predefinita, il limite superiore è incluso.By default, the upper bound is included.

Se le funzioni con valori di tabella della query generata hanno esito negativo nel caso in cui venga fornito un valore Null per @from_lsn o @to_lsn, le funzioni del wrapper datetime usano Null per consentire ai wrapper datetime di restituire tutte le modifiche correnti.While the generated query TVFs fail if supplied a null value for either the @from_lsn value or the @to_lsn value, the datetime wrapper functions use null to allow the datetime wrappers to return all current changes. Se Null viene passato come endpoint basso della finestra di query al wrapper datetime, l'endpoint basso dell'intervallo di validità dell'istanza di acquisizione viene utilizzato nell'istruzione SELECT sottostante applicata alla funzione con valori di tabella della query.That is, if null is passed as the low end-point of the query window to the datetime wrapper, the low end point of the capture instance validity interval is used in the underlying SELECT statement that is applied to the query TVF. Analogamente, se Null viene passato come endpoint alto della finestra di query, l'endpoint alto dell'intervallo di validità dell'istanza di acquisizione viene utilizzato per la selezione eseguita dalla funzione con valori di tabella della query.Similarly, if null is passed as the high end-point of the query window, the high end-point of the capture instance validity interval is used when selecting from the query TVF.

Il set di risultati restituito da una funzione wrapper include tutte le colonne richieste seguite da una colonna dell'operazione, registrata come uno o due caratteri per identificare l'operazione associata alla riga.The result set returned by a wrapper function includes all the requested columns followed by an operation column, recoded as one or two characters to identify the operation that is associated with the row. Se sono stati richiesti flag di aggiornamento, vengono visualizzati come colonne bit dopo il codice dell'operazione, nell'ordine specificato nel parametro @update_flag_list.</span><span class="sxs-lookup">If update flags have been requested, they appear as bit columns after the operation code, in the order specified in the @update_flag_list parameter. Per informazioni sulle opzioni di chiamata per la personalizzazione dei wrapper datetime generati, vedere sys.sp_cdc_generate_wrapper_function (Transact-SQL).For information about the calling options for customizing the generated datetime wrappers, see sys.sp_cdc_generate_wrapper_function (Transact-SQL).

Il modello Instantiate a Wrapper TVF With Update Flag è una dimostrazione di come personalizzare una funzione wrapper generata per aggiungere un flag di aggiornamento per una colonna specificata al set di risultati restituito da una query delle modifiche delta.The template Instantiate a Wrapper TVF With Update Flag shows how to customize a generated wrapper function to append an update flag for a specified column to the result set returned by a net changes query. Il modello Instantiate CDC Wrapper TVFs for a Schema è una dimostrazione di come creare un'istanza dei wrapper datetime per le funzioni con valori di tabella delle query per tutte le istanze di acquisizione create per le tabelle di origine in un determinato schema del database.The template Instantiate CDC Wrapper TVFs for a Schema shows how to instantiate the Datetime Wrappers for the Query TVFs for all of the capture instances created for the source tables in a given database schema.

Per un esempio di utilizzo di un wrapper datetime per eseguire una query per i dati delle modifiche, vedere il modello Get Net Changes Using Wrapper With Update Flags.For an example that uses a datetime wrapper to query for change data, see the template Get Net Changes Using Wrapper With Update Flags. Questo modello è una dimostrazione di come eseguire query per le modifiche delta con una funzione wrapper quando il wrapper è configurato per la restituzione di flag di aggiornamento.This template demonstrates how to query for net changes with a wrapper function when the wrapper is configured to return update flags. Si noti che l'opzione del filtro di riga 'all with mask' è necessaria affinché la funzione di query sottostante restituisca una maschera di aggiornamento non Null all'aggiornamento.Note that the row filter option 'all with mask' is required for the underlying query function to return a non-null update mask on update. I valori Null vengono passati per i limiti inferiore e superiore dell'intervallo datetime per indicare alla funzione di utilizzare l'endpoint basso e l'endpoint alto dell'intervallo di validità per l'istanza di acquisizione durante l'esecuzione della query basata su LSN sottostante.Null values are passed for both the lower and upper datetime interval boundaries to signal the function to use the low end point and the high end point of the validity interval for the capture instance when performing the underlying LSN based query. La query restituisce una riga per ogni modifica a una riga di origine che si è verificata nell'intervallo valido per l'istanza di acquisizione.The query returns one row for each modification to a source row that occurred within the valid range for the capture instance.

Utilizzo delle funzioni wrapper datetime per la transizione tra istanze di acquisizioneUsing the Datetime Wrapper Functions to Transition Between Capture Instances

Change Data Capture supporta fino a due istanze di acquisizione per una singola tabella di origine in cui viene eseguito il rilevamento delle modifiche.Change data capture supports up to two capture instances for a single tracked source table. L'utilizzo principale di questa funzionalità consiste nell'inserire una transizione tra più istanze di acquisizione quando le modifiche DDL (Data Definition Language) apportate alla tabella di origine espandono il set di colonne disponibili per il rilevamento.The principal use of this capability is to accommodate a transition between multiple capture instances when data definition language (DDL) changes to the source table expand the set of available columns for tracking. Durante la transizione a una nuova istanza di acquisizione, è possibile proteggere i livelli dell'applicazione più elevati dalle modifiche ai nomi delle funzioni di query sottostanti eseguendo il wrapping della chiamata sottostante tramite un'apposita funzione.When transitioning to a new capture instance, one way to protect higher application levels from changes in the names of the underlying query functions is to use a wrapper function to wrap the underlying call. Assicurarsi che il nome della funzione wrapper rimanga invariato.Then, ensure that the name of the wrapper function remains the same. Al momento della transizione, è possibile eliminare la funzione wrapper precedente e crearne una nuova con lo stesso nome che faccia riferimento alle nuove funzioni di query.When the switch is to occur, the old wrapper function can be dropped, and a new one with the same name created that references the new query functions. Modificando lo script generato per creare una funzione wrapper con lo stesso nome, è possibile passare a una nuova istanza di acquisizione senza influire sui livelli dell'applicazione più elevati.By first modifying the generated script to create a wrapper function of the same name, you can make the switch to a new capture instance without affecting higher application layers.

Vedere ancheSee Also

Rilevare le modifiche ai dati (SQL Server) Track Data Changes (SQL Server)
Informazioni su Change Data Capture (SQL Server) About Change Data Capture (SQL Server)
Abilitare e disabilitare Change Data Capture (SQL Server) Enable and Disable Change Data Capture (SQL Server)
Amministrare e monitorare Change Data Capture (SQL Server)Administer and Monitor Change Data Capture (SQL Server)