Polars read_csv(): carregue dados CSV rapidamente no Python

Se você usa Python regularmente para análise de dados, como eu, logo percebe que ler arquivos CSV é uma das tarefas mais comuns. Porém, à medida que seus conjuntos de dados crescem, esse processo pode ficar lento ou consumir muita memória.

Polars é uma biblioteca de DataFrame rápida e moderna para Python, pensada como uma alternativa de alto desempenho ao Pandas. Ela lida com grandes volumes de dados com muito mais fluidez do que as ferramentas tradicionais, já que foi construída com foco em velocidade e baixo uso de memória.

A função principal pl.read_csv() do Polars oferece uma forma simples de carregar arquivos CSV em um DataFrame, com opções nativas para controlar o parsing, os tipos de dados e o consumo de memória.

Neste guia, eu vou mostrar como ler arquivos CSV, controlar o parsing e trabalhar com grandes volumes de dados usando a função pl.read_csv() do Polars. Se você está começando agora, confira nosso curso Introduction to Polars para aprender a manipular dados e extrair insights com Polars.

Uso básico do pl.read_csv()

Antes de avançar, veja nosso tutorial de Python Polars para configurar seu ambiente.

Agora, vamos ver como a função pl.read_csv() funciona:

# import the module
import polars as pl

# Load CSV into a Polars DataFrame
fuel_data = pl.read_csv("Fuel_Consumption_2000-2022.csv")  

# Preview first few rows
print(fuel_data.head())  

No exemplo acima, o Polars lê o arquivo e o carrega em um DataFrame. A função retorna um DataFrame do Polars, que é uma estrutura tabular de dados, semelhante ao que você teria no pandas.

Por padrão, pl.read_csv():

• Assume que a primeira linha contém os nomes das colunas (has_header=True)

• Faz a inferência automática dos tipos de dados das colunas

• Usa vírgula (,) como delimitador

• Lê o arquivo inteiro na memória

Parâmetros comuns em pl.read_csv()

Agora que você viu como o pl.read_csv() carrega os dados, vamos conhecer os parâmetros que permitem ajustar como o Polars faz o parsing do seu dataset.

Caminho e origem do arquivo

O Polars permite carregar dados de diferentes fontes. Você pode passar um caminho local como string, um objeto Pathlib ou até uma URL. Por exemplo, o código abaixo lê um arquivo CSV grande da web com o PIB de vários países em diversos anos.

# Reading from a URL
url = "https://raw.githubusercontent.com/datasets/gdp/master/data/gdp.csv"
gdp_data = pl.read_csv(url)

Delimitadores e separadores

Nem todos os arquivos CSV usam vírgulas. Você pode usar o argumento separator para lidar com tabulações, ponto e vírgula, pipes ou outros caracteres. O exemplo abaixo mostra como especificar separadores ao ler arquivos:

# Reading a Semicolon-separated file
sales_data = pl.read_csv("2024_sales.csv", separator=";")

# Reading a Tab-separated file (TSV)
orders_data = pl.read_csv("all_orders.tsv", separator="\t")

Tratamento de header

Como vimos, o Polars assume que a primeira linha dos dados contém os nomes das colunas. Se o seu arquivo não tiver linha de cabeçalho, use o parâmetro has_header=False como abaixo. O Polars atribuirá automaticamente nomes como column_1, column_2, column_3 e assim por diante.

# Load file without a header
orders_data = pl.read_csv("all_orders.csv", has_header=False)

Você também pode renomear as colunas informando os nomes específicos. Por exemplo:

# Providing specific column names
sales_data = pl.read_csv("sales_April.csv", new_columns=[
    "OrderDate", "OrderNumber", "ProductKey", "SalespersonKey", "Salesperson"])

Codificação (encoding)

Arquivos CSV diferentes podem usar codificações de texto distintas. Se você encontrar caracteres estranhos ou erros, especifique a codificação:

# Load CSV into a Polars DataFrame
fuel_data = pl.read_csv("Fuel_Consumption_2000-2022.csv", encoding="utf8")  

Outras opções comuns de encoding incluem "latin1" e "utf8-lossy", que tratam caracteres inválidos de forma adequada.

