ClickHouse 命令行工具 clickhouse-client 参数说明

clickhouse

发布日期: 2021-09-01

文章字数: 1.3k

阅读时长: 5 分

阅读次数:

1. 介绍

clickhouse-client 是 ClickHouse 最常用的命令行客户端工具，主要用于连接 ClickHouse Server，然后执行 SQL、查看结果、导入导出数据、排查查询问题。

通过 clickhouse-client --help 可以看到非常多参数，其中很多参数其实是 ClickHouse 的查询 settings，不需要全部记住。日常使用时重点关注下面几类即可：

连接参数
执行 SQL 参数
输出格式参数
批量执行参数
导入导出参数
排查问题参数

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

2. 查看帮助信息

clickhouse-client --help

帮助信息中主要有两类内容：

分类	说明
`Main options`	客户端常用参数，例如连接、执行 SQL、输出格式等
`External tables options`	外部表相关参数，可以临时把本地文件作为一张表参与查询

外部表常见参数包括 --file、--name、--format、--structure、--types。这些参数本身仍然是英文名称，但理解起来可以按照“文件路径、临时表名、文件格式、表结构、字段类型”这几个方向记。

3. 连接相关参数

连接 ClickHouse Server 时最常用的是下面几个参数。

参数	中文说明
`-h` / `--host`	指定 ClickHouse Server 地址，默认是 `localhost`
`--port`	指定 TCP 端口，默认是 `9000`
`-u` / `--user`	指定登录用户，默认是 `default`
`--password`	指定密码
`--ask-password`	交互式输入密码
`-d` / `--database`	指定默认数据库
`-s` / `--secure`	使用 TLS 安全连接

连接本机 ClickHouse：

clickhouse-client -h localhost --port 9000 -u default

连接指定数据库：

clickhouse-client -h node1 -u default -d test

如果用户设置了密码，不建议直接把密码写到命令里，因为命令可能会被 shell history 记录。可以使用交互式输入：

clickhouse-client -h node1 -u default --ask-password

4. 执行 SQL 相关参数

参数	中文说明
`-q` / `--query`	执行一条 SQL
`-n` / `--multiquery`	允许一次执行多条 SQL
`--queries-file`	从文件中读取 SQL 并执行
`--ignore-error`	多语句执行时遇到错误不立即停止
`--echo`	执行前先打印 SQL

执行一条 SQL：

clickhouse-client -q "SELECT version()"

执行多条 SQL：

clickhouse-client -n -q "SELECT 1; SELECT 2;"

执行 SQL 文件：

clickhouse-client --queries-file /tmp/init.sql

在脚本中执行 SQL 时，可以加上 --echo，这样日志中能看到实际执行了什么 SQL。

clickhouse-client --echo --queries-file /tmp/check.sql

5. 输出格式相关参数

ClickHouse 支持很多输出格式，命令行中常用的是 --format 或 -f。

参数	中文说明
`-f` / `--format`	指定默认输出格式
`-E` / `--vertical`	使用纵向格式输出，等价于 `FORMAT Vertical`
`-t` / `--time`	在非交互模式下打印查询耗时

使用 PrettyCompact 格式查看结果：

clickhouse-client -q "SELECT number FROM system.numbers LIMIT 3" --format PrettyCompact

字段比较多时，可以使用纵向输出：

clickhouse-client -q "SELECT * FROM system.settings LIMIT 1" --vertical

常见格式可以这样选择：

输出格式	使用场景
`TabSeparated`	默认格式，适合脚本继续处理
`CSV`	导出 CSV 文件
`JSONEachRow`	和程序、日志系统对接
`PrettyCompact`	人工查看比较清晰
`Vertical`	单行字段很多时查看

6. 导入导出相关参数

ClickHouse 可以通过标准输入导入数据，也可以把查询结果重定向到文件。

导出 CSV：

clickhouse-client \
  -q "SELECT * FROM system.numbers LIMIT 5 FORMAT CSV" \
  > /tmp/numbers.csv

从文件导入数据时，通常配合 INSERT INTO ... FORMAT ... 使用：

clickhouse-client \
  -q "INSERT INTO test.user FORMAT CSV" \
  < /tmp/user.csv

如果只是临时拿一个文件参与查询，可以使用外部表参数。

参数	中文说明
`--file`	指定数据文件，`-` 表示从标准输入读取
`--name`	指定外部表名，默认是 `_data`
`--format`	指定数据格式，默认是 `TabSeparated`
`--structure`	指定表结构
`--types`	指定字段类型

例如有一个 TSV 文件：

1	Tom
2	Jerry

可以将它作为外部表查询：

clickhouse-client \
  --file /tmp/user.tsv \
  --name user_tmp \
  --format TabSeparated \
  --structure 'id UInt32, name String' \
  -q 'SELECT * FROM user_tmp'

7. 排查问题相关参数

排查查询问题时，下面几个参数比较常用。

参数	中文说明
`--stacktrace`	出现异常时打印堆栈信息
`--progress`	非交互模式下也显示查询进度
`--query_id`	指定查询 ID，方便在系统表中追踪
`--log-level`	指定客户端日志级别
`--server_logs_file`	将服务端日志写入指定文件
`--time`	输出查询耗时

指定 query_id 执行查询：

clickhouse-client \
  --query_id='test_query_001' \
  -q 'SELECT count() FROM system.numbers LIMIT 1000000'

然后可以在 system.query_log 中查找这次查询：

SELECT
    query_id,
    query,
    type,
    event_time
FROM system.query_log
WHERE query_id = 'test_query_001'
ORDER BY event_time DESC;

8. 小结

clickhouse-client --help 中的参数很多，但日常使用不需要全部记住。一般按照下面的思路掌握即可：

场景	常用参数
连接服务端	`--host`、`--port`、`--user`、`--ask-password`、`--database`
执行 SQL	`--query`、`--multiquery`、`--queries-file`
查看结果	`--format`、`--vertical`
导入导出	`INSERT ... FORMAT`、`--file`、`--structure`
排查问题	`--query_id`、`--stacktrace`、`--progress`、`--time`