Carga incremental no Azure Data Factory: o padrão de watermark passo a passo

Existe um padrão que se repete em quase todo pipeline de ingestão: no começo do projeto, recarregar a tabela inteira a cada execução parece inofensivo. A origem é pequena, a carga roda em segundos, e ninguém pensa duas vezes. O problema aparece meses depois, quando a tabela tem dezenas de milhões de linhas e a carga "full" que rodava de madrugada passa a invadir o horário comercial.

A solução no Azure Data Factory não exige ferramenta nova nem reescrever o pipeline do zero. É o padrão de watermark: em vez de reprocessar tudo, você guarda o último valor já carregado e, na execução seguinte, traz apenas as linhas que chegaram depois dele.

O que é um watermark

Watermark é simplesmente o ponto até onde você já carregou. Na prática, é o valor máximo de uma coluna que só cresce na origem:

• uma coluna de data/hora de modificação (ModifiedDate, UpdatedAt);
• um identificador incremental (Id, RowVersion);
• ou um marcador de change tracking / CDC, quando a origem não tem uma coluna confiável.

Você mantém esse valor em uma pequena tabela de controle. A cada execução, o pipeline lê o watermark antigo, descobre o novo máximo na origem e move só o intervalo entre os dois.

A tabela de controle

Comece com algo mínimo:

CREATE TABLE dbo.controle_carga (
    TabelaDestino   sysname      NOT NULL,
    WatermarkValue  datetime2    NOT NULL,
    CONSTRAINT PK_controle_carga PRIMARY KEY (TabelaDestino)
);

-- semente: uma data bem antiga para a primeira carga pegar tudo
INSERT INTO dbo.controle_carga VALUES ('vendas', '1900-01-01');

Passo 1 — Lookup do watermark antigo e do novo

No pipeline, use duas atividades Lookup:

• Lookup "watermark antigo" — lê o valor atual da tabela de controle:

SELECT WatermarkValue AS old
FROM dbo.controle_carga
WHERE TabelaDestino = 'vendas';

• Lookup "watermark novo" — lê o máximo atual da origem:

SELECT MAX(ModifiedDate) AS new
FROM dbo.vendas;

Ler o novo máximo uma vez, no início, fecha a janela (old, new] antes de mover qualquer dado. Isso evita o clássico problema de linhas que chegam durante a carga e ficariam num limbo entre uma execução e outra.

Passo 2 — Copy Data só da janela nova

Na atividade Copy Data, use uma query dinâmica na origem, parametrizada com a saída dos dois Lookups:

SELECT *
FROM dbo.vendas
WHERE ModifiedDate >  '@{activity('lkp_old').output.firstRow.old}'
  AND ModifiedDate <= '@{activity('lkp_new').output.firstRow.new}'

O detalhe que evita duplicação: use estritamente maior que o watermark antigo e menor ou igual ao novo (> @old AND <= @new). Se você usar >= dos dois lados, a linha exatamente na borda entra em duas execuções consecutivas.

Passo 3 — Stored Procedure atualiza o watermark

A última atividade do pipeline é uma Stored Procedure que grava o novo valor só depois que o Copy terminou com sucesso:

CREATE PROCEDURE dbo.sp_atualiza_watermark
    @Tabela sysname,
    @NovoValor datetime2
AS
BEGIN
    UPDATE dbo.controle_carga
    SET WatermarkValue = @NovoValor
    WHERE TabelaDestino = @Tabela;
END

Como o update depende do sucesso do Copy, se o pipeline falhar no meio o watermark não avança — e a reexecução simplesmente refaz a mesma janela. É isso que torna a carga idempotente: rodar de novo não duplica nem pula linha.

Quando o watermark não basta

O padrão pressupõe uma coluna que só cresce e reflete toda alteração. Ele funciona muito bem para inserts e updates com ModifiedDate mantido pela aplicação, mas tem limites:

• Deletes físicos não aparecem — a linha some da origem sem mexer no máximo. Para capturá-los, use soft delete (um flag) ou CDC.
• Origens sem coluna confiável de modificação — troque o watermark por Change Tracking ou CDC do SQL Server, que entregam exatamente o conjunto de mudanças desde o último ponto.
• Fabric / OneLake — o mesmo padrão vale no Copy Job e nos pipelines do Fabric Data Factory; muda a interface, não a lógica.

Checklist rápido

1. Tabela de controle com um watermark por destino, semeada com um valor antigo.
2. Lookup do watermark antigo (controle) + Lookup do novo máximo (origem).
3. Copy Data com query WHERE coluna > @old AND coluna <= @new.
4. Stored Procedure grava @new no controle após o sucesso do Copy.
5. Para deletes ou origens sem coluna de data, migrar para CDC / change tracking.

Conclusão

Antes de pedir mais compute ou espremer a janela de madrugada, troque a carga full por incremental. O padrão de watermark no Azure Data Factory é um dos ajustes de melhor custo-benefício em ingestão: menos dados trafegando, cargas em minutos e a liberdade de rodar de hora em hora em vez de uma vez por dia. É controle de estado, não mágica — e cabe em quatro atividades no pipeline.