clickhouse-local

单机运行 ClickHouse 查询引擎

补充说明

clickhouse-local 不启动服务端，直接用一个进程执行 ClickHouse 查询，适合处理本地 CSV/JSON/Parquet 文件、做一次性 ETL 或验证 SQL。它复用 ClickHouse 的引擎和函数，但不提供网络服务。

常用示例

clickhouse-local -q 'SELECT 1'
clickhouse-local -q 'SELECT count() FROM file("events.csv", CSV, "id UInt64, ts DateTime")'
clickhouse-local --input-format CSV --output-format JSONEachRow -q 'SELECT * FROM table'
cat events.json | clickhouse-local --input-format JSONEachRow -q 'SELECT count() FROM table'
clickhouse-local -q 'SELECT * FROM file("data.parquet", Parquet) LIMIT 5'
clickhouse-local --path /tmp/ch-local -q 'CREATE TABLE t (id UInt64) ENGINE=Memory'
clickhouse-local --config-file local.xml -q 'SELECT 1'

易错点与排错

• 它是单进程工具，不监听端口；需要并发访问或长期服务时用 clickhouse-server。
• 默认表引擎和系统表能力有限；依赖副本、分布式表或用户体系的查询不能直接跑。
• --path 会让本地实例持久化元数据；不指定时多数对象只在本次进程内有效。
• file() 的路径和列定义要匹配；CSV 表头、分隔符和引号规则不同会解析错位。
• 输入格式要和数据实际格式一致；JSONEachRow 与 JSON 不是一回事。
• 大文件处理受内存限制；必要时用 max_memory_usage 或分块。
• 访问 s3()、url() 等表函数需要网络和凭据；权限不足时报错不一定直观。
• 本地时区和日期解析依赖运行环境；跨时区数据显式指定类型和时区。

相关命令

• clickhouse-client — 连接服务端
• clickhouse-server — 服务端