quality gate¶

controle

valida um conjunto de regras de qualidade sobre o dataset completo e decide se o pipeline continua ou é bloqueado. não persiste nenhum dado — é uma barreira, não um destino. a persistência acontece depois, no lakehouse writer.

este é o nó canônico de qualidade da plataforma — substitui o antigo nó "staging" (veja staging para a nota de compatibilidade).

quando usar¶

bloquear a gravação no lakehouse quando o dataset não atende a critérios mínimos de qualidade (ex: nenhuma linha, coluna obrigatória com nulos, duplicatas em uma chave)
validar uma regra de negócio arbitrária via sql customizado antes de considerar os dados prontos para persistir
como última barreira do pipeline, logo antes do lakehouse writer

configuração¶

campo	tipo	obrigatório	descrição
`rules`	lista de regras	sim	uma ou mais regras de qualidade avaliadas sobre o dataset
`fail_on_error`	bool	sim	se `true`, qualquer regra que falhe interrompe o pipeline · padrão: `true`
`description`	string	não	nota livre exibida na interface, para documentar o propósito do gate

tipos de regra (`rules[]`)¶

tipo	campos usados	o que valida
`not_null`	`column`	a coluna não pode ter nenhum valor nulo no dataset
`unique`	`column`	a coluna não pode ter valores duplicados
`min_rows`	`value`	o dataset deve ter pelo menos `value` linhas
`max_rows`	`value`	o dataset deve ter no máximo `value` linhas
`custom_sql`	`sql`	sql arbitrário — se a consulta retornar linhas, é considerado uma violação

todas as regras aceitam um campo opcional label, usado para identificar a regra no relatório de execução.

exemplo¶

{
  "fail_on_error": true,
  "rules": [
    { "type": "not_null", "column": "cliente_id", "label": "cliente_id obrigatório" },
    { "type": "unique", "column": "pedido_id", "label": "pedido_id único" },
    { "type": "min_rows", "value": 1, "label": "dataset não pode ser vazio" },
    {
      "type": "custom_sql",
      "sql": "SELECT * FROM {{upstream}} WHERE valor < 0",
      "label": "nenhum valor negativo"
    }
  ]
}

se qualquer regra falhar, o pipeline é interrompido com uma mensagem detalhando qual regra e quantas linhas violaram.

modo não bloqueante¶

{
  "fail_on_error": false,
  "rules": [
    { "type": "not_null", "column": "telefone", "label": "telefone preenchido" }
  ]
}

com fail_on_error: false, o resultado da validação aparece no log de execução, mas o pipeline segue adiante mesmo que a regra falhe — útil para monitorar qualidade sem bloquear operação enquanto uma fonte ainda está instável.

quality gate vs. validar schema¶

nó	atua sobre	granularidade
validar schema	cada linha individualmente	pode descartar linhas específicas e deixar as demais passarem
quality gate (este nó)	o dataset como um todo	decide passar ou bloquear o lote inteiro; não descarta linhas

um padrão comum é usar validar schema para limpar linha a linha logo após a fonte, e um quality gate como última barreira, logo antes do lakehouse writer.