为什么是 tantivy

主线位置：三条主线的外面。本页回答全文检索要解决什么、tantivy 替你做了哪些、留给你的是什么；它和 Lucene 的概念怎么对应；和几种常见的全文检索方案比，差别落在哪里；最后是 ARCHITECTURE.md 写的设计原则在代码里的样子。

flowchart TB
  app["你的程序"] --> w["IndexWriter 写入"]
  app --> s["Searcher 查询"]
  w --> segs["不可变段"]
  w --> meta["meta.json"]
  s --> segs
  segs --> dir["Directory mmap"]
  qw["Quickwit 等服务"] --> app

全文检索要解决什么

ARCHITECTURE.md 开头给的问题是：「Given a large set of textual documents, and a text query, return the K-most relevant documents in a very efficient way.」要快，就得事先建索引；要「最相关」，就得有打分。tantivy 的答案是倒排索引加 BM25：每个词对应一张「包含它的文档」的表，查询时只看查询里那几个词的表，用 BM25 算分，取前 K 个。一次查询里，old man 在三篇文档里只碰了两张表，explain 把分数拆到了每一项。

它的范围不止于此。同一份文档还可以存进按列存储的快速字段（fast field），用来排序、过滤、按值聚合；ARCHITECTURE.md 举的例子是电商的分面计数、房产网站的每平米均价，甚至「use tantivy to power an OLAP database」。src/ 里最大的目录是 aggregation/（36320 行），比查询本身还大，见源码地图。

库，不是服务

README 的定位很直接：「Tantivy is closer to Apache Lucene than to Elasticsearch or Apache Solr in the sense it is not an off-the-shelf search engine server, but rather a crate that can be used to build such a search engine.」doc/src/avant-propos.md 的说法是「Library means that you will have to write code」。落到依赖上：

• 没有网络层。cargo tree -p tantivy@0.27.0 里没有 HTTP 库，也没有 tokio。你在自己的进程里调 IndexWriter::add_document、Searcher::search。
• 没有分布式。README 的 Non-features 一节写着「Distributed search is out of the scope of Tantivy」，指向建在它上面的 Quickwit。多个索引怎么分片、怎么合并结果，是上层的事。
• 同步 API，自己管线程。写入用标准库线程和 crossbeam-channel，后台任务用 rayon，一次写入列出了 writer() 之后进程里的全部 9 个线程。放进 async 程序时，要自己把调用挪到阻塞线程池里。
• 扩展点是 trait。avant-propos.md 说要扩展功能「most frequently this will mean writing your own Collector, your own Scorer or your own TokenFilter」。对应的 trait 是 Collector、Scorer、tantivy-tokenizer-api 的 Tokenizer/TokenFilter，以及存储层的 Directory；0.27.0 又加了 SegmentPlugin，可以往段里加自己的文件。

本站的站内搜索就是这样用它的：搜索模块在自己的进程里建一个 MmapDirectory 索引，分词器换成 tantivy-jieba，见 08 在本站中。

和 Lucene 的对应

ARCHITECTURE.md 说 tantivy「is by no means a port of Lucene, its architecture is strongly inspired by it」，读过 Lucene 的人会发现名词几乎一样：

能从 tantivy 这一侧核实的差别有三处：

• schema 是严格的，而且一对一。 Schema 在建索引时定下，存进 meta.json，每个字段的类型和索引方式固定。ARCHITECTURE.md 的 Limitations 写明「tantivy's schema imposes a 1:1 relationship between a field that is being ingested and a field represented in the search index」：同一段文本想用两种分词器各索引一次，要自己复制成两个字段。
• 文件是切片，不是流。 ARCHITECTURE.md：「Contrary to Lucene however, "files" are quite different from some kind of io::Read object.」Directory::open_read 返回 FileSlice，读出来是 OwnedBytes；doc/src/basis.md 承认这个 trait「somewhat assumes that your data can be mapped to memory」，缓存全交给操作系统。见 Directory。
• 没有主键，也没有 update。 删除只能按 Term（或者按查询，delete_query 在文档里是隐藏的），ARCHITECTURE.md：「Tantivy does not offer any notion of primary id」。更新一篇文档就是先 delete_term 再 add_document；IndexWriter::run 能把一个 Delete 和一个 Add 放进同一批、拿到连续的 opstamp，但仍是一删一增两个操作。见提交和 06 设计取舍。

