DataStore Pandas 호환성 | ClickHouse Docs

DataStore는 완전한 API 호환성을 위해 209개의 pandas DataFrame 메서드를 구현합니다. 기존 pandas 코드는 거의 수정하지 않고도 사용할 수 있습니다.

호환성 접근법

# Typical migration - just change the import
- import pandas as pd
+ from chdb import datastore as pd

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

핵심 원칙:

209개의 pandas DataFrame 메서드를 모두 구현
SQL 최적화를 위한 지연 평가
자동 유형 래핑(DataFrame → DataStore, Series → ColumnExpr)
불변 연산(inplace=True 미지원)

속성 및 프로퍼티

속성	설명	실행 트리거
`shape`	(행, 컬럼) 튜플	예
`columns`	컬럼 이름 (Index)	예
`dtypes`	컬럼 데이터 타입	예
`values`	NumPy 배열	예
`index`	행 인덱스	예
`size`	원소 수	예
`ndim`	차원 수	아니요
`empty`	DataFrame이 비어 있는지 여부	예
`T`	전치	예
`axes`	축 목록	예

예시:

from chdb import datastore as pd

ds = pd.read_csv("data.csv")

print(ds.shape)      # (1000, 5)
print(ds.columns)    # Index(['name', 'age', 'city', 'salary', 'dept'])
print(ds.dtypes)     # name: object, age: int64, ...
print(ds.empty)      # False

인덱싱 및 선택

메서드	설명	예시
`df['col']`	컬럼 선택	`ds['age']`
`df[['col1', 'col2']]`	여러 컬럼 선택	`ds[['name', 'age']]`
`df[condition]`	Boolean 인덱싱	`ds[ds['age'] > 25]`
`df.loc[...]`	레이블 기반 접근	`ds.loc[0:10, 'name']`
`df.iloc[...]`	정수 위치 기반 접근	`ds.iloc[0:10, 0:3]`
`df.at[...]`	레이블로 단일 값 접근	`ds.at[0, 'name']`
`df.iat[...]`	위치로 단일 값 접근	`ds.iat[0, 0]`
`df.head(n)`	처음 n개 행	`ds.head(10)`
`df.tail(n)`	마지막 n개 행	`ds.tail(10)`
`df.sample(n)`	무작위 표본 추출	`ds.sample(100)`
`df.select_dtypes()`	Dtype별 선택	`ds.select_dtypes(include='number')`
`df.query()`	쿼리 표현식	`ds.query('age > 25')`
`df.where()`	조건부 대체	`ds.where(ds['age'] > 0, 0)`
`df.mask()`	where의 반대 조건 적용	`ds.mask(ds['age'] < 0, 0)`
`df.isin()`	값 포함 여부 확인	`ds['city'].isin(['NYC', 'LA'])`
`df.get()`	안전한 컬럼 접근	`ds.get('col', default=None)`
`df.xs()`	단면 선택	`ds.xs('key')`
`df.pop()`	컬럼 제거	`ds.pop('col')`

통계 메서드

메서드	설명	SQL 대응식
`mean()`	평균값	`AVG()`
`median()`	중앙값	`MEDIAN()`
`mode()`	최빈값	-
`std()`	표준편차	`STDDEV()`
`var()`	분산	`VAR()`
`min()`	최솟값	`MIN()`
`max()`	최댓값	`MAX()`
`sum()`	합계	`SUM()`
`prod()`	곱	-
`count()`	NULL이 아닌 개수	`COUNT()`
`nunique()`	고유값 개수	`UNIQ()`
`value_counts()`	값별 빈도	`GROUP BY`
`quantile()`	분위수	`QUANTILE()`
`describe()`	요약 통계	-
`corr()`	상관관계 매트릭스	`CORR()`
`cov()`	공분산 매트릭스	`COV()`
`corrwith()`	쌍별 상관관계	-
`rank()`	순위값	`RANK()`
`abs()`	절댓값	`ABS()`
`round()`	값 반올림	`ROUND()`
`clip()`	값 클리핑	-
`cumsum()`	누적 합	윈도 함수
`cumprod()`	누적 곱	윈도 함수
`cummin()`	누적 최솟값	윈도 함수
`cummax()`	누적 최댓값	윈도 함수
`diff()`	차이	윈도 함수
`pct_change()`	변화율	윈도 함수
`skew()`	왜도	`SKEW()`
`kurt()`	첨도	`KURT()`
`sem()`	표준 오차	-
`all()`	모두 true	-
`any()`	하나라도 true	-
`idxmin()`	최솟값의 인덱스	-
`idxmax()`	최댓값의 인덱스	-

