DATTA Extract — Guia do Usuário

Extract é o fluxo ELT do DATTA: extrair dados de fontes externas e persistir como datasets estruturados no catálogo, opcionalmente materializando em Iceberg, Neo4j ou OpenSearch.

Três telas convivem sob DATTA Extract:

• Pacotes (/pipeline-pacotes.html): galeria/inventário dos pipelines de extração já existentes — buscar, filtrar, executar, agendar, duplicar, arquivar e abrir cada um no editor correto.
• DATTA Extract (/pipeline-designer.html): o editor, com dois modos sobre o mesmo pacote — alterna no seletor da barra superior.
  • Assistente (?modo=simples): fluxo guiado em 3 passos, com mesa de trabalho — origem, transformar, destino.
  • Avançado (?modo=avancado): canvas de fluxo, com várias origens, junções, vários destinos e undo/redo.

Mudou. Eram duas páginas, com motores de execução diferentes: o Designer submetia ao Spark e a Extração Rápida executava na JVM do serviço. Agora são dois modos da mesma tela, sobre o mesmo motor — e o Spark saiu do caminho de ETL. O endereço antigo (/pipeline-quick.html) continua funcionando: redireciona para o modo Assistente, preservando o ?id= do pacote.

A galeria é o ponto de entrada comum, e os dois modos persistem o mesmo tipo de dataset no catalog-service.

1. Quando usar qual

Trocar de modo não muda o que o pacote é capaz de fazer — a capacidade é a mesma, porque o motor é o mesmo. Muda como você monta. A mesa de trabalho, que era exclusiva do Assistente, também está no modo Avançado: selecione um nó de origem e use Mesa de trabalho no painel de configuração. | Achar, executar ou editar um pipeline que já existe | Pacotes |

2. Pacotes — galeria dos pipelines de extração

/pipeline-pacotes.html, no menu DATTA Extract › Pacotes. É o inventário de tudo que existe: pipelines desenhados no ETL Designer, criados na Extração Rápida e os fluxos de fontes externas registrados por seed (CVM e base negativa pública — ver Fontes Externas).

2.1 O que a tela mostra

Uma faixa de indicadores no topo (Pacotes, Rodando agora, Agendados, Executados hoje, Taxa de sucesso) vinda de GET /api/pipelines/stats. Se esse endpoint falhar, a faixa simplesmente não aparece — o resto da tela continua funcionando. Os quatro primeiros cartões filtram a lista (§2.2).

A lista vem de GET /api/pipelines/summary (paginada, 24 itens por página) e cada pacote aparece como cartão ou linha de tabela — o alternador Cards / Tabela fica na barra de ferramentas. Em cada item:

• Nome e descrição e selo de status (ativo, pausado, rascunho, arquivado). No modo Cards o pacote também traz o selo de origem (Designer, Assistente, Agente ETL); na tabela não há coluna Origem — quem criou o pacote não muda como ele é operado.
• Cadeia do fluxo: tipo de origem → número de transformações → tipo de destino.
• Chip da integração e da especificação de origem quando o pacote declara esses metadados (é o caso dos fluxos de fontes externas). Na tabela, o chip de integração aparece ao lado do nome do pacote.
• Agendamento em português legível (ex.: "Todo dia 3 de cada mês às 05:30") quando há cron; pacote agendado por intenção, sem expressão cron, aparece como "Agendado".
• Atualizado em (relativo) e última execução com status colorido. Pacote que nunca rodou mostra "Nunca executado" — nunca uma duração falsa. Se o serviço não conseguir apurar a última execução, o cartão diz "Última execução indisponível" com um botão de recarregar; ele nunca troca uma falha de consulta por "Nunca executado".

2.2 Buscar e filtrar

• Busca por nome ou descrição (ignora acento e caixa), aplicada com um pequeno atraso enquanto você digita.
• Filtros de Status e Integração. As opções e as contagens vêm das facetas calculadas pelo backend sobre o resultado da busca — filtro sem nenhum pacote não aparece na lista.
• Cartões que filtram: clicar em um dos quatro primeiros indicadores recorta a lista; clicar de novo no cartão marcado desfaz o recorte.

O número do cartão e a lista que ele abre saem do mesmo predicado no backend — por isso o total da lista filtrada bate com o número mostrado. Os quatro contam pacotes, não execuções: duas execuções simultâneas do mesmo pacote contam 1 em "Rodando agora", que é o que a lista mostra. Taxa de sucesso não filtra: é percentual, não recorte de lista, e por isso não é clicável.

• Os cartões são botões: funcionam por Tab + Enter/Espaço e têm alvo de toque de 44px em tela pequena.
• Filtros ativos: uma faixa abaixo da barra de ferramentas lista o que está filtrando agora (busca, cartão, status, integração), permite remover item a item e traz Limpar tudo. Os filtros se combinam por E lógico.
• Ordenar por atualização mais recente (padrão), nome ou última execução.
• Atualizar ao lado recarrega lista e indicadores.

