ClickHouse 向量检索手册

适用版本：近似向量索引 vector_similarity 自 25.8 起可用；当前稳定版本号未核实，以官方为准，核实于 2026-11 许可与形态：当前许可证未核实，以官方为准；列式 OLAP 数据库（MergeTree 引擎族），向量能力为表内 skip index，非独立向量库 一句话定位：在已有 ClickHouse 里用 Array(Float32) 列 + 距离函数做精确检索，25.8 起加 vector_similarity skip index 做近似检索，不新增一套数据库。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

ClickHouse 的向量能力不是独立服务，而是 MergeTree 表内的一个列 + 距离函数 + 一类特殊 skip index。精确检索一直可用（ORDER BY L2Distance(vec, ref) LIMIT k 全表扫描）；近似向量索引 vector_similarity 自 25.8 起可用，属特殊 skip index，当前唯一方法是 HNSW。

核心主题：已有 ClickHouse 时，向量检索是在一张表里加一个数组列和一个 skip index，而不是再部署一套向量数据库。

适合：① 向量本来就伴随大规模分析数据（日志 / 用户行为 / 特征明细），希望检索与聚合在同一条 SQL；② 以批量写入、分析型查询为主；③ 数据量已由 ClickHouse 的分区 / 副本 / 压缩体系承载；④ 25.8+ 且接受 skip index 的近似语义；⑤ 中小规模精确检索即可满足（无需索引）。

不适合：① 高并发低延迟在线点查（列式 OLAP 不是为点查设计）；② 需要强事务 / 频繁单行更新；③ 需要复杂量化族、GPU 或分布式向量分片；④ 版本 <25.8 却要求近似 ANN 索引；⑤ 需要把向量当独立服务弹性扩缩。

1.2 规模、链路位置与「何时该换」

链路位置：离线「明细数据 + Embedding → 写入 MergeTree 表的向量列」；在线「query → Embedding → SELECT ... WHERE <分区/标量条件> ORDER BY 距离函数 LIMIT k → 聚合 / 取回明细 → 展示或下游」。ClickHouse 位于分析 + 召回混合层。

该换专用向量库的信号：在线点查 QPS 高且延迟要求严；需要频繁单行更新向量；过滤后近似召回不稳；需要独立弹性扩缩或内核级混合检索；向量查询要与分析负载隔离。

2. 版本、许可与官方入口

2.1 版本状态表

避坑：本产品的稳定版本号与许可证在官方资料中是明确的「未核实」项。行文、方案、CMDB 里都不要写死具体稳定版号或许可名称，统一写「以官方为准」。

2.2 入口与版本识别

SELECT version();   -- ClickHouse 通用函数（经验性，以所用版本为准），确认是否 ≥25.8

2.3 近两年重要变更与弃用提醒

版本差异：25.8 之前的版本没有该近似索引，只能做精确全表扫描；升级到 25.8+ 后索引不会自动覆盖已有 part。

3. 安装与启动

3.1 说明与前置条件

本类产品通常已有 ClickHouse 集群，「安装」实为「在已有表上启用向量能力」。官方资料未提供官方安装命令、镜像 tag 与端口，部署安装以官方文档为准，勿臆测。前置条件：版本 ≥25.8（近似索引）；表引擎为 MergeTree 族；向量列类型符合约束（见 4.2）。

3.2 方式一：精确检索（无需索引，零配置）

-- 连接：clickhouse-client --host <host> --port <port> --user <user> --database <db>
SELECT L2Distance([1.0, 2.0, 3.0], [3.0, 1.0, 2.0]) AS d;   -- 返回数值即距离函数可用

示例用 3 维，实际常见 768 / 1024 / 1536 维。精确检索走全表扫描，适合小数据量或强过滤后剩余很少的场景。

3.3 方式二：近似检索（建 vector_similarity skip index）

ALTER TABLE items
    ADD INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 3, 'bf16', 32, 128)
    GRANULARITY 100000000;
ALTER TABLE items MATERIALIZE INDEX idx SETTINGS mutations_sync = 2;

语法取自官方 annindexes 文档：方法 hnsw、距离 L2Distance、维度 3、量化 bf16、M 32、ef_construction 128。示例用 3 维，实际常见 768（官方示例为 768）。ADD INDEX 后必须对存量执行 MATERIALIZE INDEX，否则旧 part 没有索引。

3.4 目录、端口与健康检查

健康检查：SELECT L2Distance(...) 能返回数值即距离函数可用；建索引后用一个已知近邻执行 ORDER BY L2Distance(...) LIMIT k 验证结果符合预期。

