O canvas

Adicionando nós

Três formas, todas equivalentes:

• Arraste um item da palette para o canvas.
• Clique num item da palette — o nó cai após o último, já organizado.
• Duplo-clique no canvas vazio para uma busca de adição rápida; digite, aperte Enter.

Aperte / em qualquer lugar para focar a busca da palette.

Tipos de nó

Nó	Compila para	Inputs
Source	input, ou um with de join/union	nenhum
Transformation	uma entrada de transformations	um (dois para join e union)
Validation rule	uma entrada de validations.rules — uma caixa por regra	um
Quality destination	validations.report ou validations.outputs.valid/.invalid	nenhum — é uma declaração
Destination	uma entrada de outputs	um
Note	nada	nenhum

Um nó mostra seu parâmetro mais significativo sob o título — a condição de um filter, a expressão de uma coluna calculada, o tipo e a chave do join — então um Job é legível sem abrir nada.

Destinos de qualidade

O bloco validations grava até três datasets próprios, e cada um é uma caixa que você adiciona pela seção Quality da paleta — não algo que você liga com uma aresta:

Item da paleta	Compila para
Quality report	validations.report — uma linha por regra
Quarantine — valid rows	validations.outputs.valid
Quarantine — invalid rows	validations.outputs.invalid

Eles não recebem conexões: o bloco validations é um por Job, então pertencem ao Job, não a uma regra específica. Solte um em qualquer lugar do canvas e ele compila. Um Job aceita um de cada; um segundo é erro, assim como um destino de qualidade sem nenhuma regra de validação para alimentá-lo.

Quarentena audita — `filter` roteia

Quarentena é cópia, não desvio. O framework grava os destinos de quarentena e depois grava os destinos do próprio Job a partir do mesmo DataFrame completo — inclusive as linhas inválidas. Ou seja, um Job com quarentena grava as linhas ruins duas vezes: uma na quarentena, outra no destino principal.

Use para auditar: “quais linhas violaram uma regra, e quantas?” — sem mexer no fluxo.

Para rotear — só as linhas boas chegando na tabela final — use o próprio pipeline: um nó filter antes do destino, e um segundo branch para as rejeitadas. O custo é reescrever a condição em SQL, então mantenha-a em sincronia com as regras; o ganho é o destino principal carregar exatamente o que você quis.

on_failure não é um destino e continua nas configurações do Job: ela decide se uma violação aborta a execução.

Conectando

Arraste do handle direito de um nó para o handle esquerdo do próximo. As conexões são validadas enquanto você desenha: o Studio recusa um link para uma source, um self-link e qualquer coisa que criaria um ciclo.

Cada input handle recebe uma conexão. Soltar uma segunda substitui a primeira, que é o jeito mais rápido de emendar um nó para fora de uma cadeia.

Pelo teclado: foque um nó, aperte C, Tab até o alvo, então C de novo. Escape cancela. A toolbar do nó tem as mesmas ações em Connect to….

Ramificando para vários destinos

Conecte o mesmo nó a dois destinos e o grafo se ramifica. Tudo antes do fork fica no transformations principal; tudo depois pertence àquele destino.

source → filter → cast ─┬─→ group_by → delta        ← group_by é o próprio da saída delta
                        └─→ parquet                  ← filter e cast são compartilhados

Checkpoint antes de um fork

Cada destino relê o mesmo DataFrame, então coloque um checkpoint como a última transformação compartilhada. Sem ele o Spark recomputa a linhagem inteira uma vez por destino.

Joins e unions

Esses nós têm dois inputs. O da esquerda continua a cadeia principal; o da direita pega a segunda fonte.

                 ┌── delta(customers) → filter → select ──┐   ← with + with_transformations
source → filter ─┴──────────────────────────────────────→ join → destination

Tudo entre a fonte lateral e o join vira with_transformations, aplicado ao lado direito antes do join rodar.

Cuidado

union não tem with_transformations no framework, então o Studio marca uma cadeia lateral não-vazia como erro em vez de compilar algo que seria ignorado silenciosamente em runtime.

Mutar e deletar

Mute uma transformação (o olho da toolbar, ou o menu do inspector) para mantê-la no canvas excluindo-a do JSON compilado — o jeito mais rápido de testar se um passo é o problema, sem perder a configuração.

Deletar remove o nó e suas conexões num único passo de undo.

Layout

Shift+Ctrl/⌘+L reroda o layout automático: da esquerda para a direita, cadeias laterais empilhadas sob o nó que alimentam. As posições são salvas com o Job, então um grafo arrumado continua arrumado.

Teclado

Atalho	Ação
Ctrl/⌘+K	Command palette
Ctrl/⌘+S	Salvar agora (edições autosalvam mesmo assim)
Ctrl/⌘+Z / Shift+Ctrl/⌘+Z	Desfazer / refazer
Ctrl/⌘+D	Duplicar seleção
Delete	Remover seleção
Ctrl/⌘+Enter	Painel Run
Ctrl/⌘+J	Painel JSON
Ctrl/⌘+/	Assistente de IA
Ctrl/⌘+E	Painel Issues
Shift+Ctrl/⌘+L	Auto-layout
C	Iniciar / completar uma conexão a partir do nó focado
/	Focar a busca da palette

O painel de issues

O lint roda enquanto você digita. Ele reporta o que é estaticamente decidível e fica quieto sobre o resto — um falso positivo custa mais que um aviso ausente.

Severidade	Exemplos
Error	sem destino; um nó órfão; um campo obrigatório vazio; merge sem merge_keys; um destino binary (formato só de leitura); duas entradas principais num nó
Warning	um collect sem checkpoint a montante; um {{variable}} que ninguém publica; um {param} nunca declarado; dois destinos escrevendo no mesmo path; uma union posicional
Info	um nó debug deixado no Job; sem bloco de validations

Clique em qualquer issue para selecionar o nó e pular ao campo problemático.

Salvando

Edições autosalvam um instante depois que você para de digitar; a status bar mostra Saved ou Unsaved. Ctrl/⌘+S força. Fechar um Job descarrega o que estava pendente, então navegar para longe nunca perde as últimas teclas.

O histórico de undo cobre mudanças estruturais e edições de campo, agrupando digitação rápida num passo só, para que um único undo volte uma palavra em vez de um caractere.