O filtro de Origem saiu da tela: pacote criado no Assistente e pacote criado no Designer são igualmente válidos, então a procedência de autoria não responde nenhuma pergunta de operação. O parâmetro origin continua aceito por GET /api/pipelines/summary para quem consulta por script.

"Executados hoje" usa o fuso configurado em datta.pipeline.timezone (variável DATTA_PIPELINE_TIMEZONE); vazio, vale o fuso da JVM do serviço — o mesmo que o agendador usa quando o pacote não declara timezone próprio.

2.3 Abrir um pacote no editor certo

Clicar no cartão abre o pacote no modo Avançado, o canvas. O campo editor de cada item continua vindo do backend e faz parte do contrato JSON, mas hoje vale sempre DESIGNER: o canvas desenha qualquer grafo, inclusive a cadeia linear que o Assistente monta, e mandar o usuário para um editor que mostra menos do que o pacote tem não se justifica.

Quando o grafo não é uma cadeia linear — mais de uma origem, junção, mais de um destino, ramos —, o motivo aparece em português no cartão e no painel de detalhes. Pacote linear não exibe motivo nenhum: uma linha idêntica em todo cartão seria ruído.

Antes, a escolha também dependia do motor — havia tipos que "só executavam no Designer" —, e isso deixou de existir.

A navegação acontece dentro do shell (o menu lateral e a trilha de navegação acompanham); nenhum link troca o iframe por fora.

2.4 Gerenciar sem sair da galeria

O menu Ações de cada pacote oferece:

Cada ação mostra o resultado como aviso em português e recarrega a lista.

Uma ressalva honesta:

• Duplicar não copia credenciais. A cópia recebe as senhas mascaradas; a tela avisa e você precisa reinformá-las no editor antes de executar a cópia.

2.5 Painel de detalhes

O painel lateral mostra origem, status, modo, versão, autor, agendamento e datas de criação/atualização, permite editar nome e descrição, e desenha o fluxo do pacote em um canvas somente leitura (o mesmo componente usado na Assistente — §3.4). Pacote sem etapas desenhadas mostra o estado vazio em vez de um canvas em branco.

2.6 Galeria vazia numa instalação nova

Numa instalação recém-criada a galeria nasce vazia e explica o caminho: criar um pacote pelo Assistente, desenhar um no modo Avançado, ou registrar os fluxos de fontes externas rodando scripts/seed-extract-pipelines.sh — o mesmo script que o setup-datta.sh executa na Fase 7B de uma instalação nova (ver Fontes Externas).

2.7 Permissões

O gate da galeria é ANY-OF: GET /api/pipelines/summary aceita PIPELINE_VIEW ou DATTAX_EXECUTE, então quem só tem a permissão de executar continua enxergando o inventário do que pode rodar. Só toma a mensagem de permissão — em português, sem código HTTP na tela — quem não tem nenhuma das duas. Hoje o perfil Analista não tem nenhuma permissão PIPELINE_* (mas tem DATTAX_EXECUTE, e por isso abre a galeria) e o Usuário Avançado não tem PIPELINE_DELETE — ver RBAC para conceder.

3. Modo Assistente — Fluxo linear

3.1 Passo 1: Conexão

O picker lista conexões do connection-manager-service visíveis ao usuário (as PRIVATE dele + WORKSPACE + PUBLIC).

Se a conexão não existe:

• O botão + Nova conexão abre o dialog canônico (compiled/dattabi/InlineConnectionDialog.js, exposto como window.DattabiInlineConnection).
• Nota: no Assistente, o botão + Nova conexão redireciona para /configurar/conexoes (decisão de design, 2026-04-25). Crie a conexão lá e retorne.
• Após criar, o ACOC dispara scan em background; a conexão já aparece utilizável.

3.2 Passo 2: Schema / Tabela / Colunas

• Picker de schema (quando JDBC).
• Picker de tabela ou coleção/índice/label.
• Checkbox de colunas com preview inline (10 linhas).

3.3 Passo 3: Sink

A lista de destinos é filtrada por GET /api/pipelines/quick/capabilities: o assistente só oferece o que o motor sabe gravar, para nunca salvar um pacote que falharia na validação depois. Os destinos disponíveis são:

Também é possível não escolher sink: o resultado fica como Dataset lógico no catálogo, utilizável direto no DATTABI.

Também executam, e aparecem no modo Avançado:

• DATTA Search Engine (OpenSearch) — mesma implementação do destino OpenSearch, com mode (index/upsert/delete) e idColumn.
• DATTA Relational Engine e HDFS — gravam em Iceberg via Trino. No runner Spark eram saveAsTable no Impala/Hive e df.write em HDFS; sem Spark, o Iceberg é o destino analítico em que o dado gravado continua consultável pelo DATTABI.

