DataStore: SQL 최적화가 적용된 Pandas 호환 API

DataStore는 고성능 데이터 분석을 위한 SQL 최적화 기반의 Pandas 호환 API를 제공합니다

DataStore는 익숙한 Pandas DataFrame 인터페이스와 SQL 쿼리 최적화의 강점을 결합한 chDB의 Pandas 호환 API로, Pandas 스타일의 코드를 작성하면서도 ClickHouse의 성능을 활용할 수 있습니다.

​

주요 기능

• Pandas 호환성: 209개의 pandas DataFrame 메서드, 56개의 .str 메서드, 42개 이상의 .dt 메서드
• SQL 최적화: 연산이 자동으로 최적화된 SQL 쿼리로 컴파일됩니다
• 지연 평가: 결과가 필요한 시점까지 연산이 지연됩니다
• 630개 이상의 API 메서드: 데이터 조작을 위한 포괄적인 API 범위
• ClickHouse 확장 기능: pandas에서 제공하지 않는 추가 Accessor(.arr, .json, .url, .ip, .geo)

​

아키텍처

DataStore는 **지연 평가(lazy evaluation)**와 이중 엔진 실행을 사용합니다:

1. 지연 연산 체인: 연산은 즉시 실행되지 않고 기록만 됩니다
2. 스마트 엔진 선택: QueryPlanner가 각 세그먼트를 최적의 엔진으로 보냅니다(SQL은 chDB, 복잡한 연산은 Pandas)
3. 중간 결과 캐싱: 빠른 반복 탐색을 위해 각 단계의 결과를 캐시합니다

자세한 내용은 실행 모델을 참조하십시오.

​

Pandas에서 한 줄로 마이그레이션

# 이전 (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# 이후 (DataStore) - import만 변경하면 됩니다!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

기존 pandas 코드는 변경 없이 그대로 작동하지만, 이제 ClickHouse engine에서 실행됩니다.

​

성능 비교

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 연산을 수행할 때
• 파일, 데이터베이스 또는 클라우드 스토리지의 데이터를 쿼리할 때
• 복잡한 데이터 파이프라인을 구축할 때
• 더 나은 성능의 pandas API가 필요할 때

다음과 같은 경우 raw SQL API를 사용하세요:

• SQL을 직접 작성하는 방식을 선호할 때
• 쿼리 실행을 세밀하게 제어해야 할 때
• pandas API에서 제공되지 않는 ClickHouse 고유 기능을 사용해야 할 때

​

기능 비교

기능	Pandas	Polars	DuckDB	DataStore
Pandas API 호환성	-	부분 지원	아니요	완전 지원
지연 평가	아니요	예	예	예
SQL 쿼리 지원	아니요	예	예	예
ClickHouse 함수	아니요	아니요	아니요	예
String/DateTime Accessor	예	예	아니요	예 + 추가 기능
배열/JSON/URL/IP/Geo	아니요	부분 지원	아니요	예
파일 직접 쿼리	아니요	예	예	예
클라우드 스토리지 지원	아니요	제한적	예	예

​

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+	-

​

문서 탐색

​

시작하기

• Quickstart - 설치 및 기본 사용법
• Pandas 마이그레이션 - 단계별 마이그레이션 가이드

​

API 참조

• 팩토리 메서드 - 다양한 소스에서 DataStore를 생성
• 쿼리 작성 - SQL 스타일 쿼리 작업
• Pandas 호환성 - pandas와 호환되는 209개 메서드
• Accessor - String, DateTime, 배열, JSON, URL, IP, Geo Accessor
• 집계 - 집계 및 윈도우 함수
• I/O 작업 - 데이터 읽기 및 쓰기

​

고급 주제

• 실행 모델 - 지연 평가 및 캐싱
• 클래스 참조 - 전체 API 참조

​

구성 및 디버깅

• 구성 - 모든 구성 옵션
• 성능 모드 - 최대 처리량을 위한 SQL 우선 모드
• 디버깅 - Explain, 프로파일링, 로깅

​

Pandas 사용자 가이드

• Pandas Cookbook - 자주 쓰는 패턴
• Key Differences - Pandas와의 주요 차이점
• 성능 가이드 - 최적화 팁
• SQL for Pandas Users - Pandas 작업의 기반이 되는 SQL 이해하기

​

간단한 예시

from chdb import datastore as pd

# 다양한 소스에서 데이터 읽기
ds = pd.read_csv("sales.csv")
# 또는: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# 또는: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# 익숙한 pandas 연산 - 자동으로 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
)

# 생성된 SQL 확인
print(result.to_sql())

# 실행 및 결과 가져오기
df = result.to_df()  # pandas DataFrame 반환

​

다음 단계

• DataStore가 처음이신가요? quickstart 가이드부터 시작하세요
• pandas를 사용 중이신가요? 마이그레이션 가이드를 읽어보세요
• 더 알아보고 싶으신가요? API 참조를 살펴보세요