速查
from chdb.datastore.config import config
# 快速设置预设
config.enable_debug() # 启用详细日志
config.use_chdb() # 强制使用 ClickHouse 引擎
config.use_pandas() # 强制使用 pandas 引擎
config.use_auto() # 自动选择引擎（默认）
config.use_performance_mode() # SQL 优先，最大吞吐量
config.use_pandas_compat() # 完整 Pandas 兼容性（默认）
config.enable_profiling() # 启用性能分析
所有配置选项
| 类别 | 选项 | 取值 | 默认值 | 描述 |
|---|---|---|---|---|
| 日志 | log_level | DEBUG/INFO/WARNING/ERROR | WARNING | 日志详细级别 |
log_format | ”simple”, “verbose" | "simple” | 日志消息格式 | |
| 缓存 | cache_enabled | True/False | True | 启用结果缓存 |
cache_ttl | float (秒) | 0.0 | 缓存生存时间 (TTL) | |
| 引擎 | execution_engine | ”auto”, “chdb”, “pandas" | "auto” | 执行引擎 |
cross_datastore_engine | ”auto”, “chdb”, “pandas" | "auto” | 跨 DataStore 操作 | |
| 兼容性 | compat_mode | ”pandas”, “performance" | "pandas” | 侧重 Pandas 兼容性还是 SQL 优先的吞吐量 |
| 性能分析 | profiling_enabled | True/False | False | 启用性能分析 |
| Dtype | correction_level | NONE/CRITICAL/HIGH/MEDIUM/ALL | HIGH | Dtype 修正级别 |
配置方式
日志配置
from chdb.datastore.config import config
import logging
# 设置日志级别
config.set_log_level(logging.DEBUG)
config.set_log_level(logging.INFO)
config.set_log_level(logging.WARNING) # 默认
config.set_log_level(logging.ERROR)
# 设置日志格式
config.set_log_format("simple") # 默认
config.set_log_format("verbose") # 更多详情
# 快速启用调试模式
config.enable_debug() # 设置 DEBUG 级别 + 详细格式
缓存配置
# 启用/禁用缓存
config.set_cache_enabled(True) # 默认
config.set_cache_enabled(False) # 禁用缓存
# 设置缓存 TTL（生存时间）
config.set_cache_ttl(60.0) # 缓存 60 秒后过期
config.set_cache_ttl(0.0) # 永不过期（默认）
# 查看当前设置
print(config.cache_enabled)
print(config.cache_ttl)
引擎配置
# 设置执行引擎
config.set_execution_engine('auto') # 自动选择（默认）
config.set_execution_engine('chdb') # 强制使用 ClickHouse
config.set_execution_engine('pandas') # 强制使用 pandas
# 快速预设
config.use_auto() # 自动选择
config.use_chdb() # 强制使用 ClickHouse
config.use_pandas() # 强制使用 pandas
# 跨 DataStore 执行引擎（用于不同 DataStore 之间的操作）
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
# 查看当前执行引擎
print(config.execution_engine)
兼容模式
# 性能模式：SQL 优先，无 pandas 兼容性开销
config.use_performance_mode()
# 或：config.set_compat_mode('performance')
# Pandas 兼容性模式（默认）
config.use_pandas_compat()
# 或：config.set_compat_mode('pandas')
# 检查当前模式
print(config.compat_mode) # 'pandas' 或 'performance'
性能分析配置
# 启用性能分析
config.enable_profiling()
config.set_profiling_enabled(True)
# 禁用性能分析
config.set_profiling_enabled(False)
# 检查性能分析是否已启用
print(config.profiling_enabled)
Dtype 修正
from chdb.datastore.dtype_correction.config import CorrectionLevel
# 设置修正级别
config.set_correction_level(CorrectionLevel.NONE) # 不进行修正
config.set_correction_level(CorrectionLevel.CRITICAL) # 仅修正关键类型
config.set_correction_level(CorrectionLevel.HIGH) # 默认
config.set_correction_level(CorrectionLevel.MEDIUM) # 更多修正
config.set_correction_level(CorrectionLevel.ALL) # 全部修正
使用 config 对象
config 对象是一个用于管理所有配置的单例：
from chdb.datastore.config import config
# 读取设置
print(config.log_level)
print(config.execution_engine)
print(config.cache_enabled)
print(config.profiling_enabled)
# 修改设置
config.set_log_level(logging.DEBUG)
config.set_execution_engine('chdb')
config.set_cache_enabled(False)
config.enable_profiling()
代码中的配置
脚本级配置
from chdb import datastore as pd
from chdb.datastore.config import config
# 在脚本开头进行配置
config.enable_debug()
config.use_chdb()
config.enable_profiling()
# 你的 DataStore 代码
ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})
Context 管理器 (即将推出)
# 计划功能：临时配置
with config.override(execution_engine='pandas'):
result = ds.process()
# 恢复原始设置
常见配置场景
开发/调试
from chdb.datastore.config import config
config.enable_debug() # 详细日志
config.enable_profiling() # 性能追踪
config.set_cache_enabled(False) # 禁用缓存以获取最新结果
生产环境
from chdb.datastore.config import config
import logging
config.set_log_level(logging.WARNING) # 最小化日志
config.set_execution_engine('auto') # 最优引擎选择
config.set_cache_enabled(True) # 启用缓存
config.set_profiling_enabled(False) # 禁用性能分析开销
最大吞吐量
from chdb.datastore.config import config
config.use_performance_mode() # SQL 优先，无 pandas 开销
config.set_cache_enabled(False) # 禁用流式传输的缓存
性能测试
from chdb.datastore.config import config
config.use_chdb() # 强制使用 ClickHouse 进行基准测试
config.enable_profiling() # 跟踪性能
config.set_cache_enabled(False) # 禁用缓存以确保计时准确
Pandas 兼容性测试
from chdb.datastore.config import config
config.use_pandas() # 强制使用 pandas 引擎
config.enable_debug() # 查看使用了哪些操作