附录 B：ClickHouse 常用命令速查表

开机即用的 ClickHouse 工具书。每张表按「语法 → 示例」成组，Ctrl+F 搜关键词即可。基于 ClickHouse 24.x。低版本差异会注明。

1. clickhouse-client 命令行参数

参数	作用
`-h 127.0.0.1 --port 9000`	TCP 连接地址（HTTP 用 `--port 8123 --secure`）
`-u default --password xxx`	用户名/密码（生产用环境变量 `CLICKHOUSE_PASSWORD`）
`-d learn_ck`	默认数据库
`-q 'SELECT 1'` / `--query`	单行执行
`-n` / `--multiquery`	允许多条 SQL
`--multiline`	多行输入（分号结束）
`--format TSV / JSONEachRow / Parquet / PrettyCompact`	输出格式
`--time`	打印耗时
`--progress`	打印进度条
`--max_memory_usage=8G`	单查询内存上限
`--stacktrace`	错误打栈
`--echo`	回显 SQL
`--compression 1`	开启网络层压缩
`--input_format_allow_errors_num=10`	导入允许错误行数

常用组合：

bash

clickhouse-client -h 127.0.0.1 --port 9000 -d learn_ck --multiline --time

# 流式 INSERT CSV
clickhouse-client -q "INSERT INTO events FORMAT CSV" < events.csv

# 跑脚本
clickhouse-client --multiquery < init.sql

# 直出 Parquet
clickhouse-client -q "SELECT * FROM events LIMIT 1e6" --format Parquet > dump.parquet

2. DDL 速查

2.1 库 / 表 / 视图

sql

CREATE DATABASE IF NOT EXISTS learn_ck;
DROP DATABASE learn_ck SYNC;                              -- SYNC = 真删除
RENAME DATABASE old_db TO new_db;

CREATE TABLE t (id UInt64, v String) ENGINE = MergeTree ORDER BY id;
CREATE TABLE t2 AS t ENGINE = MergeTree ORDER BY id;       -- 复制结构
CREATE TABLE t3 ENGINE = MergeTree ORDER BY id AS SELECT * FROM t;

DROP TABLE t;  DROP TABLE t NO DELAY;                      -- 立刻
TRUNCATE TABLE t;                                          -- 保留结构清空
RENAME TABLE t TO tt;

CREATE VIEW v_today AS SELECT ...;                         -- 只是 SQL 别名
CREATE MATERIALIZED VIEW mv TO target AS SELECT ...;       -- INSERT 触发器
CREATE LIVE VIEW lv AS ...;                                -- 实时推送（实验性）

2.2 列操作

sql

ALTER TABLE t ADD COLUMN  age UInt8 DEFAULT 0 AFTER id;
ALTER TABLE t DROP COLUMN extra;
ALTER TABLE t MODIFY COLUMN v LowCardinality(String);
ALTER TABLE t RENAME COLUMN v TO val;
ALTER TABLE t COMMENT COLUMN val '标题';
ALTER TABLE t MODIFY COLUMN ip CODEC(ZSTD(3));
ALTER TABLE t MODIFY TTL event_time + INTERVAL 30 DAY DELETE;

2.3 索引 / Projection

sql

ALTER TABLE t ADD INDEX idx_p product_id TYPE minmax    GRANULARITY 4;
ALTER TABLE t ADD INDEX idx_u user_id    TYPE bloom_filter(0.01) GRANULARITY 4;
ALTER TABLE t ADD INDEX idx_n name       TYPE ngrambf_v1(3, 256, 2, 0) GRANULARITY 4;
ALTER TABLE t DROP INDEX idx_p;
ALTER TABLE t MATERIALIZE INDEX idx_p;
ALTER TABLE t CLEAR INDEX idx_p IN PARTITION '2026';

ALTER TABLE t ADD PROJECTION pj (SELECT * ORDER BY user_id);
ALTER TABLE t MATERIALIZE PROJECTION pj;
ALTER TABLE t DROP PROJECTION pj;

2.4 分区操作

sql

ALTER TABLE t DROP   PARTITION '20260417';
ALTER TABLE t DETACH PARTITION '20260417';       -- 移到 detached/ 目录
ALTER TABLE t ATTACH PARTITION '20260417';
ALTER TABLE t REPLACE PARTITION '20260417' FROM t_src;
ALTER TABLE t MOVE PARTITION '20260417' TO DISK 'cold';
ALTER TABLE t FREEZE PARTITION '20260417';        -- 硬链到 shadow/，用于备份

2.5 Mutation

sql

