Apache Lucene 全文搜索引擎库深度详解

版本: Apache Lucene 10.x（2026 年主线版本）
更新日期: 2026-07-20
涵盖主题: 倒排索引原理、段与合并策略、分析器与 Tokenizer、查询解析、向量检索（HNSW）、性能调优、生产级实战
面向读者: 搜索引擎开发者、Elasticsearch / Solr 二次开发者、对底层信息检索原理感兴趣的后端工程师

第零章为什么你必须读懂 Lucene

如果你曾经用过 Elasticsearch、Solr、OpenSearch，甚至基于 Lucene 自研搜索中台，那么你已经在「间接调用 Lucene」。Lucene 是上述所有搜索平台的「内核」——它不是一个开箱即用的搜索服务，而是一个 搜索引擎库（Search Engine Library），由 Doug Cutting 于 1997 年创建，2001 年捐献给 Apache 基金会。今天，它是全球范围内事实上的全文检索基础设施。

为什么单独学 Lucene？

理解「为什么 ES 这么设计」：ES 的 segment、merge、refresh、flush 全部源自 Lucene 概念；不懂 Lucene 就只能在 DSL 层面打转，遇到 GC、IO、写入抖动等问题无从下手。
构建轻量级搜索能力：不需要起一个 32GB 的 ES 集群，单进程 Lucene 即可支撑百万级文档搜索，适合嵌入式场景、IDE 搜索、桌面搜索（如 Obsidian 的全文检索）。
向量检索时代的基础：Lucene 10 已原生支持 HNSW + 量化（量化由 9.0 起加入），是当前很多 RAG / Embedding 检索方案中性价比最高的底层选项之一。

本文将按照「概念 → 架构 → 模块 → 实战 → 调优 → 生态」的顺序展开，力求把 Lucene 的知识体系讲清楚、讲透。

第一章 Lucene 概览与核心概念

1.1 Lucene 是什么

Apache Lucene 是一个用 Java 编写的高性能、功能齐全的全文搜索引擎库，其核心特征如下：

维度	描述
定位	搜索引擎库，而非搜索服务；没有 HTTP API、没有分布式协调，需要应用层封装
语言	Java（核心），通过 PyLucene、Lucene.NET 提供多语言绑定
索引格式	自定义二进制格式（Postings、DocValues、Terms、Vector 等），跨平台一致
许可证	Apache License 2.0，可商业闭源使用
主要能力	倒排索引、向量检索、近实时搜索、高亮、拼写纠正、分词、地理检索
不提供	分布式、副本、集群管理、HTTP API、安全认证

与 ES/Solr 的关系：Elasticsearch 在 Lucene 之上添加了：集群管理（基于 Discovery）、副本（基于 Cluster State）、HTTP/REST、脚本引擎、安全（RBAC）、SQL/ES|QL、ML 等；Solr 在 Lucene 之上添加了：分布式（SolrCloud）、Schema、Facet、HTTP API。Lucene 是它们的「单机内核」。

1.2 一次搜索的完整链路

理解 Lucene 最有效的方式，是跟踪一次「写入 + 搜索」全过程。下面是一个高层的调用链：

文档对象 Document
      │
      ▼ IndexWriter.addDocument()
分词器 Analyzer（Tokenizer + TokenFilter 链）
      │
      ▼ Token 流 TokenStream
倒排构建 IndexingChain（含 PostingList / DocValues / StoredFields / Vectors）
      │
      ▼
内存缓冲区 DocumentsWriterPerThread (DWPT)
      │  (达到 flush 阈值)
      ▼
新生段 Segment → 写入 Directory (磁盘文件)
      │
      ▼ (后台 MergePolicy)
段合并 MergeScheduler，合并多个段为一个更大的段
      │
      ▼
IndexReader (DirectoryReader / SearcherManager) 打开段集合
      │
      ▼ 用户查询 Query
QueryParser 解析 → Query 树
      │
      ▼ IndexSearcher.search()
Weight → Scorer → BulkScorer (基于跳表/SIMD 加速)
      │
      ▼ TopDocs (命中文档 id + score)
StoredFieldsVisitor 读取原文 → 返回给调用方

这条链路上的每一个节点都是 Lucene 的核心模块，本文后续章节会逐一拆解。

1.3 关键术语速查

术语	含义
Document	索引与检索的逻辑单元，由若干 Field 组成
Field	字段，例如 title / body / tags；字段类型决定如何被索引
Analyzer	分词器，由 Tokenizer（切词）+ TokenFilter（规范化）组成
TokenStream	分词产生的 token 序列，是 Lucene 处理文本的核心数据结构
Term	字段名 + 词项文本，是倒排索引的最小索引单元
Inverted Index	倒排索引：Term → Postings List（docId 列表 + 词频 + 位置）
Segment	不可变的索引片段，单次 flush 产出，可被独立搜索
SegmentInfos	记录所有段元信息的「提交点」(`segments_N` 文件)
Commit Point	一个 segments_N 文件，代表一个可恢复的索引快照
Directory	对底层存储的抽象（FSDirectory / RAMDirectory / MMapDirectory）
IndexWriter	写入入口，单线程或多线程共享，负责段生命周期
IndexReader	读取入口，对应一个提交点的所有段
IndexSearcher	搜索入口，封装 IndexReader + 执行策略
QueryParser	将查询字符串解析为 Query 树
Scorer	在文档集上迭代并打分的迭代器
Similarity	相关性算法（BM25 / LM / DFR 等）
DocValues	列式存储，用于排序、聚合、脚本访问
Stored Fields	行存原文，用于返回搜索结果
Term Vectors	每个文档的词项明细，用于高亮、MoreLikeThis

理解这些术语后，后续章节就是把这些词填进架构图里。

第二章整体技术架构

2.1 模块分层

Lucene 的源码组织（org.apache.lucene）反映了清晰的分层：

┌────────────────────────────────────────────────────────┐
│                  应用层 (ES / Solr / 自研)             │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Search 层                              │
│  IndexSearcher / QueryParser / Collector / Highlighter  │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Query 层                               │
│  BooleanQuery / TermQuery / PhraseQuery / BlendedQuery  │
│  / KnnVectorQuery / MultiTermQuery (Regex / Fuzzy)      │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Reader 层                              │
│  IndexReader / SegmentReader / DocValues / Fields       │
│  / StoredFields / TermVectors                          │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Writer 层                              │
│  IndexWriter / DocumentsWriterPerThread                │
│  / IndexingChain / FlushPolicy / MergePolicy           │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Format 层 (Codec)                     │
│  Lucene Codec / PostingsFormat / DocValuesFormat       │
│  / KnnVectorsFormat / StoredFieldsFormat               │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Store 层 (Directory)                  │
│  MMapDirectory / FSDirectory / ByteBuffersDirectory    │
│  / NIOFSDirectory / RAMDirectory (deprecated)          │
└────────────────────────────────────────────────────────┘
                          ▲
┌────────────────────────────────────────────────────────┐
│                  Analysis 层 (分词)                    │
│  Analyzer / Tokenizer / TokenFilter / CharFilter       │
└────────────────────────────────────────────────────────┘

每一层只依赖下一层，自上而下职责递减：Codec 决定「怎么写」，Directory 决定「写到哪」，Analysis 决定「写入前如何处理文本」，Writer/Reader 在 Codec 与 Directory 之上提供「写入 / 读取」入口，Query 与 Search 层封装查询语义。

2.2 包结构总览

Lucene 10 的 Maven 模块划分（与 lucene-* 子工程一一对应）：

模块	作用
`lucene-core`	倒排索引、段管理、Directory、基础 Codec、Similarity、IndexWriter/Reader/Searcher
`lucene-analysis-common`	通用分析器：Standard / Whitespace / Stop / Keyword / Synonym 等
`lucene-analysis-nku` / `-smartcn` / `-icu`	中文分词、ICU 规范化等
`lucene-queryparser`	经典 QueryParser、MultiFieldQueryParser、Surround / ComplexPhrase
`lucene-queries`	常用查询（MoreLikeThis、BoostingQuery、FallbackQuery）
`lucene-facet`	分面计数（DrillDown / DrillSideways）
`lucene-highlighter`	高亮（FastVectorHighlighter / UnifiedHighlighter）
`lucene-suggest`	拼写纠正、自动补全（FST / Levenshtein）
`lucene-spatial` / `lucene-spatial-extras`	地理检索（基于 RPT / LatLonShape）
`lucene-expressions`	基于 JavaScript 表达式的动态评分
`lucene-grouping`	二级聚合分组
`lucene-join`	嵌套文档 / BlockJoin
`lucene-backward-codecs`	跨版本读取旧索引（升级索引时使用）
`lucene-codecs`	实验性 Codec（Lucene90/91/… 系列）
`lucene-monitor`	反向搜索：预编译大量 Query，对每篇新文档匹配（用于订阅告警）

2.3 写入与读取的对称性