Ainda não executam (declarados na paleta e bloqueados na validação, com o motivo em português): API REST, MongoDB, OpenShift e S3/MinIO como destino (S3 executa como origem, não como destino); LDAP e e-mail como origem; e as cinco análises estatísticas, com suporte já planejado. Antes eles não falhavam — passavam os dados adiante em silêncio, e o pacote terminava "com sucesso" sem ter feito nada.

3.3.1 Destino Neo4j: chaves, direção e relacionamentos

• Database é obrigatório. O banco de destino nunca é adivinhado; um destino sem database é recusado antes de gravar qualquer nó.
• Label e chave: Label do Nó e Propriedade Chave (MERGE). Sem preenchimento valem os padrões históricos (Entity e id) e a aplicação de cada padrão é registrada no log da execução. Atenção: esses padrões não são uma rede de segurança — a carga só é recusada quando as linhas não têm valor na chave; um dataset que por acaso tenha uma coluna id preenchida grava nós :Entity sem reclamar. Preencha os dois campos.
• Sintaxe coluna:propriedade nas duas chaves (do nó e do alvo): use quando o nome da coluna do fluxo difere do nome da propriedade no grafo — por exemplo cnpjBasico:empresaCnpj liga a coluna cnpjBasico à propriedade empresaCnpj do nó alvo. Sem os dois-pontos, coluna e propriedade têm o mesmo nome.
• Direção: SAIDA (padrão) grava (nó do pipeline)-[REL]->(nó alvo); ENTRADA inverte a seta — (nó alvo)-[REL]->(nó do pipeline). Qualquer outro valor é recusado. Nas duas direções quem dirige a busca é o nó que o pipeline acabou de gravar, então o custo acompanha o tamanho da carga, e não o do label alvo (que costuma ser a base de referência inteira).
• As arestas são da execução, não do label. Cada carga carimba nos nós que grava uma propriedade técnica dattaCargaId com o id daquela execução, e as arestas são criadas só a partir dela. Sem isso, uma execução religaria também os nós de execuções anteriores e de outros pipelines que gravam no mesmo label. A propriedade fica no nó e é sobrescrita na carga seguinte; ela só é gravada quando Criar Relacionamentos está ligado.
• O nó alvo nunca é criado. Ele é sempre procurado; registro sem correspondente fica sem aresta, e isso é intencional — a carga não inventa nós fantasma na base de referência.
• A gravação é sempre idempotente (MERGE pela chave), então reexecutar não duplica. O formulário deste destino não tem campo de modo de escrita; ele só aparece em pacotes importados ou montados por API. Se o pacote declarar append — que no motor antigo significava criar um conjunto novo de nós a cada execução —, a execução termina normalmente e o run traz o aviso Modo de escrita ignorado, para você corrigir a declaração do pacote em vez de o modo fingir que foi honrado.

3.4 Canvas do pipeline gerado

Ainda no passo 3, ao lado do resumo, o cartão Pipeline gerado desenha o pipeline que será criado a partir das suas escolhas — origem, cada transformação na ordem e o destino, ligados pelas setas.

• O desenho vem de POST /api/pipelines/quick/preview: o backend faz a mesma conversão que faria ao salvar, mas não grava e não executa nada. Assim o canvas mostra o pipeline de verdade, não uma aproximação desenhada no navegador.
• Atualiza sozinho enquanto você mexe nos passos (com um pequeno atraso), com indicador de carregamento.
• Ver pipeline abre o mesmo canvas em tela cheia.
• Clicar em um nó seleciona a etapa correspondente: aparece a barra "Etapa selecionada" com atalho para a mesa de trabalho daquela transformação.
• O canvas é somente leitura — dá para aproximar, afastar, arrastar e usar Ajustar à tela, mas não se move nem se apaga nó por ali; a edição continua nos passos do assistente.
• Se o desenho não puder ser montado (serviço fora do ar, por exemplo), o cartão diz isso em português com Tentar novamente, e o resumo em forma de etiquetas continua disponível. Nada de pipeline inventado.

3.5 Abrir um pacote existente no Assistente

Hoje não há como abrir um pacote existente no Assistente. Todo pacote abre no modo Avançado (§2.3), e as duas vias que pareceriam levar ao Assistente redirecionam para o canvas:

• Endereço direto /pipeline-designer.html?modo=simples&id=<id-do-pacote> (e o antigo /pipeline-quick.html?id=…): o Assistente lê o id no boot e troca para o modo Avançado em vez de hidratar o wizard.
• Trocar de modo com o pacote aberto: a troca só reescreve o ?modo= na URL e avisa que alterações não salvas serão descartadas — nada do pacote em memória é passado adiante. Com ?id= na URL, volta ao canvas; sem ?id=, o Assistente abre em branco.

