ClickHouse 本地查询工具 clickhouse-local 参数说明

1. 介绍

clickhouse-local 是 ClickHouse 提供的本地查询工具。它可以在不连接 ClickHouse Server 的情况下，直接对本地文件或标准输入执行 SQL。

这个工具比较适合下面几类场景：

• 临时分析 CSV、TSV、JSONEachRow 等文件
• 在服务器上快速统计日志或命令输出
• 验证 ClickHouse SQL 写法
• 不想先建表、导入数据，只想临时查一下文件内容

本文整理的是 2021-09-15 左右 clickhouse-local --help 中常用的参数，内容以当时的命令能力为准。

2. 查看帮助信息

clickhouse-local --help

帮助信息开头说明了它的基本用法，可以简化理解为：

clickhouse-local [初始表定义] --query <查询语句>

也就是说，clickhouse-local 可以通过一条命令对数据文件执行 SQL。使用时需要先定义数据来源、数据格式和表结构，然后就可以像查询普通表一样执行 SQL。

3. 与 clickhouse-client 的区别

工具	是否需要服务端	主要用途
clickhouse-client	需要连接 ClickHouse Server	查询服务端表、导入导出、运维排查
clickhouse-local	不需要连接 ClickHouse Server	直接查询本地文件或标准输入

可以简单理解为：

• 数据已经在 ClickHouse 表里，用 clickhouse-client。
• 数据只是一个本地文件，想临时分析，用 clickhouse-local。

4. 输入数据相关参数

clickhouse-local 首先要知道数据从哪里来、是什么格式。

参数	中文说明
-f / --file	指定输入文件，不指定时可以从标准输入读取
--input-format	指定输入数据格式
-N / --table	指定临时表名
-S / --structure	指定临时表结构
--no-system-tables	不加载 system 表，启动更快

假设有一个 TSV 文件：

1	Tom	20
2	Jerry	18
3	Lucy	22

可以这样查询：

clickhouse-local \
  --table user_tmp \
  --structure 'id UInt32, name String, age UInt8' \
  --input-format TabSeparated \
  --file /tmp/user.tsv \
  --query 'SELECT name, age FROM user_tmp WHERE age >= 20 FORMAT PrettyCompact'

这里的参数含义如下：

参数	中文说明
--table user_tmp	将输入数据定义成一张临时表，表名为 user_tmp
--structure	指定字段名和字段类型
--input-format	指定文件格式，这里是 TabSeparated
--file	指定读取的文件路径
--query	对临时表执行 SQL

5. 查询 SQL 相关参数

参数	中文说明
-q / --query	指定要执行的 SQL
--queries-file	从文件中读取 SQL
-d / --database	指定数据库名
--ignore-error	执行多条 SQL 时遇到错误不立即停止
--echo	执行前打印 SQL
--verbose	打印 SQL 和更多调试信息

如果 SQL 比较长，可以写入文件：

clickhouse-local \
  --table user_tmp \
  --structure 'id UInt32, name String, age UInt8' \
  --input-format TabSeparated \
  --file /tmp/user.tsv \
  --queries-file /tmp/query.sql

query.sql 示例：

SELECT
    name,
    age
FROM user_tmp
WHERE age >= 20
FORMAT PrettyCompact;

6. 输出格式相关参数

参数	中文说明
--output-format	指定默认输出格式
--format	指定默认输出格式，兼容 clickhouse-client 的写法
--stacktrace	异常时打印堆栈信息
-V / --version	打印版本信息

输出 JSONEachRow：

clickhouse-local \
  --structure 'id UInt32, name String' \
  --input-format TabSeparated \
  --query 'SELECT * FROM table FORMAT JSONEachRow'

如果只是人工查看结果，可以使用 PrettyCompact：

clickhouse-local \
  --structure 'id UInt32, name String' \
  --input-format TabSeparated \
  --query 'SELECT * FROM table FORMAT PrettyCompact'

7. 使用标准输入处理数据

clickhouse-local 很适合和 Linux 管道一起使用。草稿中记录了一个统计 Unix 用户内存占用的例子：

ps aux \
  | tail -n +2 \
  | awk '{ printf("%s\t%s\n", $1, $4) }' \
  | clickhouse-local \
      -S "user String, mem Float64" \
      -q "SELECT user, round(sum(mem), 2) AS mem_total FROM table GROUP BY user ORDER BY mem_total DESC FORMAT PrettyCompact"

这条命令可以拆成三步理解：

1. ps aux 输出当前进程信息。
2. awk 提取用户和内存占用比例，并转换成 TSV。
3. clickhouse-local 从标准输入读取 TSV，然后按照 user String, mem Float64 的结构执行聚合查询。

这里没有显式指定表名时，可以直接查询默认表 table。

8. 通过 SQL 创建 File 表

帮助信息中也提到，可以直接在 SQL 中创建 File 引擎表。这个方式更接近普通 ClickHouse SQL。

CREATE TABLE user_tmp
(
    id UInt32,
    name String,
    age UInt8
)
ENGINE = File(TabSeparated, '/tmp/user.tsv');

SELECT
    name,
    age
FROM user_tmp
WHERE age >= 20
FORMAT PrettyCompact;

如果查询逻辑比较复杂，这种方式比在命令行中拼很多参数更清楚。

9. 常用参数小结

分类	常用参数	说明
输入文件	--file	指定本地文件
输入格式	--input-format	指定文件格式，例如 TabSeparated、CSV、JSONEachRow
表结构	--structure	指定字段名和字段类型
表名	--table	指定临时表名，不指定时可以使用默认表 table
查询	--query、--queries-file	执行 SQL 或 SQL 文件
输出	--output-format、FORMAT	控制结果输出格式
排查	--stacktrace、--verbose	查看异常堆栈和调试信息

从本质上看，clickhouse-local 解决的是“临时数据也想用 SQL 分析”的问题。它不适合替代 ClickHouse Server，但在排查日志、处理一次性文件、验证 SQL 时非常方便。