Lucene 的设计有一个贯穿始终的原则：写入侧与读取侧对称。每种字段类型，写入侧有 Consumer，读取侧有对应的 Values / Terms / PostingsEnum：

写入侧	读取侧	用途
`InvertedDocConsumer`	`TermsEnum` / `PostingsEnum`	倒排索引
`DocValuesConsumer`	`NumericDocValues` / `SortedDocValues`	列式存储
`StoredFieldsWriter`	`StoredFieldsReader`	原文回查
`TermVectorsConsumer`	`TermsEnum` (per-doc)	文档词项明细
`KnnVectorsWriter`	`KnnVectorsReader`	向量索引
`NormsConsumer`	`NumericDocValues`（norms）	字段权重（BM25 norm）
`PointsWriter`	`PointValues`	数值范围 / 地理框

这种对称性让 Codec 升级时只要同时替换读写两端即可，对外部 API 几乎透明。

第三章核心数据结构：倒排索引

3.1 倒排索引的本质

正向索引：文档 → 词项列表（即我们存原文的形式）。给定文档，能快速拿到词项。
倒排索引：词项 → 文档列表。给定词项，能快速拿到所有包含它的文档。

全文搜索是「给一个词，找包含它的文档」，因此倒排索引是天然契合的。Lucene 的倒排索引并不只存「docId 列表」，它还存储了三个维度的信息：

词频（Term Frequency, TF）：每个文档中该词出现多少次。用于 BM25 打分。
位置（Positions）：词在文档中的位置序列。用于短语查询、距离查询。
偏移（Offsets）：词在原文中的起止字符位置。用于高亮。

这三种信息可以按需开关。例如只索引不计算位置的 IndexOptions.DOCS 占用最少；要支持短语查询需 DOCS_AND_FREQS_AND_POSITIONS；要支持高亮可再加 STORE_OFFSETS_IN_INDEX。

3.2 Lucene 的 PostingList 编码

PostingList 是倒排索引的核心，存储 (docId, freq, positions[], offsets[]) 的列表。Lucene 通过一系列压缩技巧将其压缩到极致：

3.2.1 PFor Delta

PFor Delta (Patched Frame of Reference) 是 Lucene 的 PostingList 默认编码（在 Lucene99PostingsFormat 中实现）。其核心思路：

Delta 编码：把 docId 序列 [3, 7, 9, 15, 20] 转为差值 [3, 4, 2, 6, 5]。
分块：每 128 个 delta 为一块（block）。
位宽选择：统计块内 90% 的值，选一个能覆盖它们的位宽 b。
异常值处理：剩下 10% 超过 b 位的值，单独存到异常区，原位置存一个标记。
SIMD 批量解压：b 位对齐后，可以用 SIMD 一次解压多个值。

这个算法把原本每 docId 至少 4 字节的存储压缩到平均 < 1 字节。

3.2.2 跳表 (SkipList)

倒排索引的另一个关键优化是跳表，用于快速跳过文档号。例如查询 title:Lucene AND body:codec：

title:Lucene 在文档号 [1, 5, 10, 100, 200, 500] 中出现
body:codec 在文档号 [3, 7, 100, 101, 500, 600] 中出现

朴素做法是双指针归并，但 body:codec 有 1 亿个 docId 时单步迭代代价极高。Lucene 在 PostingList 中每隔 skipInterval（默认 128 个 docId）建立一层跳表节点，存 (docId, blockOffset)。当 title:Lucene 的当前 docId 是 200，可以直接在 body:codec 中跳过到第一个 >= 200 的块，块级跳过。

Lucene99PostingsWriter 的跳表是多层（默认 10 层），每层间隔倍增，类似经典跳表。

3.3 Term Dictionary 与 Term Index

PostingList 按 Term 排序存储，但 Term 本身 在哪？Lucene 把 Term 分为两层：

┌────────────────────────────┐
│ Term Index (FST, .tip)     │  ← 内存常驻，前缀压缩
└─────────────┬──────────────┘
              │ 指向
              ▼
┌────────────────────────────┐
│ Term Dictionary (.tim)     │  ← 磁盘，按 Term 排序的块
└─────────────┬──────────────┘
              │ 指向
              ▼
┌────────────────────────────┐
│ Posting List (.doc/.pos)   │  ← 磁盘，压缩后的倒排
└────────────────────────────┘

Term Dictionary：所有 Term 按字典序分块存储，每块 128 个 Term。
Term Index：使用 FST (Finite State Transducer) 把 Term 前缀压缩为有穷状态机。FST 驻留内存，给定 Term 前缀，能定位到 Term Dictionary 中的某个块，再在块内扫描。

FST 的优秀之处：1 亿个 Term 的 Term Index 通常只占几十 MB 内存，远低于 HashMap。这就是为什么 ES 即使上亿级文档也能保持低延迟。

3.4 DocValues：列式存储

倒排索引擅长「给词找文档」，但很多场景需要反过来——给定文档，读某个字段值。例如：

排序：ORDER BY timestamp DESC
聚合：GROUP BY user_id
脚本：doc['price'].value * 0.9

倒排索引不擅长这种访问模式（要扫所有 Term）。Lucene 提供 DocValues 作为列式存储：

类型	含义
`NUMERIC`	单值数值（long / double）
`SORTED_NUMERIC`	多值数值（按值排序）
`SORTED`	单值字符串，按值字典序编码为 ord
`SORTED_SET`	多值字符串，按值字典序编码
`BINARY`	二进制字节流
`SORTED_BINARY`	多值二进制

DocValues 的存储格式（Lucene99DocValuesFormat）综合了：

Table 编码：当基数很小时，全 doc 共享一个查找表。
Delta + Bitpacked：当数值差值较小时，按位打包。
GCD Compression：当数值能整除某个最大公约数时，存 (value / gcd) 进一步压缩。
Block-Sorted：字符串值排序后，存 ord + 字典。

DocValues 默认开启，可用 docValuesType 字段属性控制。Elasticsearch 中 doc_values: false 即关闭，能省空间但不能用于排序聚合。

3.5 Stored Fields：行存原文

倒排、DocValues 都不存原文。返回搜索结果时，需要拿「标题、摘要、作者」等原文，这由 Stored Fields 提供，它是 行存（按文档组织），类似 LSM 的 SSTable。

格式（Lucene90StoredFieldsFormat）使用 LZ4 压缩 + 文档块（每 16 个文档一块），既支持按 docId 随机读，又能批量顺序读。

行存 vs 列存的取舍：

Stored Fields 适合「取少量字段，但每字段都有用」：返回搜索结果。

DocValues 适合「取大量文档的单个字段」：排序、聚合。

ES 的 index.photon.* 与 synthetic source（9.0 后）就是从 Stored Fields 切换到 DocValues 重构 source，节省 30%+ 存储。

3.6 Term Vectors

Term Vectors 是 每文档的 mini 倒排，记录「这个文档有哪些 Term、各自的位置与偏移」。主要用于：

高亮（FastVectorHighlighter）
MoreLikeThis（找相似文档）
跨文档的词项统计

Term Vectors 是可选的，默认不开（占空间），需要时显式声明 storeTermVectors=true。

3.7 Points：多维数值索引

Points 是基于 BKD Tree 的多维数值索引，支持：

一维数值范围查询（如 price IN [100, 200]）
二维/三维地理点查询
高维（<= 8 维）范围交集

LatLonShape 等地理字段类型底层也是 BKD。BKD 树把多维空间递归切分，叶子块存原始点，适合范围与相交查询，但不擅长 TopK 邻近查询（那需要 HNSW）。

3.8 Vector Index：HNSW 与量化

Lucene 9.0 起原生支持 向量检索，9.1 起作为稳定特性。10.x 进一步引入了 量化（Scalar Quantization） 与 积量化（Product Quantization），并在 10.0 起默认对 fp32 向量做 int8 量化。

维度	说明
算法	HNSW（Hierarchical Navigable Small World）
距离	EUCLIDEAN（L2）、COSINE、DOT_PRODUCT、MAXIMUM_INNER_PRODUCT
量化	int8 / int4 / int7 Scalar Quantization；Product Quantization（10.x）
存储	`.vec`（向量原值） + `.vex`（量化后的索引） + `.vemq`（量化剪枝）
算法调优	`M`（图连接度，默认 16）、`efConstruction`（构建时邻居候选数，默认 100）、`efSearch`（搜索时候选数，默认 50）

HNSW 的核心思想是 多层小世界图：底层包含所有点，每层往上节点数指数级减少。查询时从顶层稀疏图开始导航，逐层下降到底层，找到 TopK 近邻。Lucene 的实现还做了若干工程优化：

级别分层：节点级别满足几何分布，期望层数为 log(N)。
候选剪枝：通过距离比较剔除较远的候选邻居。
并发合并：合并段时使用分片并发构建 HNSW，加速大段合并。
过滤搜索：结合 HNSW 与 DocValues，支持「带条件 KNN」，比如「只在 status=published 的文档中搜索相似向量」。

