LanceDB Node.js 全文检索 BooleanQuery 指南：用 Occur 组合子查询构建精准 FTS 查询

LanceDB Node.js 全文检索 BooleanQuery 指南用 Occur 组合子查询构建精准 FTS 查询【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedbBooleanQuery 是 LanceDB Node.js SDKlancedb/lancedb中用于组合全文检索Full-Text Search, FTS子查询的类。本文将深入讲解它的构造方式、Occur出现语义Must / Should / MustNot与queryType()方法并结合 query.ts 的源码实现与 table.test.ts 中的真实测试用例演示如何用它实现必须包含 A、可以包含 B、不能包含 C这类复杂检索需求。1. BooleanQuery 是什么从类型体系上看BooleanQuery实现了FullTextQuery接口见 FullTextQuery 接口文档是 LanceDB FTS 查询家族的成员之一。它本身不直接执行搜索而是把若干个子查询按照布尔出现语义组合成一个复合查询对象再交给Table.search()执行。在 query.ts 中可以看到其完整定义export class BooleanQuery implements FullTextQuery { /** ignore */ public readonly inner: JsFullTextQuery; constructor(queries: [Occur, FullTextQuery][]) { this.inner JsFullTextQuery.booleanQuery( queries.map(([occur, query]) [occur, query.inner]), ); } queryType(): FullTextQueryType { return FullTextQueryType.Boolean; } }与MatchQuery、PhraseQuery、BoostQuery、MultiMatchQuery一样BooleanQuery通过inner字段持有底层原生查询对象napi 绑定中的JsFullTextQuery并在构造时把每个子查询的inner解包后一并传给原生层。2. 构造函数queries 参数与 Occur 语义BooleanQuery的构造函数签名如下new BooleanQuery(queries): BooleanQuery其中queries[Occur, FullTextQuery][]即一组出现语义 子查询的二元组数组。Occur决定该子查询在整体匹配中的权重与约束子查询可以是MatchQuery、PhraseQuery、MultiMatchQuery、BoostQuery甚至嵌套的BooleanQuery。2.1 Occur 枚举MUST / SHOULD / MUST_NOTOccur枚举定义在 query.ts其语义对应 Lucene 风格的布尔查询成员值语义ShouldSHOULD子查询匹配时计入相关性得分但不是必须匹配MustMUST子查询必须匹配否则文档不会进入结果集MustNotMUST_NOT子查询必须不匹配匹配则该文档被排除三种语义组合起来就能表达绝大多数布尔检索需求Must Must所有条件都满足逻辑 ANDShould Should至少一个条件满足即可逻辑 OR并影响得分排序Must MustNot满足 A 且不满足 B排除式过滤。完整枚举定义可参考 Occur 枚举文档。2.2 子查询类型FullTextQueryTypeBooleanQuery的queryType()固定返回FullTextQueryType.Boolean值为boolean。整个FullTextQueryType枚举FullTextQueryType 枚举文档如下export enum FullTextQueryType { Match match, MatchPhrase match_phrase, Boost boost, MultiMatch multi_match, Boolean boolean, }也就是说一个BooleanQuery内部可以自由混合MatchQuerymatch、PhraseQuerymatch_phrase、BoostQueryboost和MultiMatchQuerymulti_match等任意子查询类型从而构造出层级化的查询树。3. 源码级原理从 TypeScript 到原生查询BooleanQuery只是门面真正的组合逻辑发生在 Rust 侧。在 nodejs/src/query.rs 中napi 工厂方法boolean_query接收Vec(String, JsFullTextQuery)即从 TypeScript 传入的[Occur 字符串值, 子查询对象]列表逐个把Occur字符串解析为 Rust 枚举再克隆子查询的innerpub fn boolean_query(queries: Vec(String, JsFullTextQuery)) - napi::ResultSelf { let mut sub_queries Vec::with_capacity(queries.len()); for (occur, q) in queries { let occur Occur::try_from(occur.as_str()) .map_err(|e| napi::Error::from_reason(e.to_string()))?; sub_queries.push((occur, q.inner.clone())); } Ok(Self { inner: BooleanQuery::new(sub_queries).into(), }) }从源码结构可以看出Occur的字符串值SHOULD、MUST、MUST_NOT是跨语言传递的契约TypeScript 层与 Rust 层必须保持一致每个子查询在进入 Rust 层前先通过query.inner解包因此子查询可以是任意FullTextQuery实现包括嵌套的BooleanQuery底层BooleanQuery::new直接构造复合查询对象随后在真正的 FTS 执行器tantivy 引擎中按Occur语义求值。4. 实战示例把 BooleanQuery 用于 Table.search()BooleanQuery的典型用法是将其作为Table.search()的参数。Query.fullTextSearch()与Query.nearestToText()都接受string | FullTextQuery当传入BooleanQuery这类对象时SDK 会走结构化查询分支见 query.ts把查询对象整体交给原生层而不是把字符串当作普通词项处理。下面是一个完整可运行的示例数据与断言改编自仓库测试 table.test.tsimport { connect, Index, BooleanQuery, Occur, MatchQuery } from lancedb/lancedb; const db await connect(/tmp/lancedb-boolean-demo); const data [ { text: The cat and dog are playing }, { text: The cat is sleeping }, { text: The dog is barking }, { text: The dog chases the cat }, ]; const table await db.createTable(test, data); // FTS 需要先在目标列上创建全文索引 await table.createIndex(text, { config: Index.fts({ withPosition: false }), }); // 1) SHOULD SHOULD命中 cat 或 dog 的文档都返回逻辑 OR const shouldResults await table .search( new BooleanQuery([ [Occur.Should, new MatchQuery(cat, text)], [Occur.Should, new MatchQuery(dog, text)], ]), ) .toArray(); // 4 条文档全部命中4 条里要么含 cat 要么含 dog // 2) MUST MUST同时包含 cat 和 dog 的文档才返回逻辑 AND const mustResults await table .search( new BooleanQuery([ [Occur.Must, new MatchQuery(cat, text)], [Occur.Must, new MatchQuery(dog, text)], ]), ) .toArray(); // 命中 The cat and dog are playing 和 The dog chases the cat共 2 条 // 3) MUST MUST_NOT包含 cat 但不包含 dog 的文档才返回 const mustNotResults await table .search( new BooleanQuery([ [Occur.Must, new MatchQuery(cat, text)], [Occur.MustNot, new MatchQuery(dog, text)], ]), ) .toArray(); // 命中 The cat is sleeping共 1 条4.1 关键使用前提必须先建 FTS 索引对text列执行createIndex并配置Index.fts(...)后全文检索含布尔组合才能工作子查询必须落在同一类查询语义上MatchQuery构造时的column参数指定检索列布尔组合通常针对同一文本列进行结果仍走.toArray()/ 迭代器search()返回链式Query对象最终通过.toArray()或异步迭代消费结果与普通 FTS 一致。5. 在查询家族中的位置BooleanQuery不是孤立存在的它与另外四个查询类共同构成FullTextQuery体系全部定义在 query.ts 中并从 index.ts 对外导出MatchQuerymatch单列词项检索支持boost、fuzziness、maxExpansions、operator、prefixLengthPhraseQuerymatch_phrase精确短语检索支持slopBoostQueryboost正/负查询加权negativeBoost控制负查询惩罚力度MultiMatchQuerymulti_match跨多列检索支持逐列boostsBooleanQueryboolean用Occur组合上述任意查询。由于FullTextQuery接口只要求实现queryType()并持有innerBooleanQuery的构造参数类型是FullTextQuery[]因此你完全可以在布尔查询里嵌套BoostQuery或另一个BooleanQuery构造出A 必须 且 B 应该但不能 C这类高精度检索表达式。6. 小结BooleanQuery是 LanceDB Node.js SDK 中构造复合全文检索的核心工具构造函数接收[Occur, FullTextQuery][]数组用MUST/SHOULD/MUST_NOT表达每个子查询的约束强度queryType()固定返回FullTextQueryType.Boolean标识这是一个布尔组合查询内部通过 napi 把Occur与子查询inner转发到 Rust 层query.rs由底层 FTS 引擎统一求值实际使用时将它传给Table.search()配合createIndex建立的 FTS 索引即可执行AND / OR / NOT组合检索仓库测试 table.test.ts 提供了可直接对照验证的完整用例。对需要精确控制命中条件与排除规则的全文检索场景如搜索包含某关键词但排除另一关键词的文档BooleanQuery是比普通字符串搜索更可靠、语义更明确的方案。【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考