Polars

Visão Geral

Polars é uma biblioteca de DataFrames colunares para Python e Rust com interoperabilidade Arrow. Trabalhe com a API baseada em expressões do Polars, framework de avaliação preguiçosa (lazy evaluation) e capacidades de manipulação de dados de alta performance para processamento de dados eficiente, migração do pandas e otimização de pipelines de dados.

Revisado contra a documentação oficial estável e Polars nativo 1.44.2. Testes de regressão locais cobrem as APIs corrigidas e casos de falha científicos; receitas de nuvem, GPU, BigQuery e bancos de dados remotos são ilustrativas e requerem configuração do provedor. Fragmentos que usam colunas, caminhos ou ... indefinidos requerem adaptação ao conjunto de dados.

Início Rápido

Instalação e Uso Básico

Instale a versão estável atual do Polars verificada durante esta atualização:

uv pip install "polars==1.44.2"

Instale integrações opcionais apenas quando necessário:

uv pip install "polars[excel,database,fsspec,pandas,numpy]==1.44.2"

Criação e operações básicas de DataFrame:

import polars as pl

# Create DataFrame
df = pl.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "age": [25, 30, 35],
    "city": ["NY", "LA", "SF"]
})

# Select columns
df.select("name", "age")

# Filter rows
df.filter(pl.col("age") > 25)

# Add computed columns
df.with_columns(
    age_plus_10=pl.col("age") + 10
)

Conceitos Principais

Expressões

Expressões são os blocos de construção fundamentais das operações do Polars. Elas descrevem transformações em dados e podem ser compostas, reutilizadas e otimizadas.

Princípios chave:

• Use pl.col("column_name") para referenciar colunas
• Encadeie métodos para construir transformações complexas
• Expressões são preguiçosas e só executam dentro de contextos (select, with_columns, filter, group_by)

Exemplo:

# Expression-based computation
df.select(
    pl.col("name"),
    (pl.col("age") * 12).alias("age_in_months")
)

Avaliação Preguiçosa (Lazy) vs. Imediata (Eager)

Imediata (DataFrame): Operações executam imediatamente

df = pl.read_csv("file.csv")  # Reads immediately
result = df.filter(pl.col("age") > 25)  # Executes immediately

Preguiçosa (LazyFrame): Operações constroem um plano de consulta, otimizado antes da execução

lf = pl.scan_csv("file.csv")  # Builds a plan; schema inference can read the source
result = lf.filter(pl.col("age") > 25).select("name", "age")
df = result.collect()  # Now executes optimized query

Quando usar lazy:

• Trabalhando com grandes conjuntos de dados
• Pipelines de consulta complexos
• Quando apenas algumas colunas/linhas são necessárias
• Performance é crítica

Benefícios da avaliação preguiçosa:

• Otimização automática de consulta
• Predicate pushdown (empurramento de predicados)
• Projection pushdown (empurramento de projeções)
• Execução paralela

Para conceitos detalhados, carregue references/core_concepts.md.

Operações Comuns

Select

Selecione e manipule colunas:

# Select specific columns
df.select("name", "age")

# Select with expressions
df.select(
    pl.col("name"),
    (pl.col("age") * 2).alias("double_age")
)

# Select all columns matching a pattern
df.select(pl.col("^.*_id$"))

Filter

Filtre linhas por condições:

# Single condition
df.filter(pl.col("age") > 25)

# Multiple conditions (cleaner than using &)
df.filter(
    pl.col("age") > 25,
    pl.col("city") == "NY"
)

# Complex conditions
df.filter(
    (pl.col("age") > 25) | (pl.col("city") == "LA")
)

With Columns

Adicione ou modifique colunas preservando as existentes:

# Add new columns
df.with_columns(
    age_plus_10=pl.col("age") + 10,
    name_upper=pl.col("name").str.to_uppercase()
)

# Parallel computation (all columns computed in parallel)
df.with_columns(
    (pl.col("value") * 10).alias("value_times_10"),
    (pl.col("value") * 100).alias("value_times_100"),
)

Group By e Agregações

Agrupe dados e compute agregações:

# Basic grouping
df.group_by("city").agg(
    pl.col("age").mean().alias("avg_age"),
    pl.len().alias("count")
)

# Multiple group keys
df.group_by("city", "department").agg(
    pl.col("salary").sum()
)

# Conditional aggregations
df.group_by("city").agg(
    (pl.col("age") > 30).sum().alias("over_30")
)

Para padrões de operação detalhados, carregue references/operations.md.

Agregações e Funções de Janela

Funções de Agregação

Agregações comuns dentro do contexto group_by:

• pl.len() - conta linhas
• pl.col("x").sum() - soma valores
• pl.col("x").mean() - média
• pl.col("x").min() / pl.col("x").max() - extremos
• pl.first() / pl.last() - primeiros/últimos valores

…