Polars

Polars

Visão Geral

Polars é uma biblioteca DataFrame extremamente rápida para Python e Rust construída no Apache Arrow. Trabalhe com a API baseada em expressões do Polars, framework de avaliação preguiçosa e capacidades de manipulação de dados de alto desempenho para processamento eficiente de dados, migração de pandas e otimização de pipeline de dados.

Início Rápido

Instalação e Uso Básico

Instale o Polars:

uv pip install polars

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

import polars as pl

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

# Selecionar colunas
df.select("name", "age")

# Filtrar linhas
df.filter(pl.col("age") > 25)

# Adicionar colunas computadas
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 nos 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:

# Computação baseada em expressões
df.select(
    pl.col("name"),
    (pl.col("age") * 12).alias("age_in_months")
)

Avaliação Preguiçosa vs Antecipada

Antecipada (DataFrame): Operações executam imediatamente

df = pl.read_csv("file.csv")  # Lê imediatamente
result = df.filter(pl.col("age") > 25)  # Executa imediatamente

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

lf = pl.scan_csv("file.csv")  # Não lê ainda
result = lf.filter(pl.col("age") > 25).select("name", "age")
df = result.collect()  # Agora executa consulta otimizada

Quando usar preguiçosa:

• Trabalhar com datasets grandes
• Pipelines de consulta complexos
• Quando apenas algumas colunas/linhas são necessárias
• Desempenho é crítico

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

• Otimização automática de consultas
• Predicate pushdown
• Projection pushdown
• Execução paralela

Para conceitos detalhados, carregue references/core_concepts.md.

Operações Comuns

Select

Selecione e manipule colunas:

# Selecionar colunas específicas
df.select("name", "age")

# Selecionar com expressões
df.select(
    pl.col("name"),
    (pl.col("age") * 2).alias("double_age")
)

# Selecionar todas as colunas que correspondem a um padrão
df.select(pl.col("^.*_id$"))

Filter

Filtre linhas por condições:

# Condição única
df.filter(pl.col("age") > 25)

# Múltiplas condições (mais limpo do que usar &)
df.filter(
    pl.col("age") > 25,
    pl.col("city") == "NY"
)

# Condições complexas
df.filter(
    (pl.col("age") > 25) | (pl.col("city") == "LA")
)

With Columns

Adicione ou modifique colunas preservando as existentes:

# Adicionar novas colunas
df.with_columns(
    age_plus_10=pl.col("age") + 10,
    name_upper=pl.col("name").str.to_uppercase()
)

# Computação paralela (todas as colunas computadas em paralelo)
df.with_columns(
    pl.col("value") * 10,
    pl.col("value") * 100,
)

Group By e Agregações

Agrupe dados e calcule agregações:

# Agrupamento básico
df.group_by("city").agg(
    pl.col("age").mean().alias("avg_age"),
    pl.len().alias("count")
)

# Múltiplas chaves de agrupamento
df.group_by("city", "department").agg(
    pl.col("salary").sum()
)

# Agregações condicionais
df.group_by("city").agg(
    (pl.col("age") > 30).sum().alias("over_30")
)

Para padrões detalhados de operações, 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() - contar linhas
• pl.col("x").sum() - somar valores
• pl.col("x").mean() - média
• pl.col("x").min() / pl.col("x").max() - extremos
• pl.first() / pl.last() - primeiros/últimos valores

Funções de Janela com over()

Aplique agregações preservando a contagem de linhas:

# Adicionar estatísticas de grupo a cada linha
df.with_columns(
    avg_age_by_city=pl.col("age").mean().over("city"),
    rank_in_city=pl.col("salary").rank().over("city")
)

# Múltiplas colunas de agrupamento
df.with_columns(
    group_avg=pl.col("value").mean().over("category", "region")
)

Estratégias de mapeamento:

• group_to_rows (padrão): Preserva ordem de linha original
• explode: Mais rápido mas agrupa linhas juntas
• join: Cria colunas de lista

Data I/O

Formatos Suportados

Polars suporta leitura e escrita de:

• CSV, Parquet, JSON, Excel
• Bancos de dados (via conectores)
• Armazenamento em nuvem (S3, Azure, GCS)
• Google BigQuery
• Múltiplos/arquivos particionados

Operações Comuns de I/O

