실행 엔진 구성

DataStore 실행 엔진 구성 - auto, chdb 또는 pandas

DataStore는 다양한 백엔드를 사용해 연산을 실행할 수 있습니다. 이 가이드에서는 실행 엔진 선택을 구성하고 최적화하는 방법을 설명합니다.

​

사용 가능한 엔진

엔진	설명	가장 적합한 용도
auto	작업별로 가장 적합한 엔진을 자동으로 선택합니다	일반 용도(기본값)
chdb	모든 작업에 ClickHouse SQL을 사용합니다	대규모 데이터, 집계
pandas	모든 작업에 pandas를 사용합니다	호환성 테스트, pandas 전용 기능

​

엔진 설정

​

전역 구성

from chdb.datastore.config import config

# 옵션 1: set 메서드 사용
config.set_execution_engine('auto')    # 기본값
config.set_execution_engine('chdb')    # ClickHouse 강제 사용
config.set_execution_engine('pandas')  # pandas 강제 사용

# 옵션 2: 단축 메서드 사용
config.use_auto()     # 자동 선택
config.use_chdb()     # ClickHouse 강제 사용
config.use_pandas()   # pandas 강제 사용

​

현재 엔진 확인

print(config.execution_engine)  # 'auto', 'chdb', 또는 'pandas'

---

​

자동 모드

auto 모드(기본값)에서는 DataStore가 각 연산에 가장 적합한 엔진을 선택합니다:

​

chDB에서 실행되는 연산

• SQL 호환 필터링 (filter(), where())
• 컬럼 선택 (select())
• 정렬 (sort(), orderby())
• 그룹화 및 집계 (groupby().agg())
• 조인 (join(), merge())
• 중복 제거 (distinct(), drop_duplicates())
• 개수 제한 (limit(), head(), tail())

​

pandas에서 실행하는 작업

• 사용자 정의 apply 함수 (apply(custom_func))
• 사용자 정의 집계를 사용하는 복잡한 피벗 테이블
• SQL로 표현할 수 없는 작업
• 입력이 이미 pandas DataFrame인 경우

​

예시

from chdb import datastore as pd
from chdb.datastore.config import config

config.use_auto()  # 기본값

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

# chDB(SQL) 사용
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# pandas 사용 (사용자 정의 함수)
result = ds.apply(lambda row: complex_calculation(row), axis=1)

---

​

chDB 모드

모든 작업을 ClickHouse SQL을 통해 수행하도록 강제합니다:

config.use_chdb()

​

사용해야 하는 경우

• 대규모 데이터셋(수백만 개의 행) 처리
• 집계 중심 워크로드
• SQL 최적화를 최대한 활용하려는 경우
• 모든 작업에서 일관된 동작이 필요한 경우

​

성능 특성

작업 유형	성능
GroupBy/집계	매우 우수함 (최대 20배 빠름)
복잡한 필터링	매우 우수함
정렬	매우 우수
단순한 단일 필터	양호함 (약간의 오버헤드)

​

제한 사항

• 사용자 정의 Python 함수는 지원되지 않을 수 있습니다.
• 일부 pandas 전용 기능은 변환이 필요할 수 있습니다.

---

​

pandas 모드

모든 작업을 pandas를 통해 수행하도록 강제합니다:

config.use_pandas()

​

사용해야 하는 경우

• pandas와의 호환성 테스트
• pandas 전용 기능 사용
• pandas 관련 문제 디버깅
• 데이터가 이미 pandas 포맷인 경우

​

성능 특성

작업 유형	성능
단순 작업	양호
사용자 정의 함수	매우 우수
복잡한 집계	chDB보다 느림
대규모 데이터셋	메모리 사용량이 큼

---

​

Cross-DataStore 엔진

서로 다른 DataStore의 컬럼을 결합하는 작업에 사용할 엔진을 구성합니다:

# cross-DataStore 엔진 설정
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')

​

예시

ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# 이 작업은 두 개의 DataStore를 포함합니다
result = ds1.join(ds2, on='product_id')
# cross_datastore_engine 설정을 사용합니다

---

​

엔진 선택 로직

​

자동 모드 의사결정 트리

작업 요청
    │
    ├─ SQL로 표현 가능?
    │      │
    │      ├─ 예 → chDB 사용
    │      │
    │      └─ 아니오 → pandas 사용
    │
    └─ Cross-DataStore 작업?
           │
           └─ cross_datastore_engine 설정 사용

​

함수 수준 재정의

일부 함수는 사용할 엔진을 명시적으로 지정할 수 있습니다:

from chdb.datastore.config import function_config

# 특정 함수가 특정 엔진을 사용하도록 강제 지정
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')

자세한 내용은 Function Config를 참고하십시오.

---

​

성능 비교

1,000만 행 기준 벤치마크 결과:

연산	pandas (ms)	chdb (ms)	속도 향상
GroupBy 카운트	347	17	19.93x
복합 연산	1,535	234	6.56x
복잡한 파이프라인	2,047	380	5.39x
Filter+Sort+Head	1,537	350	4.40x
GroupBy 집계	406	141	2.88x
단일 필터	276	526	0.52x

핵심 사항:

• chdb는 집계와 복잡한 파이프라인에서 강점을 보입니다
• pandas는 단순한 단일 연산에서는 약간 더 빠릅니다
• 두 방식의 장점을 모두 활용하려면 auto 모드를 사용하세요

---

​

권장 사항

​

1. 자동 모드부터 시작하세요

config.use_auto()  # DataStore가 자동으로 결정

​

2. 강제 적용 전 프로파일링

config.enable_profiling()
# 워크로드를 실행하세요
# 프로파일러 보고서를 확인하여 시간이 소요되는 부분을 파악하세요

​

3. 특정 워크로드에 엔진 강제 지정

# 대용량 집계 워크로드의 경우
config.use_chdb()

# pandas 호환성 테스트의 경우
config.use_pandas()

​

4. explain()을 사용해 실행 과정 이해하기

ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

# 생성될 SQL 확인
query.explain()

---

​

문제 해결

​

문제: 작업 속도가 예상보다 느림

# 현재 엔진 확인
print(config.execution_engine)

# 디버그를 활성화하여 상황 확인
config.enable_debug()

# 특정 엔진 강제 지정 시도
config.use_chdb()  # or config.use_pandas()

​

문제: chdb 모드에서 지원되지 않는 작업

# 일부 pandas 연산은 SQL에서 지원되지 않습니다
# 해결 방법: auto 모드 사용
config.use_auto()

# 또는 먼저 pandas로 명시적으로 변환
df = ds.to_df()
result = df.some_pandas_specific_operation()

​

문제: 대용량 데이터 처리 시 메모리 문제

# 모든 데이터를 메모리에 로드하지 않도록 chdb 엔진을 사용합니다
config.use_chdb()

# 데이터 크기를 줄이기 위해 초기에 필터링합니다
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# 대용량 데이터셋의 최대 처리량을 위해 성능 모드를 사용합니다
# 성능 모드는 병렬 Parquet 읽기와 단일 SQL 집계를 활성화합니다
config.use_performance_mode()

성능 모드

집계 부하가 큰 워크로드를 실행 중이며 pandas 출력과의 완전한 호환성(행 순서, MultiIndex, dtype 보정)이 필요하지 않다면 성능 모드 사용을 고려하십시오. 이 모드는 엔진을 자동으로 chdb로 설정하고 pandas 호환성으로 인한 모든 오버헤드를 제거합니다.