cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)

Artigo
02/18/2014

Retorna uma linha de alteração líquida para cada linha de origem alterada dentro do intervalo LSN especificado. Ou seja, quando uma linha de origem tiver várias alterações durante o intervalo de LSN, uma única linha que reflete o conteúdo final da linha será retornada pela função. Por exemplo, se uma transação inserir uma linha na tabela de origem e uma transação subsequente dentro do intervalo de 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, onde capture_instance é o valor especificado para a instância de captura quando a tabela de origem é habilitada para Change Data Capture. Para obter mais informações, consulte sys.sp_cdc_enable_table (Transact-SQL).

Ícone de vínculo de tópico Convenções da sintaxe 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 é binary(10).

Somente as linhas na tabela de alteração cdc.[capture_instance]_CT com um valor em __$start_lsn maior ou igual a from_lsn serã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 é binary(10).

Somente as linhas na tabela de alteração cdc.[capture_instance]_CT com um valor em __$start_lsn menor ou igual a from_lsn ou igual a to_lsn serã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 será 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 é retornada (__$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 terá um destes dois valores: 1 para excluir 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 será 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 é muito atraente em ambientes de destino em que uma operação de mesclagem está diretamente disponível, como um ambiente SQL Server 2012.

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 qual com o mesmo valor de __$start_lsn.
__$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 all ou all with mask, o valor dessa coluna poderá ser um dos seguintes: 1 = excluir 2 = inserir 4 = atualizar Se o valor do parâmetro row_filter_option for all with merge, o valor dessa coluna poderá ser um dos seguintes: 1 = excluir
__$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, apenas os bits correspondentes às colunas que foram alteradas serão definidos como 1.
<captured source table columns>	varies	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

Exige associação à função de servidor fixa sysadmin ou à 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 tiver permissão para exibir os dados de origem, a função retornará o erro 208 (Nome de objeto inválido).

Comentários

Se o intervalo de LSN especificado não cair dentro da linha do tempo do rastreamento de alterações da instância de captura, a função retornará o erro 208 (Nome de objeto inválido).

Exemplos

O exemplo a seguir usa a função cdc.fn_cdc_get_net_changes_HR_Department para relatar as alterações líquidas efetuadas na tabela de origem HumanResources.Department 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. Em seguida, a função sys.fn_cdc_map_time_to_lsn é usada para mapear o intervalo de tempo para um intervalo de consultas de Change Data Capture vinculado 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. Antes de executar esse exemplo, você deve executar o exemplo B em 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');