如何结合SQLite与Tantivy实现Rust全文检索

SQLite 的 LIKE 模糊查询在数据量较小时足够简单，但当 articles 表增长到十万行以上，LIKE '%关键词%' 无法走普通 B-Tree 索引，只能逐行扫描，响应时间会随数据量线性增加。Tantivy 是 Rust 生态中相对成熟的全文检索库，它使用倒排索引和 BM25 评分算法，可以在毫秒级完成关键词召回和相关性排序。把两者结合起来，SQLite 继续扮演嵌入式存储和事务管理的角色，Tantivy 负责构建索引并处理查询，这样既能保留 SQLite 单文件部署的优势，又能获得专业搜索引擎的查询体验。本文会以一个文章检索项目为例，完整演示从建库、建索引到查询和增量更新的过程。

开始前需要明确一个原则：Tantivy 索引中只保存用于检索的字段和主键，完整记录仍然存储在 SQLite 中。查询流程是先访问 Tantivy 获取文档主键和评分，再根据主键回 SQLite 读取标题、正文等完整字段。这种设计避免了双份数据带来的同步问题，也让 SQLite 的备份恢复机制能够继续发挥作用。

为什么不用 SQLite 自带的 FTS5

SQLite 官方提供了 FTS5 全文检索扩展，可以通过 CREATE VIRTUAL TABLE 创建全文索引表。FTS5 在简单英文场景下确实够用，但它需要编译时开启相应选项，某些发行版或嵌入式环境不一定包含完整支持。对于中文文本，FTS5 默认的 unicode61 分词器会把连续汉字当成一个整体，查询效果不理想。虽然可以通过外部内容表或自定义分词器改善，但配置相对繁琐，而且跨平台打包时容易出现版本差异。

Tantivy 的优势在于它是 Rust crate，直接在 Cargo.toml 中声明依赖即可，编译时不用关心 SQLite 是否带 FTS5。Tantivy 的分词器可以灵活替换，中文场景可以接入 tantivy-jieba 等分词库。查询阶段，Tantivy 的 QueryParser 支持布尔查询、短语查询和模糊查询，打分默认使用 BM25，相关度排序更符合用户预期。此外，Tantivy 索引由多个段组成，后台会自动合并小段，写入和查询可以并发进行，不会像 FTS5 那样在大量更新时出现明显的写入阻塞。

但 Tantivy 不是数据库，它没有事务、约束和 SQL 查询能力，也不适合存储需要频繁修改的字段。因此项目中常见做法是把权威数据放在 SQLite 中，Tantivy 只作为可重建的派生索引。即使索引目录损坏，也可以根据 SQLite 数据重新生成，降低了数据丢失风险。

架构设计与数据流

假设文章表结构如下：articles(id INTEGER PRIMARY KEY, title TEXT NOT NULL, body TEXT NOT NULL, updated_at INTEGER NOT NULL)。SQLite 中的每篇文章对应 Tantivy 索引中的一个文档。Tantivy 的 schema 可以定义三个字段：id 使用 u64 类型并建立倒排索引，title 和 body 使用文本类型。把 id 作为 u64 字段而不是字符串字段，可以减少索引体积，也方便与 SQLite 的 INTEGER 主键对应。

写入流程通常分为三步：第一步从 SQLite 读取新增或修改的记录，可以通过 updated_at 字段筛选出上次同步之后变化的数据；第二步将每条记录转换为 Tantivy 的 Document 并加入 IndexWriter；第三步调用 commit 提交索引变更。删除操作也需要同步，Tantivy 提供了按 term 删除的接口，可以先构造 Term::from_field_u64(id_field, article_id)，再调用 writer.delete_term(term)。

