polars

Polars

概要

Polars は、Apache Arrow を基盤とする Python および Rust 向けの超高速 DataFrame ライブラリです。Polars の式ベースの API、遅延評価フレームワーク、高性能なデータ操作機能を活用し、効率的なデータ処理、pandas からの移行、データパイプラインの最適化を実現できます。

クイックスタート

インストールと基本的な使い方

この更新時に確認した、現行の安定版 Polars をインストールします：

uv pip install "polars==1.41.2"

必要な場合にのみ、オプションの統合機能をインストールします：

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

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
)

基本概念

式

式は Polars の操作を構成する基本要素です。データに対する変換を記述し、組み合わせ、再利用、最適化できます。

主な原則：

• pl.col("column_name") を使って列を参照します
• メソッドをチェーンして複雑な変換を構築します
• 式は遅延評価され、コンテキスト（select、with_columns、filter、group_by）内でのみ実行されます

例：

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

遅延評価と即時評価

即時評価（DataFrame）： 操作がすぐに実行されます

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

遅延評価（LazyFrame）： 操作によってクエリプランが構築され、実行前に最適化されます

lf = pl.scan_csv("file.csv")  # Doesn't read yet
result = lf.filter(pl.col("age") > 25).select("name", "age")
df = result.collect()  # Now executes optimized query

遅延評価を使う場面：

• 大規模なデータセットを扱う場合
• 複雑なクエリパイプラインを扱う場合
• 一部の列や行だけが必要な場合
• パフォーマンスが重要な場合

遅延評価のメリット：

• クエリの自動最適化
• 述語プッシュダウン
• 射影プッシュダウン
• 並列実行

詳しい概念については、references/core_concepts.md を読み込んでください。

一般的な操作

選択

列を選択して操作します：

# 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$"))

フィルター

条件で行を絞り込みます：

# 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")
)

列の追加

既存の列を保持しながら列を追加または変更します：

# 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,
    pl.col("value") * 100,
)

グループ化と集計

データをグループ化して集計値を計算します：

# 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")
)

操作パターンの詳細については、references/operations.md を読み込んでください。

集計とウィンドウ関数

集計関数

group_by コンテキストでよく使われる集計：

• pl.len() - 行数
• pl.col("x").sum() - 値の合計
• pl.col("x").mean() - 平均
• pl.col("x").min() / pl.col("x").max() - 最小値／最大値
• pl.first() / pl.last() - 最初／最後の値

over() を使ったウィンドウ関数

行数を維持したまま集計を適用します：

# Add group statistics to each row
df.with_columns(
    avg_age_by_city=pl.col("age").mean().over("city"),
    rank_in_city=pl.col("salary").rank().over("city")
)

# Multiple grouping columns
df.with_columns(
    group_avg=pl.col("value").mean().over("category", "region")
)

マッピング方法：

• group_to_rows（デフォルト）：元の行順を維持します
• explode：高速ですが、行をグループごとにまとめます
• join：リスト列を作成します

データの入出力

対応フォーマット

Polars は次の形式の読み込みと書き込みに対応しています：

• CSV、Parquet、JSON、Excel
• データベース（コネクター経由）
• クラウドストレージ（S3、Azure、GCS）
• Google BigQuery
• 複数ファイル／パーティション分割されたファイル

一般的な入出力操作

CSV：

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

# Lazy (preferred for large files)
lf = pl.scan_csv("file.csv")
result = lf.filter(...).select(...).collect()

Parquet（パフォーマンス面で推奨）：

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

JSON：

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

入出力の包括的なドキュメントについては、references/io_guide.md を読み込んでください。

変換

結合

DataFrame を結合します：

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

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

# Join on different column names
df1.join(df2, left_on="user_id", right_on="id")

連結

DataFrame を縦に積み重ねます：

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

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

# Diagonal (union with different schemas)
pl.concat([df1, df2], how="diagonal")

ピボットとアンピボット

データの形状を変更します：

# Pivot (wide format)
df.pivot(on="product", values="sales", index="date")

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

変換の詳しい例については、references/transformations.md を読み込んでください。

pandas からの移行