// 向量索引示例
FieldType fieldType = KnnFloatVectorField.createType(768, VectorSimilarityFunction.COSINE);
fieldType.setVectorIndexOptions(VectorIndexOptions.HNSW_M(32, 200));  // M=32, efCtor=200
fieldType.setVectorDataOptions(VectorDataOptions.OFF);                // 不存原始 fp32，省空间

Document doc = new Document();
doc.add(new KnnFloatVectorField("embedding", vector, fieldType));

Lucene 10 的量化方案细节：

Scalar Quantization (SQ)：把 fp32 分桶到 int8/int7/int4，存储减为 1/4。距离计算时反量化为 fp32，使用 SIMD 加速。
Product Quantization (PQ)：把 d 维向量切成 d/M 段，每段独立聚类。10.x 提供 7-bit PQ 与 4-bit PQ 选项。配合 HNSW 时，先把所有向量量化，搜索时只在 TopN 候选中反量化精排。
Adaptive Quantization：Lucene 10 引入自适应量化，对每段数据自动选择 SQ 还是 PQ。

第四章写入路径详解

4.1 IndexWriter：唯一的写入入口

整个 Lucene 实例通常只有一个 IndexWriter（多写会有锁冲突）。它的核心职责：

接受文档添加/更新/删除请求。
分配文档号（global docId per segment per writer）。
控制段生命周期：flush、commit、merge。
维护 commit 点，提供原子可见性。

IndexWriterConfig 决定所有写入行为：

IndexWriterConfig config = new IndexWriterConfig(analyzer)
    .setOpenMode(IndexWriterConfig.OpenMode.CREATE_OR_APPEND)
    .setRAMBufferSizeMB(64.0)               // 内存缓冲上限
    .setMaxBufferedDocs(1000)               // 文档数上限（任一触发即 flush）
    .setRAMPerThreadHardLimitMB(64.0)        // 每线程缓冲上限
    .setCommitOnClose(false)                 // 是否在 close 时自动 commit
    .setMergePolicy(mergePolicy)
    .setMergeScheduler(mergeScheduler)
    .setIndexerThreadPool(new DocumentWrapperThreadPool(8))
    .setReaderPooling(true)
    .setCodec(Codec.getDefault());

4.2 DocumentsWriterPerThread (DWPT)

为了多线程并发写入，IndexWriter 内部维护了一个 DocumentsWriterPerThreadPool，每个写入线程绑定一个 DWPT：

IndexWriter
    │
    ▼
DocumentsWriter (单例，内部协调)
    │
    ├── DocumentsWriterPerThread (Thread-A)
    │       │
    │       ├── IndexingChain（构建倒排/DocValues/Stored/Vector 等）
    │       ├── StoredFieldsConsumer
    │       └── ByteSliceReader / ByteSliceWriter（分词缓冲）
    │
    └── DocumentsWriterPerThread (Thread-B)
            └── ...

每个 DWPT 持有自己的 IndexingChain，独立分词、独立建索引。线程内顺序处理，线程间不互锁——这是 Lucene 写入高吞吐的关键。

4.2.1 IndexingChain

IndexingChain 是 DWPT 内的索引构建管线：

Document
    │
    ▼
FieldHash → InvertedDocConsumer（倒排索引）
    │             │
    │             ├── TermsHash（Term → PostingList）
    │             ├── NormsConsumer（字段 norm）
    │             └── TermVectorsConsumer（可选）
    │
    ▼
StoredFieldsConsumer
    │
    ▼
DocValuesConsumer
    │
    ▼
KnnVectorsConsumer（若有向量字段）
    │
    ▼
PointsConsumer（若有数值字段）

每次添加文档，FieldHash 决定字段是否需要重新分词、是否进入下一个 Consumer。这是一条责任链模式。

4.3 Flush：从内存到段

当 DWPT 缓冲达到阈值（RAMBufferSizeMB 或 MaxBufferedDocs）时，触发 Flush，把当前 DWPT 的内存数据写成新段（一个不可变的 Segment）：

冻结 DWPT：停止接收新文档，等当前文档处理完。
写入段文件：按 Codec 顺序写出 .si、.cfe、.cfs、.fdt、.tim、.tip、.doc、.pos 等。
更新 SegmentInfos：把新段加入活跃段列表。
释放 DWPT：可被重新分配给其他线程（thread reuse）。

注意：flush 后段对搜索可见，需要新的 IndexReader 打开；如果不重新打开 IndexReader，仍是旧视图。这就是 ES 中「refresh」的本质—— refresh 触发 Lucene flush + 重新打开 reader。

4.4 Commit：提交点

commit() 与 flush() 不同：

flush：把内存数据写成段文件，但 segments_N 不变。
commit：先 flush 所有待写数据，然后写新的 segments_N，并通过 fsync 持久化。只有 commit 后索引在进程崩溃后仍可恢复。

ES 的 flush API 实际对应 Lucene 的 commit()。Lucene 用 Two-Phase Commit 保证 commit 原子性：

prepareCommit()：写 segments_N 的临时文件。
commit()：原子 rename + fsync，使 segments_N 正式生效。

4.5 段合并

4.5.1 为什么需要合并

段数过多：每个段对应一个 reader，搜索时要并行扫描所有段，段多会拖慢搜索。
删除堆积：删除标记在 segment 文件里不立即释放，合并可物理清除已删除文档。
空间放大：小段间有重复的元数据（如 Term Dictionary 头）。

合并策略由 MergePolicy 决定：

策略	适用场景
`TieredMergePolicy`（默认）	分层合并：小段优先合并，避免合并差不多大的大段。ES 默认
`LogByteSizeMergePolicy`	每段大小按对数因子合并
`LogDocMergePolicy`	按文档数而非字节数合并
`NoMergePolicy`	不合并，用于测试或冷数据归档

TieredMergePolicy 的关键参数：

参数	默认	含义
`maxMergeAtOnce`	10	一次最多合并多少段
`maxMergedSegmentBytes`	5GB	单段大小上限，超过即不再被合并
`segmentsPerTier`	10	每层最少段数，低于此即触发合并
`floorSegmentBytes`	2MB	小于此的段都视为 2MB 计算
`deletesPctAllowed`	20%	允许的删除堆积阈值，超过触发合并

4.5.2 合并调度器

MergeScheduler 控制如何执行合并任务：

ConcurrentMergeScheduler：用多个后台线程并发合并。默认。
SerialMergeScheduler：单线程顺序合并。
NoMergeScheduler：不执行合并（用于只读 / 测试）。

ConcurrentMergeScheduler 关键参数：

setMaxMergesAndThreads(maxMergeCount, maxThreadCount)：常见配置 (5, 2)，即最多 5 个待合并任务、2 个并发线程。让 IO 与 CPU 适度饱和但不过载。

合并过程中，搜索可继续访问旧段；合并完成后，旧段被替换为新段，新段对应的 reader 注册后旧段才被回收。

4.6 删除与更新

Lucene 中段不可变，删除是打标记：

删除按 Term：维护一个 BufferedDeletes，存 Term → Delete，查询时跳过命中文档。
删除按 Query：同样维护 BufferedDeletes，但 Query 删除只在段合并时真正生效（因为不能预先 enumerate）。
删除标记 存在 LiveDocs 中（位图），段合并时丢弃标记删除的文档。

updateDocument() 本质是 delete(term) + addDocument()，因此更新是「先删后加」，不保证原子（中间可见）。

第五章分析器与分词

5.1 Analyzer 的组成

Analyzer 是 Lucene 处理文本的入口。一个 Analyzer 由以下组件串联构成：

原文
  │
  ▼
CharFilter (可选，可多个)    ← 字符级处理（如 HTML 转义、音译）
  │
  ▼
Tokenizer (必需，单一个)     ← 切分为 token 流
  │
  ▼
TokenFilter (可选，可多个)   ← 逐 token 修改（小写化、停用词、同义词）
  │
  ▼
TokenStream → 倒排索引

关键原则：索引与查询必须用相同的 Analyzer（或者至少等价的 Analyzer），否则会出现「索引时小写化、查询时未小写」导致命中失败。

5.2 内置 Tokenizer

Tokenizer	切词规则
`StandardTokenizer`	基于 UAX#29 单词边界切分（默认）
`WhitespaceTokenizer`	空白字符切分
`KeywordTokenizer`	不切分，整体作为一个 token
`LetterTokenizer`	字母连续段
`NGramTokenizer`	n-gram 滑窗（前/后缀匹配）
`EdgeNGramTokenizer`	边缘 n-gram（自动补全）
`PathHierarchyTokenizer`	路径分层切分（适合文件路径）
`UAX29URLEmailTokenizer`	区分 URL / Email
`ClassicTokenizer`	老版本兼容，规则类似 Standard

5.3 常用 TokenFilter

