DataStore 디버깅 | ClickHouse Docs

DataStore는 데이터 파이프라인을 이해하고 최적화하는 데 도움이 되는 종합적인 디버깅 도구를 제공합니다.

디버깅 도구 개요

도구	목적	사용 시점
`explain()`	실행 계획 보기	실행될 SQL 파악
프로파일러	성능 측정	느린 작업 식별
로깅	실행 세부 정보 보기	예기치 않은 동작 문제 해결

빠른 의사결정 매트릭스

필요 사항	도구	명령
실행 계획 확인	`explain()`	`ds.explain()`
성능 측정	프로파일러	`config.enable_profiling()`
SQL 쿼리 디버깅	로깅	`config.enable_debug()`
위 항목 모두	조합	아래 참조

빠른 설정

전체 디버깅 활성화

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

# Enable all debugging
config.enable_debug()        # Verbose logging
config.enable_profiling()    # Performance tracking

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

# View execution plan
result.explain()

# Get profiler report
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()

explain() 메서드

쿼리를 실행하기 전에 실행 계획을 확인합니다.

Querypython

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

query = (ds
    .filter(ds['amount'] > 1000)
    .groupby('region')
    .agg({'amount': ['sum', 'mean']})
)

# View plan
query.explain()

Responsetext

Pipeline:
  Source: file('data.csv', 'CSVWithNames')
  Filter: amount > 1000
  GroupBy: region
  Aggregate: sum(amount), avg(amount)

Generated SQL:
SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE amount > 1000
GROUP BY region

explain() 문서에서 자세한 내용을 확인하십시오.

프로파일링

각 연산의 실행 시간을 측정합니다.

Querypython

from chdb.datastore.config import config, get_profiler

# Enable profiling
config.enable_profiling()

# Run operations
ds = pd.read_csv("large_data.csv")
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('category')
    .agg({'amount': 'sum'})
    .sort('sum', ascending=False)
    .head(10)
    .to_df()
)

# View report
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)

Responsetext

Performance Report
==================
Step                          Duration    Calls
----                          --------    -----
read_csv                      1.234s      1
filter                        0.002s      1
groupby                       0.001s      1
agg                           0.089s      1
sort                          0.045s      1
head                          0.001s      1
to_df (SQL execution)         0.567s      1
----                          --------    -----
Total                         1.939s      7

자세한 내용은 프로파일링 가이드를 참조하십시오.

로깅

자세한 실행 로그를 확인합니다.

from chdb.datastore.config import config

# Enable debug logging
config.enable_debug()

# Run operations - logs will show:
# - SQL queries generated
# - Execution engine used
# - Cache hits/misses
# - Timing information

로그 출력 예시:

DEBUG - DataStore: Creating from file 'data.csv'
DEBUG - Query: SELECT region, SUM(amount) FROM ... WHERE amount > 1000 GROUP BY region
DEBUG - Engine: Using chdb for aggregation
DEBUG - Execution time: 0.089s
DEBUG - Cache: Storing result (key: abc123)

자세한 내용은 로깅 구성을 확인하십시오.

일반적인 디버깅 시나리오

1. 쿼리 결과가 예상과 다른 경우

# Step 1: View the execution plan
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)

# Step 2: Enable logging to see SQL
config.enable_debug()

# Step 3: Run and check logs
result = query.to_df()

2. 쿼리 실행이 느린 경우

# Step 1: Enable profiling
config.enable_profiling()

# Step 2: Run your query
result = process_data()

# Step 3: Check profiler report
profiler = get_profiler()
profiler.report()

# Step 4: Identify slow operations and optimize

3. 엔진 선택 이해하기

# Enable verbose logging
config.enable_debug()

# Run operations
result = ds.filter(ds['x'] > 10).apply(custom_func)

# Logs will show which engine was used for each operation:
# DEBUG - filter: Using chdb engine
# DEBUG - apply: Using pandas engine (custom function)

4. 캐시 문제 디버깅

# Enable debug to see cache operations
config.enable_debug()

# First run
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache miss, executing query

# Second run (should use cache)
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache hit, returning cached result

# If not caching when expected, check:
# - Are operations identical?
# - Is cache enabled? config.cache_enabled

권장 사항

1. 프로덕션이 아닌 개발 환경에서 디버깅하기

# Development
config.enable_debug()
config.enable_profiling()

# Production
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)

2. 대규모 쿼리를 실행하기 전에 explain()을 사용하세요

# Build query
query = ds.filter(...).groupby(...).agg(...)

# Check plan first
query.explain()

# If plan looks good, execute
result = query.to_df()

3. 최적화 전에 프로파일링하세요

# Don't guess what's slow - measure it
config.enable_profiling()
result = your_pipeline()
get_profiler().report()

4. 결과가 올바르지 않을 때 SQL 확인

# View generated SQL
print(query.to_sql())

# Compare with expected SQL
# Run SQL directly in ClickHouse to verify

디버깅 도구 요약

도구	명령	출력
실행 계획 확인	`ds.explain()`	실행 단계 + SQL
상세 실행 계획 확인	`ds.explain(verbose=True)`	+ 메타데이터
SQL 보기	`ds.to_sql()`	SQL 쿼리 문자열
디버그 활성화	`config.enable_debug()`	상세 logs
프로파일링 활성화	`config.enable_profiling()`	시간 측정 데이터
프로파일러 보고서	`get_profiler().report()`	성능 요약
프로파일러 초기화	`get_profiler().reset()`	시간 측정 데이터 삭제

다음 단계

explain() 메서드 - 상세한 실행 계획 문서
프로파일링 가이드 - 성능 측정
로깅 구성 - 로그 레벨 및 포맷 설정