Como selecionar colunas ao ler CSV no Polars

Ao trabalhar com arquivos CSV grandes, muitas vezes você não precisa de todas as colunas. O Polars permite carregar apenas as colunas necessárias usando o parâmetro columns.

# Load only specific columns
fuel_data = pl.read_csv("Fuel_Consumption_2000-2022.csv",
    columns=["YEAR", "MAKE", "MODEL"]
)

Selecionar as colunas já no carregamento reduz o uso de memória ao evitar dados desnecessários. Isso também acelera a leitura do arquivo e melhora a performance geral do pipeline.

Como lidar com tipos de dados (schema) em CSVs no Polars

O Polars é uma biblioteca fortemente tipada, o que significa que cada coluna deve ter um tipo de dado consistente, como todos inteiros ou todas strings.

Inferência automática de tipos

Por padrão, o Polars inspeciona seus dados e determina automaticamente os tipos das colunas. Esse método funciona bem na maioria dos casos, mas às vezes pode interpretar colunas de forma equivocada, como tratar IDs como inteiros em vez de strings.

Especificando o schema manualmente

Quando você precisa de consistência no DataFrame, é melhor especificar o schema manualmente. Isso garante uniformidade entre vários arquivos e ajuda a evitar erros relacionados a tipos nas etapas seguintes do processamento.

Na maioria dos casos, use schema_overrides para definir o tipo de dados de colunas específicas enquanto permite que o Polars infira as demais.

import polars as pl

# Manually overriding specific data types
empl_data = pl.read_csv(
    "all_employees.csv",
    schema_overrides={
        "id": pl.Int64,
        "name": pl.String,
        "age": pl.Int64,
        "salary": pl.Float64
    }
)

Ou use schema para definir toda a estrutura do DataFrame.

# Manually define the full schema
empl_data = pl.read_csv(
    "all_employees.csv",
    schema={
        "id": pl.Int64,
        "name": pl.String,
        "age": pl.Int64,
        "salary": pl.Float64
    }
)

Como tratar valores ausentes em CSVs no Polars

Por padrão, o Polars detecta automaticamente valores ausentes e os representa como null. Às vezes esses ausentes aparecem como strings específicas, como "NA", "N/A" ou "missing". Você pode defini-las com null_values para que sejam tratadas como null.

# Treating "N/A" and "EMPTY" as nulls
survey_data = pl.read_csv(
    "survey_results.csv",
    null_values=["N/A", "EMPTY", "null"]
)

Ao tratar corretamente os valores ausentes, você garante consistência de tipos e evita cálculos incorretos, reduzindo erros durante a análise e a modelagem.

Lendo arquivos CSV grandes no Polars

Ao trabalhar com datasets grandes que excedem a sua RAM disponível, o Polars se destaca por processar os dados sem carregar o arquivo inteiro de uma vez.

Carregamento preguiçoso com scan_csv()

Em vez de carregar os dados imediatamente na memória como o read_csv(), o Polars oferece uma alternativa preguiçosa, scan_csv(), que cria um plano de consulta otimizado e executa apenas o que for necessário.

No exemplo abaixo, pl.scan_csv apenas examina o arquivo CSV sem carregá-lo, monta uma consulta para buscar as colunas “YEAR”, “MAKE” e “MODEL” onde a marca é “ACURA” e, então, executa essa consulta. Isso carrega para a memória somente o recorte filtrado, em vez do arquivo inteiro.

# Lazily reference the file (no data loaded yet)
fuel_consumption = pl.scan_csv("Fuel_Consumption_2000-2022.csv")  

fuel_consumption_filtered = fuel_consumption.select(
    ["YEAR", "MAKE", "MODEL"]).filter(pl.col("MAKE") == "ACURA")

# Execute the query and load only the required data
fuel_consumption_acura = fuel_consumption_filtered.collect()  

Eu recomendo usar scan_csv() quando:

• Trabalhar com arquivos grandes que não cabem confortavelmente na memória
• Aplicar várias transformações, como filtros, seleção e agregações
• Você quer otimização da consulta antes da execução

Streaming e eficiência de memória