Filter	作用
`LowerCaseFilter`	小写化
`StopFilter`	停用词过滤
`PorterStemFilter`	Porter 词干提取
`SynonymGraphFilter`	同义词扩展（图结构）
`WordDelimiterGraphFilter`	拆词（如 Wi-Fi → Wi, Fi）
`ASCIIFoldingFilter`	ASCII 化（café → cafe）
`NGramTokenFilter`	n-gram 拼接
`SnowballFilter`	多语种词干
`StopwordFilter`	停用词
`CJKWidthFilter`	CJK 全半角统一

5.4 中文分词

Lucene 内置中文相关分析器：

分析器	特点
`StandardAnalyzer`	对中文按字切分（一汉字一 token），简单但召回差
`SmartChineseAnalyzer`	基于隐马尔可夫模型，词质量一般，已较旧
`CJKAnalyzer`	二元切分，简单召回高
`ICUAnalyzer`	集成 ICU，支持 Unicode 规范化与分词
第三方：jieba-analysis、IKAnalyzer、HanLP-LP	国产开源中文分词，效果更好

中文分词的工程实践：

一致性原则：索引与查询必须用同一分词器，否则会「分词粒度不一致」。
混合分词：常用方案是 SmartChineseAnalyzer + 自定义词典，或 IK 的 ik_smart + ik_max_word 双分词。
同义词扩展：通过 SynonymGraphFilter 在索引侧或查询侧扩展，索引侧扩展存储大但查询快。
混合英数：对字母数字混合（如型号 ABC123），用 WordDelimiterGraphFilter 控制。

5.5 自定义 Analyzer

Lucene 允许组合任意 Tokenizer + Filter 链自定义 Analyzer：

Analyzer analyzer = new Analyzer() {
    @Override
    protected TokenStreamComponents createComponents(String fieldName) {
        Tokenizer tokenizer = new StandardTokenizer();
        TokenStream stream = new LowerCaseFilter(tokenizer);
        stream = new StopFilter(stream, StopFilter.ENGLISH_STOP_WORDS);
        stream = new PorterStemFilter(stream);
        return new TokenStreamComponents(tokenizer, stream);
    }

    @Override
    protected Reader initReaderForNormalization(String fieldName, Reader reader) {
        return new LowerCaseCharFilter(reader);  // 字段 norm 也要 lowercase
    }
};

也可以用 Lucene 9+ 的 AnalyzerWrapper + CustomAnalyzer（lucene-analyzers-common 提供的 Builder 模式）：

Analyzer analyzer = CustomAnalyzer.builder()
    .withTokenizer(StandardTokenizerFactory.NAME)
    .addTokenFilter(LowerCaseFilterFactory.NAME)
    .addTokenFilter(StopFilterFactory.NAME)
    .addTokenFilter(PorterStemFilterFactory.NAME)
    .build();

第六章查询语言与 Query 体系

6.1 Query 类层级

Lucene 把查询建模为 Query 类树。常用的：

Query	含义
`TermQuery`	单个词项查询
`BooleanQuery`	布尔组合（MUST/SHOULD/FILTER/MUST_NOT）
`PhraseQuery`	短语查询，要求多个 term 按序相邻
`MultiPhraseQuery`	多候选项短语
`FuzzyQuery`	模糊匹配（Levenshtein）
`RegexQuery`	正则匹配
`WildcardQuery`	通配符 `*?`
`PrefixQuery`	前缀
`RangeQuery`	范围（数值/字符串/日期）
`PointRangeQuery`	基于 BKD 的范围
`ConstantScoreQuery`	包裹一个 Query，使其分数固定
`BoostingQuery`	区分正负向
`BlendedTermQuery`	多字段加权
`BooleanWeight` / `DisjunctionMaxQuery`	跨字段 disjunction
`KnnVectorQuery`	向量检索
`TermInSetQuery`	多 Term 集合（in 查询）
`MultiTermQueryConstantScoreWrapper`	通配/正则变常分

6.2 QueryParser

Lucene 提供了字符串到 Query 的解析器 QueryParser：

title:("apache lucene"^2 AND intro:*search*) -status:draft
   published_at:[2020-01-01 TO *]~text:lucene~0.7

主要语法：

语法	含义
`field:term`	指定字段查询
`term1 term2`	默认 OR
`term1 AND term2`	必须都包含
`term1 OR term2`	任一包含
`"phrase here"`	短语
`field:[a TO b]`	范围
`term~`	模糊（默认 2 编辑距离）
`term~0.7`	模糊（指定相似度）
`term^2`	加权
`term`	通配符
`/regex/`	正则
`field:(a b c)`	字段下分组
`-term`	排除

MultiFieldQueryParser 可一次查询多字段。ClassicParseOnly 与 StandardQueryParser 支持更现代的语法。

QueryParser parser = new QueryParser("body", analyzer);
parser.setDefaultOperator(Operator.AND);
Query query = parser.parse("title:\"apache lucene\"^2 -status:draft");

6.3 Query 重写

很多查询（如 Wildcard、Fuzzy、Regex）底层要展开为多个 TermQuery。Lucene 通过 Query.rewrite(IndexReader) 实现：

常量分重写：MultiTermQueryConstantScoreWrapper，把所有命中变成常分。
Scoring 重写：SCORING_BOOLEAN_REWRITE，转为 BooleanQuery。
TopN 重写：TOP_TERMS_REWRITE，只保留频次最高的 N 个 term，避免爆炸。

这对通配符查询尤其重要：term* 可能匹配数十万 term，必须剪枝。

6.4 Scorer 与打分

Query 经过 Weight → Scorer 转换为文档迭代器。Scorer 提供：

iterator()：文档号迭代器（DocIdSetIterator）
scorerSupplier()（Lucene 8+）：批量供给，支持 SIMD 跳跃
score()：当前文档的分数

打分算法由 Similarity 控制：

Similarity	特点
`BM25Similarity`（默认）	Okapi BM25，对词频饱和
`ClassicSimilarity`	TF-IDF
`LMJelinekMercerSimilarity`	语言模型
`LMDirichletSimilarity`	Dirichlet 先验
`DFRSimilarity`	Divergence from Randomness
`BooleanSimilarity`	二值（命中即 1，不命中即 0）

BM25 公式：

score(q, d) = Σ_t  IDF(t) * ( f(t,d) * (k1+1) ) / ( f(t,d) + k1 * (1 - b + b * |d| / avgdl) )

IDF(t)：词项的稀有度（出现文档越少越重要）
f(t,d)：词在文档中的频率
|d|、avgdl：文档长度、平均文档长度
k1：词频饱和度（默认 1.2）
b：文档长度归一强度（默认 0.75）

调优经验：长文档场景调低 b（如 0.3）；短文档场景调高 k1（如 2.0）。

6.5 Collector：控制结果收集

Collector 决定如何收集打分结果：

TopScoreDocCollector：TopK + 分数（最常用）
TopFieldCollector：按字段排序后取 TopK
TotalHitCountCollector：仅计命中数
GroupingCollector：分组 TopK
MultiCollector：多 Collector 联合

Collector 在 LeafCollector 层是按段处理的，可以提前终止（如 TopScoreDocCollector 达到 10000 命中后可早停）。

第七章 IndexReader 与 IndexSearcher

7.1 IndexReader 层级

IndexReader (abstract)
   ├── CompositeReader (abstract)
   │     └── DirectoryReader  ← 整个索引
   │
   └── LeafReader
         └── SegmentReader  ← 单个段

DirectoryReader.open(directory) 返回最新的提交点视图。
DirectoryReader 内部包含若干 SegmentReader。
每个 SegmentReader 持有对应段的 Fields、DocValues、StoredFields 等接口。

每次新段可见都需要重新 open reader，这就是 NRT (Near Real-Time) 的核心：DirectoryReader.openIfChanged(oldReader) 增量打开新段，复用旧段 reader，避免全量加载。

7.2 SearcherManager 与 NRT

SearcherManager 是 Lucene 提供的 NRT 工具：

SearcherManager manager = new SearcherManager(indexWriter, true, null);

// 后台定期刷新
ScheduledExecutorService scheduler = ...;
scheduler.scheduleAtFixedRate(() -> {
    try {
        manager.maybeRefreshBlocking();  // 触发 flush + 增量 reopen
    } catch (Exception e) { ... }
}, 0, 1, TimeUnit.SECONDS);

// 搜索
IndexSearcher searcher = manager.acquire();
try {
    TopDocs top = searcher.search(query, 10);
} finally {
    manager.release(searcher);
}

ReferenceManager.RefreshListener 可在每次 refresh 时回调，用于更新缓存、统计等。

7.3 IndexSearcher

IndexSearcher.search(Query, Collector) 是搜索入口：

IndexSearcher searcher = new IndexSearcher(reader);
TopDocs top = searcher.search(query, 100);  // TopK by score
ScoreDoc[] hits = top.scoreDocs;
for (ScoreDoc hit : hits) {
    int docId = hit.doc;
    float score = hit.score;
    Document doc = searcher.doc(docId);  // 读 Stored Fields
}

