cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)
Aplica-se: 
SQL Server
Retorna uma linha de alteração líquida para cada linha de origem alterada dentro do intervalo LSN (Números de Sequência de Log) especificado.
Espere, o que é um LSN? Cada registro no log de transações do SQL Server é identificado exclusivamente por um LSN (número de seqüência de log). Os LSNs são ordenados de modo que, se LSN2 for maior que LSN1, a alteração descrita pelo registro de log referido por LSN2 ocorreu após a alteração descrita pelo LSN do registro de log.
O LSN de um registro de log em que ocorreu um evento significativo pode ser útil para construir sequências de restauração corretas. Como os LSNs são ordenados, você pode compará-los quanto à igualdade e desigualdade (ou seja, <, , >=, <=, >=). Essas comparações são úteis ao construir sequências de restauração.
Quando uma linha de origem tem várias alterações durante o intervalo LSN, uma única linha que reflete o conteúdo final da linha é retornada pela função de enumeração descrita abaixo. Por exemplo, se uma transação inserir uma linha na tabela de origem e uma transação subsequente dentro do intervalo LSN atualizar uma ou mais colunas nessa linha, a função retornará apenas uma linha, que inclui os valores de coluna atualizados.
Essa função de enumeração é criada quando uma tabela de origem é habilitada para Change Data Capture e o rastreamento líquido é especificado. Para habilitar o rastreamento líquido, a tabela de origem deve ter uma chave primária ou índice exclusivo. O nome da função é derivado e usa o formato cdc.fn_cdc_get_net_changes_<capture_instance>, em que <capture_instance> é o valor especificado para a instância de captura quando a tabela de origem foi habilitada para captura de dados de alteração. Para obter mais informações, consulte sys.sp_cdc_enable_table (Transact-SQL).
Convenções de sintaxe de Transact-SQL
Sintaxe
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
}
Argumentos
from_lsn
O LSN que representa o ponto de extremidade inferior do intervalo de LSN para incluir no conjunto de resultados. from_lsn é binário(10).
Somente linhas no cdc.[ capture_instance]_CT alterar tabela com um valor em __$start_lsn maior ou igual a from_lsn são incluídas no conjunto de resultados.
to_lsn
O LSN que representa o ponto de extremidade superior do intervalo de LSN para incluir no conjunto de resultados. to_lsn é binário (10).
Somente linhas no cdc.[ capture_instance]_CT alterar tabela com um valor em __$start_lsn menor ou igual a from_lsn ou igual a to_lsn são incluídas no conjunto de resultados.
<> row_filter_option ::= { all | all with mask | all with merge }
Opção que rege o conteúdo das colunas de metadados, assim como as linhas retornadas no conjunto de resultados. Pode ser uma das seguintes opções:
all
Retorna o LSN da alteração final para a linha e a operação necessária para aplicar a linha nas colunas de metadados __$start_lsn e __$operation. A coluna __$update_mask é sempre NULL.
all with mask
Retorna o LSN da alteração final para a linha e a operação necessária para aplicar a linha nas colunas de metadados __$start_lsn e __$operation. Além disso, quando uma operação de atualização retorna (__$operation = 4), as colunas capturadas modificadas na atualização são marcadas no valor retornado em __$update_mask.
all with merge
Retorna o LSN da alteração final para a linha nas colunas de metadados __$start_lsn. A coluna __$operation será um dos dois valores: 1 para delete e 5 para indicar que a operação necessária para aplicar a alteração é uma inserção ou uma atualização. A coluna __$update_mask é sempre NULL.
Como a lógica para determinar a operação precisa de uma determinada alteração aumenta a complexidade de consulta, essa opção se destina a melhorar o desempenho de consulta quando for suficiente indicar se a operação necessária para aplicar os dados de alteração é uma inserção ou uma atualização, mas não for necessário distingui-las explicitamente. Essa opção é mais atraente em ambientes de destino em que uma operação de mesclagem está disponível diretamente.
Tabela retornada
| Nome da coluna | Tipo de dados | Descrição |
|---|---|---|
| __$start_lsn | binary(10) | LSN associado à transação de confirmação da alteração. Todas as alterações confirmadas na mesma transação compartilham o mesmo LSN de confirmação. Por exemplo, se uma operação de atualização na tabela de origem modificar duas colunas em duas linhas, a tabela de alteração conterá quatro linhas, cada uma com o mesmo __$start_lsnvalue. |
| __$operation | int | Identifica a operação DML (linguagem de manipulação de dados) necessária para aplicar a linha de dados de alteração à fonte de dados de destino. Se o valor do parâmetro row_filter_option for tudo ou tudo com máscara, o valor desta coluna poderá ser um dos seguintes valores: 1 = excluir 2 = inserir 4 = atualizar Se o valor do parâmetro row_filter_option for tudo ou tudo com mesclagem, o valor desta coluna poderá ser um dos seguintes valores: 1 = excluir 5 = inserir ou atualizar |
| __$update_mask | varbinary(128) | Uma máscara de bits com um bit correspondente a cada coluna capturada identificada para a instância de captura. Esse valor tem todos os bits definidos configurados como 1 quando __$operation = 1 ou 2. Quando __$operation = 3 ou 4, somente os bits correspondentes às colunas que foram alteradas são definidos como 1. |
| <colunas da tabela de origem capturada> | varia | As colunas restantes retornadas pela função são as colunas da tabela de origem que foram identificadas como colunas capturadas quando a instância de captura foi criada. Se nenhuma coluna tiver sido especificada na lista de colunas capturadas, todas as colunas da tabela de origem serão retornadas. |
Permissões
Requer associação na função de servidor fixa sysadmin ou na função de banco de dados fixa db_owner. Para todos os outros usuários, requer a permissão SELECT em todas as colunas capturadas na tabela de origem e, se uma função associada para a instância de captura tiver sido definida, faça associação nessa função de banco de dados. Quando o chamador não tem permissão para exibir os dados de origem, a função retorna uma linha com valores NULL para todas as colunas.
Comentários
Modificações no identificador exclusivo de uma linha farão com que fn_cdc_get_net_changes o comando UPDATE inicial seja mostrado com um comando DELETE e, em seguida, INSERT. Esse comportamento é necessário para rastrear a chave antes e depois da alteração.
O erro 313 é esperado se o intervalo LSN fornecido não for apropriado ao chamar cdc.fn_cdc_get_all_changes_<capture_instance> ou cdc.fn_cdc_get_net_changes_<capture_instance>. Se o lsn_value parâmetro estiver além do tempo do LSN mais baixo ou do LSN mais alto, a execução dessas funções retornará no erro 313: Msg 313, Level 16, State 3, Line 1 An insufficient number of arguments were supplied for the procedure or function. Esse erro deve ser resolvido pelo desenvolvedor.
Exemplos
O exemplo a seguir usa a função cdc.fn_cdc_get_net_changes_HR_Department para relatar as alterações líquidas feitas na tabela HumanResources.Department de origem durante um intervalo de tempo específico.
Primeiro, a função GETDATE é usada para marcar o início do intervalo de tempo. Depois que diversas instruções DML são aplicadas à tabela de origem, a função GETDATE é chamada novamente para identificar o final do intervalo de tempo. A função sys.fn_cdc_map_time_to_lsn é usada para mapear o intervalo de tempo para um intervalo de consulta de captura de dados de alteração limitado por valores LSN. Finalmente, a função cdc.fn_cdc_get_net_changes_HR_Department é consultada para obter as alterações líquidas efetuadas na tabela de origem nesse intervalo de tempo. Note que a linha que é inserida e, depois, excluída não aparece no conjunto de resultados retornado pela função. Isso porque uma linha inicialmente adicionada e, depois, excluída dentro de uma janela de consulta não produz nenhuma alteração líquida na tabela de origem nesse intervalo.
Observação
Antes de executar este exemplo, você deve primeiro executar o exemplo B no sys.sp_cdc_enable_table (Transact-SQL) para habilitar o CDC na tabela HumanResources.Department. No exemplo abaixo, HR_Department é o nome da instância de captura de CDC, conforme especificado em sys.sp_cdc_enable_table.
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');