CSV:

# Antecipado
df = pl.read_csv("file.csv")
df.write_csv("output.csv")

# Preguiçoso (preferido para arquivos grandes)
lf = pl.scan_csv("file.csv")
result = lf.filter(...).select(...).collect()

Parquet (recomendado para desempenho):

df = pl.read_parquet("file.parquet")
df.write_parquet("output.parquet")

JSON:

df = pl.read_json("file.json")
df.write_json("output.json")

Para documentação abrangente de I/O, carregue references/io_guide.md.

Transformações

Joins

Combine DataFrames:

# Inner join
df1.join(df2, on="id", how="inner")

# Left join
df1.join(df2, on="id", how="left")

# Join em nomes de colunas diferentes
df1.join(df2, left_on="user_id", right_on="id")

Concatenação

Empilhe DataFrames:

# Vertical (empilhar linhas)
pl.concat([df1, df2], how="vertical")

# Horizontal (adicionar colunas)
pl.concat([df1, df2], how="horizontal")

# Diagonal (união com schemas diferentes)
pl.concat([df1, df2], how="diagonal")

Pivot e Unpivot

Reformate dados:

# Pivot (formato amplo)
df.pivot(values="sales", index="date", columns="product")

# Unpivot (formato longo)
df.unpivot(index="id", on=["col1", "col2"])

Para exemplos detalhados de transformação, carregue references/transformations.md.

Migração de Pandas

Polars oferece melhorias significativas de desempenho sobre pandas com uma API mais limpa. Principais diferenças:

Diferenças Conceituais

• Sem índice: Polars usa apenas posições inteiras
• Tipagem rigorosa: Sem conversões de tipo silenciosas
• Avaliação preguiçosa: Disponível via LazyFrame
• Paralelo por padrão: Operações paralelizadas automaticamente

Mapeamentos de Operações Comuns

Padrões de Sintaxe-Chave

Pandas sequencial (lento):

df.assign(
    col_a=lambda df_: df_.value * 10,
    col_b=lambda df_: df_.value * 100
)

Polars paralelo (rápido):

df.with_columns(
    col_a=pl.col("value") * 10,
    col_b=pl.col("value") * 100,
)

Para guia abrangente de migração, carregue references/pandas_migration.md.

Melhores Práticas

Otimização de Desempenho

1. Use avaliação preguiçosa para datasets grandes:

   lf = pl.scan_csv("large.csv")  # Não use read_csv
   result = lf.filter(...).select(...).collect()
   

2. Evite funções Python em caminhos críticos:

   • Mantenha-se na expression API para paralelização
   • Use .map_elements() apenas quando necessário
   • Prefira operações nativas do Polars

3. Use streaming para dados muito grandes:

   lf.collect(streaming=True)
   

4. Selecione apenas colunas necessárias cedo:

   # Bom: Selecionar colunas cedo
   lf.select("col1", "col2").filter(...)
   
   # Ruim: Filtrar em todas as colunas primeiro
   lf.filter(...).select("col1", "col2")
   

5. Use tipos de dados apropriados:

   • Categorical para strings de baixa cardinalidade
   • Tamanhos inteiros apropriados (i32 vs i64)
   • Tipos de data para dados temporais

Padrões de Expressão

Operações condicionais:

pl.when(condition).then(value).otherwise(other_value)

Operações de coluna em múltiplas colunas:

df.select(pl.col("^.*_value$") * 2)  # Padrão regex

Manipulação de nulos:

pl.col("x").fill_null(0)
pl.col("x").is_null()
pl.col("x").drop_nulls()

Para melhores práticas e padrões adicionais, carregue references/best_practices.md.

Recursos

Esta skill inclui documentação de referência abrangente:

references/

• core_concepts.md - Explicações detalhadas de expressões, avaliação preguiçosa e sistema de tipos
• operations.md - Guia abrangente de todas as operações comuns com exemplos
• pandas_migration.md - Guia completo de migração de pandas para Polars
• io_guide.md - Operações de data I/O para todos os formatos suportados
• transformations.md - Joins, concatenação, pivots e operações de reformatação
• best_practices.md - Dicas de otimização de desempenho e padrões comuns

Carregue essas referências conforme necessário quando usuários precisarem de informações detalhadas sobre tópicos específicos.