怎么读这一卷

主线位置：三条主线的总览。本页把写入、查询、磁盘三条主线各拆成几步，标出每一步落在哪个函数、哪一页讲它；再说明实验环境，哪些数字随核数变化；最后逐个核对 Cargo.toml 里的 feature，其中 quickwit 会换掉词典的格式，用它写的索引在默认构建下打得开、一查就报错。一次写入、一次查询和一个段在本机上把三条线各跑一遍。

flowchart TB
  start[从这里开始] --> q{读这一卷为了什么}
  q -->|会用| use1["01 全景 再到 05"]
  q -->|读懂实现| all[00 到 09 按顺序]
  q -->|只关心写入| w["一次写入 再到 03"]
  q -->|只关心格式| d["一个段 再到 04"]

锁定版本

tantivy 的仓库是一个 Cargo 工作区：主 crate tantivy 在根目录，九个子 crate（columnar、sstable、stacker、bitpacker、common、ownedbytes、query-grammar、tokenizer-api、jitexpr）在各自的目录里。它们一起打 tag，但版本号不统一。本卷锁 0.27.0：

源码链接一律指向 tag：https://github.com/quickwit-oss/tantivy/blob/0.27.0/<路径>#L<行>，行号是条目开始的那一行。子 crate 的路径在同一个仓库里，如 stacker/src/memory_arena.rs。

仓库里有 README.md、ARCHITECTURE.md、CHANGELOG.md、doc/src/ 下一本没写完的小书和 examples/ 下 23 个例子。本卷把它们当资料读，引用前在源码或实验里核实。举一个例子：Index::writer 的文档说锁文件已存在时返回 Error::FileAlreadyExists，0.27.0 里没有这个变体；在同一个目录上开第二个 writer，实测得到的是：

second writer: Failed to acquire Lockfile: LockBusy. Some("Failed to acquire index lock. If you are using a regular directory, this means there is already an `IndexWriter` working on this `Directory`, in this process or in a different process.")

而且锁文件 .tantivy-writer.lock 在 writer 释放之后还留在目录里：MmapDirectory::acquire_lock 用的是 flock，锁在文件句柄关闭时释放，文件本身不删。directory_lock.rs 里「This lock file, when present, is in charge of preventing other processes...」的说法对 MmapDirectory 不成立，看文件在不在判断不了有没有 writer。

三条主线

写入主线：加 3 篇文档，提交一次

flowchart TB
  create["create_in_dir"] --> writer["Index writer 起线程"]
  writer --> add["add_document 打 opstamp"]
  add --> ch["有界 channel"]
  ch --> sw["SegmentWriter 进内存池"]
  sw --> pc["prepare_commit 收段"]
  pc --> fin["finalize 写六个文件"]
  fin --> su["SegmentUpdater 写 meta"]
  su --> gc["GC 与考虑合并"]

查询主线：old man，取前 10

flowchart TB
  rd["IndexReader"] --> se["Searcher 快照"]
  se --> qp["QueryParser 解析"]
  qp --> wt["query weight 算 BM25 统计"]
  wt --> seg["每段 Scorer"]
  seg --> col["TopDocs 剪枝收集"]
  col --> mg["合并各段"]
  mg --> doc["searcher doc 取原文"]

磁盘主线：一个词怎么找到

三条线在 SegmentReader 交汇：写入主线生产段，磁盘主线说明段长什么样，查询主线在每个段上各跑一遍再合并。

实验环境

所有实验都只在 macOS 上做。会随机器变化的数字页面上会注明：

• Index::writer(budget) 的索引线程数是 min(核数, 8) 再受预算限制，本机 writer(50_000_000) 是 3 个，writer(200_000_000) 是 8 个；同样 3 篇文档，提交后的段数就是拿到文档的线程数，见一次写入。
• 文件大小、meta.json 里的段 UUID 每次运行都不同；目录清单和 meta.json 引用的都是同一次运行的原样输出。
• 计时受并行跑的其他实验影响，页面上的耗时都注明次数和取法。

feature 各打开什么

Cargo.toml 的 [features] 一共 11 个，默认开前五个：

sstable、fail、memmap2 这些不在 [features] 里的名字也能写进依赖方的 features：它们是可选依赖自动生成的同名 feature。卷目录里「sstable feature 下的另一种词典」的说法不对：termdict/mod.rs 按 quickwit 选择 fst_termdict 还是 sstable_termdict，src/ 里没有一处 cfg(feature = "sstable")。只开 sstable 等于什么都没换。

quickwit 写的索引，默认构建读不了