IndexSearcher 的关键参数：

setQueryCache(...)：是否缓存 Query → DocIdSet。默认开。
setQueryCachingPolicy(...)：何时缓存（如 MIN_SIZE_AT_LEAST_5 阈值）。
setSliceExecutionControl：并行执行（Lucene 8+ 支持跨段并行）。
setSimilarity(...)：打分器。

7.4 跨段并行

Lucene 8 引入了 IndexSearcher.setTaskExecutor 支持跨段并行：

IndexSearcher searcher = new IndexSearcher(reader);
searcher.setTaskExecutor(ExecutorService);
searcher.setSliceExecutionControl(...);

每段作为一个 task 提交，并行执行后合并 TopK。适合大段少段、CPU 富裕的场景。注意并发查询可能造成 CPU 抖动，建议与限流策略结合。

第八章完整实战示例

8.1 项目搭建

Maven 依赖（Lucene 10.x）：

<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-core</artifactId>
    <version>10.1.0</version>
</dependency>
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-analysis-common</artifactId>
    <version>10.1.0</version>
</dependency>
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-queryparser</artifactId>
    <version>10.1.0</version>
</dependency>
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-highlighter</artifactId>
    <version>10.1.0</version>
</dependency>

8.2 完整搜索 Demo

public class LuceneDemo {

    private static final Path INDEX_DIR = Path.of("index");

    // 1) 定义 Analyzer
    static Analyzer analyzer = new StandardAnalyzer();

    public static void main(String[] args) throws Exception {
        buildIndex();
        searchIndex("lucene architecture");
    }

    static void buildIndex() throws Exception {
        IndexWriterConfig config = new IndexWriterConfig(analyzer)
            .setOpenMode(IndexWriterConfig.OpenMode.CREATE)
            .setRAMBufferSizeMB(32)
            .setMergePolicy(new TieredMergePolicy());
        Directory dir = FSDirectory.open(INDEX_DIR);
        try (IndexWriter writer = new IndexWriter(dir, config)) {
            writer.addDocument(buildDoc(
                "Lucene Architecture Overview",
                "Apache Lucene is a high-performance full-text search library with inverted index at its core.",
                "architecture"));
            writer.addDocument(buildDoc(
                "HNSW Vector Search",
                "Lucene 9 introduces HNSW for approximate nearest neighbor search.",
                "vector"));
            writer.addDocument(buildDoc(
                "BM25 Scoring",
                "BM25 is the default similarity in Lucene with parameters k1 and b.",
                "scoring"));
            writer.commit();
        }
    }

    static Document buildDoc(String title, String body, String tag) {
        FieldType storedIndexed = new FieldType();
        storedIndexed.setIndexOptions(IndexOptions.DOCS_AND_FREQS_AND_POSITIONS);
        storedIndexed.setStored(true);

        Document doc = new Document();
        doc.add(new Field("title", title, storedIndexed));
        doc.add(new Field("body", body, storedIndexed));
        doc.add(new StringField("tag", tag, Field.Store.YES));
        return doc;
    }

    static void searchIndex(String queryString) throws Exception {
        Directory dir = FSDirectory.open(INDEX_DIR);
        try (DirectoryReader reader = DirectoryReader.open(dir)) {
            IndexSearcher searcher = new IndexSearcher(reader);
            searcher.setSimilarity(new BM25Similarity(1.2f, 0.75f));

            QueryParser parser = new QueryParser("body", analyzer);
            Query query = parser.parse(queryString);
            System.out.println("Query: " + query);

            TopDocs top = searcher.search(query, 10);
            for (ScoreDoc hit : top.scoreDocs) {
                Document doc = searcher.storedFields().document(hit.doc);
                System.out.printf("score=%.3f  title=%s  tag=%s%n",
                    hit.score,
                    doc.get("title"),
                    doc.get("tag"));
            }
        }
    }
}

8.3 向量检索示例

public class VectorSearchDemo {

    static final int DIM = 768;
    static final Analyzer analyzer = new StandardAnalyzer();

    public static void main(String[] args) throws Exception {
        Path indexDir = Path.of("vector-index");

        // 1) 构建向量索引
        IndexWriterConfig config = new IndexWriterConfig(analyzer);
        try (IndexWriter writer = new IndexWriter(FSDirectory.open(indexDir), config)) {
            for (int i = 0; i < 100; i++) {
                Document doc = new Document();
                doc.add(new StringField("id", String.valueOf(i), Field.Store.YES));
                doc.add(new KnnFloatVectorField(
                    "emb",
                    randomVector(DIM),
                    KnnFloatVectorField.createType(
                        DIM, VectorSimilarityFunction.COSINE)));
                writer.addDocument(doc);
            }
            writer.commit();
        }

        // 2) 检索 Top5 最近邻
        try (DirectoryReader reader = DirectoryReader.open(FSDirectory.open(indexDir))) {
            IndexSearcher searcher = new IndexSearcher(reader);
            float[] queryVector = randomVector(DIM);

            // 过滤条件：只搜 id 偶数
            Query filter = new TermInSetQuery("id",
                IntStream.range(0, 100).filter(i -> i % 2 == 0)
                    .mapToObj(String::valueOf)
                    .map(BytesRef::new)
                    .collect(Collectors.toList()));

            KnnFloatVectorQuery knnQuery = new KnnFloatVectorQuery(
                "emb", queryVector, 100, 5, filter);

            TopDocs top = searcher.search(knnQuery, 5);
            for (ScoreDoc hit : top.scoreDocs) {
                Document doc = searcher.storedFields().document(hit.doc);
                System.out.printf("id=%s score=%.3f%n", doc.get("id"), hit.score);
            }
        }
    }

    static float[] randomVector(int dim) {
        Random r = new Random();
        float[] v = new float[dim];
        float norm = 0;
        for (int i = 0; i < dim; i++) {
            v[i] = r.nextGaussian();
            norm += v[i] * v[i];
        }
        norm = (float) Math.sqrt(norm);
        for (int i = 0; i < dim; i++) v[i] /= norm;
        return v;
    }
}

8.4 高亮示例

public class HighlightDemo {
    public static void main(String[] args) throws Exception {
        Query query = new QueryParser("body", analyzer).parse("lucene");
        UnifiedHighlighter highlighter = new UnifiedHighlighter(searcher, analyzer);
        highlighter.setHighlightFlags(HighlightFlag.MULTI_TERM_QUERY);

        String text = "Apache Lucene is a high-performance search library.";
        String[] fragments = highlighter.highlight("body", new String[]{text}, query, 2);
        // fragments[0] = "<b>Apache Lucene</b> is a high-performance search library."
    }
}

UnifiedHighlighter 是 Lucene 6+ 的统一高亮器，能根据 Term Vectors / Postings / 重分析三种模式自动选择，性能与精度兼优。

第九章性能调优

9.1 写入调优

调优点	建议
`RAMBufferSizeMB`	大批写入调高到 128-512 MB，减少 flush 频率
`MaxBufferedDocs`	文档数极大时设大（如 100000），但通常 RAM 先达上限
`IndexerThreadPool`	多线程写入，每线程独占 DWPT；不要超 CPU 核数
`RAMPerThreadHardLimitMB`	防止单 DWPT 占用过高，触发 OOM
`MergePolicy`	TieredMergePolicy，`maxMergedSegmentBytes` 按磁盘 IO 调整
`MergeScheduler`	ConcurrentMergeScheduler，限制 `maxThreadCount` 避免拖慢
关闭 `storeTermVectors`	不需要高亮 / MLT 就不要开
关闭 `storeOffsetsInIndex`	除非必须用 postings 高亮
节流写入	大量写入时限制单 writer 的吞吐，给 merge 留 IO

9.2 查询调优

调优点	建议
`setSimilarity`	长文档用小 `b`，短文档调高 `k1`
Query Cache	默认开，但缓存空间有限，避免缓存大结果集 query
SearcherManager	周期性 refresh，但不要过频（< 1s）
StoredFields	只 SELECT 必要字段，避免读 source 全字段
DocValues	排序聚合字段开启 DocValues，避免读源
范围查询	数值用 `LongPoint/DoublePoint`，不要用 `TermRangeQuery`
Fuzzy/Regex	限制 `prefixLength`，避免全字典扫描
KNN	调小 `efSearch`，配合过滤；候选 K 一般是 TopK * 10
并行搜索	多段场景用 `setTaskExecutor`，但要监控 CPU
Filter 复用	把 filter 包成 `ConstantScoreQuery` 触发 cache

9.3 段与合并调优