3.5 生产最小配置建议

认证 / TLS / RBAC / 网络暴露面沿用 ClickHouse 基线（通用运维见根目录手册）；MATERIALIZE INDEX 是 mutation，会消耗 CPU / IO，应在维护窗口执行；向量列会显著增大 part，压缩与磁盘水位需重新评估。

⚠️ 危险：MATERIALIZE INDEX 与 ALTER TABLE ... UPDATE/DELETE 均为 mutation，大表上可能长时间占用资源，务必在维护窗口、有备份的前提下执行。

4. 核心概念与数据模型

4.1 术语对照与数据模型

数据模型：database → MergeTree table（标量列 + 向量数组列 + 分区键 + 排序键）→ vector_similarity skip index。一行 = 一个实体，向量是其中一列；没有 collection / load 概念，也没有独立的向量服务进程。

4.2 字段与向量类型约束（重点）

避坑：把向量列写成 Array(Nullable(Float32)) 或塞进空数组会直接报错 / 无法建索引；这是列式存储约束，不是配置能绕过的。

4.3 距离函数与 ASC / DESC 对应关系（重点，必须写清）

避坑：这是最容易被写反的地方。L2Distance / cosineDistance 求最小用 ORDER BY ... ASC；dotProduct 求最大用 ORDER BY ... DESC。排序方向与距离函数不匹配，索引不会生效甚至结果错误；建索引时声明的距离函数也必须与查询一致。

4.4 索引参数表

INDEX idx vectors TYPE vector_similarity('hnsw', 'L2Distance', 768, 'bf16', 32, 128) GRANULARITY 100000000

4.5 生命周期与一致性（重点）

避坑：ADD INDEX 之后立刻查老数据「感觉没变快」是正常的——存量必须 MATERIALIZE INDEX。加 SETTINGS mutations_sync = 2 是为了等 mutation 真正完成再验收，否则异步未结束就下结论。

一致性：ClickHouse 是 OLAP 语义，无强事务；写入为批量 part，副本 / 分布式表沿用集群模型；索引随 part 与 merge 演进，非事务型。

5. 快速上手：完整 CRUD 示例

示例用 3 维向量便于阅读；实际常见 768 / 1024 / 1536 维。ALTER TABLE ... UPDATE/DELETE 为 ClickHouse 标准 mutation 语法（通用能力，异步执行，以官方文档为准）。

5.1 完整 SQL 脚本（clickhouse-client，可直接复制运行）

-- 连接：clickhouse-client --host <host> --port <port> --user <user> --database <db>
DROP TABLE IF EXISTS items;
CREATE TABLE items
(
    id       UInt64,
    content  String,
    category String,
    vec      Array(Float32)
)
ENGINE = MergeTree
ORDER BY id;

-- 1) 插入
INSERT INTO items VALUES
    (1, '向量检索入门',     'tech', [1.0, 2.0, 3.0]),
    (2, '列式数据库运维',   'tech', [4.0, 5.0, 6.0]),
    (3, '咖啡拉花教程',     'life', [7.0, 1.0, 2.0]),
    (4, 'skip index 原理',  'tech', [2.0, 3.0, 3.0]);

-- 2) 精确相似度检索（全表扫描，L2 越小越相似，只能 ASC）
SELECT id, content, L2Distance(vec, [3.0, 1.0, 2.0]) AS distance
FROM items
ORDER BY L2Distance(vec, [3.0, 1.0, 2.0]) ASC
LIMIT 3;

-- 3) 带标量过滤的检索
SELECT id, content, category, L2Distance(vec, [3.0, 1.0, 2.0]) AS distance
FROM items
WHERE category = 'tech'
ORDER BY L2Distance(vec, [3.0, 1.0, 2.0]) ASC
LIMIT 3;

-- 4) 加近似 skip index（25.8+）——只对新写入生效
ALTER TABLE items
    ADD INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 3, 'bf16', 32, 128)
    GRANULARITY 100000000;

-- 5) 存量必须物化，否则旧 part 仍无索引
ALTER TABLE items MATERIALIZE INDEX idx SETTINGS mutations_sync = 2;

-- 6) 近似检索（距离函数、排序方向须与索引声明一致）
SELECT id, content, L2Distance(vec, [3.0, 1.0, 2.0]) AS distance
FROM items
ORDER BY L2Distance(vec, [3.0, 1.0, 2.0]) ASC
LIMIT 3;