예시:

ds = pd.read_csv("data.csv")

# Basic statistics
print(ds['salary'].mean())
print(ds['age'].std())
print(ds.describe())

# Group statistics
print(ds.groupby('department')['salary'].mean())
print(ds.groupby('city').agg({'salary': ['mean', 'std'], 'age': 'count'}))

데이터 조작

Method	Description
`drop()`	행/컬럼 삭제
`drop_duplicates()`	중복 제거
`duplicated()`	중복 표시
`dropna()`	결측값 제거
`fillna()`	결측값 채우기
`ffill()`	이전 값으로 채우기
`bfill()`	다음 값으로 채우기
`interpolate()`	값 보간
`replace()`	값 대체
`rename()`	컬럼/인덱스 이름 변경
`rename_axis()`	축 이름 변경
`assign()`	새 컬럼 추가
`astype()`	타입 변환
`convert_dtypes()`	타입 추론
`copy()`	DataFrame 복사

예시:

ds = pd.read_csv("data.csv")

# Drop operations
result = ds.drop(columns=['unused_col'])
result = ds.drop_duplicates(subset=['user_id'])
result = ds.dropna(subset=['email'])

# Fill operations
result = ds.fillna(0)
result = ds.fillna({'age': 0, 'name': 'Unknown'})

# Transform operations
result = ds.rename(columns={'old_name': 'new_name'})
result = ds.assign(
    full_name=lambda x: x['first_name'] + ' ' + x['last_name'],
    age_group=lambda x: pd.cut(x['age'], bins=[0, 25, 50, 100])
)

정렬 및 순위 매기기

메서드	설명
`sort_values()`	값을 기준으로 정렬
`sort_index()`	인덱스를 기준으로 정렬
`nlargest()`	가장 큰 값 N개
`nsmallest()`	가장 작은 값 N개

예시:

# Sort by single column
result = ds.sort_values('salary', ascending=False)

# Sort by multiple columns
result = ds.sort_values(['department', 'salary'], ascending=[True, False])

# Get top/bottom N
result = ds.nlargest(10, 'salary')
result = ds.nsmallest(5, 'age')

형태 변환

메서드	설명
`pivot()`	피벗 테이블
`pivot_table()`	집계 피벗
`melt()`	언피벗
`stack()`	컬럼을 인덱스로 변환
`unstack()`	인덱스를 컬럼으로 변환
`transpose()` / `T`	전치
`explode()`	리스트를 행으로 펼치기
`squeeze()`	차원 축소
`droplevel()`	인덱스 수준 삭제
`swaplevel()`	인덱스 수준 스왑
`reorder_levels()`	수준 순서 재정렬

예시:

# Pivot table
result = ds.pivot_table(
    values='amount',
    index='region',
    columns='product',
    aggfunc='sum'
)

# Melt (unpivot)
result = ds.melt(
    id_vars=['name'],
    value_vars=['score1', 'score2', 'score3'],
    var_name='test',
    value_name='score'
)

# Explode arrays
result = ds.explode('tags')

결합 / 조인

메서드	설명
`merge()`	SQL 방식 머지
`join()`	인덱스를 기준으로 조인
`concat()`	연결
`append()`	행 추가
`combine()`	함수를 사용해 결합
`combine_first()`	우선순위에 따라 결합
`update()`	값 업데이트
`compare()`	차이점 표시

예시:

# Merge (join)
result = pd.merge(df1, df2, on='id', how='left')
result = df1.join(df2, on='id')

# Concatenate
result = pd.concat([df1, df2, df3])
result = pd.concat([df1, df2], axis=1)

이항 연산

메서드	설명
`add()` / `radd()`	덧셈
`sub()` / `rsub()`	뺄셈
`mul()` / `rmul()`	곱셈
`div()` / `rdiv()`	나눗셈
`truediv()` / `rtruediv()`	실수 나눗셈
`floordiv()` / `rfloordiv()`	내림 나눗셈
`mod()` / `rmod()`	modulo
`pow()` / `rpow()`	거듭제곱
`dot()`	매트릭스 곱셈

