DataStore クラスリファレンス - ClickHouse Documentation

このリファレンスでは、DataStore API の中核となるクラスについて説明します。

DataStore

データ操作のための主要なDataFrameライクなクラスです。

from chdb.datastore import DataStore

コンストラクタ

DataStore(data=None, columns=None, index=None, dtype=None, copy=None)

パラメータ:

パラメータ	型	説明
`data`	dict/list/DataFrame/DataStore	入力データ
`columns`	list	カラム名
`index`	Index	行インデックス
`dtype`	dict	カラムのデータ型
`copy`	bool	データのコピー

例:

# 辞書から
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

# pandas DataFrameから
import pandas as pd
ds = DataStore(pd.DataFrame({'a': [1, 2, 3]}))

# 空のDataStore
ds = DataStore()

プロパティ

プロパティ	型	説明
`columns`	Index	カラム名
`dtypes`	Series	カラムのデータ型
`shape`	tuple	(行数, カラム数)
`size`	int	要素の総数
`ndim`	int	次元数 (2)
`empty`	bool	DataFrame が空かどうか
`values`	ndarray	基になるデータを NumPy 配列として表したもの
`index`	Index	行インデックス
`T`	DataStore	転置
`axes`	list	軸のリスト

ファクトリメソッド

メソッド	説明
`uri(uri)`	URI から作成する汎用ファクトリ
`from_file(path, ...)`	ファイルから作成
`from_df(df)`	pandas DataFrame から作成
`from_s3(url, ...)`	S3 から作成
`from_gcs(url, ...)`	Google Cloud Storage から作成
`from_azure(url, ...)`	Azure Blob から作成
`from_mysql(...)`	MySQL から作成
`from_postgresql(...)`	PostgreSQL から作成
`from_clickhouse(...)`	ClickHouse から作成
`from_mongodb(...)`	MongoDB から作成
`from_sqlite(...)`	SQLite から作成
`from_iceberg(path)`	Iceberg テーブルから作成
`from_delta(path)`	Delta Lake から作成
`from_numbers(n)`	連番で作成
`from_random(rows, cols)`	ランダムなデータで作成
`run_sql(query)`	SQL クエリから作成

詳細はファクトリメソッドを参照してください。

クエリメソッド

メソッド	戻り値	説明
`select(*cols)`	DataStore	カラムを選択
`filter(condition)`	DataStore	行を絞り込み
`where(condition)`	DataStore	`filter` の別名
`sort(*cols, ascending=True)`	DataStore	行をソート
`orderby(*cols)`	DataStore	`sort` の別名
`limit(n)`	DataStore	行数を制限
`offset(n)`	DataStore	行をスキップ
`distinct(subset=None)`	DataStore	重複を削除
`groupby(*cols)`	LazyGroupBy	行をグループ化
`having(condition)`	DataStore	グループを絞り込み
`join(right, ...)`	DataStore	DataStore を結合
`union(other, all=False)`	DataStore	DataStore を連結
`when(cond, val)`	CaseWhen	CASE WHEN

詳細は、クエリの構築を参照してください。

Pandas 互換メソッド

209 個のメソッドの完全な一覧については、Pandas Compatibility をご覧ください。 インデックス操作: head(), tail(), sample(), loc, iloc, at, iat, query(), isin(), where(), mask(), get(), xs(), pop() 集計: sum(), mean(), std(), var(), min(), max(), median(), count(), nunique(), quantile(), describe(), corr(), cov(), skew(), kurt() 操作: drop(), drop_duplicates(), dropna(), fillna(), replace(), rename(), assign(), astype(), copy() ソート: sort_values(), sort_index(), nlargest(), nsmallest(), rank() 整形: pivot(), pivot_table(), melt(), stack(), unstack(), transpose(), explode(), squeeze() 結合: merge(), join(), concat(), append(), combine(), update(), compare() 適用/変換: apply(), applymap(), map(), agg(), transform(), pipe(), groupby() 時系列: rolling(), expanding(), ewm(), shift(), diff(), pct_change(), resample()

I/O メソッド