O código de hidratação existe (hydrateFromDefinition/openPipeline, com os rótulos Editando pacote e Salvar alterações, o aviso de rascunho em andamento e o desvio Abrir no Designer para grafo não linear), mas está inalcançável: openPipeline só roda a partir de requestOpen, que não é chamado em lugar nenhum nem é exportado.

3.6 Ao terminar

• Executar cria e roda o pacote; ao final a tela oferece Ver na galeria, Abrir no Designer e Acompanhar execução.
• Salvar pacote grava sem executar, e oferece ir direto para a galeria.
• O antigo modal "Meus Pipelines" saiu: o botão Pacotes leva à galeria (§2), que é o único inventário.

4. Extract Pipeline (Designer)

/pipeline-designer.html + compiled/pipeline-designer.js.

4.1 Canvas

• Componentes como cards M3 ligados por conexões diretas.
• Drag-and-drop do sidebar esquerdo para o canvas.
• Não há auto-save: o desenho só é gravado no clique em Salvar. Justamente por isso, enquanto houver alteração não salva, fechar ou recarregar a aba dispara a confirmação do navegador.

4.2 Componentes disponíveis

Destino Neo4j — parâmetro Tamanho da transação (linhas)

Quantas linhas o Neo4j grava por transação. Vazio mantém o comportamento histórico: o lote inteiro vira uma transação só.

O parâmetro é distinto do tamanho do lote, que é quantas linhas seguem numa requisição. Um lote de 10.000 linhas pode virar dez transações de 1.000 — a requisição é a mesma, o que muda é quando o banco confirma.

Preencher importa em carga volumosa. O teto de memória de transação do Neo4j (db.memory.transaction.total.max) é a soma das transações vivas; sem fatiar, a carga inteira conta como uma. Foi o que derrubou a carga do CNPJ com 4,2 GiB de teto e de novo com 8 GiB — subir o teto adiou a falha de 78 para 131 minutos sem removê-la, a assinatura de teto contra causa que o teto não governa. O pacote CNPJ versionado usa 10.000 em todos os destinos de grafo.

Executar pacote do Extract

Encadeia pacotes: este nó roda outro pacote salvo como um passo do fluxo. Serve para quebrar uma carga grande em pacotes menores e reaproveitáveis — a carga do CNPJ, por exemplo, é uma sequência de etapas que já existem como pacotes independentes.

• Pacote a executar lista os pacotes salvos. O pacote atual não aparece na lista: um pacote que chama a si mesmo roda para sempre.
• Aguardar conclusão (padrão: ligado) segura o fluxo até o sub-pacote terminar. É o que dá ordem ao encadeamento — quem põe B depois de A quer que B veja o que A gravou. Desligado, o pacote é disparado e o fluxo segue; a falha do sub-pacote passa a chegar depois de ninguém estar olhando.
• Tempo máximo de espera limita a espera. Estourar o tempo não cancela o sub-pacote: ele continua rodando, e é este fluxo que para. Vazio usa 6 horas.
• Sub-pacote que falha faz o nó falhar. Seguir verde sobre uma carga que não aconteceu é pior que parar.
• O encadeamento tem teto de 5 níveis, e um pacote que já está na cadeia é recusado com o caminho inteiro na mensagem (a > b > a), para o operador ver onde o laço fecha.

As linhas que chegam ao nó são descartadas: ele ordena execução, não transporta dado. Ligá-lo depois de uma etapa é o que garante que ela terminou primeiro.

Caixa de colunas — parâmetro Colunas

Todo parâmetro que pede colunas (Selecionar Colunas, Remover Colunas, Ordenar, Remover Duplicatas, Concatenar, Remover Espaços, …) usa a mesma caixa, nos dois modos do Extract. Ela guarda uma lista de nomes — é o que o motor lê, e é a forma que aparece nos pacotes versionados: "columns": ["documento", "nome"].

• Marcar / desmarcar escolhe a coluna. A lista mostra primeiro as colunas já escolhidas, na ordem gravada, e abaixo as demais colunas detectadas na prévia da origem. Marcar todas e Limpar valem para a lista inteira.
• A ordem das marcadas é a ordem da saída em Selecionar Colunas e Concatenar. Arraste pela alça ⠿ para reordenar.
• O lápis edita o nome usado neste parâmetro — serve para acertar uma grafia ou digitar coluna que a prévia não trouxe. Ele não renomeia a coluna no destino: para isso existe a transformação Renomear Colunas.
• Adicionar coluna digita um nome à mão. É o caminho quando a origem ainda não rodou a prévia: sem colunas detectadas, a caixa continua preenchível.
• Nada marcado significa "todas as colunas" nos parâmetros opcionais (Remover Duplicatas, Remover Espaços). Onde o parâmetro é obrigatório, a caixa acusa Campo obrigatório enquanto nenhuma coluna estiver marcada.

