Polars

概要

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

クイックスタート

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

Polars をインストール:

uv pip install polars

基本的な DataFrame の作成と操作:

import polars as pl

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

# 列を選択
df.select("name", "age")

# 行をフィルタリング
df.filter(pl.col("age") > 25)

# 計算列を追加
df.with_columns(
    age_plus_10=pl.col("age") + 10
)

コアコンセプト

式 (Expressions)

式は Polars 操作の基本的な構成要素です。データの変換を記述し、構成、再利用、最適化することができます。

主な原則:

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

例:

# 式ベースの計算
df.select(
    pl.col("name"),
    (pl.col("age") * 12).alias("age_in_months")
)

遅延評価 vs 即座評価

即座評価 (DataFrame): 操作は直ちに実行される

df = pl.read_csv("file.csv")  # すぐに読み込まれる
result = df.filter(pl.col("age") > 25)  # 直ちに実行される

遅延評価 (LazyFrame): 操作はクエリプランを構築し、実行前に最適化される

lf = pl.scan_csv("file.csv")  # まだ読み込まれない
result = lf.filter(pl.col("age") > 25).select("name", "age")
df = result.collect()  # ここで最適化されたクエリが実行される

遅延評価を使用する場合:

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

遅延評価の利点:

• 自動クエリ最適化
• 述語の押し下ろし
• 投影の押し下ろし
• 並列実行

詳細なコンセプトについては、references/core_concepts.md を参照してください。

一般的な操作

Select

列を選択および操作:

# 特定の列を選択
df.select("name", "age")

# 式で選択
df.select(
    pl.col("name"),
    (pl.col("age") * 2).alias("double_age")
)

# パターンに一致するすべての列を選択
df.select(pl.col("^.*_id$"))

Filter

条件で行をフィルタリング:

# 単一条件
df.filter(pl.col("age") > 25)

# 複数条件 (&を使用するより清潔)
df.filter(
    pl.col("age") > 25,
    pl.col("city") == "NY"
)

# 複雑な条件
df.filter(
    (pl.col("age") > 25) | (pl.col("city") == "LA")
)

With Columns

既存の列を保持しながら列を追加または修正:

# 新しい列を追加
df.with_columns(
    age_plus_10=pl.col("age") + 10,
    name_upper=pl.col("name").str.to_uppercase()
)

# 並列計算 (すべての列が並列で計算される)
df.with_columns(
    pl.col("value") * 10,
    pl.col("value") * 100,
)

Group By と集計

データをグループ化し、集計を計算:

# 基本的なグループ化
df.group_by("city").agg(
    pl.col("age").mean().alias("avg_age"),
    pl.len().alias("count")
)

# 複数のグループキー
df.group_by("city", "department").agg(
    pl.col("salary").sum()
)

# 条件付き集計
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() を使用したウィンドウ関数

行数を保持しながら集計を適用:

# 各行にグループ統計を追加
df.with_columns(
    avg_age_by_city=pl.col("age").mean().over("city"),
    rank_in_city=pl.col("salary").rank().over("city")
)

# 複数のグループ化列
df.with_columns(
    group_avg=pl.col("value").mean().over("category", "region")
)

マッピング戦略:

• group_to_rows (デフォルト): 元の行の順序を保持
• explode: より高速だがグループの行をまとめる
• join: リスト列を作成

データ I/O

サポートされているフォーマット

Polars は以下のフォーマットの読み書きをサポート:

• CSV、Parquet、JSON、Excel
• データベース (コネクタ経由)
• クラウドストレージ (S3、Azure、GCS)
• Google BigQuery
• 複数/パーティショニングファイル

一般的な I/O 操作

CSV:

# 即座評価
df = pl.read_csv("file.csv")
df.write_csv("output.csv")

# 遅延評価 (大きなファイルに推奨)
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")

包括的な I/O ドキュメントについては、references/io_guide.md を参照してください。

変換

Join

DataFrame を組み合わせ:

# 内部結合
df1.join(df2, on="id", how="inner")

# 左結合
df1.join(df2, on="id", how="left")

# 異なる列名で結合
df1.join(df2, left_on="user_id", right_on="id")

連結

DataFrame をスタック:

# 縦方向 (行をスタック)
pl.concat([df1, df2], how="vertical")

# 横方向 (列を追加)
pl.concat([df1, df2], how="horizontal")

# 対角線方向 (異なるスキーマで結合)
pl.concat([df1, df2], how="diagonal")

Pivot と Unpivot

データを再形成:

# Pivot (広いフォーマット)
df.pivot(values="sales", index="date", columns="product")

# Unpivot (長いフォーマット)
df.unpivot(index="id", on=["col1", "col2"])

詳細な変換例については、references/transformations.md を参照してください。

Pandas からの移行

Polars は pandas よりも大幅なパフォーマンス改善とより清潔な API を提供します。主な違い:

概念的な違い

• インデックスなし: 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=...)
Group by	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")  # read_csv を使用しない
   result = lf.filter(...).select(...).collect()
   

2. ホットパスでの Python 関数を回避:

   • 式 API 内で並列化を維持
   • .map_elements() は必要な場合のみ使用
   • ネイティブ Polars 操作を優先

3. 非常に大規模なデータにはストリーミングを使用:

   lf.collect(streaming=True)
   

4. 必要な列を早期に選択:

   # 良い例: 列を早期に選択
   lf.select("col1", "col2").filter(...)
   
   # 悪い例: すべての列でフィルタリングしてから選択
   lf.filter(...).select("col1", "col2")
   

5. 適切なデータ型を使用:

   • 低カーディナリティ文字列には Categorical を使用
   • 適切な整数サイズ (i32 vs i64)
   • 時間データには Date 型を使用

式パターン

条件付き操作:

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

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

df.select(pl.col("^.*_value$") * 2)  # 正規表現パターン

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 - パフォーマンス最適化のヒントと一般的なパターン

必要に応じて、これらのリファレンスをロードして、特定のトピックに関する詳細情報を取得してください。