VexDB-Lite 混合过滤查询实战：WHERE 条件 + 向量 ANN 搜索如何协同工作

VexDB-Lite 混合过滤查询实战WHERE 条件 向量 ANN 搜索如何协同工作【免费下载链接】VexDB-LiteA cross-platform vector database, which can be integrated into existing databases as a plugin.项目地址: https://gitcode.com/gh_mirrors/ve/VexDB-LiteVexDB-Lite是一款可嵌入 PostgreSQL、DuckDB、SQLite 的跨平台向量数据库插件。它的图索引GRAPH_INDEX不只支持纯向量 ANN 搜索还能让WHERE 条件过滤与向量近似最近邻ANN查询协同工作——本文带你搞懂这套混合过滤查询Filtered ANN Search的两种执行路径、自动过采样机制以及如何用 EXPLAIN 验证计划。为什么需要混合过滤查询在 RAG、多模态检索等真实场景中纯向量搜索几乎不够用。典型的提问方式是只搜图书类商品里与这句话语义最接近的 10 条商品在 2026 年之后的文档中找与这段文本最相似的 5 篇只返回status active的用户记忆向量也就是标量条件WHERE 向量距离排序ORDER BY 距离函数 LIMIT k三者组合。传统方案往往要么先过滤再暴力算距离慢要么先 ANN 再逐条筛结果可能不够 k 条。VexDB-Lite 的优化器会自动处理这种模式识别ORDER BY l2_distance(...) LIMIT k后改写为VEXDB_INDEX_SCAN并把 WHERE 条件拆成进图过滤和后置过滤两部分。详细机制见 vexdb_duckdb/README.md 与 documentation/features.md。两条协同路径进图过滤 vs 后置过滤这是理解混合过滤查询的核心VexDB-Lite 采用双路径 自动过采样的设计路径机制适用条件优点进图过滤pre-filter标量条件直接下推进图遍历过程条件列已加入索引定义遍历时直接跳过不匹配节点效率高后置过滤post-filterANN 先多取候选再逐条筛选条件无法下推如 LIKE、OR、严格任意 WHERE 都不丢索引结果始终正确关键设计即使 WHERE 里出现无法下推的条件优化器也不会退回全表扫描而是能推的先推、推不了的留作后置过滤partial push-down。这一行为由回归测试 graph_index_filter_mixed.test 锁定测试注释明确指出它防止了遇到不认识的谓词就整段放弃索引的性能悬崖。快速上手3 步建立混合过滤查询DuckDB第 1 步建表并插入数据向量用原生FLOAT[N]CREATE TABLE items (id INTEGER, category VARCHAR, price FLOAT, vec FLOAT[128]);第 2 步建索引把过滤列一起带进索引CREATE INDEX idx_items_vec_meta ON items USING GRAPH_INDEX (vec, category, price);注意索引括号里除了向量列vec还可以跟随标量列category、price。这些列的条件就能被下推进图遍历。第 3 步写混合查询SET vexdb_ef_search 64; SELECT id, price FROM items WHERE category book AND price 20 ORDER BY l2_distance(vec, [...]::FLOAT[128]) LIMIT 10;优化器会自动改写为VEXDB_INDEX_SCAN 过滤可用EXPLAIN验证物理计划中是否出现VEXDB_INDEX_SCAN。哪些 WHERE 条件支持哪些只是后置过滤根据 features.md 的说明和过滤测试用例支持矩阵大致如下✅下推进图等值、IN列表、BETWEEN拆成和两段、闭区间范围/、多条件 AND 组合常量在左侧20 price也会自动交换处理⚠️保留为后置过滤LIKE前缀匹配、严格不等号/因图内 RangeFilter 是闭区间、OR组合部分下推如rating 2 AND category LIKE a%范围条件进图、LIKE 留在图上做残差过滤举个例子来自测试用例中的商品表-- 范围合并price 20 AND price 60 会合并成一个 RangeFilter 下推 SELECT id FROM prod WHERE price 20 AND price 60 ORDER BY l2_distance(vec, [...]) LIMIT 4; -- 部分下推rating 进图LIKE 后置 SELECT id FROM prod WHERE rating 2 AND category LIKE a% ORDER BY l2_distance(vec, [...]) LIMIT 3;实践建议如果你的高频过滤条件就集中在几个标量列上分类、状态、时间范围把它们都写进GRAPH_INDEX (vec, 过滤列...)的定义里可获得最佳的进图过滤收益。自动过采样过滤后结果还能凑够 k 条吗后置过滤有个经典问题ANN 只取回 k 条筛掉一半后就不够数了。VexDB-Lite 的优化器内置了**过采样over-fetch**逻辑——在 vex_optimizer.cpp 中可以看到决策函数ComputeScanK当优化器能估计过滤选择性时按k ÷ 选择性反推需要扫描的候选数例如 10 万行表里过滤只剩 25%则取回约 4k 条当无法估计时回退到默认过采样因子4即取回k × 4条候选再筛并钳制到表实际行数避免无谓浪费对应能力对比见 README.md 中的 Filtered ANN search: WHERE filter with automatic oversampling 一行——这正是 DuckDB 侧 VexDB-Lite 相对内置 VSS 的差异化能力之一。这种设计对多模态场景尤其友好——比如上面这类图片向量库常见查询是WHERE category building AND year 2024再按视觉向量相似度排序无需手动写多取几条的补偿逻辑。PostgreSQL 侧同样的 SQL不同的协同方式PostgreSQL 插件侧的混合过滤查询更透明你不需要把过滤列写进索引定义标准 SQL 写法即可CREATE INDEX idx_items_vec ON items USING vexdb_graph (vec floatvector_l2_ops) WITH (m 16, ef_construction 64); -- 混合过滤WHERE 由优化器在 ANN Index Scan 之上处理 SET vexdb.ef_search 100; SET enable_seqscan off; SELECT id, vec - [0.15, 0.25, 0.35] AS dist FROM items WHERE category book ORDER BY vec - [0.15, 0.25, 0.35] LIMIT 10;优化器把ORDER BY 距离运算符 LIMIT k模式改写为 ANN Index ScanWHERE 条件作为后置过滤作用于索引扫描结果。三大引擎PG / DuckDB / SQLite共享同一套图索引与 SIMD 距离内核位于 common/算法行为保持一致详见 features.md。调优清单让混合查询又快又准参数作用建议vexdb_ef_search/vexdb.ef_search图搜索宽度默认 40/64召回不足时提到 100~200vexdb_brute_force_threshold行数低于该值直接暴力扫默认 10000小数据自动 100% 召回调试图路径时设为 0vexdb_pq_search_modepq_only仅用量化码排序极致 QPS 场景开启三个实用技巧先用 EXPLAIN 确认走索引EXPLAIN SELECT ... WHERE ... ORDER BY l2_distance(...) LIMIT 10;物理计划里应有VEXDB_INDEX_SCANEXPLAIN 里看不到 VEXDB_INDEX_SCAN大概率是行数低于暴力搜索阈值这是特性不是 bug或ORDER BY没用l2_distance/cosine_distance/inner_product详见 vexdb_duckdb/README.md 的故障排查章节PQ / RaBitQ 量化索引同样支持进图过滤测试用例验证了quantizerpq 元数据过滤的交叉场景量化搜索路径同样遵守图内过滤常见问题速答Q加了 WHERE 后召回率明显下降过滤条件越严格进图过滤下能用的候选空间越小。可以调高ef_search量化索引可配合 refinevexdb_pq_refine_k_factor找回精度。Q结果会出错吗过滤条件是精确的吗后置过滤保证结果精确满足 WHERE所有不匹配行都会被剔除进图过滤同样精确等值用哈希集合、范围用闭区间 RangeFilter。近似性只体现在向量距离排序取 top-k这一环节这是所有 ANN 索引的通性。Q空结果集会怎样正常返回 0 行不会报错。测试用例覆盖了WHERE category zzz这类零命中场景。小结VexDB-Lite 的混合过滤查询设计可以概括为三句话双路径协同标量条件下推进图遍历无法下推的做后置过滤永不因复杂 WHERE 退回全表扫描自动过采样按选择性估计或默认 4 倍因子多取候选过滤后依然凑得够 k 条SQL 无感知PG / DuckDB 上都是标准WHERE ORDER BY 距离 LIMIT写法EXPLAIN一条命令即可验证执行计划配合 tests/spec/ 下的 YAML 规格测试如 graph_index_hybrid_disabled.yaml你可以放心把这类查询放进生产环境。【免费下载链接】VexDB-LiteA cross-platform vector database, which can be integrated into existing databases as a plugin.项目地址: https://gitcode.com/gh_mirrors/ve/VexDB-Lite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考