Pacote salvo por versão anterior da tela podia gravar objetos no lugar dos nomes — nesse formato o executor não casava nenhuma coluna e o nó devolvia linhas vazias. Abrir o nó e mexer na caixa regrava no formato correto.

4.3 Modo avançado SQL

Em cada componente Source ou Transform, o toggle Modo avançado mostra o SQL / DATTAX gerado. O usuário pode editar livremente; o designer mantém o contrato de outputs (se a edição quebrar o schema, exibe mensagem PT-BR).

4.4 Undo / Redo

• Ctrl+Z / Ctrl+Y.
• Histórico em memória (últimos 50 passos).
• Fechar a aba sem salvar descarta o desenho — não fica rascunho guardado em lugar nenhum; o navegador pede confirmação antes (§4.1).

4.5 Agendar a execução — o botão Agendar na barra

O agendamento se define na mesma tela em que o pacote é montado. O botão Agendar, entre Salvar e Executar, abre o editor visual de repetição — o mesmo da aba Calendário: a cada N minutos/horas /dias, diária, semanal, mensal ou cron, com horários, dias, janela de validade e a prévia ao vivo das próximas execuções.

O rótulo do botão diz o que está gravado:

Duas regras que evitam gravar meia definição:

• Pacote ainda não salvo não pode ser agendado. O agendamento vive na definição gravada; o botão pede o salvamento primeiro, em português.
• Com alterações não salvas no desenho, a tela pergunta antes. O editor grava o agendamento sobre a versão já salva do pacote — o desenho aberto continua na tela e não vai junto. A pergunta aparece antes de qualquer gravação, e o próprio diálogo repete o aviso enquanto está aberto.

Nos dois sentidos as ações são independentes: salvar o agendamento não exige salvar o fluxo, e salvar o fluxo não apaga o agendamento — o Designer reenvia a definição completa (§4.7).

O agendamento salvo aqui é gravado no próprio pacote — é a mesma definição, não uma cópia — e a aba Calendário do Scheduler passa a mostrar as novas ocorrências assim que o calendário é recarregado.

Limitação conhecida — a coluna "Agendamento" da galeria. A galeria de Pacotes lê um resumo leve, que não carrega a repetição por inteiro: ela mostra a descrição completa apenas para pacotes antigos, agendados por expressão cron. Um pacote agendado pelo editor visual aparece como "Agendado", sem a descrição. E, num pacote antigo que passou a ser agendado pelo editor, a coluna continua exibindo a expressão cron anterior, que já não é a que dispara — a repetição que vale é sempre a mostrada no botão Agendar do Designer e na aba Calendário do Scheduler. Corrigir isso é mudança no resumo do pipeline-designer-service, não na tela.

Quem vê o botão. Só quem tem permissão de editar o pacote (PIPELINE_CREATE, ou perfil administrador). Sem ela o botão não aparece, e uma tentativa por acesso direto recebe a recusa em português — sem código HTTP na tela. Ver RBAC.

Os mesmos três caminhos, um só editor. O componente (compiled/pipeline-schedule-editor.js) é carregado pelo Designer, pela aba Calendário do Scheduler e pela galeria de Pacotes. Não existem três telas de agendamento para divergirem entre si.

Como o agendamento é executado:

• Manual: executa só ao clicar em Executar.
• Agendado: agendamento de pipelines dispara pela mesma conta que calcula a prévia — o horário mostrado é o horário que roda.
• Event: dispara quando outro pipeline termina (lineage).

4.6 Acompanhar a execução no próprio canvas

Com um pacote em execução, o Designer vira a tela de acompanhamento: o diagrama que você desenhou continua à vista e cada caixa mostra o que está acontecendo nela. Não há mais janela por cima do desenho.

O que aparece no canvas enquanto a carga roda:

Por que existe a etiqueta "parcial". O motor é preguiçoso: nenhuma linha atravessa o fluxo até um destino puxar. Enquanto houver destino trabalhando, o número de quem está antes dele no desenho é um retrato do meio do caminho — e seria enganoso mostrá-lo como total final. Quando o último destino termina, as etiquetas somem e os números exibidos são os definitivos, iguais aos que ficam no histórico.

Número que sobe, não barra que enche. Cada caixa mostra quantas linhas passaram por ela até agora — nunca uma porcentagem, e nunca uma barrinha de progresso por etapa. O motor lê a origem em fluxo, sem contar antes quantas linhas existem, então uma porcentagem por caixa só poderia ser chute. O que a tela mostra é contagem medida: sobe enquanto a carga anda e nunca anda para trás. A única fração exata da tela é a do topo do passo a passo — quantas etapas já fecharam, do total do pacote —, e ela fecha por conclusão ou falha de etapa, não por linha processada.

Quando a carga é dividida entre vários trabalhadores

Quando a origem permite, a plataforma divide a leitura em pedaços e entrega cada pedaço a um trabalhador diferente, para a carga terminar mais rápido. O canvas acende do mesmo jeito. Cada caixa mostra o total do fluxo naquele ponto — a soma do que cada pedaço já reportou —, e não o número de um trabalhador isolado. É por isso que a etiqueta parcial costuma demorar mais a sumir numa carga dividida: ela só cai quando o último pedaço fecha.

O que muda em relação à carga que roda num lugar só:

• Os números aparecem em passos um pouco mais espaçados. Cada trabalhador manda notícia de tempos em tempos; a tela junta o que chegou. O número nunca anda para trás: cada notícia substitui a anterior daquele pedaço, não se soma a ela.
• Uma caixa só fica verde quando todos os pedaços que passaram por ela terminaram. Enquanto qualquer um estiver trabalhando, ela continua azul.
• Um pedaço que falha pinta a caixa de vermelho, não de verde, e a mensagem diz qual pedaço falhou. Concluído com um pedaço estourado seria a pior informação possível nesta tela.
• Caixa sem medição fica sem números — nunca 0 → 0. Um ramo que a carga ainda não alcançou aparece só com o nome. Zero é uma afirmação; ausência de medição não é.
• Se o acompanhamento ao vivo cair no meio, a carga continua normalmente e a tela avisa em português que parou de receber notícias, em vez de exibir números velhos como se fossem de agora.

O detalhamento por nó dessa carga também fica guardado no histórico: depois que ela termina, a tabela Execução por Nó do Job Monitor mostra a quebra por caixa. Cargas divididas que rodaram antes desta versão continuam sem esse detalhe no histórico — o dado não chegou a ser gravado na época, e não há como recuperá-lo depois.

Por que às vezes a carga roda num lugar só

Dividir a leitura só vale quando dividir não muda o resultado. Alguns passos precisam ver o conjunto inteiro para dar a resposta certa — remover duplicados, ordenar, limitar a N linhas, cruzar com outra tabela. Se um passo desses ficar depois de uma origem que foi dividida, cada pedaço enxergaria só a própria fatia e o resultado sairia errado sem erro nenhum na tela. Nesse caso a plataforma recusa dividir e executa a carga inteira num lugar só.

O que mudou: a recusa passou a olhar onde o passo está, e não apenas se ele existe no fluxo. Deduplicar uma tabela de domínio pequena, que é lida inteira de ponta a ponta, não tem como errar — e por isso deixou de vetar o fluxo todo. Na prática, um pacote grande não vai mais para um único lugar por causa de uma caixa pequena no canto do desenho: o lado grande vai para os trabalhadores, o lado pequeno é resolvido antes, e o fluxo termina mais rápido.

O run diz o que aconteceu, em português: quantos ramos foram para os trabalhadores, quantos ficaram, e — quando a carga inteira ficou num lugar só — qual passo impediu a divisão e qual origem o alcança. Uma origem que a plataforma não sabe dividir (um arquivo baixado de um endereço na internet, por exemplo) também deixa a carga num lugar só, e o aviso diz isso com essas palavras.

O diagrama continua respondendo — em modo leitura

Com uma carga em voo o Designer não fica travado: dá para clicar em cada caixa e ler a configuração dela, arrastar as caixas para enxergar melhor o desenho, aproximar, afastar e ajustar à tela. O que não dá é alterar.

• Clicar numa caixa abre, no painel ao lado, a configuração daquela etapa — os mesmos campos de sempre, com os valores que estão valendo, só que sem aceitar digitação. Uma faixa no topo do painel diz por quê, e o link ‹ Passo a passo no cabeçalho devolve o acompanhamento. Clicar no fundo do canvas também volta para lá.
• Arrastar as caixas muda só o arranjo na sua tela; nada é gravado enquanto a carga roda. O arranjo novo é salvo junto com o pacote na primeira vez que você salvar, depois que a execução terminar.
• Enquanto a carga estiver em voo ficam fora: salvar, agendar, desfazer e refazer, pausar/retomar/arquivar, acrescentar etapa pela paleta, duplicar ou remover uma etapa, o preview de dados e a mesa de trabalho. Testar conexão continua valendo — ele não escreve nada. Ocultar o passo a passo esconde o painel, não libera a edição.
• Assim que a execução encerra — por conclusão, falha ou cancelamento — a edição volta sozinha, mesmo com o acompanhamento ainda aberto na tela.

Painel de passo a passo

