Matricule-se
Voltar para o blog
Python

DuckDB no Python: guia completo para análise de dados

Rodrigo Silva Harder

Aprenda a usar o DuckDB no Python para ler, filtrar e agregar bases de dados enormes com muito mais velocidade.

Introdução ao DuckDB no Python

Fala, impressionador(a)!

Se você já tentou carregar um arquivo CSV de vários gigabytes no Pandas e viu o computador travar, ou simplesmente demorar minutos para processar algo que deveria ser rápido, você está no lugar certo.

Existe uma ferramenta chamada DuckDB que resolve exatamente esse problema. Ela permite que você execute comandos SQL diretamente sobre arquivos CSV, Parquet e JSON, sem precisar transformar nada, sem instalar servidor e com uma velocidade que vai te surpreender na primeira vez que você usar.

Neste guia, você vai aprender do zero: o que é o DuckDB, como instalar, como usar as principais operações e, principalmente, quando faz sentido combiná-lo com o Pandas no seu fluxo de análise de dados.

Então, vem comigo!

Para fazer o download dos exercícios e soluções, preencha com o seu e-mail:

Não vamos te encaminhar nenhum tipo de SPAM! A Hashtag Treinamentos é uma empresa preocupada com a proteção de seus dados e realiza o tratamento de acordo com a Lei Geral de Proteção de Dados (Lei n. 13.709/18). Qualquer dúvida, nos contate.

O que é o DuckDB?

O DuckDB é um sistema de banco de dados projetado para análise de dados. Pensa nele como um SQLite turbinado,  mas com foco em velocidade para operações analíticas, como filtros, agrupamentos e junções de tabelas.

A grande diferença em relação a outras ferramentas de banco de dados é que você não precisa instalar servidor nenhum. Basta instalar a biblioteca Python e começar a usar.

Mas há algo que o DuckDB faz que é diferente de quase tudo: ele consegue ler arquivos CSV, Parquet e JSON diretamente, tratando-os como se fossem tabelas de um banco de dados. Você não precisa importar o arquivo para depois consultá-lo. O DuckDB já faz isso por você de forma muito eficiente.

Por que o DuckDB é tão rápido?

 Existem três motivos principais que tornam o DuckDB tão rápido:

Processamento por colunas

O Pandas e o NumPy trabalham linha por linha. Para somar todos os valores de uma coluna, o Pandas percorre cada linha do arquivo, passando por todas as colunas de cada uma.

O DuckDB funciona diferente. Ele organiza os dados por colunas, não por linhas. Para somar a coluna valor, ele acessa só essa coluna diretamente, sem precisar "ver" as outras. Isso é chamado de armazenamento colunar e é muito mais eficiente para análises.

Processamento paralelo

Por padrão, o Python processa as coisas em sequência: termina uma tarefa, começa a próxima. O DuckDB divide automaticamente o trabalho entre os núcleos do seu processador. Se você tem 8 cores disponíveis, ele usa todos ao mesmo tempo. Resultado: operações que demorariam minutos ficam prontas em segundos.

Streaming automático para bases gigantes

Se você tentar carregar um arquivo de 40 GB no Pandas com 32 GB de RAM, o Python vai travar. O Pandas precisa carregar tudo na memória de uma vez.

O DuckDB faz diferente. Ele processa os dados em partes — carrega um pedaço, processa, descarta da memória e vai para o próximo. Isso acontece automaticamente, sem você precisar configurar nada. Por isso, o DuckDB consegue trabalhar com arquivos maiores do que a memória disponível.

Como instalar e importar o DuckDB

Para instalar o DuckDB você precisa fazer o mesmo procedimento de qualquer biblioteca Python: Abra o terminal integrado do seu editor de código, por exemplo, VS Code e rode o seguinte comando:

Codigo
pip install duckdb

Para utilizá-lo no seu código ou notebook basta usar a expressão:

Python
import duckdb
Ícone PythonPython Impressionador