查询时先构造 Searcher，使用 QueryParser 解析用户输入。TopDocs::with_limit(10) 可以返回评分最高的十条结果，每条结果包含 DocAddress 和 score。通过 searcher.doc(doc_address) 读取文档，取出 id 字段，再拼接 SQL 的 IN 子句回到 SQLite 查询完整记录。由于 IN 子句返回的顺序不一定与 Tantivy 的评分排序一致，需要在应用层用 HashMap 或按 id 重新排序，确保搜索结果按相关度显示。

这种设计的一个关键点是增量同步。如果文章数量不大，可以在每次启动时全量重建索引，简单可靠。但当数据频繁更新时，最好维护一个 sync_state 表记录上次同步时间戳，然后按批次读取变化记录。为了避免同步过程中出现新写入导致遗漏，可以把读取 SQLite 和记录时间戳放在同一个事务中，或者采用 updated_at > last_sync 配合合理的时间窗口。

核心代码实现

下面给出一个最小可运行的 Rust 示例。首先在 Cargo.toml 中声明依赖：

[dependencies]
rusqlite = { version = "0.31", features = ["bundled"] }
tantivy = "0.22"
tantivy-jieba = "0.11"

接着构建 schema 和索引目录。这里使用 tantivy-jieba 作为中文分词器，通过 TextTokenizer 注册到字段上：

use tantivy::schema::{Schema, IndexRecordOption, TextOptions, TextFieldIndexing};
use tantivy::tokenizer::TextAnalyzer;
use tantivy::{doc, Index, IndexWriter};
use tantivy_jieba::JiebaTokenizer;
use std::path::Path;

fn create_index(index_path: &str) -> tantivy::Result<(Index, IndexWriter)> {
    let mut schema_builder = Schema::builder();
    let id_field = schema_builder.add_u64_field("id", tantivy::schema::INDEXED | tantivy::schema::STORED);
    let text_indexing = TextFieldIndexing::default()
        .set_tokenizer("jieba")
        .set_index_option(IndexRecordOption::WithFreqsAndPositions);
    let text_options = TextOptions::default()
        .set_indexing_options(text_indexing)
        .set_stored();
    let title_field = schema_builder.add_text_field("title", text_options.clone());
    let body_field = schema_builder.add_text_field("body", text_options);
    let schema = schema_builder.build();

    let index = Index::create_in_dir(Path::new(index_path), schema.clone())?;
    let tokenizer = JiebaTokenizer::new();
    index.tokenizers().register("jieba", tokenizer);
    let writer = index.writer(50_000_000)?;
    Ok((index, writer))
}

在上面的代码里，INDEXED | STORED 表示 id 字段既参与倒排索引也保存原始值。文本字段通过 set_tokenizer("jieba") 指定中文分词器，WithFreqsAndPositions 会记录词频和位置信息，便于后续短语查询和高亮。索引写入器分配了 50 MB 内存缓冲区，数值可以根据实际机器内存调整。

把 SQLite 中的记录写入索引的函数可以这样实现：

use rusqlite::Connection;
use tantivy::schema::Value;
use tantivy::Term;

fn sync_articles(conn: &Connection, writer: &IndexWriter, id_field: tantivy::schema::Field, title_field: tantivy::schema::Field, body_field: tantivy::schema::Field) -> tantivy::Result<()> {
    let mut stmt = conn.prepare("SELECT id, title, body FROM articles")?;
    let rows = stmt.query_map([], |row| {
        Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?, row.get::<_, String>(2)?))
    })?;
    for row in rows {
        let (id, title, body) = row?;
        writer.delete_term(Term::from_field_u64(id_field, id as u64));
        writer.add_document(doc!(
            id_field => id as u64,
            title_field => title,
            body_field => body
        ))?;
    }
    writer.commit()?;
    Ok(())
}

这里每次同步先按主键删除旧文档，再添加新文档，确保修改不会残留旧索引。删除操作使用 Term::from_field_u64 精确匹配主键字段。如果文章数量很大，全量同步会较慢，可以改用增量查询并只处理变化记录。需要注意的是 writer.commit() 会触发段合并和磁盘写入，频繁调用会影响性能，实际项目中可以每处理 500 条记录提交一次，或者在定时任务中统一提交。

