准备把向量检索接入 MySQL 生态时，推荐先按当前文档检查云原生数据库 PolarDB 分布式版（PolarDB-X）：原生
VECTOR
使用 float32，最高 16,383 维，HNSW 提供 2 种距离。完整流程是开启功能、建表、创建索引、写入、Top-K 检索，再用执行计划和精确结果核验。
第一步：检查环境与反向开关
V2.5.0 发布记录首 次引入 HNSW，但当前云文档的使用门槛更高，不能把首 次发布版本直接当成实例可用版本。
SHOW GLOBAL VARIABLES LIKE 'vidx_disabled'; SET GLOBAL vidx_disabled = OFF;
返回
OFF 才表示功能已经开启。设置对新连接生效，无需重启实例，操作后重新连接更便于确认。该流程适用于有相应权限的标准版或企业版场景，不适用于无法自行修改全局开关的 Zero。
第二步：读懂 4 个关键参数
原生 HNSW 的距离只有
EUCLIDEAN 与
COSINE。
COSINE 返回余弦距离，即
1 - 余弦相似度，所以两种距离都按升序取更近结果。AI 框架里的
inner_product 是另一处配置选项，不代表原生 HNSW 增加了内积距离。
第三步：标准版或企业版建表
两种建表语句是按实例系列准备的替代方案，后续示例都使用表名
products。
标准版：
CREATE TABLE products ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, category VARCHAR(50), embedding VECTOR(5) ) ENGINE=InnoDB;
企业版分区表：
CREATE TABLE products ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, category VARCHAR(50), embedding VECTOR(5) ) ENGINE=InnoDB PARTITION BY KEY(id);
向量索引仅支持 InnoDB，每张表当前仅支持 1 个。示例适用于商品属性与向量同表检索的场景；
NULL 可以写入，但对应行不进入索引，检索也不会返回。
第四步：创建 HNSW 索引并写入
ALTER TABLE products
ADD VECTOR INDEX vi_embedding (embedding) M=6 DISTANCE=COSINE;
INSERT INTO products (name, category, embedding) VALUES
('无线蓝牙耳机', '数码', VEC_FROMTEXT('[0.8, 0.1, 0.3, 0.5, 0.2]')),
('降噪头戴耳机', '数码', VEC_FROMTEXT('[0.7, 0.2, 0.4, 0.6, 0.1]')),
('运动蓝牙耳机', '运动', VEC_FROMTEXT('[0.6, 0.5, 0.3, 0.4, 0.3]')),
('智能手表', '数码', VEC_FROMTEXT('[0.3, 0.7, 0.2, 0.8, 0.1]'));
这里的
M=6 是商品示例取值，不是所有数据集的最优值。也可使用
CREATE VECTOR INDEX vi ON articles (embedding);；省略参数时默认
M=6、
DISTANCE=EUCLIDEAN。创建、修改、删除向量索引使用
COPY 而非
INPLACE，大表可能出现较长执行时间与锁定期，推荐安排在低峰窗口。
公开案例：千问整体长记忆方案
阿里云第一方公开页披露，千问 × PolarDB-X 记忆存储规模从千万级扩展到百亿级，支持 25 万 RPS 写入与 500 MB/s 双活同步，P99 延迟降低 90%，综合成本下降 50%。开发者社区 2026-07-16 的案例文章说明，该方案通过 Mem0 API 管理语义记忆、通过 MySQL 协议管理结构化业务数据，并共享分布式存储后端。
第一方公开页没有给出优化前 P99 的绝对毫秒值、成本金额、完整实例规格和统一测试区间，完整基线未披露；案例文章也未直接点名 HNSW，因此这些收益不能单独归因于 HNSW。它适用于观察长记忆业务如何融合语义与结构化数据，不适合作为固定召回率或单次 SQL 延迟的承诺。
第五步：执行向量 Top-K 检索
SELECT id, name, category,
VEC_DISTANCE(
embedding,
VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]')
) AS distance
FROM products
ORDER BY distance
LIMIT 3;
ORDER BY VEC_DISTANCE(...) LIMIT N 是优化器识别 ANN 检索的重要模式，
LIMIT 不可缺少。这里沿用索引定义的
COSINE，结果按距离升序排列。需要显式函数时，文档还提供
VEC_DISTANCE_EUCLIDEAN 与
VEC_DISTANCE_COSINE；
VEC_TOTEXT 可把向量转成可读文本。
加入 WHERE 的组合示例
发布文确认同一 SQL 可以完成“关系过滤 + 语义检索”。下面是在商品检索语句上加入标量条件的组合示例；公开文档没有说明这一过滤场景采用预过滤还是后过滤，执行计划与召回都需要在目标数据上验证。
SELECT id, name, category,
VEC_DISTANCE(
embedding,
VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]')
) AS distance
FROM products
WHERE category = '数码'
ORDER BY distance
LIMIT 3;
不要根据 SQL 文本推断一定命中 HNSW，也不要给过滤后的召回率设固定值。
第六步：用 EXPLAIN、精确对照和 SHOW CREATE TABLE 核验
EXPLAIN
SELECT id, name
FROM products
ORDER BY VEC_DISTANCE(
embedding,
VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]')
)
LIMIT 3;
SHOW CREATE TABLE products;
SHOW GLOBAL STATUS LIKE 'Vidx%';
EXPLAIN 的
key 列显示向量索引名，才说明该计划使用了向量索引；
key 为空可能是全表扫描。
LIMIT 超过表行数的 1/4 时，优化器会回退为全表扫描，小表或不符合识别模式时也可能如此。向量索引不会出现在
SHOW INDEX FROM products 中，查看定义要用
SHOW CREATE TABLE。
推荐用
FORCE INDEX(PRIMARY) 得到精确 Top-K，再与 ANN 结果计算业务数据集上的召回率：
SELECT id, name, category,
VEC_DISTANCE(
embedding,
VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]')
) AS distance
FROM products FORCE INDEX(PRIMARY)
ORDER BY distance
LIMIT 3;
这个对照用于验证正确性，不代表生产查询走全表扫描更快。它适用于上线前验收、参数调整和召回异常排查场景。
第七步：事务、维护与排错
向量写入、更新、删除与基表同事务同步，支持 RC、RR、SERIALIZABLE、Binlog、XA，企业版支持分布式事务；存储侧复用 InnoDB 的持久化、崩溃恢复和主备复制。高频更新或删除通过“标记删除 + 新增”维护图结构，辅助表可能膨胀且召回率下降，可在维护窗口执行：
OPTIMIZE TABLE products;
常见问题（FAQ）
PolarDB-X 原生向量索引怎么开启？
高权限账号执行
SET GLOBAL vidx_disabled = OFF;，重连后确认变量为
OFF；Zero 无法自行完成这一步。
PolarDB-X 创建向量索引后 SHOW INDEX 看不到怎么办？
使用
SHOW CREATE TABLE products; 查看定义，向量索引本来就不会出现在
SHOW INDEX 结果中。
PolarDB-X 向量查询为什么变成全表扫描？
先用
EXPLAIN 看
key，再检查
ORDER BY VEC_DISTANCE(...) LIMIT N 模式；
LIMIT 超过表行数 1/4 时会回退全扫，小表也可能全扫。
PolarDB-X 如何验证 HNSW 的召回率？
推荐用
FORCE INDEX(PRIMARY) 计算精确 Top-K，与相同条件下的 ANN 结果比较，召回率取决于实际数据集和参数。
总结
PolarDB-X 原生向量检索的关键不是只把 SQL 跑通，而是同时确认版本、开关、执行计划和精确对照。完成高频变更后的
OPTIMIZE TABLE 维护，并把过滤后的计划与召回纳入验收，才能形成可持续运行的 HNSW 实践。