-- 7) 更新（ClickHouse mutation，通用语法）
ALTER TABLE items UPDATE vec = [1.0, 2.0, 4.0] WHERE id = 1;

-- 8) 删除（ClickHouse mutation，通用语法）
ALTER TABLE items DELETE WHERE id = 3;

-- 9) 清理
DROP TABLE items;

避坑：旧教程 / 直觉会认为「ADD INDEX 之后全表就都有索引了」。在 ClickHouse 的 vector_similarity skip index 上恰恰相反——ADD INDEX 只对新写入生效，存量必须 MATERIALIZE INDEX（第 5 步）。漏掉这一步是本篇第一大坑。

5.2 输出怎么读

若第 6 步与第 2 步结果差异明显，先确认 MATERIALIZE INDEX 是否完成、距离函数与 ASC 是否与索引声明一致。

5.3 clickhouse-client 等价示例

CH="clickhouse-client --host <host> --port <port> --user <user>"
$CH --query "SELECT id, L2Distance(vec, [3.0,1.0,2.0]) AS distance \
             FROM items ORDER BY L2Distance(vec, [3.0,1.0,2.0]) ASC LIMIT 3"

CLI 连接方式属通用用法，参数以所用版本文档为准；Python / REST 等价示例不再另给，SQL 已覆盖全链路。

6. 索引与检索进阶

6.1 参数调优表

6.2 recall 与延迟取舍

vector_similarity 是 skip index：它按 granule 跳过「不可能有近邻」的数据块，而不是构造一个全局 ANN 图。量化档位、M、ef_construction 与 GRANULARITY 共同影响召回与延迟。方法（经验）：先以精确扫描（ORDER BY 距离函数 LIMIT k，无索引）跑 ground truth，再加索引对同一批 query 算 recall@k，逐步调整参数。没有官方承诺的召回数字，必须实测。

6.3 标量过滤、混合检索与多向量

• 过滤行为：WHERE 与 ORDER BY 距离函数 组合时，ClickHouse 会结合分区 / 主键 / skip index 裁剪扫描范围；过滤与近邻的 pre/post 语义官方资料未给出官方结论，以 EXPLAIN 与实测为准，不要把别的产品的过滤结论套过来。
• 混合检索：可把全文 / 标量打分与距离在 SQL 里组合（如两路 CTE 后应用层融合）；官方资料未提供 ClickHouse 内置 RRF / 混合检索的逐字函数名，勿臆测，按官方文档或应用层实现。
• 多向量 / 稀疏 / 重排：一表多个 Array(Float32) 列可承载多向量；稀疏向量官方资料未提供逐字支持；两阶段「近似取候选 + 精确距离重排」为经验做法。

6.4 距离方向与量化压缩

避坑：L2Distance / cosineDistance 越小越相似、索引只能 ASC；dotProduct 越大越相似、只能 DESC。方向写反会让索引不生效或结果错误，改距离函数还要同步改索引声明并重新物化。

量化档位 f64 / f32 / f16 / bf16（默认）/ i8 / b1 提供精度与内存的取舍；列本身可用 Array(BFloat16) 从存储层压缩。

6.5 容量估算（经验公式，非官方承诺）

单行向量存储 ≈ 4 × dim 字节（Array(Float32)）；dim=768 → 3072 B ≈ 3.0 KB / 行
BFloat16 约为 Float32 的一半；i8 / b1 量化索引进一步压缩索引体积
索引体积 ≈ 向量体积 × 系数（随 M、量化、GRANULARITY 与 part 数量变化，须实测）
总磁盘 ≈ (数据 + 索引) × (1 + 副本数) / 压缩比

系数为经验区间，非官方承诺；用 system.parts / system.columns 对真实表实测后做容量规划。

7. 生产部署与运维

• 高可用 / 分片 / 副本：向量列与 skip index 随 MergeTree part 复制；分布式表 / 副本沿用现有集群方案；索引在 part merge 后重建。
• 备份恢复：沿用 ClickHouse 现有备份方案；恢复后核对索引是否随 part 恢复，必要时重新 MATERIALIZE INDEX。
• 监控（沿用集群监控，无独立向量端点；具体视图 / 端点官方资料未核实，以官方文档为准）：

• 扩缩容：以 6.5 估算为起点；向量列显著增大压缩后体积，扩容前重新评估磁盘与 merge 压力。
• 升级迁移：升到 25.8+ 才有近似索引；升级后存量 part 不会自动有索引，需 MATERIALIZE INDEX。
• 安全 / 日志：认证、TLS、RBAC、网络暴露面沿用 ClickHouse 基线；mutation 权限收敛（通用运维见根目录手册）。日志为 ClickHouse server 日志，无独立向量日志。

