Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

DataStore: SQL 最適化を備えた pandas互換 API

View as MarkdownEdit this pageReport an issueSet up docs MCP

DataStore は、使い慣れた pandas DataFrame インターフェイスと SQL によるクエリ最適化の力を組み合わせた、chDB の pandas-compatible API です。pandas スタイルのコードを書きながら、ClickHouse のパフォーマンスを活用できます。

主な機能

  • Pandas 互換性: 209 の pandas DataFrame メソッド、56 の .str メソッド、42 以上の .dt メソッド
  • SQL 最適化: 操作は自動的に最適化された SQL クエリへコンパイルされます
  • 遅延評価: 結果が必要になるまで操作の実行を遅らせます
  • 630+ API メソッド: データ操作のための包括的な API
  • ClickHouse 拡張機能: pandas にはない追加のアクセサ (.arr、.json、.url、.ip、.geo)

アーキテクチャ

DataStore アーキテクチャ

DataStore は、遅延評価 と デュアルエンジン実行 を採用しています。

  1. 遅延操作チェーン: 操作は記録されますが、すぐには実行されません
  2. スマートなエンジン選択: QueryPlanner が各セグメントを最適なエンジンに振り分けます (SQL は chDB、複雑な操作は Pandas)
  3. 中間結果のキャッシュ: 反復的な探索を高速化するため、各ステップの結果がキャッシュされます

詳しくは 実行モデル を参照してください。

Pandas からのワンライナーでの移行

# Before (pandas)
import pandas as pd

df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# After (DataStore) - just change the import!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

既存のpandasコードは変更なしでそのまま動作し、ClickHouseエンジン上で実行されます。

パフォーマンス比較

DataStore は、特に集計や複雑なパイプラインにおいて、pandas と比べて大幅に高いパフォーマンスを発揮します。

Operation Pandas DataStore Speedup
GroupBy count 347ms 17ms 19.93x
Complex pipeline 2,047ms 380ms 5.39x
Filter+Sort+Head 1,537ms 350ms 4.40x
GroupBy agg 406ms 141ms 2.88x

1,000万行でのベンチマークです。詳しくは ベンチマークスクリプト と パフォーマンスガイド を参照してください。

DataStore を使うタイミング

次のような場合は DataStore を使用します。

  • 大規模なデータセット (数百万行) を扱う場合
  • 集計や groupby 操作を行う場合
  • ファイル、データベース、または Cloud ストレージ内のデータをクエリする場合
  • 複雑なデータパイプラインを構築する場合
  • より高いパフォーマンスで pandas API を使いたい場合

次のような場合は raw SQL API を使用します。

  • SQL を直接書きたい場合
  • クエリ実行を細かく制御する必要がある場合
  • pandas API では利用できない ClickHouse 固有の機能を使う場合

機能比較

機能 Pandas Polars DuckDB DataStore
Pandas API 互換性 - 一部 いいえ 完全
遅延実行 いいえ はい はい はい
SQL クエリ対応 いいえ はい はい はい
ClickHouse 関数 いいえ いいえ いいえ はい
String/DateTime アクセサ はい はい いいえ はい + 追加機能
Array/JSON/URL/IP/Geo いいえ 一部 いいえ はい
ファイルへの直接クエリ いいえ はい はい はい
Cloud ストレージ対応 いいえ 限定的 はい はい

API統計

カテゴリ 件数 対応率
DataFrame メソッド 209 pandas の 100%
Series.str アクセサ 56 pandas の 100%
Series.dt アクセサ 42+ 100%超 (ClickHouse の拡張を含む)
Series.arr アクセサ 37 ClickHouse固有
Series.json アクセサ 13 ClickHouse固有
Series.url アクセサ 15 ClickHouse固有
Series.ip アクセサ 9 ClickHouse固有
Series.geo アクセサ 14 ClickHouse固有
APIメソッド総数 630+ -

はじめに

API リファレンス

応用トピック

設定とデバッグ

Pandasユーザーガイド

簡単な使用例

from chdb import datastore as pd

# Read data from various sources
ds = pd.read_csv("sales.csv")
# or: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# or: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Familiar pandas operations - automatically optimized to SQL
result = (ds
    .filter(ds['amount'] > 1000)           # WHERE amount > 1000
    .groupby('region')                      # GROUP BY region
    .agg({'amount': ['sum', 'mean']})       # SUM(amount), AVG(amount)
    .sort_values('sum', ascending=False)    # ORDER BY sum DESC
    .head(10)                               # LIMIT 10
)

# View the generated SQL
print(result.to_sql())

# Execute and get results
df = result.to_df()  # Returns pandas DataFrame

次のステップ

Navigation