实验 intro-qw 开 features = ["quickwit"]，用一个线程写一篇文档、提交；然后用默认 feature 的 intro-run 打开同一个目录，按一次查询的方式查 old man（release）：

written with quickwit: tantivy v0.27.0, index_format v7
segments: 1
  seg 0: e6e7ce4fc00c41f0b992146dae1fcd89 max_doc=1
query: BooleanQuery { subqueries: [(Should, TermQuery(Term(field=0, type=Str, "old"))), (Should, TermQuery(Term(field=1, type=Str, "old"))), (Should, TermQuery(Term(field=0, type=Str, "man"))), (Should, TermQuery(Term(field=1, type=Str, "man")))], minimum_number_should_match: 1 }
Error: IoError(Custom { kind: Other, error: "Unsupported dictionary type, compiled tantivy with Fst, but got SSTable" })

两边的 version_string() 一样，index_format 都是 7，meta.json 里也没有任何字段记录词典的类型；Index::open_in_dir、建 reader、拿 searcher 都成功，第一次读某个字段的词典时才报错。原因在 TermDictionary::open：每个字段的词典末尾 4 字节是一个 u32 类型号（DictionaryType::Fst = 1、SSTable = 2），打开时和编译期的 CURRENT_TYPE 比较，不同就报上面这条错。如果在依赖图的某处有 crate 开了 quickwit，feature 统一会让整个程序换成 sstable 词典，此前写的索引就都不能查了。

不讲什么

• jitexpr 子 crate（15605 行）：只在聚合提一句。
• SegmentPlugin 的自定义扩展：0.27.0 起三个内置组件（倒排索引、快速字段、文档存储）本身就是用这个 trait 写的，一次写入和一个段会讲到这一层；怎么写一个自定义插件不讲。
• quickwit feature 下的 sstable 词典和异步接口：词典对照一句。
• 聚合的各个类型、failpoints 测试、compare_hash_only、Windows 上的差异。

阅读路线

• 只想会用：01 全景 的四页；Schema 与字段、分词；提交；IndexReader 与 Searcher、查询解析器、收集器。
• 想读懂实现：按顺序读。02 讲清楚一篇文档变成哪些 Term，03 讲清楚它们怎么进内存池、怎么写成段，04 的格式才好读；05 在 04 的格式上跑。
• 只关心写入：一次写入 → IndexWriter → SegmentWriter 与内存池 → 提交 → 合并。
• 只关心磁盘格式：一个段 → Directory → 词典 → 倒排表 → 位置 → 文档存储 → 快速字段 → fieldnorm 与删除位图。

前置知识

• 倒排索引：词 → 包含它的文档列表（倒排表，posting list）；词典（term dictionary）负责从词找到倒排表。
• BM25 的大意：词在文档里出现得越多、在整个语料里越少见、文档越短，分越高。公式在 BM25 里逐项对代码。
• Rust：trait 对象、Send/Sync、Arc；标准库线程和 channel。tantivy 不依赖 tokio，cargo tree -p tantivy@0.27.0 里没有它；写入用自己的线程和 crossbeam-channel，SegmentUpdater、合并和多线程查询用 rayon 线程池。
• mmap：文件映射进地址空间，读多少由操作系统按页调入。tantivy 的读路径几乎都建立在这上面。
• 读过 serde 卷 会帮助理解 文档 一页，读过 bytes 卷 会帮助理解 OwnedBytes。

小结

• 锁 tag 0.27.0（67889269c），crates.io 包就是这个 commit；子 crate 版本号不统一；0.26.x 是另一条分支；之后 main 上的 7 个提交不跟。
• 写入主线：create_in_dir → writer 起线程拿锁 → add_document 打 opstamp 进 channel → SegmentWriter → prepare_commit 收段、定稿 → SegmentUpdater 落删除、写 meta.json、GC、考虑合并。
• 查询主线：reader → Searcher 快照 → QueryParser 默认 OR → weight 用全局统计 → 每段 Scorer，TopK 走 Block-Max WAND → 合并 → doc 解压原文。
• 磁盘主线：footer → .term → .idx → .pos → .fieldnorm → .store → .fast。
• 默认 feature 是 mmap、stopwords、lz4-compression、columnar-zstd-compression、stemmer；换词典格式的是 quickwit 不是 sstable，quickwit 写的索引在默认构建下查询时报 Unsupported dictionary type。
• 锁文件 .tantivy-writer.lock 是 flock，文件会一直留着；第二个 writer 报 LockBusy，不是文档说的 FileAlreadyExists。