查询部分的核心逻辑如下：

use tantivy::collector::TopDocs;
use tantivy::query::QueryParser;
use tantivy::{Searcher, Index};

fn search(index: &Index, query_str: &str, id_field: tantivy::schema::Field) -> tantivy::Result<Vec<u64>> {
    let reader = index.reader()?;
    let searcher: Searcher = reader.searcher();
    let query_parser = QueryParser::for_index(&index, vec![id_field, index.schema().get_field("title")?, index.schema().get_field("body")?]);
    let query = query_parser.parse_query(query_str)?;
    let top_docs = searcher.search(&query, &TopDocs::with_limit(20))?;
    let mut ids = Vec::new();
    for (score, doc_address) in top_docs {
        let retrieved = searcher.doc(doc_address)?;
        if let Some(id_value) = retrieved.get_first(id_field) {
            if let Some(id_num) = id_value.as_u64() {
                ids.push(id_num);
            }
        }
    }
    Ok(ids)
}

查询解析器默认会在 title 和 body 两个字段中搜索。返回结果按 BM25 评分降序排列，每个文档通过 searcher.doc 取出存储字段。拿到主键集合后，可以构造 SELECT * FROM articles WHERE id IN (?, ?, ...) 回查 SQLite。如果结果需要保持评分顺序，可以在 SQL 查询后按返回的 id 列表重新排序，而不是依赖数据库返回顺序。

索引维护与性能调优

索引维护中最常见的问题是同步延迟。写入 IndexWriter 后如果没有及时 commit，reader 可能读不到新文档，因为 Tantivy 的 reader 默认只在重新加载时看到已提交的段。可以通过定时调用 reader.reload() 来刷新视图。对于更新频繁的场景，建议把 commit 放到批量任务末尾，而不是每条记录后都提交，这样可以把多次磁盘写入合并为一次，显著提升吞吐。

内存方面，index.writer(50_000_000) 中的参数表示写入器可用的内存预算，单位是字节。写入文档时，Tantivy 会先把数据写入内存中的段，当内存占用达到阈值后再刷新到磁盘。如果内存设置过小，会频繁产生小段，增加后续合并开销；如果设置过大，可能导致进程内存峰值过高。对于普通文章检索项目，32 MB 到 128 MB 是相对合适的范围。

段合并策略也会影响查询性能。Tantivy 后台会自动合并小段，但可以在创建索引时通过 IndexSettings 调整合并策略。例如设置 merge_policy 使用 LogMergePolicy 并指定最大段大小，避免单个段过大导致查询延迟。SQLite 方面，确保主键索引存在，id 字段本身有主键约束，但 IN 子句中的参数数量不要过多，一般控制在几百个以内。如果搜索结果需要跨多个关键词，Tantivy 的布尔查询会返回并集，回查 SQLite 时可以分批处理，降低单条 SQL 的复杂度。

一致性是另一个需要关注的工程问题。如果 SQLite 中删除了记录，但 Tantivy 索引没有同步删除，用户会搜索到已经不存在的内容。解决方式可以是在应用层维护一个 deleted 标记或使用外键触发器记录变更日志。分布式场景下也可以采用 outbox 模式，把变更事件写入 SQLite 的一张队列表，后台任务消费队列并同步到 Tantivy。这样即使索引暂时落后，也能通过重放队列最终一致。

当索引目录和 SQLite 文件需要一起迁移时，建议把两者放在同一个父目录下，压缩打包后一并拷贝。由于 Tantivy 索引可以直接由 SQLite 数据重建，备份时也可以只备份 SQLite 文件，恢复后再运行一次全量同步。对于需要高可用的服务，还可以使用 tantivy 的 reader 多线程并发搜索，但写入端需要保持单写，避免两个 IndexWriter 同时操作同一个索引目录。

SQLite全文检索TantivyRust修改时间：2026-09-23 17:47:22