メソッド	説明
`to_csv(path, ...)`	CSV にエクスポート
`to_parquet(path, ...)`	Parquet にエクスポート
`to_json(path, ...)`	JSON にエクスポート
`to_excel(path, ...)`	Excel にエクスポート
`to_df()`	pandas DataFrame に変換
`to_pandas()`	to_df のエイリアス
`to_arrow()`	Arrow テーブルに変換
`to_dict(orient)`	辞書に変換
`to_records()`	レコードに変換
`to_numpy()`	NumPy 配列に変換
`to_sql()`	SQL 文字列を生成
`to_string()`	文字列表現
`to_markdown()`	Markdown テーブル
`to_html()`	HTML テーブル

詳細は I/O 操作を参照してください。

デバッグメソッド

メソッド	説明
`explain(verbose=False)`	実行計画を表示
`clear_cache()`	キャッシュ済みの結果をクリア

詳しくはデバッグを参照してください。

特殊メソッド

メソッド	説明
`__getitem__(key)`	`ds['col']`, `ds[['a', 'b']]`, `ds[condition]`
`__setitem__(key, value)`	`ds['col'] = value`
`__delitem__(key)`	`del ds['col']`
`__len__()`	`len(ds)`
`__iter__()`	`for col in ds`
`__contains__(key)`	`'col' in ds`
`__repr__()`	`repr(ds)`
`__str__()`	`str(ds)`
`__eq__(other)`	`ds == other`
`__ne__(other)`	`ds != other`
`__lt__(other)`	`ds < other`
`__le__(other)`	`ds <= other`
`__gt__(other)`	`ds > other`
`__ge__(other)`	`ds >= other`
`__add__(other)`	`ds + other`
`__sub__(other)`	`ds - other`
`__mul__(other)`	`ds * other`
`__truediv__(other)`	`ds / other`
`__floordiv__(other)`	`ds // other`
`__mod__(other)`	`ds % other`
`__pow__(other)`	`ds ** other`
`__and__(other)`	`ds & other`
`__or__(other)`	`ds	other`
`__invert__()`	`~ds`
`__neg__()`	`-ds`
`__pos__()`	`+ds`
`__abs__()`	`abs(ds)`

ColumnExpr

遅延評価用のカラム式を表します。カラムにアクセスしたときに返されます。

# ColumnExpr は自動的に返されます
col = ds['name']  # ColumnExpr を返します

プロパティ

プロパティ	型	説明
`name`	str	カラム名
`dtype`	dtype	データ型

アクセサ

アクセサ	説明	メソッド
`.str`	文字列操作	56 メソッド
`.dt`	DateTime 操作	42+ メソッド
`.arr`	Array 操作	37 メソッド
`.json`	JSON のパース	13 メソッド
`.url`	URL のパース	15 メソッド
`.ip`	IP アドレス操作	9 メソッド
`.geo`	Geo/距離の操作	14 メソッド

完全なドキュメントについては、Accessorsを参照してください。

算術演算

ds['total'] = ds['price'] * ds['quantity']
ds['profit'] = ds['revenue'] - ds['cost']
ds['ratio'] = ds['a'] / ds['b']
ds['squared'] = ds['value'] ** 2
ds['remainder'] = ds['value'] % 10

比較演算

ds[ds['age'] > 25]           # より大きい
ds[ds['age'] >= 25]          # 以上
ds[ds['age'] < 25]           # より小さい
ds[ds['age'] <= 25]          # 以下
ds[ds['name'] == 'Alice']    # 等しい
ds[ds['name'] != 'Bob']      # 等しくない

論理演算

ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # AND
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # OR
ds[~(ds['status'] == 'inactive')]               # NOT

メソッド

メソッド	説明
`as_(alias)`	エイリアス名を設定
`cast(dtype)`	型に CAST
`astype(dtype)`	cast のエイリアス
`isnull()`	NULL である
`notnull()`	NULL ではない
`isna()`	isnull のエイリアス
`notna()`	notnull のエイリアス
`isin(values)`	値のリストに含まれる
`between(low, high)`	2 つの値の間にある
`fillna(value)`	NULL を補完
`replace(to_replace, value)`	値を置換
`clip(lower, upper)`	値を範囲内に切り詰める
`abs()`	絶対値
`round(decimals)`	値を丸める
`floor()`	切り捨て
`ceil()`	切り上げ
`apply(func)`	関数を適用
`map(mapper)`	値をマッピング

集計メソッド

メソッド	説明
`sum()`	合計
`mean()`	平均
`avg()`	`mean` の別名
`min()`	最小値
`max()`	最大値
`count()`	null 以外の値の数
`nunique()`	一意な値の数
`std()`	標準偏差
`var()`	分散
`median()`	中央値
`quantile(q)`	分位点
`first()`	最初の値
`last()`	最後の値
`any()`	いずれかが true
`all()`	すべてが true

