cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)

S’APPLIQUE À : ouiSQL Server nonAzure SQL Database nonAzure Synapse Analytics (SQL DW) nonParallel Data Warehouse APPLIES TO: yesSQL Server noAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Retourne une ligne de modification nette pour chaque ligne source modifiée dans la plage de numéros de séquence de journal (LSN) spécifiée.Returns one net change row for each source row changed within the specified Log Sequence Numbers (LSN) range.

Délai d’attente, ce qui est un LSN ?Wait, what is an LSN? Chaque enregistrement dans le journal des transactions SQL Server est identifiée par un numéro de séquence de journal (LSN).Every record in the SQL Server transaction log is uniquely identified by a log sequence number (LSN). Les numéros LSN sont ordonnés de sorte que si LSN2 est supérieur à LSN1, la modification décrite par l’enregistrement de journal référencé par LSN2 s’est produite après la modification décrite par le numéro LSN d’enregistrement de journal.LSNs are ordered such that if LSN2 is greater than LSN1, the change described by the log record referred to by LSN2 occurred after the change described by the log record LSN.

Le numéro LSN d’un enregistrement de journal où un événement significatif s’est produit peut être utile pour la construction des séquences de restauration correct.The LSN of a log record where a significant event occurred can be useful for constructing correct restore sequences. Étant donné que les numéros LSN sont ordonnés, vous pouvez les comparer l’égalité et d’inégalité (autrement dit, <, >, =, <=, > =).Because LSNs are ordered, you can compare them for equality and inequality (that is, <, >, =, <=, >=). Ces comparaisons sont utiles pour créer des séquences de restauration.Such comparisons are useful when constructing restore sequences.

Lorsqu’une ligne source subit plusieurs modifications pendant la plage de numéros séquentiels, une seule ligne qui reflète le contenu final de la ligne est retournée par la fonction de l’énumération décrite ci-dessous.When a source row has multiple changes during the LSN range, a single row that reflects the final content of the row is returned by the enumeration function described below. Par exemple, si une transaction insère une ligne dans la table source et une transaction au sein de la plage de numéros séquentiels suivante met à jour une ou plusieurs colonnes de cette ligne, la fonction retourne uniquement un ligne, qui inclut les valeurs de colonne mise à jour.For example, if a transaction inserts a row in the source table and a subsequent transaction within the LSN range updates one or more columns in that row, the function returns only one row, which includes the updated column values.

Cette fonction d'énumération est créée lorsqu'une table source est activée pour la capture des données modifiées et que le suivi net est spécifié.This enumeration function is created when a source table is enabled for change data capture and net tracking is specified. Pour activer le suivi net, la table source doit avoir une clé primaire ou un index unique.To enable net tracking, the source table must have a primary key or unique index. Le nom de fonction est dérivé et utilise le format cdc.fn_cdc_get_net_changes_capture_instance, où capture_instance est la valeur spécifiée pour l’instance de capture lorsque la table source a été activé pour la capture de données modifiées.The function name is derived and uses the format cdc.fn_cdc_get_net_changes_capture_instance, where capture_instance is the value specified for the capture instance when the source table was enabled for change data capture. Pour plus d’informations, consultez sys.sp_cdc_enable_table (Transact-SQL).For more information, see sys.sp_cdc_enable_table (Transact-SQL).

Icône de lien de rubrique Conventions de la syntaxe Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SyntaxeSyntax

  
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  
}  

ArgumentsArguments

from_lsnfrom_lsn
Numéro séquentiel dans le journal qui représente le point de terminaison inférieur de la plage de numéros séquentiels dans le journal à inclure dans le jeu de résultats.The LSN that represents the low endpoint of the LSN range to include in the result set. from_lsn est Binary (10) .from_lsn is binary(10).

Seules les lignes de la cdc.[ capture_instance]_CT modifier la table avec une valeur dans __ $start_lsn supérieure ou égale à from_lsn sont inclus dans le jeu de résultats.Only rows in the cdc.[capture_instance]_CT change table with a value in __$start_lsn greater than or equal to from_lsn are included in the result set.

to_lsnto_lsn
Numéro séquentiel dans le journal qui représente le point de terminaison supérieur de la plage de numéros séquentiels dans le journal à inclure dans le jeu de résultats.The LSN that represents the high endpoint of the LSN range to include in the result set. to_lsn est Binary (10) .to_lsn is binary(10).

Seules les lignes de la cdc.[ capture_instance]_CT modifier la table avec une valeur dans __ $start_lsn inférieure ou égale à from_lsn ou égale à to_lsn sont inclus dans le jeu de résultats.Only rows in the cdc.[capture_instance]_CT change table with a value in __$start_lsn less than or equal to from_lsn or equal to to_lsn are included in the result set.