⚠️ 危险：DROP TABLE / TRUNCATE 会连带删除向量数据，且 mutation 类操作不可逆，执行前必须确认目标表与备份。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：ADD INDEX 后老数据查询依旧慢。原因：ADD INDEX 只对新写入生效。怎么做：存量必须 ALTER TABLE ... MATERIALIZE INDEX ... SETTINGS mutations_sync = 2。
2. 现象：L2Distance / cosineDistance 用了 DESC，索引不生效。原因：两者越小越相似，索引只能 ASC。怎么做：改成 ASC。
3. 现象：dotProduct 用了 ASC 结果反了。原因：它越大越相似，只能 DESC。怎么做：改成 DESC。
4. 现象：向量列写成 Array(Nullable(Float32)) 或有空数组，建索引失败。原因：不支持 Nullable / LowCardinality 数组、不允许空数组。怎么做：用合法 Array(Float32|Float64|BFloat16) 并清洗空数组。
5. 现象：方案里写死了 ClickHouse 稳定版本号 / 许可证。原因：两项官方资料明确未核实。怎么做：统一写「以官方为准」，勿编造。
6. 现象：<25.8 的版本想用近似索引。原因：vector_similarity 自 25.8 起才有。怎么做：升级，或退回精确全表扫描。
7. 现象：改了距离函数却没重建索引。原因：索引声明里的距离函数固化。怎么做：改索引定义并重新 MATERIALIZE INDEX。
8. 现象：MATERIALIZE INDEX 没等完成就验收，误判无效。原因：mutation 异步。怎么做：加 SETTINGS mutations_sync = 2 等待完成。
9. 现象：量化用 i8 / b1 后召回明显下降。原因：压缩损失。怎么做：精度优先改 f32 / bf16，用精确扫描做基线对照。
10. 现象：把 vector_similarity 当成全局 ANN 索引、套用别产品的过滤结论。原因：它是 skip index（按 granule 跳过）。怎么做：以 EXPLAIN 与实测判断过滤行为，勿臆测 pre/post。
11. 现象：大表 MATERIALIZE INDEX 拖垮集群。原因：mutation 消耗 CPU / IO。怎么做：⚠️ 维护窗口 + 备份 + 资源评估，可能引发线上事故。
12. 现象：DROP TABLE / TRUNCATE 后向量全丢。原因：向量就是普通列。怎么做：⚠️ 确认目标表与备份，属数据丢失级操作。

10. 速查表

11. 参考与延伸

官方链接：https://clickhouse.com/docs/ru/reference/engines/table-engines/mergetree-family/annindexes （ANN 索引文档）。官网、文档根、镜像仓库、SDK、控制台 URL 官方资料未提供，勿臆测。

与同册其他产品的关系：已有 ClickHouse → 本篇；已有 PG → pgvector.md；已有 ES / OpenSearch → Elasticsearch-OpenSearch.md；已有 Redis → Redis-Vector-Search.md；已有国产关系库 → 国产数据库向量能力.md；需在线高并发点查 / 专用向量库 → 01-专用向量数据库 分册。

进阶阅读：官方 annindexes 文档的 vector_similarity 参数与约束；MergeTree 的 part / granule / skip index / mutation 机制；ClickHouse EXPLAIN 与 system 表。

本篇「未核实 / 以官方为准」事项：

1. ClickHouse 当前稳定版本号与许可证未核实（官方资料「六、未核实清单」第 4 条明确列出），正文请勿当作确定事实，一律「以官方为准」。
2. SELECT version()、HTTP / Native 端口 8123 / 9000、ALTER TABLE ... UPDATE/DELETE、SHOW CREATE TABLE、DESCRIBE TABLE、EXPLAIN、system.parts / system.columns 等属通用知识与经验性表述，以所用版本官方文档为准。
3. 过滤与近邻排序的 pre/post-filter 官方语义未核实，6.3 只给经验性说明，须以 EXPLAIN 实测。
4. 内置 RRF / 混合检索 / 稀疏向量的逐字函数名未核实，勿臆测，按官方文档或应用层实现。
5. 官网 / 文档根 / 镜像仓库 / SDK / 控制台 URL、安装命令、镜像 tag、监控端点均官方资料未提供，勿臆测。
6. 规模、QPS、容量公式、告警阈值均为经验值，非官方承诺，须实测。