Documentation
¶
Overview ¶
Package search 是全文检索底座里「纯逻辑」的一层:把文本变成 SQLite FTS5 能正确索引的形式, 把用户输入的查询规划成 FTS5 的 MATCH 表达式,并在候选文本里定位命中位置、生成片段。 本包不碰数据库,所有函数都是纯函数,便于做表驱动测试与模糊测试;引擎(建表、增量维护、回填、查询)在 internal/store。
分词全部在 Go 这一侧完成,FTS5 只负责按空格切开并建倒排:
- 索引与查询走同一套规则(IndexText / NewPlan),所以查询里的词条与索引里的词条逐字节一致, 不会因为两边对「什么算词字符」的理解不同而漏检;
- FTS5 用 ascii 分词器:ASCII 字母数字是词字符,其余 ASCII 是分隔符,非 ASCII 字节一律是词字符。 我们送进去的文本已经把所有非词字符换成了空格,所以它不会再切出任何我们没预料的词;
- 不用 unicode61,是因为它自带的字符类别表停在很旧的 Unicode 版本,会把未分配或较新的符号当成字母, Go 这边没法和它精确对齐,模糊测试几秒内就能找到「查询词被它切成短语」的输入。
汉字不靠空格分词:连续的汉字 / 假名展开成相邻二元组(「项目群」→「项目」「目群」), 查询时同样展开后做 AND,三字及以上的片段再用原文子串校验去掉二元组拼凑出的假阳性, 语义与原来的 LIKE 子串匹配一致。
Index ¶
- Constants
- func Fold(s string) string
- func HasTerm(text string, terms []string) bool
- func IndexText(s string) string
- func IsCJK(r rune) bool
- func Snippet(text string, terms []string, width int) string
- type Plan
- func (p Plan) FullMatch(scopes []string) (expr string, ok bool)
- func (p Plan) MatchExpr(scopes []string, titleOnly bool) (expr string, ok bool)
- func (p Plan) MatchExprIn(kindToken string, restrict bool, scopes []string, titleOnly bool) (expr string, ok bool)
- func (p Plan) MatchExprUnion(parts []ScopePart, filter bool, titleOnly bool) (expr string, ok bool)
- func (p Plan) Matches(text string) bool
- func (p Plan) MatchesAll(text string) bool
- type ScopePart
- type Word
Constants ¶
const CreateFTSSQL = "CREATE VIRTUAL TABLE IF NOT EXISTS " + FTSTable +
" USING fts5(title, body, scope, content='', detail=column, columnsize=0, tokenize='ascii')"
CreateFTSSQL 建全文索引虚表。几个选项都是有意的:
- content 设为空串(无内容表):索引里不存原文副本,原文只在业务表里,查询时回源校验;
- detail=column:只记「词出现在哪一列」,不记位置,索引体积约为原文的 1.2 倍(完整模式约 1.6 倍)。 代价有两个:不支持短语 / NEAR 查询——NewPlan 因此只生成单词条的 AND,短语语义靠原文子串校验; bm25 排序失效(实测所有分数都是 0)——所以不用 bm25,排序由引擎按「标题命中优先、再按时间倒序」完成, 而且这样 ORDER BY rowid DESC LIMIT n 可以提前结束,宽泛查询也不用把全部命中算一遍;
- columnsize=0:不存每行每列的词数,进一步压缩体积并加快写入;
- ascii 分词器:分词在 Go 一侧做完(见包注释),FTS5 只按空格切开。
三列含义:title 标题类文本(权重高)、body 正文、scope 范围词条(不透明字母数字串,只用于限定可见范围)。
const DefaultSnippetWidth = 160
DefaultSnippetWidth 是片段默认宽度(字符数)。
const FTSTable = "search_fts"
FTSTable 是全文索引虚表的名字。
const SchemaVersion = 1
SchemaVersion 是「索引文本约定」的版本号:归一化规则、列含义、DDL 任何一项变了就加一, 引擎据此判定旧索引作废并整库重建。
Variables ¶
This section is empty.
Functions ¶
func HasTerm ¶
HasTerm 报告 text 里是否含有 terms 中的任意一个。text 先按 Fold 归一,terms 要求已是归一后的(NewPlan 产出的 Terms 就是); 空串的词不算命中,terms 为空一律为 false。页面搜索用它在几栏文字里挑出「第一个带命中的栏」来取片段。
func IndexText ¶
IndexText 把一段文本转成喂给 FTS5 的索引文本:所有词用单个空格隔开、统一小写, 汉字 / 假名连续段展开成相邻二元组,孤立的单个汉字原样保留,非词字符一律变成空格。 输出只用于喂给 FTS5,不会存储,也不会返回给用户。
Types ¶
type Plan ¶
type Plan struct {
// Match 是 FTS5 的词条表达式(空格拼接 = AND),不含列过滤;Indexable 为 false 时为空。
Match string
// Verify 是候选文本必须包含的精确子串(已归一):三字及以上的汉字片段、单个汉字。
Verify []string
// Terms 是归一后的查询词(汉字片段保持原样),用于定位片段与高亮。
Terms []string
// Words 是查询里的英文 / 数字词(已归一)及是否按前缀匹配;MatchesAll 用它对原文做整词校验。
Words []Word
// Indexable 报告这条查询能否走全文索引。
Indexable bool
// contains filtered or unexported fields
}
Plan 是把一条用户查询翻译成「FTS5 候选 + 原文校验」两步之后的结果。
匹配语义(与此前逐表 LIKE 的差别见 docs/search.md):
- 查询按词切开,所有词都要命中(AND),没有顺序要求;
- 汉字 / 假名片段按子串匹配(与 LIKE 一致):两个字走一个二元组,三个字及以上走二元组 AND 加原文子串校验;
- 单个汉字无法走索引(索引里只有二元组);整条查询只剩单字时 Indexable 为 false,由调用方走原来的 LIKE;
- 英文 / 数字按整词匹配,三个字符及以上的词自动带前缀(「archiv」能找到「archive」),不再匹配词中间的片段;
- 大小写不敏感,全角英文数字等同半角;不折叠变音符号。
func (Plan) FullMatch ¶
FullMatch 生成完整的 MATCH 表达式:内容词条在 title / body 两列里找, scopes 非空时再加上 scope 列的范围过滤。等价于 MatchExpr(scopes, false)。
func (Plan) MatchExpr ¶
MatchExpr 生成完整的 MATCH 表达式。titleOnly 为 true 时内容词条只在 title 列里找 (引擎用它先取标题命中的候选,排在只有正文命中的前面)。 scope 词条是引擎生成的不透明字母数字串;含有其它字符的范围一律丢弃 (不做「清洗后凑合用」,清洗可能撞上另一个范围的词条)。
返回 ok 为 false 有两种情况,调用方要分开处理:计划本身不可走索引(Indexable 为 false,走旧的 LIKE 路径); 或者给了范围但没有一个有效(必须按「没有结果」处理,绝不能去掉范围过滤——那会越权)。
func (Plan) MatchExprIn ¶
func (p Plan) MatchExprIn(kindToken string, restrict bool, scopes []string, titleOnly bool) (expr string, ok bool)
MatchExprIn 在 MatchExpr 的基础上多一层「类型」限定:kindToken 非空时,scope 列必须含这个词条(引擎给每个条目都写了它的类型词条); restrict 为 true 时,scope 列还必须含 scopes 里的任一词条。 两层是 AND 关系,所以「某个类型 × 某几个主人」一次查询就能表达;restrict 为 true 而 scopes 里没有一个有效词条时失败闭合(ok 为 false, 调用方按「没有结果」处理,不能去掉限定)。kindToken 不是合法词条同样失败闭合。
func (Plan) MatchExprUnion ¶
MatchExprUnion 是 MatchExprIn 的多类型版本:一次查询同时覆盖若干个类型,各类型可以有各自的主人范围。 各分量之间是 OR,每个分量内部是「类型 AND 任一主人」,整体再与检索词 AND——这样所有类型的候选落在同一条按 rowid 排序的结果流里, 调用方不用再各类型分别扫描、事后再合并。
filter 为 false 时不加任何 scope 限定(调用方确认「所有类型都在查,而且都不限主人」,这是最常见也最便宜的情形)。 失败闭合:词条不合法、或限定了主人却没有一个有效词条的分量整个丢掉(它本来就不可能命中);没有分量留下时 ok 为 false, 调用方按「没有结果」处理,不能去掉限定。
func (Plan) MatchesAll ¶
MatchesAll 对原文做完整的精确校验:汉字片段按子串、英文 / 数字词按整词(三个字符及以上按前缀),所有要求都要满足。 引擎在把候选交给用户之前用它核对「现在的原文」——索引可能落后于原文(刚改完还没来得及重建索引、或索引里留着旧文本), 所以不能只信 FTS 的命中。校验规则与 IndexText 的切词规则一致,因此对已索引的最新文本,FTS 命中的一定也通过这里。