< row_filter_option > :: = {toutes les | tout avec le masque | tout avec fusion}<row_filter_option> ::= { all | all with mask | all with merge }
Option qui régit le contenu des colonnes de métadonnées aussi bien que les lignes retournées dans le jeu de résultats.An option that governs the content of the metadata columns as well as the rows returned in the result set. Il peut s'agir de l'une des options suivantes :Can be one of the following options:

allall
Retourne la valeur LSN de la modification finale apportée à la ligne et l’opération permettant d’appliquer la ligne dans les colonnes de métadonnées __ $start_lsn et _ _$operation.Returns the LSN of the final change to the row and the operation needed to apply the row in the metadata columns __$start_lsn and __$operation. La colonne _ _$update_mask a toujours la valeur NULL.The column __$update_mask is always NULL.

all with maskall with mask
Retourne la valeur LSN de la modification finale apportée à la ligne et l’opération permettant d’appliquer la ligne dans les colonnes de métadonnées __ $start_lsn et _ _$operation.Returns the LSN of the final change to the row and the operation needed to apply the row in the metadata columns __$start_lsn and __$operation. En outre, lorsqu’une opération de mise à jour retourne (__$operation = 4) les colonnes capturées modifiées dans la mise à jour sont marqués dans la valeur retournée dans _ _$update_mask.In addition, when an update operation returns (__$operation = 4) the captured columns modified in the update are marked in the value returned in __$update_mask.

all with mergeall with merge
Retourne le numéro séquentiel dans le journal de la modification finale apportée à la ligne dans les colonnes de métadonnées __$start_lsn.Returns the LSN of the final change to the row in the metadata columns __$start_lsn. La colonne _ _$operation aura l’une des deux valeurs : 1 pour suppression et 5 pour indiquer que l’opération nécessaire pour appliquer la modification est une insertion ou une mise à jour.The column __$operation will be one of two values: 1 for delete and 5 to indicate that the operation needed to apply the change is either an insert or an update. La colonne _ _$update_mask a toujours la valeur NULL.The column __$update_mask is always NULL.

Dans la mesure où la logique permettant de déterminer l'opération précise pour une modification donnée augmente la complexité de la requête, cette option est conçue pour améliorer le performances des requêtes lorsqu'il suffit d'indiquer que l'opération nécessaire pour appliquer la donnée modifiée est une insertion ou une mise à jour, mais il n'est pas utile de différencier explicitement les deux.Because the logic to determine the precise operation for a given change adds to query complexity, this option is designed to improve query performance when it is sufficient to indicate that the operation needed to apply the change data is either an insert or an update, but it is not necessary to explicitly distinguish between the two. Cette option est très intéressante dans les environnements cibles où une opération de fusion est disponible directement, tel qu'un environnement SQL ServerSQL Server.This option is most attractive in target environments where a merge operation is available directly, such as a SQL ServerSQL Server environment.

Table retournéeTable Returned

Nom de la colonneColumn name Type de donnéesData type DescriptionDescription
$start_lsn$start_lsn binary(10)binary(10) Numéro séquentiel dans le journal associé à la transaction de validation de la modification.LSN associated with the commit transaction for the change.

Toutes les modifications validées dans la même transaction partagent le même numéro séquentiel dans le journal de validation.All changes committed in the same transaction share the same commit LSN. Par exemple, si une opération de mise à jour sur la table source modifie deux colonnes sur deux lignes, la table de modifications contiendra quatre lignes, chacune avec la même start_lsnvalue de $ __.For example, if an update operation on the source table modifies two columns in two rows, the change table will contain four rows, each with the same __$start_lsnvalue.
$operation$operation intint Identifie l'opération du langage de manipulation de données permettant d'appliquer la ligne de données de modification à la source de données cible.Identifies the data manipulation language (DML) operation needed to apply the row of change data to the target data source.

Si la valeur du paramètre row_filter_option est tout ou tout avec le masque, la valeur dans cette colonne peut être l'une des valeurs suivantes :If the value of the row_filter_option parameter is all or all with mask, the value in this column can be one of the following values:

1 = suppression1 = delete

2 = insertion2 = insert

4 = mise à jour4 = update

Si la valeur du paramètre row_filter_option est tout ou tout avec fusion, la valeur dans cette colonne peut être l'une des suivantes :If the value of the row_filter_option parameter is all with merge, the value in this column can be one of the following values:

1 = suppression1 = delete
$update_mask$update_mask varbinary(128)varbinary(128) Masque de bits avec un bit correspondant à chaque colonne capturée identifiée pour l'instance de capture.A bit mask with a bit corresponding to each captured column identified for the capture instance. Tous les bits définis de cette valeur ont la valeur 1 lorsque __$operation = 1 ou 2.This value has all defined bits set to 1 when __$operation = 1 or 2. Lorsque _ _$operation = 3 ou 4, seuls les bits correspondant aux colonnes qui ont changé sont définis sur 1.When __$operation = 3 or 4, only those bits corresponding to columns that changed are set to 1.
<<colonnes_de_table_source_capturées><captured source table columns> variablevaries Les colonnes restantes retournées par la fonction sont les colonnes de la table source qui ont été identifiées comme colonnes capturées lorsque l'instance de capture a été créée.The remaining columns returned by the function are the columns from the source table that were identified as captured columns when the capture instance was created. Si aucune colonne n'a été spécifiée dans la liste des colonnes capturées, toutes les colonnes de la table source sont retournées.If no columns were specified in the captured column list, all columns in the source table are returned.

AutorisationsPermissions

Requiert l'appartenance au rôle serveur fixe sysadmin ou au rôle de base de données fixe db_owner.Requires membership in the sysadmin fixed server role or db_owner fixed database role. Pour tous les autres utilisateurs, requiert l'autorisation SELECT sur toutes les colonnes capturées dans la table source et, si un rôle de régulation pour l'instance de capture a été défini, l'appartenance à ce rôle de base de données.For all other users, requires SELECT permission on all captured columns in the source table and, if a gating role for the capture instance was defined, membership in that database role. Lorsque l'appelant n'a pas l'autorisation de consulter les données sources, la fonction retourne l'erreur 208 (nom d'objet non valide).When the caller does not have permission to view the source data, the function returns error 208 (Invalid object name).

NotesRemarks

Si la plage spécifiée de numéro séquentiel dans le journal ne se situe pas dans la chronologie de suivi des modifications pour l'instance de capture, la fonction retourne l'erreur 208 (nom d'objet non valide).If the specified LSN range does not fall within the change tracking timeline for the capture instance, the function returns error 208 (Invalid object name).

Modifications de l’identificateur unique d’une ligne entraîne fn_cdc_get_net_changes afficher la commande de mise à jour initiale avec une suppression puis insérez commande à la place.Modifications on the unique identifier of a row will cause fn_cdc_get_net_changes to show the initial UPDATE command with a DELETE and then INSERT command instead. Ce comportement est nécessaire pour effectuer le suivi de la clé à la fois avant et après la modification.This behavior is necessary to track the key both before and after the change.

ExemplesExamples

L’exemple suivant utilise la fonction cdc.fn_cdc_get_net_changes_HR_Department pour signaler les modifications nettes apportées à la table source HumanResources.Department pendant un intervalle de temps spécifique.The following example uses the function cdc.fn_cdc_get_net_changes_HR_Department to report the net changes made to the source table HumanResources.Department during a specific time interval.

En premier lieu, la fonction GETDATE est utilisée pour marquer le début de l'intervalle de temps.First, the GETDATE function is used to mark the beginning of the time interval. Après avoir appliqué à la table source plusieurs instructions DML, la fonction GETDATE est rappelée pour identifier la fin de l'intervalle de temps.After several DML statements are applied to the source table, the GETDATE function is called again to identify the end of the time interval. La fonction sys.fn_cdc_map_time_to_lsn est ensuite utilisé pour mapper l’intervalle de temps à une plage de requêtes de capture de données modification limitée par les valeurs LSN.The function sys.fn_cdc_map_time_to_lsn is then used to map the time interval to a change data capture query range bounded by LSN values. Enfin, la fonction cdc.fn_cdc_get_net_changes_HR_Department est interrogée pour obtenir les modifications nettes apportées à la table source pendant l'intervalle de temps.Finally, the function cdc.fn_cdc_get_net_changes_HR_Department is queried to obtain the net changes to the source table for the time interval. Remarquez que la ligne qui est insérée, puis supprimée n'apparaît pas dans le jeu de résultats retourné par la fonction.Notice that the row that is inserted and then deleted does not appear in the result set returned by the function. En effet, une ligne qui est d'abord ajoutée, puis supprimée dans une fenêtre de requête ne produit aucune modification nette dans la table source pendant l'intervalle.This is because a row that is first added and then deleted within a query window produces no net change on the source table for the interval. Avant d’exécuter cet exemple, vous devez d’abord exécuter l’exemple B dans sys.sp_cdc_enable_table (Transact-SQL).Before you run this example, you must first run example 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');  

Voir aussiSee Also

cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL) cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL)
sys.fn_cdc_map_time_to_lsn (Transact-SQL) sys.fn_cdc_map_time_to_lsn (Transact-SQL)
sys.sp_cdc_enable_table (Transact-SQL) sys.sp_cdc_enable_table (Transact-SQL)
sys.sp_cdc_help_change_data_capture (Transact-SQL) sys.sp_cdc_help_change_data_capture (Transact-SQL)
À propos de la capture de données modifiées (SQL Server)About Change Data Capture (SQL Server)