调优点	建议
段数控制	单 shard 段数 20-50 为佳；过多合并、过少触发大合并
大段合并	大段合并占 IO + CPU；可设置 `maxMergedSegmentBytes` 阈值
Force Merge	对只读索引做 `forceMerge(1)`，减段数；但不要在线上做
删除堆积	`deletesPctAllowed` 默认 20%，删除频繁时调到 10%
冷热分层	冷数据用 `NoMergePolicy` 避免再合并
SSD 与 HDD	Lucene 对 SSD 友好；HDD 上并发合并线程数 <= 1

9.4 内存与 GC 调优

项	建议
MMapDirectory	默认，把 `.tim` / `.tip` / `.dvd` / `.vec` mmap，节省堆内存
Heap	Lucene 自身堆使用很少，主要是 ES / Solr 层堆；IndexReader 缓存对象极少
Direct Memory	MMap 占虚拟内存，不占 Heap；注意 OS page cache
文件句柄	段越多句柄越多；`ulimit -n` 至少 65536
GC	大合并时会触发较多对象分配，看 G1/ZGC

9.5 监控指标

Lucene 自身不暴露 metric（要 ES / Solr 层），但跟踪以下指标至关重要：

段数（numSegments）
总文档数与活跃文档数（maxDoc vs numDocs）
删除堆积率（deletedDocPct）
合并待办任务数（pendingMerges）
写入吞吐（docs/sec）
查询 P99 与慢查询日志

第十章 Codec 与文件格式

10.1 Codec 的设计哲学

Lucene 用 Codec 抽象索引格式，让不同维度（Postings / DocValues / StoredFields / KnnVectors / Terms / Norms / LiveDocs）格式可独立替换。一个 Codec 由若干 *Format 组成：

public abstract class Codec {
    public abstract PostingsFormat postingsFormat();
    public abstract DocValuesFormat docValuesFormat();
    public abstract StoredFieldsFormat storedFieldsFormat();
    public abstract TermVectorsFormat termVectorsFormat();
    public abstract NormsFormat normsFormat();
    public abstract LiveDocsFormat liveDocsFormat();
    public abstract FieldInfosFormat fieldInfosFormat();
    public abstract SegmentInfoFormat segmentInfoFormat();
    public abstract CompoundFormat compoundFormat();
    public abstract KnnVectorsFormat knnVectorsFormat();
    public abstract PointsFormat pointsFormat();
}

10.2 主要文件扩展名

后缀	文件类型
`segments_N`	提交点（所有段的清单）
`.si`	段信息
`.fnm`	字段元数据
`.fdt` / `.fdx` / `.fdm`	Stored Fields 数据 / 索引 / 元数据
`.tim` / `.tip`	Term Dictionary / Term Index
`.doc` / `.pos` / `.pay`	Posting List：docId / 位置 / 偏移与 payload
`.dvd` / `.dvm`	DocValues 数据 / 元数据
`.vec` / `.vem` / `.vex` / `.vemq`	向量原值 / 元数据 / 量化索引 / 量化元数据
`.nvd` / `.nvm`	Norms 数据 / 元数据
`.liv`	LiveDocs（位图）
`.kdd` / `.kdi` / `.kdm`	Points (BKD) 数据 / 索引 / 元数据
`.cfs` / `.cfe`	复合文件（多个文件打包成 .cfs，便于转移）
`.lock`	写锁

10.3 常用 Codec

Codec	特点
`Lucene99Codec` / `Lucene100Codec`	默认 Codec，使用 Postings / DocValues 等系列最新格式
`CheapBastardCodec`	极简 Codec，关闭量化、关闭跳表，测试用
`AssertingCodec`	在 assert 模式下加额外校验，测试用
`BlockPostingsFormat` / `Lucene99PostingsFormat`	当前默认 Postings 格式
`DiskDovVectorsFormat`	10.x 引入的向量磁盘格式，与 PQ 量化结合

关键：Codec 升级是 Lucene 跨版本读写的核心机制。Lucene 的 lucene-backward-codecs 提供向前兼容：新版本可读旧版本索引，但不能反过来。

第十一章高级特性

Lucene Facet 提供分面计数。它通过在文档中追加「category path 字段」并使用 DrillDownQuery 来组合过滤与计数：

// 建立分面
FacetsConfig config = new FacetsConfig();
config.setMultiValued("category", true);
Document doc = new Document();
doc.add(new FacetField("category", "lucene", "architecture"));
doc.add(new FacetField("author", "doug"));
writer.addDocument(config.build(taxoWriter, doc));

// 检索 + 分面
FacetsCollector collector = new FacetsCollector();
searcher.search(query, collector);
Facets facets = new FastTaxonomyFacetCounts(taxoReader, config, collector);
FacetResult result = facets.getTopChildren(10, "category");

底层有 Taxonomy（分类树） 与 SortedSetDocValuesFacets 两种实现：

Taxonomy：支持层级 facet，但需要额外 taxonomy index。
SortedSet：基于 DocValues，不需要额外索引，但仅支持顶层 facet。

11.2 Join (BlockJoin)

Lucene 不支持关系式 join，但提供 BlockJoin 支持「父-子嵌套文档」：

// 添加一组：一个父 + 多个子，作为一个 block 写入
List<Document> block = new ArrayList<>();
Document parent = new Document();
parent.add(new StringField("type", "product", Field.Store.YES));
block.add(parent);  // parent 最后
for (String review : reviews) {
    Document child = new Document();
    child.add(new StringField("type", "review", Field.Store.YES));
    child.add(new TextField("content", review, Field.Store.NO));
    block.add(child);
}
writer.addDocuments(block);  // 必须原子写入

// 查询：找有好评的产品
Query childQuery = new TermQuery(new Term("content", "good"));
ToParentBlockJoinQuery q = new ToParentBlockJoinQuery(
    childQuery,
    new ToParentBlockJoinQuery.ScoreMode.MAX,
    parentFilter);
TopDocs top = searcher.search(q, 10);

注意：BlockJoin 对父子比有要求（建议 < 100:1），过大将拖慢查询。

11.3 Suggest（拼写纠正 / 自动补全）

Lucene 的 lucene-suggest 提供基于 FST 的前缀补全与 Levenshtein 自动机纠正：

// 构建 FST 字典
InputIterator iterator = ...;  // 词项 + 权重
FSTCompletionLookup lookup = new FSTCompletionLookup();
lookup.build(iterator);

// 查询补全
List<LookupResult> results = lookup.lookup("luc", false, 10);

不同 Lookup 实现：

类	适用
`FSTCompletionLookup`	简单前缀补全
`AnalyzingSuggester`	分析后补全
`FreeTextSuggester`	基于 n-gram 语言模型
`WFSTCompletionLookup`	单权重 FST
`JaspellLookup`	JaSpell 拼写纠正
`TSTLookup`	三叉搜索树

11.4 Spatial（地理检索）

Lucene 提供两种主流方案：

LatLonPoint：经纬度点，基于 BKD 树，支持 GeoDistanceQuery、BoundingBox。
LatLonShape / XYShape：多边形与线段，支持「点是否在多边形内」等空间查询。

// 点索引
Document doc = new Document();
doc.add(new LatLonPoint("location", 39.9, 116.4));  // 北京
doc.add(new StoredField("location", "39.9,116.4"));

// 半径查询
Query query = LatLonPoint.newDistanceQuery(
    "location", 39.9, 116.4, 50_000);  // 50 km

11.5 Monitor（反向搜索）

lucene-monitor 把搜索问题反转：预编译大量 Query，每篇新文档匹配哪些 Query。用于：

订阅告警（如「邮件中含某关键字就告警」）
个性化推送
复杂规则匹配

Monitor monitor = new Monitor(new MonitorQueryAnalyzer(analyzer));
monitor.registerQuery(new MonitorQuery("q1", parser.parse("body:lucene")));
monitor.registerQuery(new MonitorQuery("q2", parser.parse("title:\"bug fix\"")));

Document doc = ...;
Matches matches = monitor.match(DocumentQueryBuilder.from(doc), ...);

底层为每个 Query 预编译 Presearcher，缩小到只匹配相关 term 的子集，避免逐 Query 全扫描。

11.6 Expressions

lucene-expressions 允许用 JavaScript 语法表达动态评分：

Expression expr = JavascriptCompiler.compile("_score * 0.7 + log(popularity)");
SimpleBindings bindings = new SimpleBindings();
bindings.add(new ScoreValueSource("score"));
bindings.add(new DoubleValuesSource(...) "popularity");

DoubleValuesSource src = expr.getDoubleValuesSource(bindings);
Query boostQuery = new FunctionScoreQuery(query, src);

适合需要把多个打分信号融合的场景（如「相关度 × 用户偏好」）。

第十二章知识体系总图

把前面散落的概念组织成一棵知识树，方便复习：