README 还有一句「Tantivy is approximately 2x faster than Lucene」，依据是外部的基准测试仓库，本卷离线核实不了，不引用这个数字。

和其他全文检索方案比

这张表只列形态上的差别，不比快慢：不同方案的基准结果取决于语料、查询和部署，本卷没有可复现的对比数据。从形态上看选择大致是：已经有 SQLite 或 PostgreSQL、数据量不大、要事务一致，就用数据库自带的全文检索；要一个开箱即用、带 HTTP 接口的服务，就用 meilisearch 或 Elasticsearch；要把检索嵌进自己的 Rust 程序、控制分词、打分和收集的每一步，或者要自己搭一个搜索服务，用 tantivy。

设计原则：内存有上界

ARCHITECTURE.md 列了三条原则：

• 「Search should be O(1) in memory.」
• 「Indexing should be O(1) in memory. (In practice it is just sublinear)」
• 「Search should be as fast as possible」

紧接着是代价：「This comes at the cost of the dynamicity of the index: while it is possible to add, and delete documents from our corpus, the tantivy is designed to handle these updates in large batches.」

在代码里，写入一侧的上界是每个索引线程的内存预算。index_documents 每处理完一批就检查一次：

        let mem_usage = segment_writer.mem_usage();
        if mem_usage >= memory_budget - MARGIN_IN_BYTES {
            debug!(
                "Buffer limit reached, flushing segment with maxdoc={}.",
                segment_writer.max_doc()
            );
            break;
        }

到了预算就把当前段写到磁盘，换一个新段，内存池从头开始。所以写入的内存跟预算走，不跟语料走。实验 bulk 用一个索引线程、15 MB 预算，把 wiki.json 的 1000 篇重复 k 次写入，一次提交（release，/usr/bin/time -l 的最大常驻内存）：

docs=5000 text_bytes=5348365 segments=4
            33292288  maximum resident set size
docs=20000 text_bytes=21393460 segments=2
            67911680  maximum resident set size
docs=80000 text_bytes=85573840 segments=8
            75251712  maximum resident set size
docs=160000 text_bytes=171147680 segments=8
           132464640  maximum resident set size

文本从 5 MB 涨到 171 MB（32 倍），最大常驻内存从 33 MB 涨到 132 MB（4 倍）。不是常数：后台合并线程要打开参与合并的段，已经写出的段 mmap 进来以后，被读到的页也算进常驻内存。这就是括号里那句「In practice it is just sublinear」。

查询一侧没有「把索引加载进来」这一步：段文件 mmap 进来，用到哪页读哪页；TopDocs 只留一个大小为 K 的堆；文档存储每个段最多缓存 100 个解压过的块（DOCSTORE_CACHE_CAPACITY）。一个段末尾实测了打开一个小索引到拿回第一篇原文的耗时，热缓存下在 1 ms 以内。

代价那一半落在一次写入里：三篇文档要等 commit 才能被查到，每次提交至少写一个段、六个文件，并同步改写 meta.json；一篇一提交的用法会留下一堆小段。批量写入、批量提交，是这套设计期待的用法。

小结

• tantivy 解决的是「从大量文档里快速找出最相关的 K 篇」，用倒排索引加 BM25；快速字段和聚合让它也能做过滤、排序和统计。
• 它是库：没有网络层、没有分布式、没有 tokio，同步 API，扩展点是 Collector、Scorer、Tokenizer、Directory、SegmentPlugin 这些 trait；服务形态是 Quickwit 这样的上层项目。
• 名词几乎都能对上 Lucene：段、IndexWriter、Query/Weight/Scorer、Collector、DocValues 对快速字段、stored fields 对文档存储、norms 对 fieldnorm；差别在严格的一对一 schema、FileSlice 而不是流、没有主键和 update、BM25 参数写死。
• 和 SQLite FTS5、PostgreSQL 全文检索、meilisearch、Elasticsearch 的差别在形态（库还是服务、嵌在数据库里还是独立）、存储位置和打分方式；本卷不比快慢。
• 设计原则是内存有上界：写入按每线程预算切段，实测文本涨 32 倍、常驻内存涨 4 倍；查询直接读 mmap。代价是更新要成批，提交后才可见。