search

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

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

View Source
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 范围词条(不透明字母数字串,只用于限定可见范围)。

View Source
const DefaultSnippetWidth = 160

DefaultSnippetWidth 是片段默认宽度(字符数)。

View Source
const FTSTable = "search_fts"

FTSTable 是全文索引虚表的名字。

View Source
const SchemaVersion = 1

SchemaVersion 是「索引文本约定」的版本号:归一化规则、列含义、DDL 任何一项变了就加一, 引擎据此判定旧索引作废并整库重建。

Variables

This section is empty.

Functions

func Fold

func Fold(s string) string

Fold 把文本归一成检索用的形式:全角 ASCII 转半角,再转小写(与索引和查询用的是同一套逐字符归一,字符个数不变)。

func HasTerm

func HasTerm(text string, terms []string) bool

HasTerm 报告 text 里是否含有 terms 中的任意一个。text 先按 Fold 归一,terms 要求已是归一后的(NewPlan 产出的 Terms 就是); 空串的词不算命中,terms 为空一律为 false。页面搜索用它在几栏文字里挑出「第一个带命中的栏」来取片段。

func IndexText

func IndexText(s string) string

IndexText 把一段文本转成喂给 FTS5 的索引文本:所有词用单个空格隔开、统一小写, 汉字 / 假名连续段展开成相邻二元组,孤立的单个汉字原样保留,非词字符一律变成空格。 输出只用于喂给 FTS5,不会存储,也不会返回给用户。

func IsCJK

func IsCJK(r rune) bool

IsCJK 报告 r 是否属于不靠空格分词的文字:汉字、平假名、片假名(含长音符 ー)。 韩文按空格分词,泰文等没有空格的文字不在范围内(按普通字母处理,只支持整词 / 前缀)。

func Snippet

func Snippet(text string, terms []string, width int) string

Snippet 在 text 里找到 terms 中最靠前的命中位置,取其附近约 width 个字符作为片段; 没有命中就取开头。连续空白折叠成一个空格,被截断的一侧加省略号,不会把一个英文词从中间截开。 terms 要求已是小写(NewPlan 产出的 Terms 就是)。

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 NewPlan

func NewPlan(raw string) Plan

NewPlan 规划一条查询。raw 为空、只有标点或只有单个汉字时返回 Indexable 为 false 的计划。

func (Plan) FullMatch

func (p Plan) FullMatch(scopes []string) (expr string, ok bool)

FullMatch 生成完整的 MATCH 表达式:内容词条在 title / body 两列里找, scopes 非空时再加上 scope 列的范围过滤。等价于 MatchExpr(scopes, false)。

func (Plan) MatchExpr

func (p Plan) MatchExpr(scopes []string, titleOnly bool) (expr string, ok bool)

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

func (p Plan) MatchExprUnion(parts []ScopePart, filter bool, titleOnly bool) (expr string, ok bool)

MatchExprUnion 是 MatchExprIn 的多类型版本:一次查询同时覆盖若干个类型,各类型可以有各自的主人范围。 各分量之间是 OR,每个分量内部是「类型 AND 任一主人」,整体再与检索词 AND——这样所有类型的候选落在同一条按 rowid 排序的结果流里, 调用方不用再各类型分别扫描、事后再合并。

filter 为 false 时不加任何 scope 限定(调用方确认「所有类型都在查,而且都不限主人」,这是最常见也最便宜的情形)。 失败闭合:词条不合法、或限定了主人却没有一个有效词条的分量整个丢掉(它本来就不可能命中);没有分量留下时 ok 为 false, 调用方按「没有结果」处理,不能去掉限定。

func (Plan) Matches

func (p Plan) Matches(text string) bool

Matches 报告 text 是否满足计划里所有的精确子串要求(按索引同样的规则归一后比较)。没有要求时恒为 true。

func (Plan) MatchesAll

func (p Plan) MatchesAll(text string) bool

MatchesAll 对原文做完整的精确校验:汉字片段按子串、英文 / 数字词按整词(三个字符及以上按前缀),所有要求都要满足。 引擎在把候选交给用户之前用它核对「现在的原文」——索引可能落后于原文(刚改完还没来得及重建索引、或索引里留着旧文本), 所以不能只信 FTS 的命中。校验规则与 IndexText 的切词规则一致,因此对已索引的最新文本,FTS 命中的一定也通过这里。

type ScopePart

type ScopePart struct {
	// KindToken 是类型词条(必填)。
	KindToken string
	// Restrict 为 true 时,内容还必须属于 Owners 里的任一主人词条;为 false 时这个类型不限主人。
	Restrict bool
	Owners   []string
}

ScopePart 是 MatchExprUnion 的一个分量:「这个类型的内容,在这些主人名下可见」。

type Word

type Word struct {
	Text   string
	Prefix bool
}

Word 是一个英文 / 数字查询词。Prefix 为 true 表示它按前缀匹配(三个字符及以上,见 prefixMinRunes)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL