SQL (DuckDB)

Tipo

Referência

Para

Engenharia de dados, Desenvolvedor

Na tela

HorusETL › Dataflows › editor do Dataflow

Com uma consulta SQL, o nó SQL (DuckDB) transforma as entradas e devolve o resultado do SELECT. Cada entrada vira uma tabela, e a consulta roda num DuckDB em memória dentro do Agente ETL. É o nó indicado para filtrar, calcular colunas, agrupar, cruzar tabelas e aplicar funções de janela.

Na biblioteca	kind no YAML	Grupo	Entradas
SQL (DuckDB)	SQLProcessor	Transformações	uma ou mais

Campos

Na tela	No YAML (options)	Tipo	Padrão	Regra
Editar Código SQL	SQL	texto	vazio	Obrigatório. Vazio falha com "SQL não foi fornecido nos parâmetros."
Entradas	InputAliases	mapa posição → nome	input_0, input_1...	O nome de cada entrada como tabela no SQL. A chave é a posição da entrada, começando em "0"

- internalId: sql_vendas
  kind: SQLProcessor
  inputs: [ext_vendas, ext_metas]
  options:
    InputAliases:
      "0": VENDAS
      "1": METAS
    SQL: |
      SELECT v.ID_VENDEDOR, SUM(v.VALOR) AS TOTAL
      FROM VENDAS v
      WHERE v.DATA_VENDA >= '{StartDate:yyyy-MM-dd}'
      GROUP BY v.ID_VENDEDOR

O editor de código tem um assistente de IA que escreve a consulta a partir de uma descrição.

Como as entradas e a saída se comportam

• Entradas: cada entrada é gravada em Parquet e aberta como uma view. As colunas chegam com os nomes que o nó anterior entregou, em maiúsculas.
• Variáveis: {NOME} e {NOME:formato} são trocadas pelo valor antes de a consulta rodar, como texto. Ponha aspas quando o valor for texto ou data: '{StartDate:yyyy-MM-dd}'. A lista de variáveis está em Variáveis.
• Nomes da saída: vão para maiúsculas. Dois nomes iguais (dois ID vindos de um SELECT * com join) viram ID e ID_1. Dê um AS para cada coluna calculada.
• Tipos da saída: texto vira texto, data e data com hora viram data, hora vira texto, e todo o resto é tratado como número. Converta para VARCHAR antes de devolver o que não é número (booleano, UUID, lista, struct, JSON).

O dialeto é o do DuckDB, próximo do PostgreSQL. A documentação do DuckDB traz as funções.

Exemplos

Agregar antes de cruzar

Juntar duas tabelas de fato antes de agrupar multiplica as linhas: se um vendedor tem três vendas e duas metas, o join gera seis linhas, e o SUM conta cada venda duas vezes. Agregue cada lado numa CTE e cruze depois.

Explosao Cartesiana na PraticaDuckDB

Execute cada aba para ver o problema e entender por que o JOIN direto entre fatos multiplica os valores.

Schema

WITH vendas AS (
    SELECT ID_VENDEDOR, SUM(VALOR) AS TOTAL_VENDAS
    FROM VENDAS
    GROUP BY ID_VENDEDOR
),
metas AS (
    SELECT ID_VENDEDOR, SUM(META) AS META_ALVO
    FROM METAS
    GROUP BY ID_VENDEDOR
)
SELECT
    v.ID_VENDEDOR,
    v.TOTAL_VENDAS,
    m.META_ALVO,
    CASE WHEN v.TOTAL_VENDAS >= m.META_ALVO THEN 'ATINGIU' ELSE 'NAO ATINGIU' END AS STATUS_META
FROM vendas v
LEFT JOIN metas m ON m.ID_VENDEDOR = v.ID_VENDEDOR

Os três exemplos abaixo rodam no playground, sobre um input_0 de exemplo. O último usa unnest no lugar de json_each, porque o DuckDB do navegador não roda o LATERAL; o resultado é o mesmo.

Exemplos do nó SQLDuckDB

input_0 é a saída do nó anterior, aqui com quatro vendas e a resposta de uma API guardada como texto em RESPOSTA. Rode cada exemplo da página ou edite à vontade.

Schema

Ranking com função de janela

SELECT *
FROM (
    SELECT
        ID_VENDEDOR,
        SUM(VALOR) AS VALOR_TOTAL,
        ROW_NUMBER() OVER (ORDER BY SUM(VALOR) DESC) AS POSICAO
    FROM input_0
    GROUP BY ID_VENDEDOR
)
WHERE POSICAO <= 10

Ler um campo de JSON

Útil depois de uma Requisição HTTP que guardou a resposta como texto. ->> devolve texto, -> devolve JSON.

SELECT
    ID,
    RESPOSTA->>'$.status' AS STATUS,
    CAST(RESPOSTA->>'$.data.total' AS DOUBLE) AS TOTAL
FROM input_0
WHERE json_valid(RESPOSTA)

Uma linha por item de uma lista JSON

SELECT
    t.ID,
    item.value->>'$.produto_id' AS PRODUTO_ID,
    CAST(item.value->>'$.quantidade' AS DOUBLE) AS QTD
FROM input_0 t,
LATERAL (SELECT value FROM json_each(t.RESPOSTA->'$.itens')) AS item

Relacionado

• Transformações
• Python
• Variáveis

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.