ALTER TABLE t UPDATE price = price * 0.9 WHERE product_id = 1;
ALTER TABLE t DELETE WHERE event_date < '2024-01-01';
DELETE FROM t WHERE event_date = '2024-01-01';    -- lightweight DELETE

3. DML 速查

sql

-- INSERT 五花八门
INSERT INTO t VALUES (1, 'a'), (2, 'b');
INSERT INTO t (id, v) SELECT id, name FROM src;
INSERT INTO t FORMAT JSONEachRow {"id":1,"v":"a"}
INSERT INTO t FORMAT CSV 1,a

-- async_insert：高频小批场景
INSERT INTO t SETTINGS async_insert=1, wait_for_async_insert=0 VALUES (1,'a');

-- SELECT 常见
SELECT * FROM t ORDER BY id DESC LIMIT 10 OFFSET 20;
SELECT * FROM t SAMPLE 0.01;                      -- 抽样 1%
SELECT * FROM t WHERE ... SETTINGS max_threads = 16;
SELECT * FROM t FINAL;                            -- ReplacingMergeTree 取最新
SELECT * FROM t PREWHERE user_id = 42 WHERE ...;  -- 先过滤，后读其他列

-- WITH FILL / WITH TIES
SELECT d, count()
FROM t GROUP BY d
ORDER BY d WITH FILL FROM '2026-04-01' TO '2026-04-30' STEP 1;

-- EXPLAIN 三兄弟
EXPLAIN SELECT ...;            -- AST
EXPLAIN PLAN SELECT ...;       -- 逻辑计划
EXPLAIN PIPELINE SELECT ...;   -- 物理流水线
EXPLAIN ESTIMATE SELECT ...;   -- 扫描行估算
EXPLAIN SYNTAX SELECT ...;     -- 规范化 SQL

4. DCL / 权限速查

sql

CREATE USER alice IDENTIFIED WITH sha256_password BY 'pass'
    HOST IP '10.0.0.0/8' SETTINGS PROFILE 'readonly';

CREATE ROLE analyst;
GRANT SELECT ON learn_ck.* TO analyst;
GRANT analyst TO alice;
SET ROLE analyst;

-- 列 / 行级
GRANT SELECT(user_id, price) ON learn_ck.events_raw TO alice;
CREATE ROW POLICY po_country ON learn_ck.events_raw
    USING country = 'CN' TO analyst;

-- 配额
CREATE QUOTA q1 FOR INTERVAL 1 HOUR MAX QUERIES 100, READ ROWS 1e8 TO alice;

SHOW GRANTS FOR alice;
SHOW USERS;  SHOW ROLES;  SHOW PROFILES;

5. SYSTEM 命令族

命令	作用
`SYSTEM RELOAD CONFIG`	热加载 config.xml / users.xml
`SYSTEM RELOAD DICTIONARY d`	刷新字典
`SYSTEM FLUSH LOGS`	把 `query_log` 等缓冲落盘
`SYSTEM STOP / START MERGES [table]`	暂停 / 恢复后台合并
`SYSTEM STOP / START TTL MERGES`	TTL 合并开关
`SYSTEM STOP / START REPLICATED SENDS [table]`	副本同步开关
`SYSTEM SYNC REPLICA t`	同步等待副本追平
`SYSTEM RESTART REPLICA t`	重新挂载副本
`SYSTEM DROP MARK CACHE`	清 Mark 缓存
`SYSTEM DROP UNCOMPRESSED CACHE`	清未压缩缓存
`SYSTEM DROP QUERY CACHE`	清查询缓存
`KILL QUERY WHERE query_id='xxx'`	杀查询
`KILL MUTATION WHERE mutation_id='...'`	杀 Mutation
`OPTIMIZE TABLE t FINAL`	强制合并（慎用）
`CHECK TABLE t`	校验数据完整性

6. 聚合函数速查

6.1 计数 / 求和 / 极值

函数	说明
`count()` / `count(col)` / `countIf(cond)`	计数
`sum / avg / min / max`	常规
`sumWithOverflow`	显式溢出
`any(col)` / `anyLast(col)` / `anyHeavy`	任取 / 最后一条 / 高频值
`argMax(v, k)` / `argMin(v, k)`	按 k 最大/最小时的 v
`median(col)`	中位数（= `quantile(0.5)`）

6.2 去重 / 基数

函数	精度	内存	场景
`uniqExact(x)`	精确	O(n)	小数据量 / 必须精确
`uniq(x)`	~0.5% 误差（HLL）	O(1)	默认推荐
`uniqHLL12(x)`	~0.8%	更省	节省内存
`uniqCombined(12)(x)`	~0.8%	平衡	亿级去重
`uniqTheta(x)`	~0.4%	可交集	Theta sketch