O Polars também permite processar os dados em streaming, em lotes (chunks), mantendo o pico de memória constante independentemente do tamanho do arquivo.

Para arquivos CSV grandes, comece com scan_csv() para criar uma consulta preguiçosa. O arquivo não é totalmente carregado quando scan_csv() é chamado.

# Read data in chunks
fuel_consumption = pl.scan_csv("Fuel_Consumption_2000-2022.csv",
 low_memory=True)

Como o método acima ainda usa read_csv, a melhor abordagem é combinar execução preguiçosa com streaming.

No exemplo abaixo, o Polars processa o arquivo em uma pipeline, linha a linha em lotes, mantendo na memória apenas as linhas filtradas (onde "CYLINDERS" > 3) em cada momento.

# Lazily reference the file (no data loaded yet)
fuel_consumption = pl.scan_csv("Fuel_Consumption_2000-2022.csv")  

result = fuel_consumption.filter(pl.col("CYLINDERS") > 3)

# Stream execution instead of loading everything at once
fuel_consumption_high = result.collect(engine="streaming")

Vantagem de performance vs. Pandas

Em comparação com o pandas, o Polars costuma ter melhor desempenho para leitura e processamento de CSV, como veremos na próxima seção.

Polars read_csv vs Pandas read_csv

A tabela abaixo resume as diferenças entre Polars e Pandas ao ler CSV no Python.

Recomendo ler nosso artigo sobre as diferenças entre Pandas vs. Polars para entender qual ferramenta atende melhor às suas necessidades de analytics.

Lendo CSV de diferentes fontes

Como vimos, você pode usar o Polars para ler arquivos CSV de diferentes fontes. Nos exemplos acima, mostrei como ler CSVs de arquivos locais e URLs.

Além disso, o Polars lida automaticamente com arquivos CSV compactados. Por exemplo, o código a seguir lê dados de um arquivo .gzip.

# Read gzip-compressed CSV
census_data = pl.read_csv("2018_census.csv.gz")

Erros comuns e como resolver

Mesmo com um engine de alto desempenho como o Polars, ainda podem surgir alguns problemas, especialmente ao ler um CSV. A seguir estão alguns dos mais comuns que já encontrei e como corrigi-los.

• Erros de codificação: você pode ver um erro como UnicodeDecodeError, indicando que o arquivo não usa UTF-8, algo comum em arquivos antigos ou CSVs exportados de certas versões do Excel. Para corrigir, defina a codificação apropriada ou use "utf8-lossy" se o arquivo tiver caracteres inconsistentes ou corrompidos.

• Problemas de delimitador: se o seu DataFrame carrega, mas todos os dados ficam em uma única coluna, o Polars não reconheceu o separador. Para resolver, defina explicitamente o delimitador correto usando o argumento separator, como ponto e vírgula (;), tabulação (\t) ou pipe (|).

• Tipos de dados incorretos: às vezes, o Polars pode inferir tipos de coluna de forma errada, como ler IDs numéricos como strings ou gerar erros de parsing. Nesses casos, use schema_overrides para especificar o tipo de colunas específicas. Se quiser definir os tipos de todas as colunas, use schema. Você também pode aumentar infer_schema_length para o Polars examinar mais linhas antes de inferir o schema.

• Problemas de memória com arquivos grandes: se seu processo Python trava ao carregar um arquivo grande, é sinal de RAM insuficiente. Para corrigir, troque read_csv() por scan_csv() para carregamento preguiçoso, reduzindo o uso de memória e melhorando o desempenho. Você também pode carregar menos colunas do dataset ou usar execução em streaming para processar em lotes.

Conclusão

A função read_csv() do Polars é simples de usar, mas poderosa para tarefas do dia a dia. Na minha opinião, o Polars leva vantagem clara quando os datasets começam a crescer.

Como próximo passo, confira nosso blog sobre o Polars GPU engine para saber mais sobre suas aplicações. Se você quer colocar a mão na massa, participe do nosso code-along Super Bowl Analytics with Polars para responder perguntas reais de analytics, aplicar cálculos e usar técnicas básicas de ML em problemas de análise esportiva.