예시:

# Arithmetic operations
result = ds['col1'].add(ds['col2'])
result = ds['price'].mul(ds['quantity'])

# With fill_value for missing data
result = ds['col1'].add(ds['col2'], fill_value=0)

비교 연산

메서드	설명
`eq()`	같음
`ne()`	같지 않음
`lt()`	미만
`le()`	이하
`gt()`	초과
`ge()`	이상
`equals()`	일치 여부 검사
`compare()`	차이점 표시

함수 적용

메서드	설명
`apply()`	함수 적용
`applymap()`	요소별 적용
`map()`	값 매핑
`agg()` / `aggregate()`	집계
`transform()`	변환
`pipe()`	함수 연결
`groupby()`	그룹화

예시:

# Apply function
result = ds['name'].apply(lambda x: x.upper())
result = ds.apply(lambda row: row['a'] + row['b'], axis=1)

# Aggregate
result = ds.agg({'col1': 'sum', 'col2': 'mean'})
result = ds.agg(['sum', 'mean', 'std'])

# Pipe
result = (ds
    .pipe(filter_active)
    .pipe(calculate_metrics)
    .pipe(format_output)
)

시계열

메서드	설명
`rolling()`	이동 윈도우
`expanding()`	확장 윈도우
`ewm()`	지수 가중
`resample()`	시계열 재샘플링
`shift()`	값 이동
`asfreq()`	빈도 변환
`asof()`	해당 시점 기준 최신 값
`at_time()`	지정 시간 선택
`between_time()`	시간 범위 선택
`first()` / `last()`	첫/마지막 주기
`to_period()`	주기로 변환
`to_timestamp()`	타임스탬프로 변환
`tz_convert()`	시간대 변환
`tz_localize()`	시간대 지정

예시:

# Rolling window
result = ds['value'].rolling(window=7).mean()

# Expanding window
result = ds['value'].expanding().sum()

# Shift
result = ds['value'].shift(1)  # Lag
result = ds['value'].shift(-1)  # Lead

결측 데이터

메서드	설명
`isna()` / `isnull()`	결측값 감지
`notna()` / `notnull()`	비결측값 감지
`dropna()`	결측값 삭제
`fillna()`	결측값 채우기
`ffill()`	앞의 값으로 채우기
`bfill()`	뒤의 값으로 채우기
`interpolate()`	보간
`replace()`	값 대체

I/O 메서드

메서드	설명
`to_csv()`	CSV로 내보내기
`to_json()`	JSON으로 내보내기
`to_excel()`	Excel로 내보내기
`to_parquet()`	Parquet로 내보내기
`to_feather()`	Feather로 내보내기
`to_sql()`	SQL 데이터베이스로 내보내기
`to_pickle()`	Pickle
`to_html()`	HTML 테이블
`to_latex()`	LaTeX 테이블
`to_markdown()`	Markdown 테이블
`to_string()`	문자열 표현
`to_dict()`	딕셔너리
`to_records()`	레코드
`to_numpy()`	NumPy 배열
`to_clipboard()`	클립보드

자세한 문서는 I/O Operations를 참조하십시오.

반복

메서드	설명
`items()`	(컬럼, Series) 쌍을 순회
`iterrows()`	(인덱스, Series) 쌍을 순회
`itertuples()`	이름이 지정된 Tuple 형태로 순회

Pandas와의 주요 차이점

1. 반환 타입

# Pandas returns Series
pdf['col']  # → pd.Series

# DataStore returns ColumnExpr (lazy)
ds['col']   # → ColumnExpr

2. 지연 실행

# DataStore operations are lazy
result = ds.filter(ds['age'] > 25)  # Not executed yet
df = result.to_df()  # Executed here

3. inplace 매개변수 없음

# Pandas
df.drop(columns=['col'], inplace=True)

# DataStore (always returns new object)
ds = ds.drop(columns=['col'])

4. 결과 비교

# Use to_pandas() for comparison
pd.testing.assert_frame_equal(
    ds.to_pandas(),
    expected_df
)

자세한 내용은 주요 차이점을 참조하십시오.