6.3 分位数

函数	说明
`quantile(0.95)(x)`	近似（reservoir sampling）
`quantileExact(0.95)(x)`	精确（但内存大）
`quantileTDigest(0.95)(x)`	推荐：快 + 小内存
`quantileTiming(x)`	专为延迟毫秒优化
`quantilesTDigest(0.5,0.9,0.99)(x)`	批量多分位

6.4 Top-K / 路径 / 漏斗

函数	说明
`topK(10)(x)`	Top-10 高频值
`topKWeighted(10)(x, w)`	带权 Top-K
`groupArray(x)` / `groupArray(100)(x)`	聚合成数组
`groupUniqArray(x)`	去重数组
`sequenceMatch('(?1)(?2)')(ts, cond1, cond2)`	事件序列匹配
`sequenceCount('(?1)(?2)')(ts, ...)`	匹配次数
`windowFunnel(3600)(ts, c1, c2, c3)`	漏斗，返回最深第几步
`retention(c1, c2, c3)`	多日留存数组

6.5 状态后缀（灵魂）

后缀	含义
`sumState / uniqState / quantileState / ...`	返回「聚合中间状态」（二进制），用于物化视图存储
`sumMerge / uniqMerge / quantileMerge / ...`	把多个 State 合并成最终结果
`sumMergeState / ...`	合并 State 但仍返回 State（用于多级 MV）
`-If` 后缀	条件聚合：`sumIf(x, cond)`
`-Array` 后缀	数组元素聚合：`sumArray([1,2,3])`
`-OrNull / -OrDefault` 后缀	无数据时返回 NULL / 默认值
`-ForEach` 后缀	对数组每个位置分别聚合

7. 常用字符串 / 日期 / 数组函数

7.1 字符串

函数	示例
`length / lengthUTF8`	字节 / 字符长度
`lower / upper / reverse`	-
`substring(s, pos, len)`	-
`position / positionCaseInsensitive`	查子串
`replaceOne / replaceAll / replaceRegexpAll`	-
`extract / extractAll`	正则抽取
`splitByChar / splitByString / arrayStringConcat`	切 / 拼
`startsWith / endsWith / like / match`	-
`base64Encode / base64Decode / hex / unhex`	-
`JSONExtractString(s, 'a.b')`	JSON 取值

7.2 日期

函数	示例
`now() / now64()`	-
`toDate / toDateTime / toDateTime64`	转类型
`toYYYYMM / toYYYYMMDD / toHour / toDayOfWeek`	常用分区键
`toStartOfHour / toStartOfDay / toStartOfMonth`	时间桶
`dateDiff('day', a, b)`	差值
`addDays / subtractDays / dateAdd('hour', 1, t)`	加减
`formatDateTime(t, '%Y-%m-%d')`	格式化
`toTimeZone(t, 'Asia/Shanghai')`	时区转换

7.3 数组 / Map / Tuple

函数	示例
`arrayJoin(a)`	每个元素展开为一行（= LATERAL VIEW EXPLODE）
`length(a) / empty(a) / has(a, x)`	-
`arrayMap(x -> x*2, a)`	映射
`arrayFilter(x -> x>0, a)`	过滤
`arraySum / arrayAvg / arrayMin / arrayMax`	聚合
`arrayZip(a, b)`	并联
`arrayFlatten(aa)`	拍平
`arrayEnumerate(a)`	索引数组
`arrayExists / arrayAll`	存在 / 全为
`mapKeys(m) / mapValues(m) / mapContains(m, k)`	Map 操作

8. `system.*` 视图速查

8.1 元数据

视图	一句话用途
`system.databases`	库
`system.tables`	表
`system.columns`	列（类型、压缩、默认值）
`system.functions`	所有内置/UDF 函数
`system.formats`	支持的 FORMAT
`system.settings`	所有 Settings + 当前值
`system.users` / `system.roles` / `system.grants`	用户 / 角色 / 权限

8.2 运行时 / 性能

视图	用途
`system.processes`	正在跑的 query
`system.query_log`	每次查询的耗时、读行数、内存
`system.query_thread_log`	线程级别细节
`system.trace_log`	采样栈（火焰图原料）
`system.metric_log`	每秒 metric 快照
`system.asynchronous_metric_log`	后台 metric
`system.text_log`	服务端日志（需要开启）
`system.crash_log`	崩溃栈
`system.errors`	历史错误码累计

8.3 MergeTree / 副本

