Modos de carga: full, por período e por marca d'água; substituir ou acrescentar

Selo de estado: Preview (teto atual do produto) · Curso ACD-220 — Pipelines e medalhão Bronze/Silver/Gold · Aula 2 de 12 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai escolher modo pelo efeito no destino — decidir por o que acontece com as linhas que já estão lá, não pelo nome bonito do modo.

Vídeo#

Identificador no manifesto: acd-220-02-modos-de-carga · duração-alvo 8 min · tela do produto: /sources.

Roteiro de gravação (5 capítulos):

#	Minutagem-alvo	Capítulo	Tela do produto
1	0:00–0:50	Abertura: título + selo. O vocabulário do mercado (substituir · mesclar · acrescentar) e o que a tela do Ingestia realmente oferece.	`/sources`
2	0:50–3:00	Etapa Carga: o seletor Tipo de ingestão com dois rádios — Full e Append — e a coluna-chave de controle que aparece só no Append.	`/sources`
3	3:00–5:20	O cartão "Escrita no destino — efeito real", campo por campo: escrita, marca d'água, deduplicação, histórico fora da janela, deletes, mudança de schema.	`/sources`
4	5:20–6:50	A tabela de decisão por cenário, e o aviso de quando um recurso marcado como incremental não vai carregar de forma incremental.	`/sources`
5	6:50–8:00	Silver/Gold é outro contrato: `full` recria, `append` insere e reexecutar duplica. Encerramento com o "faça você mesmo".	`/sources`

Conteúdo#

A Bronze tem exatamente dois modos de escrita