Você vai aprender a linguagem de Programação que mais cresce no Mundo para fazer automações incríveis, desenvolver sites, fazer análises de dados, trabalhar com Ciência de Dados, Inteligência Artificial, mesmo que você nunca tenha tido nenhum contato com Programação na vida.

Começar agoraSeta para a direita
Fundo PythonTelas Python
Luz Python

Lendo arquivos CSV com DuckDB

Para testar os DuckDB, você pode baixar a base de dados ("vendas_gigante.csv") e os demais arquivos com o gabarito diretamente no material disponível pra download.

Em seguida, basta descompactar a pasta e abri-la no editor de código de sua preferência, usaremos o VSCode.

Além disso, para deixar a experiência mais visual, podemos utilizar um arquivo com extensão ipynb para criar um notebook Jupyter.

Geralmente para fazer a leitura de uma base de dados CSV usamos o Pandas com o seguinte comando:

Python
import pandas as pd
df = pd.read_csv("vendas_gigante.csv")

Funciona bem para arquivos pequenos. Mas para arquivos grandes, o Pandas pode demorar vários segundos, ou até minutos, e ainda vai ocupar toda a sua memória RAM com o arquivo.

Com o DuckDB, o processo é diferente:

Python
import duckdb
resultado = duckdb.sql("SELECT * FROM 'vendas_gigante.csv'")
display(resultado)

Quando você executa duckdb.sql("SELECT * FROM 'vendas_gigante.csv'"), o DuckDB interpreta automaticamente o arquivo CSV como se fosse uma tabela dentro de um banco de dados. Ou seja, o nome do arquivo entre aspas simples na query é tratado como uma fonte de dados tabular.

Internamente, o DuckDB utiliza um leitor de CSV otimizado e executa a consulta diretamente sobre o arquivo, sem precisar fazer uma importação completa. Ele aplica técnicas como leitura sob demanda (lazy loading) e processamento vetorizado, o que significa que os dados são lidos em partes, conforme necessário para responder à consulta. Além disso, ele pode paralelizar a leitura, aproveitando melhor os recursos do computador.

Filtrando dados com DuckDB

Imagine que você precisa filtrar apenas as vendas com status "Ativo". No Pandas, você faria assim:

Codigo
df_ativos = df[df["status"] == "Ativo"]

Com o DuckDB, você aplica o filtro direto na leitura do arquivo, sem nem precisar carregar a base completa:

Codigo
resultado = duckdb.sql("""
    SELECT *
    FROM 'vendas_gigante.csv'
    WHERE status = 'Ativo'
""")

Convertendo o resultado para um DataFrame do Pandas

Depois de fazer as operações pesadas no DuckDB, você pode converter o resultado para um DataFrame normal do Pandas e continuar o seu fluxo de trabalho:

Codigo
df_duckdb = resultado.df()

Agora df_duckdb é um DataFrame do Pandas com apenas os dados filtrados. Como ele é muito menor do que a base original, o Pandas lida com ele sem problemas.

Além do .df(), o DuckDB oferece outros formatos de saída:

  • Dataframe do Polars: resultado.pl();
  • Lista de tuplas (padrão SQL): resultado.fetchall();
  • Array NumPy: resultado.fetchnumpy().

Essa flexibilidade é intencional: o DuckDB foi feito para se encaixar em qualquer fluxo de análise de dados do Python.

Fazendo agregações com DuckDB

Suponha que você quer calcular a média de quantidade vendida por categoria de produto. No Pandas:

Codigo
df_media_vendas = df.groupby("categoria")["qtd"].mean()
display(df_media_vendas)

No DuckDB, você escreve o equivalente em SQL:

Codigo
resultado_media = duckdb.sql("""
SELECT
    categoria,
    AVG(qtd) as media_vendas
FROM df
GROUP BY categoria
""")
display(resultado_media)

Criando bancos de dados com DuckDB

O DuckDB também pode ser utilizado como um banco de dados persistente, de forma semelhante ao SQLite. A principal diferença entre os dois está na forma de executar os comandos SQL e na simplicidade da API.

Exemplo com DuckDB:

Python
import duckdb

conn = duckdb.connect("meu_banco.db")

conn.sql("""
   CREATE TABLE usuarios (
       id INTEGER,
       nome VARCHAR
   )
""")

conn.sql("INSERT INTO usuarios VALUES (1, 'Lira')")

resultado = conn.sql("SELECT * FROM usuarios")
resultado.show()

conn.close()

No DuckDB, a própria conexão já executa os comandos SQL diretamente com o método .sql(), sem a necessidade de criar um cursor separado. Isso deixa o código mais simples e direto.

Exemplo equivalente com SQLite:

Python
import sqlite3

conn = sqlite3.connect("meu_banco.db")
cursor = conn.cursor()

cursor.execute("""
   CREATE TABLE usuarios (
       id INTEGER,
       nome TEXT
   )
""")

cursor.execute("INSERT INTO usuarios VALUES (1, 'Lira')")

conn.commit()

cursor.execute("SELECT * FROM usuarios")
resultado = cursor.fetchall()

print(resultado)

conn.close()

No SQLite, é necessário criar um cursor para executar os comandos SQL. Além disso, após operações de escrita (como INSERT), é preciso chamar commit() para salvar as alterações no banco.

Em ambos os casos, o arquivo meu_banco.db é criado na pasta do projeto e pode ser reutilizado posteriormente. A diferença principal é que o DuckDB oferece uma API mais enxuta e direta, enquanto o SQLite segue um padrão mais tradicional de conexão + cursor.

Quando usar DuckDB e quando usar Pandas

Essa é a pergunta mais importante: você deve substituir o Pandas pelo DuckDB? A resposta é não. Os dois são ferramentas complementares.

Use o DuckDB quando:

  • Precisar ler arquivos CSV, Parquet ou JSON muito grandes;
  • Quiser filtrar dados antes de carregar na memória;
  • For fazer agregações como GROUP BY, AVG, SUM, COUNT;
  • For fazer junções entre tabelas (JOIN
  • Já conhecer SQL e quiser usar essa linguagem no Python.

Continue com o Pandas quando:

  • A base de dados já for pequena e estiver carregada;
  • Precisar de tratamentos complexos de colunas (engenharia de features);
  • For preparar dados para usar com Scikit-learn ou outras bibliotecas de Machine Learning;
  • Precisar de operações que o SQL não cobre facilmente.

O fluxo ideal é uma combinação dos dois:

  1. Use o DuckDB para ler e filtrar;
  2. Converta para DataFrame do Pandas com .df();
  3. Use o Pandas para tratamentos e transformações
  4. Alimente o Scikit-learn, Matplotlib ou qualquer outra biblioteca normalmente.

Conclusão - DuckDB ou Pandas?

O DuckDB não veio para substituir o Pandas. Ele veio para resolver um problema específico que o Pandas não resolve bem: processar bases de dados grandes com velocidade e sem consumir toda a memória do computador.

Com apenas pip install duckdb e alguns comandos SQL, você consegue ler arquivos gigantes em segundos, filtrar e agregar dados antes mesmo de carregá-los na memória, e converter o resultado para um DataFrame do Pandas quando precisar continuar o trabalho com as ferramentas que você já conhece.

Caso queira aprender ainda mais sobre Python, você pode fazer o minicurso gratuito de análise de dados no Pyhton e o Curso de Python Impressionador.

Além disso, se preferir esse conteúdo no formato de vídeo-aula, assista ao vídeo abaixo ou acesse o nosso canal do YouTube!

Hashtag Treinamentos

Para acessar outras publicações de Python, clique aqui!

Quer aprender mais sobre Python com um minicurso básico gratuito?

Posts mais recentes de Python

Posts mais recentes da Hashtag Treinamentos

Rodrigo Silva Harder

Autor do artigo

Rodrigo Silva Harder

Redator de conteúdo na Hashtag Treinamentos. Produzo textos didáticos sobre tecnologia, buscando informar e engajar o público de forma acessível e descomplicada.

Ver mais posts