Ao lado do canvas abre o passo a passo da execução: uma linha por acontecimento, em ordem, colorida por resultado — verde para o que deu certo, âmbar para aviso, vermelho para falha. Cada linha traz a hora, a etapa e, quando faz sentido, a contagem daquele momento.

• No topo do painel, o estado da execução, quantas etapas já fecharam do total do pacote e quantos eventos o passo a passo acumulou. A contagem de etapas fecha por conclusão ou falha — não é uma porcentagem de linhas, porque o motor só sabe quantas faltam depois de ler a origem inteira.
• Filtros por etapa e por nível, para isolar só o que interessa (por exemplo, apenas as falhas de um destino).
• Rolagem automática que acompanha o evento novo — e pausa sozinha quando você rola para trás para ler algo. O botão Acompanhar o fim volta a seguir.
• Cancelar execução encerra a carga no próximo lote; o passo a passo registra o cancelamento. Ver "Parar uma carga", logo abaixo.
• Fechar o painel esconde o passo a passo sem parar a carga — e, com a carga ainda em voo, sem devolver a edição: o diagrama continua sendo o da execução, agora com a configuração da etapa selecionada ao lado. Enquanto houver execução conhecida, o botão Acompanhar na barra de ferramentas traz o passo a passo de volta.

Parar uma carga

O pedido alcança a carga onde ela estiver. Não importa qual instância da plataforma atendeu o clique, nem se a leitura foi dividida entre vários trabalhadores: o pedido vale para todos. Os pedaços que ainda não começaram são abandonados; os que estão no meio param no ponto seguro seguinte. A execução termina como cancelada, nunca como "com falha" — cancelar não é um incidente a investigar.

A parada não é instantânea, e o motivo importa. As gravações no destino são feitas em lote. Cortar no meio de um lote deixaria o destino gravado pela metade, sem ninguém saber onde parou. Por isso a carga fecha o lote em andamento e só então encerra: em carga grande, esse intervalo pode ir de alguns segundos a alguns minutos. Nesse intervalo o acompanhamento continua vivo: o passo a passo segue recebendo eventos até o encerramento de fato, e é ele que diz quando acabou — não o clique.

O que fica gravado. Cancelar interrompe; não desfaz. O que já foi escrito continua no destino. Em carga para o grafo, o desfecho típico é nós gravados sem as ligações entre eles, porque as ligações são criadas depois dos nós, e sem o passo de pós-carga, que roda no fim de tudo. Trate a carga cancelada como incompleta, não como parcial-mas-consistente: repita quando quiser o resultado inteiro. Repetir é seguro nos destinos que gravam por chave (grafo e busca), porque reprocessar a mesma linha não duplica; num destino que apenas acrescenta linhas, confira o que ficou antes de disparar de novo.

Espaço temporário. Uma carga que lê de URL ou derrama em disco usa espaço temporário enquanto roda. Ao encerrar — por conclusão, falha ou cancelamento — esse espaço é liberado, e a liberação espera o arquivo ficar sem uso: apagar antes de o download terminar de soltar o arquivo não devolveria espaço nenhum. Vale saber, ao planejar uma carga grande de arquivos compactados, que o pico de disco é o dobro do que está sendo extraído naquele momento — o compactado e o extraído coexistem até a extração terminar.

Chegar no meio (ou depois) da execução

Abrir o Designer com um pacote já rodando cai direto no acompanhamento, com tudo que aconteceu antes reconstruído — a tela não começa do zero, e o diagrama já responde ao clique e ao arraste, em modo leitura (ver acima). Um pacote já encerrado mostra o passo a passo completo, com os números finais e nenhuma etiqueta de parcial — e, como não há mais carga em voo, a edição está liberada.

O passo a passo é guardado por algumas horas depois do fim da execução. Passado esse prazo, a tela mostra o resumo registrado no histórico e avisa, em português, que o detalhamento não está mais disponível — em vez de exibir uma lista vazia sem explicação.

Quando a conexão ao vivo cai

O acompanhamento chega por um canal contínuo. Se ele cair (rede instável, aba suspensa, serviço reiniciando), a tela não finge estar viva: aparece o aviso "A conexão ao vivo caiu. Atualizando a cada 3 segundos até ela voltar", a tela passa a reler o passo a passo periodicamente e volta sozinha ao modo ao vivo assim que a conexão retorna.

Onde ver o histórico de todas as execuções

A aba Job Monitor (DATTA Extract › Scheduler, aba Job Monitor) lista as execuções de todos os pacotes, com status, duração, quem disparou, os avisos, o erro com a etapa em que aconteceu e o detalhamento por nó — quando a execução registrou esse detalhamento; quando não registrou, a tela diz isso em vez de preencher com número plausível. Não há visualizador de logs nessa aba: o detalhe linha a linha é o passo a passo descrito acima, e ele é daquele pacote. Ver Job Monitor.