Lucene
│
├── 概念层
│   ├── Document / Field / FieldType
│   ├── Term / Token / TokenStream
│   ├── Analyzer / Tokenizer / TokenFilter / CharFilter
│   └── Similarity / Scorer / Collector
│
├── 数据结构层
│   ├── Inverted Index
│   │   ├── Term Dictionary (.tim)
│   │   ├── Term Index FST (.tip)
│   │   ├── Posting List (.doc/.pos/.pay) — PFor + SkipList
│   │   └── Norms (.nvd/.nvm)
│   ├── DocValues 列存 (.dvd/.dvm)
│   │   ├── Numeric / Sorted / SortedSet / SortedNumeric
│   │   ├── Table / Delta / GCD / BlockSorted 编码
│   │   └── Used by: 排序、聚合、脚本
│   ├── Stored Fields 行存 (.fdt/.fdx/.fdm)
│   │   └── LZ4 压缩 + 文档块
│   ├── Term Vectors (.tvx/.tvd/.tvf)
│   │   └── 用于高亮、MoreLikeThis
│   ├── Points BKD (.kdd/.kdi/.kdm)
│   │   └── 数值 / 地理范围
│   └── Vector Index
│       ├── HNSW 算法 (.vec/.vem)
│       ├── 量化 (.vex) — ScalarQuantization / ProductQuantization
│       └── 距离：L2 / Cosine / Dot / MIPS
│
├── 写入路径层
│   ├── IndexWriter / IndexWriterConfig
│   ├── DocumentsWriter
│   ├── DocumentsWriterPerThread (DWPT)
│   ├── IndexingChain
│   │   ├── InvertedDocConsumer → TermsHash / NormsConsumer / TermVectorsConsumer
│   │   ├── StoredFieldsConsumer
│   │   ├── DocValuesConsumer
│   │   ├── KnnVectorsConsumer
│   │   └── PointsConsumer
│   ├── Flush — 内存 → 段
│   ├── Commit — Two-Phase Commit
│   ├── Merge
│   │   ├── MergePolicy (Tiered / LogByteSize / NoMerge)
│   │   ├── MergeScheduler (Concurrent / Serial / NoMerge)
│   │   └── 合并触发：段数 / 删除堆积
│   └── Deletes — Term / Query，标记于 LiveDocs
│
├── 读取路径层
│   ├── Directory (MMap / FS / NIOFS / ByteBuffers)
│   ├── IndexReader
│   │   ├── DirectoryReader (Composite)
│   │   └── SegmentReader (Leaf)
│   ├── SearcherManager (NRT)
│   ├── IndexSearcher
│   │   ├── search(Query, Collector)
│   │   ├── setSimilarity
│   │   ├── setQueryCache
│   │   └── setTaskExecutor (跨段并行)
│   └── Collector
│       ├── TopScoreDocCollector
│       ├── TopFieldCollector
│       ├── GroupingCollector
│       └── MultiCollector
│
├── Query 层
│   ├── Leaf Query
│   │   ├── TermQuery / TermInSetQuery
│   │   ├── PhraseQuery / MultiPhraseQuery
│   │   ├── RangeQuery / PointRangeQuery
│   │   ├── Wildcard / Regex / Fuzzy / Prefix
│   │   └── KnnVectorQuery
│   ├── Composite Query
│   │   ├── BooleanQuery (MUST / SHOULD / FILTER / MUST_NOT)
│   │   ├── DisjunctionMaxQuery
│   │   ├── BoostingQuery
│   │   └── ConstantScoreQuery
│   ├── 重写 rewrite(IndexReader)
│   ├── Weight → Scorer → BulkScorer (SIMD + SkipList)
│   └── QueryParser (Classic / Standard / MultiField)
│
├── Codec 层
│   ├── PostingsFormat (Lucene99PostingsFormat)
│   ├── DocValuesFormat
│   ├── StoredFieldsFormat
│   ├── TermVectorsFormat
│   ├── KnnVectorsFormat (DiskDovVectorsFormat)
│   ├── NormsFormat / LiveDocsFormat / FieldInfosFormat / SegmentInfoFormat / CompoundFormat
│   └── Backward-Codec 跨版本读
│
├── 高级模块层
│   ├── Facet (Taxonomy / SortedSet)
│   ├── Join (BlockJoin)
│   ├── Suggest (FST / Analyzing / FreeText / TST / Jaspell)
│   ├── Spatial (LatLonPoint / LatLonShape / XYShape)
│   ├── Highlighter (UnifiedHighlighter / FastVectorHighlighter)
│   ├── Monitor (反向搜索)
│   ├── Expressions (JavaScript 评分)
│   ├── Grouping (二级聚合)
│   └── BackwardCodecs
│
└── 调优层
    ├── 写入：RAMBuffer / DWPT / MergePolicy / MergeScheduler
    ├── 查询：Similarity / QueryCache / DocValues / Field Selection
    ├── 段数：ForceMerge / TieredMerge / deletesPctAllowed
    ├── 内存：MMap / 文件句柄 / Heap vs Direct
    └── 监控：段数 / 删除率 / 合并待办 / 慢查询

第十三章使用案例与生态

13.1 著名案例

项目	如何使用 Lucene
Elasticsearch	Lucene 作为单机内核；ES 在其上加集群、副本、HTTP、SQL
Apache Solr	Lucene 作为单机内核；Solr 加分布式、Schema、Facet、HTTP
OpenSearch	AWS fork ES，同样基于 Lucene
LinkedIn Galene	基于 Lucene 二开，专注高性能反向索引
Wikipedia / Wikimedia	基于 Lucene 的搜索中台 CirrusSearch
GitHub Code Search	基于 Lucene（早期）+ 自研
Apache Nutch	Doug Cutting 同时发起的爬虫，配合 Lucene
Obsidian	桌面笔记的本地全文搜索基于 Lucene
Apache Tika	内容提取，输出给 Lucene 索引
Maven Central Search	基于 Lucene

13.2 自研搜索中台选型决策

考虑用 Lucene 自研（不走 ES）的场景：

嵌入式 / 单机：搜索功能内嵌在产品中，不想部署服务。
超大规模单机：32 核 + NVMe 单机能跑千万级文档，Lucene 性能远超 ES。
特殊需求：完全定制的索引格式、特殊的查询语义、私有数据结构。
成本敏感：不想付 ES 商业许可 / X-Pack；自研 lucene 应用即可满足。

不建议自研 Lucene 的场景：

需要横向扩展与副本。
需要 HTTP API、多语言 SDK。
需要 SQL / ES|QL 查询、ML 推理等高级能力。
运维团队能力不足，自建容易踩坑。

13.3 与向量数据库的对比

Lucene 10 的 HNSW 与量化已非常强大，与专用向量库（Milvus、Chroma、Qdrant）相比：

维度	Lucene	专用向量库
性能	单机性能好；10.x 量化后吞吐可达 10K+ QPS	接近，但大集群扩展性好
召回率	int8 量化后 99%+ 召回	int8 / PQ 召回相当
混合检索	原生支持 BM25 + KNN + 过滤	需要外挂全文索引
存储	fp32 / int8 / PQ 任选	通常更精细（IVF-PQ / DiskANN）
扩展性	单机，需应用层分片	集群原生
易用	Java API，应用层封装	多语言 API，HTTP 友好
适合	单机 / 嵌入式 / 已有 ES	大规模 / 全新架构

实战经验：在中型规模（< 1 亿向量，< 100M 文档）场景，Lucene + ES 混合检索 往往是性价比最高的方案，因为：

复用现有 ES 运维能力；

同库同时存关键词倒排与向量，过滤与全文加权天然支持；

单次部署、单次监控、单次升级。

第十四章常见陷阱与排错

14.1 Analyzer 不一致

症状：查询返回 0 结果，但目测应该有。

排查：

System.out.println(analyzer.normalize("body", "Lucene"));  // 查询时归一化结果
// 写入侧：tokenizer 后是什么 token？
TokenStream ts = analyzer.tokenStream("body", "Lucene");
CharTermAttribute attr = ts.addAttribute(CharTermAttribute.class);
ts.reset();
while (ts.incrementToken()) System.out.println(attr.toString());

把查询与索引侧的 token 列表打印对比。

14.2 段数爆炸

症状：查询变慢，磁盘 IOPS 高。

排查：DirectoryReader.numDocs() 与段数；通过 SegmentReader.getSegmentInfo().info.maxDoc() 看每个段大小。若是大量小段：

检查 MergeScheduler 是否并发受限。
调小 segmentsPerTier，让合并更积极。
检查 RAM Buffer 是否过小导致频繁 flush 小段。

14.3 OOM

症状：堆溢出或 MappedByteBuffer 占满虚拟内存。

排查：

Heap OOM：多半是应用层缓存或 SearcherManager 未 release。
MMap 虚拟内存：Linux 默认 65536 KB，超大索引会超；调 vm.max_map_count。
Direct 内存：Lucene 自身不大量使用 direct；查 ES。

14.4 写入卡顿

症状：addDocument 偶发性慢。

排查：

合并赶不上：IndexWriter.getMergingSegments() 看是否有大段合并。
GC 抖动：监控 GC log。
IO 饱和：iostat 查看 %util、await。
锁竞争：IndexWriter 在 commit 时会持锁。