Full (substitui a tabela inteira) e Append (incremental por marca d'água, com uma coluna-chave de controle). Não existe "mesclar": nenhuma tela do pipeline pede chave de mesclagem, e a Bronze não faz upsert por chave de negócio. CDC — ler o log de transações da origem para capturar cada INSERT/UPDATE/DELETE — é Roadmap: não existe hoje.

O vocabulário do mercado × o que existe aqui

Quem vem de outra ferramenta chega com três palavras na cabeça: substituir, mesclar e acrescentar. Vale traduzir uma vez e nunca mais confundir:

Vocabulário do mercado	No Ingestia	O que acontece de fato
Substituir (replace / truncate-load)	Full	A tabela de destino é reescrita por completo a cada execução (`LOAD WRITE_TRUNCATE`).
Acrescentar (append)	Append	Recorte por janela da coluna-chave: a janela é apagada no destino e as linhas extraídas são acrescentadas (`DELETE` da janela + `LOAD WRITE_APPEND`).
Mesclar (merge / upsert por chave)	não existe na Bronze	A deduplicação por chave de negócio é assunto das Transformações (Silver), onde há SQL.

A documentação de referência fala em "UPSERT por chave" ao descrever o refresh incremental de snapshot de painéis e marts — outro subsistema, com outra tela. Para a carga da Bronze, o contrato é o da tabela acima.

Os dois rádios da etapa Carga

Na etapa Carga, cada recurso tem o seletor Tipo de ingestão, com os textos fixos do produto:

Full — "Recarrega a tabela inteira a cada execução (substitui tudo)."
Append — "Inclui só os dados novos a cada execução (incremental)."

Escolhido Append numa tabela de banco, aparece o campo Coluna-chave de controle — uma coluna só, com datas/timestamps sugeridos primeiro (marcados "— data, ideal") e depois colunas de id/*_id. Append de banco sem coluna-chave bloqueia o avanço da etapa: a carga não saberia de onde continuar. Em fontes de arquivo não há coluna-chave a configurar: o Append é controlado pela data de chegada/upload do arquivo.

Há um detalhe que decide muita coisa: a janela do destino compara coluna >= TIMESTAMP(@inicio) AND coluna < TIMESTAMP(@fim). Logo uma coluna-chave numérica (um id sequencial) não serve para a escrita — a extração até sabe paginar por id, mas a carga não saberia apagar o recorte, e acrescentar sem apagar duplica. Isso é recusa explícita, com motivo na tela, não silêncio.

O cartão que vale mais que o rádio

O topo da etapa Carga traz "Escrita no destino — efeito real". Ele é a fonte da verdade da aula:

Campo do cartão	Em Full	Em Append efetivo
Escrita	substitui a tabela inteira; reexecutar não duplica	apaga só a janela da coluna-chave (início inclusivo, fim exclusivo) e acrescenta; reexecutar a mesma janela termina no mesmo estado
Marca d'água	não se aplica — não há de onde continuar	gravada a cada carga e lida como ponto de partida da próxima
Deduplicação	a Bronze não deduplica por chave: o destino é o retrato atual da origem	é a própria janela (apagada antes da carga)
Histórico fora da janela	não preservado — a tabela é reescrita inteira	preservado: linha fora do recorte não é lida, apagada nem reescrita
Deletes na origem	a linha apagada some porque a tabela é reescrita, não porque o delete foi lido	não somem: isto não é CDC, a deleção não aparece na coluna-chave
Mudança de schema	coluna nova entra na próxima carga completa; coluna removida deixa de existir no destino	idem — confira a Revisão antes de publicar

E há um aviso que você precisa aprender a ler: quando um recurso está marcado como Append mas o adaptador daquele conector não cumpre o contrato (ou a integração no executor ainda não está ativa), a tela diz, com nome e motivo, "N recursos marcados como incrementais NÃO vão carregar de forma incremental". A regra do produto é literal: não se chama de incremental o que substitui a tabela inteira.

Tabela de decisão

Situação	Modo	Por quê
Primeira carga de qualquer fonte	Full	A primeira extração já é o backfill; não existe marca anterior
Tabela pequena (poucos milhares de linhas)	Full	Simples e barato o bastante; evita manutenção de coluna-chave
Tabela grande que só cresce/atualiza, com `atualizado_em` confiável	Append	Lê muito menos bytes e preserva o histórico fora da janela
A origem apaga linhas fisicamente	Full	Marca d'água não vê deleção; só a carga completa reflete deleção física
A coluna crescente é um `id` numérico	Full	Serve para paginar, não para recortar a escrita (a janela é de tempo)
A origem não tem nenhuma coluna crescente estável	Full	Sem ponto de partida não há incremental
Preciso reprocessar um período antigo	Full pontual ou reprocessamento por período	Ver a aula 5

A regra que sustenta tudo: o resultado incremental tem de ser idêntico ao refresh completo. Na menor dúvida de elegibilidade, o produto recusa o incremental e faz o full, com o motivo no log. Um refresh caro é problema de custo; um número errado é problema de produto.

Silver e Gold têm outro contrato

Nas transformações, o modo de carga é por tabela de destino e muda o efeito:

full → CREATE OR REPLACE TABLE: idempotente, recria a tabela.
append → INSERT INTO: reexecutar DUPLICA as linhas, porque não há chave declarada para deduplicar. A tela avisa e pede confirmação.

Exemplo: a Comércio Aurora

produtos tem 1.800 linhas e muda pouco → Full. filiais tem 12 linhas → Full. vendas tem milhões de linhas, só cresce e tem atualizado_em (timestamp) → Append com coluna-chave atualizado_em. clientes é o caso difícil: o CRM da Aurora apaga o cadastro quando o cliente pede exclusão, e nenhum sinal disso aparece em atualizado_em → Full, mesmo sendo tentador marcar Append.

Erros comuns

Sintoma	Causa provável	O que fazer
"Esperava CDC (updates e deletes)"	CDC é Roadmap	Use Append + reprocessamento; deletes não são capturados
Marquei Append e a tabela continua sendo substituída	O adaptador não cumpre o contrato, ou a integração no executor não está ativa	Leia o aviso nominal na etapa Carga — ele diz o motivo
Append com `id` numérico recusado	A janela do destino é de tempo	Escolha uma coluna de data/timestamp ou use Full
Linha apagada na origem continua no destino	Marca d'água não vê deleção	Full periódico, ou recorte por período re-buscando dias inteiros
Reexecutei uma tarefa Silver e duplicou	`loadMode: append` (INSERT INTO)	Troque para `full` (recria) ou declare a deduplicação na Silver

O que é Preview aqui

A elegibilidade do incremental, a identidade "incremental == full" e o plano de carga são provados por teste determinístico (C07.1 = GA-candidato). A execução real em BigQuery e o custo faturado são Preview/não medidos. Nada aqui é "GA".

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /sources no console). Monte a tabela de decisão sem publicar nada.

Abra um rascunho de pipeline e vá até a etapa Carga com vendas, produtos e clientes marcados.
Cenário 1 — produtos: deixe em Full. Leia o cartão "Escrita no destino — efeito real" e anote as linhas Deduplicação e Histórico fora da janela.
Cenário 2 — vendas: troque para Append e escolha atualizado_em como Coluna-chave de controle. Compare as mesmas duas linhas do cartão com o que você anotou no passo 2.
Ainda em vendas, tente escolher uma coluna de id numérico como coluna-chave e leia o motivo que a tela dá.
Cenário 3 — clientes: marque Append, leia o que o cartão diz em Deletes na origem, e volte para Full justificando por escrito.
Anote, em três linhas, qual modo cada tabela recebeu e qual frase do cartão sustenta a escolha.
Confira na Revisão que a escrita de cada tabela aparece como você decidiu — e saia sem publicar.

Você terminou quando você tem uma tabela com três linhas (produtos → Full, vendas → Append + atualizado_em, clientes → Full), cada uma justificada por uma frase lida na tela, e consegue explicar por que "mesclar" não é uma opção da Bronze.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

C07.1 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".