As outras duas abas da mesma tela respondem o resto: o Calendário mostra o mês inteiro — o que já rodou e o que vai rodar — e o Motor, para quem administra a plataforma, mostra o estado do agendador e permite pausar um pacote.

Não há timeout de execução. O pacote grava ExecutionPolicy.timeoutSeconds (default 300s; os pacotes versionados de fontes externas declaram 3600s), mas nada lê esse campo: nem motor de execução de pipelines nem o GraphExecutor aplicam qualquer limite de tempo. O único timeout no caminho é o de rede do UrlDownloader. Uma execução travada numa fonte lenta fica pendurada até alguém intervir.

Avisos da execução — leia antes de dar a carga por boa

Uma execução pode terminar Concluída e ainda assim não ter feito o que você esperava: o percurso não falhou, mas o dado se perdeu no caminho. Quando o motor percebe isso, ele diz — o run traz uma lista de avisos, e cada um aponta onde olhar. Os mesmos avisos aparecem em âmbar no passo a passo (§4.6), na hora em que acontecem.

Nenhum desses avisos interrompe a execução: uma carga legitimamente vazia — o dia em que a fonte não publicou nada — não é defeito, e por isso o motor informa em vez de falhar.

4.7 Abrir um pipeline existente no Designer

Clicar em um pacote com editor = DESIGNER na galeria (§2.3) carrega o fluxo inteiro no canvas: nós nas posições originais, rótulos, configuração de cada componente e as arestas. É assim que os fluxos de fontes externas (CVM e base negativa) passam a ser editáveis pela interface.

• Enquanto carrega, a tela mostra Abrindo pipeline…; se demorar demais ou falhar, aparece uma mensagem em português com Tentar novamente e Começar um pipeline em branco — nunca um canvas vazio sem explicação.
• Um chip no topo mostra o nome do pipeline aberto, e a trilha de navegação ganha esse nome como último elo.
• O chip tem um × que fecha o pacote e devolve o canvas em branco, sem sair da tela. Com alterações não salvas, ele pergunta antes o que fazer com elas: Continuar editando (nada muda), Descartar alterações (fecha e perde o que não foi salvo) ou Salvar e fechar (grava e só então fecha — se a gravação falhar, o pacote continua aberto com tudo na tela). Sem alteração pendente não há pergunta: o pacote fecha direto. Fechar também tira o ?id= do endereço, para um F5 não ressuscitar o pacote recém-fechado.
• Nó cujo tipo de conector não existe no catálogo desta instalação gera um aviso, em vez de desaparecer silenciosamente do desenho.
• Ao salvar, o Designer reenvia a definição completa — descrição, agendamento, política de execução, metadados e versão são preservados, e o pacote não é desagendado por engano.
• O mesmo pipeline também abre por endereço direto: /pipeline-designer.html?id=<id-do-pacote>.

5. Conexões inline

Os 4 entry points (DATTABI, modo Avançado, Assistente, Catalog) usam o mesmo componente canônico (InlineConnectionDialog.js) sem duplicação. A criação segue as Diretrizes do Projeto item 7:

1. Fingerprint sha256(type+host+port+db+user).
2. POST para /api/connections/ensure (idempotente).
3. CredentialBinding por usuário no CredentialVault.
4. O ACOC dispara scan assíncrono.
5. A resposta ao frontend traz connectionId e link SSE para acompanhar o scan.

6. Materialização pós-extract

Não existe um passo de materialização depois da execução. Quem grava é o nó de destino do próprio pacote, durante o run, no motor unificado (motor de execução de pipelines → GraphExecutor) — ver §3.3 para o que cada destino faz. Não há botão "Materializar agora" nem lineage de execução em grafo.

A materialização de datasets do DATTABI é outra coisa, no dattabi-service — é de lá que saem os dashboards e charts com refresh AFTER_MATERIALIZATION.

7. Troubleshooting

8. Referências

• Pacotes (galeria): /pipeline-pacotes.html — GET /api/pipelines/summary.
• Pipeline Designer: pipeline-designer-service.
• Modo Assistente: reusa o mesmo backend; canvas via POST /api/pipelines/quick/preview.
• Canvas somente leitura compartilhado pela galeria e pelo Assistente: compiled/pipeline-canvas.js + pipeline-canvas.css (window.DattaPipelineCanvas).
• Fontes externas (CVM, base negativa): Fontes Externas de Dados Abertos, Base Negativa Pública.
• Permissões: Roles e Permissões — Controle de Acesso.
• Connection: Gerenciamento de Conexões — Guia do Usuário.
• Catalog: catalog-service.
• DATTAX engine: DATTAX — Guia da Linguagem.
• Drivers admin: Drivers JDBC — Catálogo Oficial e Governança.