视图	用途
`system.parts`	每个 Part 的行数、字节、状态
`system.part_log`	Part 生命周期事件（NewPart / MergeParts / MovePart）
`system.merges`	当前正在合并的任务
`system.mutations`	Mutation 进度、异常
`system.replicas`	副本状态（lag、队列大小）
`system.replication_queue`	副本同步队列详情
`system.replicated_fetches`	正在拉 Part
`system.distribution_queue`	Distributed 表异步写入队列
`system.zookeeper`	从 Keeper 读任意路径
`system.dictionaries`	字典状态 / 命中率
`system.kafka_consumers`	Kafka 消费者状态

8.4 存储 / 磁盘

视图	用途
`system.disks`	所有 disk
`system.storage_policies`	策略和 volume
`system.data_skipping_indices`	Skip Index 命中情况
`system.projections`	Projection 状态

常用排查 SQL：

sql

-- Top 20 慢查询
SELECT query_duration_ms, read_rows, memory_usage, left(query, 200)
FROM system.query_log
WHERE event_date = today() AND type = 'QueryFinish'
ORDER BY query_duration_ms DESC LIMIT 20;

-- 活跃 Part 最多的表
SELECT database, table, count() AS parts, sum(rows) AS rows
FROM system.parts WHERE active
GROUP BY database, table ORDER BY parts DESC LIMIT 10;

-- Mutation 卡着
SELECT database, table, mutation_id, command,
       create_time, is_done, latest_fail_reason
FROM system.mutations WHERE is_done = 0 ORDER BY create_time;

-- 副本滞后
SELECT database, table, queue_size, absolute_delay,
       log_pointer, total_replicas, active_replicas
FROM system.replicas WHERE queue_size > 0 OR absolute_delay > 30;

-- 字典命中率
SELECT name, element_count, hit_rate, bytes_allocated, last_exception
FROM system.dictionaries;

9. Docker 启动 / 备份 / 监控片段

9.1 Docker 快速起单机

yaml

# docker-compose.yml
services:
  ck:
    image: clickhouse/clickhouse-server:24.8
    container_name: learn_ck_server
    ports:
      - "8123:8123"     # HTTP
      - "9000:9000"     # TCP
      - "9009:9009"     # 副本互传
    volumes:
      - ./data:/var/lib/clickhouse
      - ./logs:/var/log/clickhouse-server
      - ./config.d:/etc/clickhouse-server/config.d   # 自定义配置
      - ./users.d:/etc/clickhouse-server/users.d
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    environment:
      CLICKHOUSE_DB: learn_ck
      CLICKHOUSE_USER: default
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1

9.2 备份

bash

# ① 官方 BACKUP / RESTORE（24.x 推荐）
clickhouse-client -q "BACKUP DATABASE learn_ck TO Disk('backups', 'full_$(date +%F)')"
clickhouse-client -q "RESTORE DATABASE learn_ck FROM Disk('backups','full_2026-04-17')"

# ② clickhouse-backup（Altinity 出品，支持 S3）
clickhouse-backup create    full_$(date +%F)
clickhouse-backup upload    full_$(date +%F)           # 上 S3/OSS
clickhouse-backup list      remote
clickhouse-backup download  full_2026-04-17
clickhouse-backup restore   full_2026-04-17

# ③ 物理快照（分区级）
clickhouse-client -q "ALTER TABLE events_raw FREEZE PARTITION '20260417'"
# 产物在 /var/lib/clickhouse/shadow/<N>/...  用 rsync / tar 带走

9.3 Prometheus 监控

xml

<!-- /etc/clickhouse-server/config.d/prometheus.xml -->
<clickhouse>
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
    </prometheus>
</clickhouse>

Grafana 用官方 Dashboard ID 14192 / 13500 直接导入。

10. 关键配置参数 Top 30

10.1 服务器 / 内存

参数	推荐	作用
`max_server_memory_usage_to_ram_ratio`	0.9	实例内存占用上限
`max_memory_usage`	10~20G	单查询内存上限
`max_memory_usage_for_user`	0.5 × 总内存	单用户累计
`max_concurrent_queries`	100	并发查询上限
`max_concurrent_insert_queries`	50	并发 INSERT 上限
`max_threads`	CPU 核数	单 query 并行度
`max_insert_threads`	4	INSERT 并行度
`max_execution_time`	60	查询超时

10.2 写入

