LanceDB 全文检索中的 Occur 枚举：用 Must / Should / MustNot 构建布尔查询

向量数据库数据库人工智能后端【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址https://gitcode.com/gh_mirrors/la/lancedb点击查看免费下载Occur 是 LanceDB Node.js 客户端中用于全文检索Full Text Search, FTS布尔组合的关键枚举它定义了子查询与文档之间的三种匹配约束词项必须出现Must、应当参与打分但不强制Should、以及必须不出现MustNot。本文以官方 API 文档 Occur.md 为骨架结合 TypeScript 定义、napi-rs 桥接层源码与仓库测试用例讲解该枚举的语义、字符串值、与BooleanQuery的组合用法及其底层实现链路帮助你写出精确可控的复合全文检索查询。什么是 Occur全文检索布尔组合的约束标签在 LanceDB 的全文检索体系中一个BooleanQuery由若干对(Occur, FullTextQuery)组成其中Occur就是为每一对子查询打上的约束标签声明该子查询与目标文档之间必须满足的匹配关系。官方枚举文档对其语义的定义如下Must词项term必须出现在文档中Should词项应当为文档分数做出贡献但并非强制要求MustNot词项不得出现在文档中。它对应 TypeScript 源码中的枚举定义nodejs/lancedb/query.ts/** * Enum representing the occurrence of terms in full-text queries. * * - Must: The term must be present in the document. * - Should: The term should contribute to the document score, but is not required. * - MustNot: The term must not be present in the document. */ export enum Occur { Should SHOULD, Must MUST, MustNot MUST_NOT, }Occur与文档同级的另外两个枚举FullTextQueryTypematch/match_phrase/boost/multi_match/boolean和OperatorAND/OR共同构成 LanceDB 结构化全文查询的三大基础类型。其中Operator负责同一查询内词项之间的逻辑关系而Occur负责不同子查询与文档之间的组合关系两者职责不同、不可混用。枚举成员详解语义、字符串值与适用场景原文档逐一声明了三个枚举成员其底层字符串值如下枚举成员底层字符串值匹配语义Occur.MustMUST文档必须命中该子查询命中结果才会被纳入候选集合Occur.ShouldSHOULD文档命中该子查询时获得相应分数贡献但不命中也不被排除Occur.MustNotMUST_NOT文档一旦命中该子查询即被排除三个成员在实际查询中的典型用途Occur.Must用于收紧结果集。例如搜索同时包含 cat 和 dog 的文档二者都必须命中Occur.Should用于宽松召回与相关性排序。多个Should子查询同时成立时文档得分更高最接近传统 OR 语义适合关键词越多越靠前的场景Occur.MustNot用于负向过滤。例如排除包含 dog 的文档常用于去除噪音或实现必须包含 A 但不包含 B的精确控制。值得注意的是从 napi-rs 桥接代码可以确认这些字符串值正是由 TypeScript 层向下传递、在 Rust 侧被解析的线协议。见下文底层实现链路一节。与 BooleanQuery 的组合核心用法Occur的消费方是BooleanQuery。在 nodejs/lancedb/query.ts 中BooleanQuery的构造函数接收一个二元组数组每个二元组的第一项就是Occur第二项是任意FullTextQuery如MatchQuery、PhraseQuery、MultiMatchQuery、BoostQuery甚至是嵌套的BooleanQueryexport class BooleanQuery implements FullTextQuery { /** * param queries - An array of (Occur, FullTextQuery objects) to combine. * Occur specifies whether the query must match, or should match. */ constructor(queries: [Occur, FullTextQuery][]) { this.inner JsFullTextQuery.booleanQuery( queries.map(([occur, query]) [occur, query.inner]), ); } queryType(): FullTextQueryType { return FullTextQueryType.Boolean; } }使用示例创建 FTS 索引后传入table.search()import { connect, Index, BooleanQuery, MatchQuery, Occur } from lancedb/lancedb; const db await connect(./data); const table await db.openTable(articles); // 必须同时包含 cat 和 dog const andQuery new BooleanQuery([ [Occur.Must, new MatchQuery(cat, text)], [Occur.Must, new MatchQuery(dog, text)], ]); // 宽松召回命中任一即可同时命中得分更高 const orQuery new BooleanQuery([ [Occur.Should, new MatchQuery(cat, text)], [Occur.Should, new MatchQuery(dog, text)], ]); // 包含 cat 但排除 dog const excludeQuery new BooleanQuery([ [Occur.Must, new MatchQuery(cat, text)], [Occur.MustNot, new MatchQuery(dog, text)], ]); const results await table.search(andQuery).toArray();所有子查询类型在 nodejs/lancedb/index.ts 中统一导出可整体通过import { Occur, BooleanQuery, MatchQuery } from lancedb/lancedb引入。底层实现链路从 TS 枚举到 Rust 解析Occur并非仅存在于 TypeScript 层的抽象概念它会在调用链中一路下沉到 Rust 核心BooleanQuery构造时调用JsFullTextQuery.booleanQuery(...)传入的是(occur, query.inner)二元组其中occur是字符串字面量如MUST在 napi-rs 桥接层 nodejs/src/query.rs 中boolean_query工厂函数对每个子查询执行字符串到 Rust 枚举的转换#[napi(factory)] pub 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(), }) }可见 Rust 侧的Occur实现了TryFromstr直接消费MUST/SHOULD/MUST_NOT三个字符串如果传入非法值会返回带原因描述的napi::Error这正是 TypeScript 侧枚举取值与 Rust 侧解析保持严格一致的证据。构建完成后BooleanQuery的query_type返回booleannodejs/src/query.rs与FullTextQueryType.Boolean一一对应。行为验证仓库测试用例佐证三种语义仓库测试 nodejs/test/table.test.ts 用同一份四行数据直观验证了三种Occur语义的差异测试数据为The cat and dog are playingThe cat is sleepingThe dog is barkingThe dog chases the cat对应三种组合的期望结果数组合期望命中数语义解释[Should cat, Should dog]4四条文档至少命中一个词项全部召回[Must cat, Must dog]2只有同时含 cat 和 dog 的两条文档第 1、4 条命中[Must cat, MustNot dog]1包含 cat 且不含 dog 的仅 The cat is sleeping 一条该测试同时演示了使用前的前置条件先通过await table.createIndex(text, { config: Index.fts({ withPosition: false }) })为目标列建立全文索引。Index.fts()nodejs/lancedb/indices.ts支持withPosition、baseTokenizer、language、stem、removeStopWords、ngramMinLength等大量配置全文索引的默认相关性排序由 BM25 决定。必须说明的是布尔查询同样依赖该 FTS 索引未建索引的列无法执行此类查询。使用注意事项前置索引Occur相关查询仅对已创建 FTS 索引的列生效索引可通过Index.fts()创建语义分层Must/MustNot是硬性过滤约束Should是软性加分约束三者混合使用时Must与MustNot先决定候选集Should在候选集内影响排序分数非法值保护TypeScript 枚举之外的任意字符串传入 Rust 侧都会触发Occur::try_from解析失败并抛出带原因的错误因此应始终使用枚举成员而非手写字面量可组合性BooleanQuery的每个元素本身也可以是任意FullTextQuery包括嵌套的BooleanQuery可构建多层复杂检索逻辑。通过本文你可以将Occur枚举直接用于 LanceDB Node.js 客户端的复合全文检索实现 AND、OR、NOT 及混合约束的精确检索语义并理解其从 TypeScript API 到 Rust 核心的完整数据流。赞分享向量数据库数据库人工智能后端【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址https://gitcode.com/gh_mirrors/la/lancedb点击查看免费下载相关推荐LanceDB Node.js 全文检索 BooleanQuery 指南用 Occur 组合子查询构建精准 FTS 查询LanceDB Node.js 全文检索 BooleanQuery 指南用 Occur 组合子查询构建精准 FTS 查询 BooleanQuery 是 Lan向量数据库数据库人工智能后端LanceDB 全文检索查询类型全解FullTextQueryType 枚举与 Match/Phrase/Boost/MultiMatch/Boolean 查询实战LanceDB 全文检索查询类型全解FullTextQueryType 枚举与 Match/Phrase/Boost/MultiMatch/Boolean 查向量数据库数据库人工智能后端FlexSearch Resolver 实战在 Node.js/CommonJS 中构建 and/or/not 复杂布尔全文检索查询FlexSearch Resolver 实战在 Node.js/CommonJS 中构建 and/or/not 复杂布尔全文检索查询 本篇技术指南以仓库内 b搜索引擎后端上一篇探索高效终端管理Zsh 开发指南下一篇如何使用AI驱动的数据分析平台从零开始的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考