DuckDB: O Motor Analítico da Sua Stack — SQL de Alta Performance Integrado ao Python

Este guia foca no "músculo" analítico da sua stack: o DuckDB. Se o Polars é o motor de transformação procedural, o DuckDB é o motor de consulta SQL de alta performance. Ele é frequentemente chamado de "SQLite para Analytics", mas com um motor OLAP colunar que processa dados na velocidade do hardware.

Vamos integrar o DuckDB ao fluxo que já construímos, permitindo que você alterne entre Python e SQL puro sem qualquer custo de performance.

1. Instalando o DuckDB com uv

Existem duas formas complementares de usar o DuckDB: como uma ferramenta de terminal (CLI) para exploração rápida e como uma biblioteca Python para integração em pipelines.

# 1. Instale o CLI globalmente (para consultar arquivos sem abrir o Python)
uv tool install duckdb

# 2. Adicione a biblioteca ao seu projeto atual
uv add duckdb

2. O Casamento Perfeito: Polars + DuckDB (Zero-Copy)

A maior vantagem dessa integração é que você não precisa escolher entre SQL e Python. Graças ao padrão Apache Arrow, o DuckDB pode consultar um DataFrame do Polars que está na sua memória sem copiar um único byte.

Exemplo: De Python para SQL em segundos

import polars as pl
import duckdb

# 1. Processamento inicial com Polars (ex: limpeza de strings complexas)
df_vendas = pl.read_parquet("vendas.parquet")

# 2. O DuckDB "enxerga" o DataFrame do Polars como uma tabela SQL nativa
# Não há cópia de dados aqui, apenas compartilhamento de ponteiros de memória
resultado_sql = duckdb.sql("""
    SELECT 
        vendedor, 
        SUM(valor) as total,
        RANK() OVER (ORDER BY SUM(valor) DESC) as ranking
    FROM df_vendas
    GROUP BY vendedor
""").pl() # Converte o resultado de volta para Polars instantaneamente

print(resultado_sql)

3. Consultas Complexas Diretamente no Terminal

O DuckDB brilha quando você precisa explorar arquivos (CSV, Parquet, JSON) sem nem criar um script. O CLI do DuckDB funciona como um banco de dados completo que vive em um único arquivo ou apenas na RAM.

Explorando arquivos locais com SQL

Abra o terminal e digite duckdb. Agora você pode usar o poder do SQL em arquivos soltos:

-- Consultar um grupo de CSVs como se fossem uma única tabela
SELECT * FROM 'dados/logs_*.csv' LIMIT 10;

-- Unir (Join) um CSV com um Parquet diretamente do disco
SELECT 
    l.timestamp, 
    u.nome 
FROM 'logs.csv' l
JOIN 'usuarios.parquet' u ON l.user_id = u.id
WHERE l.status = 'ERRO';

4. Power User: DuckDB + Cloud (S3 / GCS)

O DuckDB possui extensões que permitem consultar dados diretamente no seu Data Lake (S3, Google Cloud Storage ou Azure) sem precisar baixar os arquivos inteiros. Ele "puxa" apenas os bytes necessários das colunas solicitadas.

Configurando o acesso ao Google Cloud Storage:

No terminal DuckDB:

INSTALL httpfs;
LOAD httpfs;
-- Define as credenciais via arquivo JSON
SET google_cloud_storage_credential_file='/caminho/seu/token.json';

-- Consultar 100GB de dados na nuvem lendo apenas os metadados necessários
SELECT category, count(*) 
FROM 'gs://meu-bucket/telemetria/*.parquet'
GROUP BY 1;

5. Comparativo: Quando usar cada um?

Resumo do Workflow Híbrido

Para extrair o máximo de produtividade do seu hardware, seu fluxo deve ser:

1. uv para gerenciar o ambiente e as ferramentas de forma instantânea.
2. Polars para carregar e realizar a "limpeza pesada" dos dados brutos.
3. DuckDB para rodar aquele SQL analítico complexo que seria difícil de expressar em métodos de DataFrame.
4. Zero-Copy (Arrow) como a ponte invisível que une os dois mundos sem latência.

Dica de Performance: Sempre que possível, converta seus CSVs iniciais para Parquet usando o DuckDB (COPY (SELECT * FROM 'dados.csv') TO 'dados.parquet'). Isso reduzirá o tempo de leitura nas próximas análises em até 90%.