14.5 Query Cache 命中率低

原因：

Query 对象每次 new（无 equals/hashCode），缓存命中失败。
大结果集 query 触发剔除策略。
字段值频繁变化导致缓存失效。

对策：复用 Query 对象、调大 QueryCache 容量。

第十五章 Lucene 10.x 新特性

15.1 Lucene 10 主要里程碑

版本	特性
9.0	引入 KNN（HNSW）、DocValues Block-Sorted 改进
9.1	KNN 稳定化、COSINE 距离
9.4	Sparse 倒排（High-dimensional）
9.7	向量 Binary Quantization（试验）
9.9	TopK 提前终止
10.0	默认 int8 标量量化、Product Quantization、DiskDovVectorsFormat
10.1	Adaptive Quantization、KNN 过滤剪枝改进

15.2 Adaptive Quantization

Lucene 10.1 起，向量字段可声明自适应量化：

FieldType fieldType = KnnFloatVectorField.createType(768, VectorSimilarityFunction.COSINE);
fieldType.setVectorIndexOptions(VectorIndexOptions.HNSW_M(16, 100));
fieldType.setVectorQuantizer(VectorQuantizer.AUTO);  // 自适应
fieldType.setVectorDataOptions(VectorDataOptions.OFF);

AUTO 模式会根据数据分布选择 SQ int8 / int7 / int4 或 PQ 4bit / 7bit。引擎会采样前若干文档，统计量化误差，选择误差最小的方案。

15.3 改进的合并并发

Lucene 10 优化了 KNN 段合并：合并时分别在新段上并发构建 HNSW 图（按 docId 分片），最后整合。这让 forceMerge 不再是「卡死几个小时」的噩梦。

15.4 ES|QL 风格的 Lucene Batch API

Lucene 10 实验性地引入 BatchSearcher，可在一次请求中提交多个 Query，复用 scorer 与解压状态。这对监控告警场景（一个文档匹配 N 条规则）有显著加速。

第十六章完整的工程清单

以下是落地一个 Lucene 项目时建议的检查清单：

16.1 部署前

[ ] 选定 Lucene 版本（推荐 10.x 最新 stable）
[ ] JVM 选型（建议 JDK 21 LTS，Lucene 10 要求 JDK 21+）
[ ] OS 调优：vm.max_map_count=262144、ulimit -n 65536、关闭 swap
[ ] 磁盘：NVMe SSD；不要用网络存储（NFS / CIFS）
[ ] GC：G1 或 ZGC；监控 Full GC
[ ] 依赖管理：检查 lucene-* 全部同版本，避免 NoSuchMethodError

16.2 索引设计

[ ] 字段命名规范（避免 .、-）
[ ] 选择合适 IndexOptions（最小够用）
[ ] 默认关闭 storeTermVectors，仅在必要时开启
[ ] 数值字段用 *Point，字符串排序用 SortedDocValues
[ ] 向量字段选 768 维（OpenAI / BGE 标准），距离选 COSINE
[ ] 大字段（如正文）独立 Stored，不参与倒排

16.3 写入

[ ] RAMBufferSizeMB >= 64 MB
[ ] 多线程写入，控制 IndexerThreadPool 大小
[ ] 合并调度：ConcurrentMergeScheduler，限制 maxThreadCount=2
[ ] 定期 commit，但不要过频（1-5 秒一次足够）
[ ] 大批量写入后做 forceMerge(1)，但仅在低峰期

16.4 查询

[ ] 使用 SearcherManager 周期 refresh
[ ] IndexSearcher.setSimilarity(new BM25Similarity(1.2, 0.75))
[ ] 高频 Query 复用对象，避免 cache 失效
[ ] 避免通配符开头（*term）—— 全字典扫描
[ ] KNN 设 efSearch 在 50-100 之间，配合过滤
[ ] 慢查询阈值：> 100ms 记录、> 1s 告警

16.5 运维

[ ] 监控段数、活跃文档数、删除堆积
[ ] 监控合并待办任务
[ ] 监控磁盘水位（> 80% 告警）
[ ] 周期 forceMerge 冷数据
[ ] 备份：SnapshotUtil 或文件级 cp
[ ] 升级路径：先在测试集群验证 backward-codecs 兼容性

第十七章 FAQ

Q1: Lucene 与 Elasticsearch 的关系是什么？

A: Lucene 是底层搜索引擎库，ES 是基于 Lucene 构建的分布式搜索引擎。Lucene 提供单机的索引/搜索能力，ES 在其上加分布式协调、HTTP API、副本、安全等。

Q2: Lucene 是多线程安全的吗？

A: IndexWriter 单实例多线程安全；IndexReader/IndexSearcher 单实例只读，可多线程并发使用。但 IndexWriter 与 IndexReader 共享一个 Directory 时，要通过 SearcherManager 获取最新的 reader。

Q3: Lucene 怎么处理超大文档？

A: 单个 Lucene 文档理论上可很大，但建议拆分（如分段索引）。大字段（> 32KB）单独存 StoredFields，不参与倒排。

Q4: Lucene 支持事务吗？

A: Lucene 支持 single-writer 模型下的「session transaction」：在 commit 之前的所有变更对外不可见，commit 后原子可见。崩溃后回滚到最近 commit 点。

Q5: Lucene 10 的 HNSW 比 Milvus 慢吗？

A: 单机吞吐与延迟，Lucene 10 与 Milvus 在 10M 量级文档上接近（差距 < 2x）。但 Milvus 在百亿级扩展性更好。Lucene 的优势是混合检索（BM25 + KNN + 过滤）天然一体。

Q6: Lucene 索引文件能跨平台迁移吗？

A: 可以。Lucene 索引是平台无关的二进制文件，可在 Linux / Windows / macOS 间直接 cp。

Q7: Lucene 的最高支持文档数？

A: 单段理论上 Integer.MAX_VALUE（约 21 亿），但实际段超过 5GB 时合并代价过大；多段累积可支持数十亿。ES 单 shard 推荐不超过 2 亿文档。

Q8: Lucene 怎么实现分布式？

A: Lucene 不直接支持分布式，需要应用层分片（按 hash 路由到不同 Lucene 实例），查询 fan-out + 合并 TopK。ES/Solr 已经做这层封装。

第十八章参考资源

18.1 官方资料

Lucene 主站：https://lucene.apache.org/
Javadoc（10.x）：https://lucene.apache.org/core/10_0_0/
源码：https://github.com/apache/lucene
Changes：https://lucene.apache.org/core/10_0_0/changes/Changes.html

18.2 经典书籍

Lucene in Action（第二版，Manning）—— 虽然基于 Lucene 3，但原理讲解扎实
Taming Text（Manning）—— 文本处理与搜索
Managing Gigabytes（Witten et al.）—— 倒排索引的经典教材
Introduction to Information Retrieval（Manning, Raghavan, Schütze）—— 信息检索理论

18.3 周边生态

Elasticsearch 源码：https://github.com/elastic/elasticsearch
Solr 源码：https://github.com/apache/solr
OpenSearch：https://github.com/opensearch-project/OpenSearch
JIEBA-Lucene 中文分词插件：https://github.com/huaban/jieba-analysis
IKAnalyzer：https://github.com/medcl/elasticsearch-analysis-ik

18.4 相关论文推荐

Doug Cutting 原始论文：Optimizing Constrained Monotone Linear Recombination
HNSW 论文：Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs
BM25 论文：A probabilistic model of information retrieval
PFor Delta 论文：Super-Scalar RAM-CPU Compression

总结

Apache Lucene 不是一个产品，而是一份搜索引擎库的工程实践模板。它的核心价值：

清晰的抽象分层：从 Codec 到 Reader 到 Searcher，每一层职责明确，可独立替换。
极致的数据结构：FST + PFor + SkipList + BKD + HNSW，每一处都是工业级优化。
完整的功能覆盖：倒排、向量、地理、Facet、Join、Suggest、Highlighter、Monitor，从检索到推荐一应俱全。
坚实的生态基础：ES / Solr / OpenSearch 等数百万生产环境验证过的代码库都基于它。

理解 Lucene，就理解了 90% 的全文检索系统内核；阅读 Lucene 源码，就是阅读信息检索工程的最佳教材。

建议学习路径：

跑通本文第八章的 demo；

阅读 IndexWriter 与 IndexingChain 源码；

跟踪一次 addDocument 从内存到段的全过程；

阅读 Lucene99PostingsFormat 的写入与读取实现；

研究 HNSW 的合并与查询代码；

对照 ES 源码理解「Lucene 之上」的封装层。

希望这篇详解能成为你 Lucene 学习与生产实践的指南。如果希望进一步深入某个模块（例如 Codec 实现、HNSW 合并算法、KNN 量化数学原理），欢迎留言讨论。

第零章 为什么你必须读懂 Lucene