SQL (DuckDB)

O nó SQL é a ferramenta mais poderosa e recomendada para transformação de dados no HorusETL. Ele utiliza o motor DuckDB embutido para executar consultas analíticas (OLAP) de altíssima performance diretamente em memória.

TIP

Por que usar DuckDB? Tudo que você conseguir fazer via SQL no DuckDB será o mais rápido possível. Para lógicas que SQL não resolve bem (expressões regulares complexas, integrações com APIs, machine learning), use o nó Python. Para operações puramente SQL (JOINs, GROUP BY, Window Functions), o DuckDB supera o Python em performance.

Ambiente de Execução

• Motor: DuckDB (Altamente compatível com o dialeto PostgreSQL)
• Abstração: Os dados de entrada são convertidos automaticamente em Tabelas Temporárias disponíveis para consulta imediata
• Case Sensitivity: Para garantir consistência no ambiente de dados do Horus, todas as referências a colunas devem ser feitas em MAIÚSCULAS

Configuração

1. Alias de Entrada

Ao conectar múltiplos fluxos a este nó, você deve identificar cada um:

• Padrão: Se não configurado, os inputs recebem nomes sequenciais: input_0, input_1, input_2
• Customizado: Você pode (e deve) dar apelidos semânticos na aba de conexões (mudar input_0 para VENDAS e input_1 para CLIENTES)

2. Consulta SQL

Escreva qualquer consulta SQL válida. O resultado do SELECT final será o output do nó.

Melhores Práticas e Exemplos

O editor conta com um assistente de IA que segue princípios rígidos de engenharia de dados. Abaixo estão padrões recomendados:

Exemplo 1: Join e Agregação

-- Seleciona vendas e cruza com metas
SELECT
    v.ID_VENDEDOR,
    v.NOME,
    SUM(v.VALOR) as TOTAL_VENDAS,
    MAX(m.META) as META_ALVO,
    
    -- Lógica de negócio via CASE
    CASE 
        WHEN SUM(v.VALOR) >= MAX(m.META) THEN 'ATINGIU' 
        ELSE 'NAO ATINGIU' 
    END as STATUS_META

FROM VENDAS v
LEFT JOIN METAS m ON v.ID_VENDEDOR = m.ID_VENDEDOR
-- Sempre filtre antes de agrupar para performance
WHERE v.DATA_VENDA >= '2024-01-01'
GROUP BY v.ID_VENDEDOR, v.NOME

Exemplo 2: Consultas Complexas (CTE)

Para lógicas complexas, prefira usar CTEs (WITH) ao invés de sub-queries aninhadas. Isso melhora a legibilidade e a manutenção.

-- 1. Calcula o total por vendedor (Tabela Temporária Lógica)
WITH VendasAgregadas AS (
    SELECT 
        ID_VENDEDOR, 
        SUM(VALOR) as VALOR_TOTAL
    FROM input_0
    GROUP BY ID_VENDEDOR
),

-- 2. Cria um ranking baseado no valor total
Ranking AS (
    SELECT
        ID_VENDEDOR,
        VALOR_TOTAL,
        -- Window Function do DuckDB
        ROW_NUMBER() OVER (ORDER BY VALOR_TOTAL DESC) as POSICAO
    FROM VendasAgregadas
)

-- 3. Seleciona apenas o TOP 10
SELECT * 
FROM Ranking
WHERE POSICAO <= 10
ORDER BY POSICAO ASC

Exemplo 3: Extração de JSON (Sintaxe Simplificada)

Use o operador ->> para extrair texto e -> para extrair objetos/arrays.

SELECT
    ID, 
    -- Sintaxe de seta (similar ao Postgres)
    RESPOSTA_API->>'$.status' as STATUS_API,
    
    -- Casting direto
    (RESPOSTA_API->>'$.data.metrics.total')::DOUBLE as TOTAL
FROM input_0
WHERE json_valid(RESPOSTA_API) -- Garante que é um JSON válido

Exemplo 4: Explodir Array JSON (Lateral Join)

Se a API retorna uma lista de itens dentro de um único registro e você quer transformar isso em várias linhas (uma por item), use a função json_each combinada com LATERAL.

SELECT 
    t.ID,
    -- Extrai campos de dentro do objeto do array (que está na coluna 'value' do json_each)
    item.value->>'$.produto_id' as PRODUTO_ID,
    item.value->>'$.quantidade' as QTD
FROM input_0 t,
-- Explode o array "itens" do JSON em novas linhas
LATERAL (SELECT value FROM json_each(t.RESPOSTA_API->'$.itens')) as item

TIP

Performance:

• O DuckDB é colunar e vetorizado. Diferente do Python, ele não precisa serializar dados para uma linguagem externa.
• Sempre que possível, prefira resolver transformações via SQL (Joins, Filtros, Agregações, Window Functions) antes de recorrer a scripts Python ou C#.