参数	推荐	作用
`max_insert_block_size`	1048576	批量块大小
`async_insert`	1（按场景）	开启 async
`async_insert_max_data_size`	1MB	async 触发刷盘大小
`async_insert_busy_timeout_ms`	200	async 刷盘间隔
`wait_for_async_insert`	1（强一致）	async 同步等待
`insert_deduplicate`	1	Replicated 去重
`parts_to_throw_insert`	3000	活跃 Part 爆表阈值
`parts_to_delay_insert`	150	开始 backpressure

10.3 MergeTree / 合并

参数	推荐	作用
`index_granularity`	8192	Granule 粒度
`merge_max_block_size`	8192	合并块大小
`max_bytes_to_merge_at_max_space_in_pool`	150G	单次合并上限
`old_parts_lifetime`	480s	合并后旧 Part 保留时长
`replicated_deduplication_window`	100	副本去重窗口

10.4 查询 / 优化器

参数	推荐	作用
`optimize_move_to_prewhere`	1	自动下推过滤
`optimize_read_in_order`	1	命中 ORDER BY 走顺序读
`use_query_cache`	0（按场景）	查询缓存
`join_algorithm`	`hash` / `grace_hash` / `partial_merge`	JOIN 算法
`distributed_product_mode`	`deny`→`global`	Distributed JOIN 控制
`prefer_localhost_replica`	1	本地副本优先

10.5 日志 / 安全

参数	推荐	作用
`log_queries`	1	开启 query_log
`log_query_threads`	1	开启线程级日志
`query_log.ttl`	30 DAY	清理策略
`readonly`	0/1/2	用户只读级别
`allow_ddl`	0/1	是否允许 DDL

修改方式：

sql

-- 会话级
SET max_threads = 16;

-- 用户 / Profile 级（users.xml 或 ALTER SETTINGS PROFILE）
ALTER SETTINGS PROFILE bi_ro SETTINGS max_memory_usage = 20000000000;

-- 服务级（config.xml / config.d/*.xml，热加载 SYSTEM RELOAD CONFIG）

📌 三件套搭配：附录 A（对比速查）· 附录 B（本文）· 附录 C（踩坑集）。遇问题顺手 Ctrl+F。

附录 B：ClickHouse 常用命令速查表 ​

目录 ​

1. clickhouse-client 命令行参数 ​

2. DDL 速查 ​

2.1 库 / 表 / 视图 ​

2.2 列操作 ​

2.3 索引 / Projection ​

2.4 分区操作 ​

2.5 Mutation ​

3. DML 速查 ​

4. DCL / 权限速查 ​

5. SYSTEM 命令族 ​

6. 聚合函数速查 ​

6.1 计数 / 求和 / 极值 ​

6.2 去重 / 基数 ​

6.3 分位数 ​

6.4 Top-K / 路径 / 漏斗 ​

6.5 状态后缀（灵魂） ​

7. 常用字符串 / 日期 / 数组函数 ​

7.1 字符串 ​

7.2 日期 ​

7.3 数组 / Map / Tuple ​

8. system.* 视图速查 ​

8.1 元数据 ​

8.2 运行时 / 性能 ​

8.3 MergeTree / 副本 ​

8.4 存储 / 磁盘 ​

9. Docker 启动 / 备份 / 监控片段 ​

9.1 Docker 快速起单机 ​

9.2 备份 ​

9.3 Prometheus 监控 ​

10. 关键配置参数 Top 30 ​

10.1 服务器 / 内存 ​

10.2 写入 ​

10.3 MergeTree / 合并 ​

10.4 查询 / 优化器 ​

10.5 日志 / 安全 ​

附录 B：ClickHouse 常用命令速查表

目录

1. clickhouse-client 命令行参数

2. DDL 速查

2.1 库 / 表 / 视图

2.2 列操作

2.3 索引 / Projection

2.4 分区操作

2.5 Mutation

3. DML 速查

4. DCL / 权限速查

5. SYSTEM 命令族

6. 聚合函数速查

6.1 计数 / 求和 / 极值

6.2 去重 / 基数

6.3 分位数

6.4 Top-K / 路径 / 漏斗

6.5 状态后缀（灵魂）

7. 常用字符串 / 日期 / 数组函数

7.1 字符串

7.2 日期

7.3 数组 / Map / Tuple

8. `system.*` 视图速查

8.1 元数据

8.2 运行时 / 性能

8.3 MergeTree / 副本

8.4 存储 / 磁盘

9. Docker 启动 / 备份 / 监控片段

9.1 Docker 快速起单机

9.2 备份

9.3 Prometheus 监控

10. 关键配置参数 Top 30

10.1 服务器 / 内存

10.2 写入

10.3 MergeTree / 合并

10.4 查询 / 优化器

10.5 日志 / 安全