LazyGroupBy

集約処理用にグループ化された DataStore を表します。

# LazyGroupBy は自動的に返されます
grouped = ds.groupby('category')  # LazyGroupBy を返します

メソッド

メソッド	戻り値	説明
`agg(spec)`	DataStore	集約
`aggregate(spec)`	DataStore	`agg` のエイリアス
`sum()`	DataStore	グループごとの合計
`mean()`	DataStore	グループごとの平均
`count()`	DataStore	グループごとの件数
`min()`	DataStore	グループごとの最小値
`max()`	DataStore	グループごとの最大値
`std()`	DataStore	グループごとの標準偏差
`var()`	DataStore	グループごとの分散
`median()`	DataStore	グループごとの中央値
`nunique()`	DataStore	グループごとの一意な値の件数
`first()`	DataStore	グループごとの最初の値
`last()`	DataStore	グループごとの最後の値
`nth(n)`	DataStore	グループごとの n 番目の値
`head(n)`	DataStore	グループごとの先頭 n 件
`tail(n)`	DataStore	グループごとの末尾 n 件
`apply(func)`	DataStore	グループごとに関数を適用
`transform(func)`	DataStore	グループごとに変換を適用
`filter(func)`	DataStore	グループを絞り込む

カラム選択

# groupby後にカラムを選択
grouped['amount'].sum()     # DataStoreを返す
grouped[['a', 'b']].sum()   # DataStoreを返す

集計仕様

# 単一の集計
grouped.agg({'amount': 'sum'})

# カラムごとの複数の集計
grouped.agg({'amount': ['sum', 'mean', 'count']})

# 名前付き集計
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)

LazySeries

遅延評価される Series (単一カラム) を表します。

プロパティ

プロパティ	型	説明
`name`	str	Series名
`dtype`	dtype	データ型

メソッド

ColumnExpr のメソッドの大半を継承します。主なメソッドは次のとおりです。

メソッド	説明
`value_counts()`	値ごとの出現頻度
`unique()`	一意の値
`nunique()`	一意の値の数
`mode()`	最頻値
`to_list()`	リストに変換
`to_numpy()`	配列に変換
`to_frame()`	DataStore に変換

F (関数)

ClickHouse 関数の名前空間。

from chdb.datastore import F, Field

# 集計
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

# 条件付き
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('active'))

# ウィンドウ
F.row_number().over(order_by='date')
F.lag('price', 1).over(partition_by='product', order_by='date')

詳細は、集約を参照してください。

Field

カラムを名前で参照します。

from chdb.datastore import Field

# フィールド参照を作成する
amount = Field('amount')
price = Field('price')

# 式で使用する
F.sum(Field('amount'))
F.avg(Field('price'))

CaseWhen

CASE WHEN 式を構築するためのクラス。

# case-when式を作成する
result = (ds
    .when(ds['score'] >= 90, 'A')
    .when(ds['score'] >= 80, 'B')
    .when(ds['score'] >= 70, 'C')
    .otherwise('F')
)

# カラムに代入する
ds['grade'] = result

Window

ウィンドウ関数のウィンドウ指定。

from chdb.datastore import F

# ウィンドウを作成
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)
)

# 集計に使用
ds['rolling_avg'] = F.avg('price').over(window)

​DataStore

​コンストラクタ

​プロパティ

​ファクトリメソッド

​クエリメソッド

​Pandas 互換メソッド

​I/O メソッド

​デバッグメソッド

​特殊メソッド

​ColumnExpr

​プロパティ

​アクセサ

​算術演算

​比較演算

​論理演算

​メソッド

​集計メソッド

​LazyGroupBy

​メソッド

​カラム選択

​集計仕様

​LazySeries

​プロパティ

​メソッド

​関連クラス

​F (関数)

​Field

​CaseWhen

​Window

DataStore

コンストラクタ

プロパティ

ファクトリメソッド

クエリメソッド

Pandas 互換メソッド

I/O メソッド

デバッグメソッド

特殊メソッド

ColumnExpr

プロパティ

アクセサ

算術演算

比較演算

論理演算

メソッド

集計メソッド

LazyGroupBy

メソッド

カラム選択

集計仕様

LazySeries

プロパティ

メソッド

関連クラス

F (関数)

Field

CaseWhen

Window