Polars は、よりすっきりした API と大幅なパフォーマンス向上を pandas に対して提供します。主な違いは次のとおりです。

概念上の違い

• インデックスなし：Polars は整数位置のみを使用します
• 厳密な型付け：暗黙の型変換は行いません
• 遅延評価：LazyFrame で利用できます
• デフォルトで並列処理：操作は自動的に並列化されます

一般的な操作の対応関係

操作	Pandas	Polars
列の選択	df["col"]	df.select("col")
フィルター	df[df["col"] > 10]	df.filter(pl.col("col") > 10)
列の追加	df.assign(x=...)	df.with_columns(x=...)
グループ化	df.groupby("col").agg(...)	df.group_by("col").agg(...)
ウィンドウ	df.groupby("col").transform(...)	df.with_columns(...).over("col")

主な構文パターン

Pandas の逐次処理（低速）：

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

Polars の並列処理（高速）：

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

包括的な移行ガイドについては、references/pandas_migration.md を読み込んでください。

ベストプラクティス

パフォーマンスの最適化

1. 大規模なデータセットには遅延評価を使用します：

   lf = pl.scan_csv("large.csv")  # Don't use read_csv
   result = lf.filter(...).select(...).collect()
   

2. 処理頻度の高い箇所では Python 関数を避けます：

   • 並列化のため、式 API の範囲内で処理します
   • 必要な場合にのみ .map_elements() を使用します
   • Polars のネイティブ操作を優先します

3. 非常に大きなデータにはストリーミングを使用します：

   lf.collect(engine="streaming")
   

4. 必要な列だけを早い段階で選択します：

   # Good: Select columns early
   lf.select("col1", "col2").filter(...)
   
   # Bad: Filter on all columns first
   lf.filter(...).select("col1", "col2")
   

5. 適切なデータ型を使用します：

   • カーディナリティの低い文字列には Categorical を使用します
   • 適切な整数サイズを使用します（i32 と i64 の使い分け）
   • 時系列データには日付型を使用します

式のパターン

条件付き操作：

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

複数列にまたがる列操作：

df.select(pl.col("^.*_value$") * 2)  # Regex pattern

Null の処理：

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

その他のベストプラクティスやパターンについては、references/best_practices.md を読み込んでください。

リソース

このスキルには、包括的なリファレンスドキュメントが含まれています：

references/

• core_concepts.md - 式、遅延評価、型システムの詳細な説明
• operations.md - 一般的な操作と例を網羅したガイド
• pandas_migration.md - pandas から Polars への完全な移行ガイド
• io_guide.md - サポートされているすべての形式でのデータ I/O 操作
• transformations.md - 結合、連結、ピボット、再構成操作
• best_practices.md - パフォーマンス最適化のヒントと一般的なパターン

特定のトピックについてユーザーが詳細な情報を求める場合は、必要に応じてこれらのリファレンスを読み込んでください。

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を明確にします。 データまたはユーザーに確認して、形式、識別子、パラメーターを特定します。結果に影響する値を推測せず、確認してください。
3. まず小規模に実行します。 サンプルまたは単一のフォールドで実行し、実行時間とメモリ使用量を確認します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 保留データ、固定した乱数シード、適切な評価指標を使用し、データリークを確認して、不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を明記します。

次の状況が発生した場合	対応
メモリ不足または実行が非常に遅い	サブサンプリング、チャンク処理や遅延計算の使用、またはモデルサイズの縮小を行い、変更内容をユーザーに伝えます。
これらの手順に記載されている関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えてください。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その算出に使用したコードの経路を示してください。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する、共有 GPU やクラウドの割り当てを消費する、個人データや患者データを扱う、または取り消せない操作を行う場合は、事前に確認してください。

関連スキル

• dask：RAM 容量を超える pandas/NumPy ワークフロー向けの分散コンピューティング。
• ray-data：ML ワークロード向けのスケーラブルなデータ処理。
• vaex：メモリマップされたデータ上で遅延評価される out-of-core DataFrame を扱う Python ライブラリ Vaex を使用して、RAM 容量を超える表形式データセットを処理・分析します…