深入解析 ZAP 段文件格式OpenCloud 搜索引擎底层索引的二进制布局【免费下载链接】opencloud️ OpenCloud is the open source platform for file management, sharing and collaboration. Simple and sovereign.项目地址: https://gitcode.com/GitHub_Trending/op/opencloudZAPZap Advanced Postings是 Bleve 搜索引擎家族scorch 索引引擎使用的不可变段文件segment格式本指南以当前仓库 vendored 的zapx/v12实现及其官方格式文档 zap.md 为主线逐字节剖析其文件布局、footer 解析入口、Stored Fields、倒排词典与 Postings、DocValues 五大核心区域。读完本文你将能够理解一个 ZAP 段文件在磁盘上的完整组织方式并结合 write.go 与 read.go 的源码印证先写数据、后写索引、最后写 footer的单遍写入策略以及它在 OpenCloud 搜索服务中的实际落地位置。ZAP 格式的背景从 bleve 到 zapx/v12zapx模块是经典 zap。在 OpenCloud 仓库中该模块被 vendored 在 vendor/github.com/blevesearch/zapx/v12与主项目 go.mod 中的github.com/blevesearch/bleve/v2 v2.6.1、github.com/blevesearch/scorch_segment_api/v2 v2.4.10配套见 go.mod。OpenCloud 的全文搜索服务在 services/search/pkg/bleve 中通过bleve.NewIndexindex.go与bleve.NewSearchRequestbackend.go构建索引并执行查询而 ZAP 正是这一层索引落盘时所使用的底层段文件格式——理解 ZAP 布局就等于理解 OpenCloud 搜索索引文件的内部构造。格式图例五种基本约定zap.md文档首先用一套 ASCII 图例统一定义了后续所有结构图中出现的基本元素是阅读本文后续所有布局图的前提图例含义\|\|Section区域一个完整的功能区块如 Stored Fields、Fields、DocValues 等\|----\|Fixed-size field定长字段宽度即类型如uint64(8B)、uint32(4B)、uint16(2B)、uint8(1B)均为大端big endian编码\|~~~~\|Varint变长整数编码范围可达uint64长度不定用于压缩数值空间\|----...---\|Arbitrary-length field任意长度字段字符串、vellum FST 数据、roaring bitmap 等[----]Chunked data分块数据以若干 chunk 连续排布配合独立的 chunk 偏移表实现按文档号随机定位文件总览footer 驱动的自底向上布局ZAP 文件整体采用自底向上、由 footer 统领的布局。整个文件的物理排布从文件末尾向文件头方向依次是|| | Stored Fields | || |----- | Stored Fields Index | | || | | Dictionaries Postings DocValues | | || | |--- | DocValues Index | | | || | | | Fields | | | || | | |- | Fields Index | | | | |||||||| | | | | D# | SF | F | FDV | CF | V | CC | (Footer) | | | ||||||||||| | | | | | | |-------------------| | | | |--------------------------| | |-------------------------------------|文件末尾的Footer是进入整个文件的唯一入口它记录了其他所有区域的位置因此解析任何 ZAP 文件的第一个动作都是先读 footer、再顺着其中的偏移量导航到目标区域。在 README.md 的Current usage一节中官方进一步明确了读取惯例整个文件被mmap映射到内存CRC-32 校验值与版本号固定在文件末尾的固定位置footer 的剩余部分按版本解析即zap.mdOverview 中强调的footer 格式版本相关footer 提供 3 个关键偏移量DocValue 偏移、Fields Index 偏移、Stored Fields Index 偏移与 2 个关键值文档数、chunk factor字段数据field data只处理一次并被缓存到堆上此后不再回读磁盘按文档号访问 Stored Fields 时先进入 Stored Fields Index再读取定长偏移槽位定位实际数据地址数据段开头的长度字段用于界定数据边界。这一footer 定天下的设计直接决定了 ZAP 文件可以单遍顺序写出因为 footer 中记录的偏移量全部指向已经写完的数据写盘过程可以一路向前最后再回填 footer。Footer版本依赖的解析入口Footer 占据文件最末的固定 44 字节各字段按大端序依次排布缩写含义宽度D#Number of Docs文档总数uint64SFStored Fields Index OffsetStored Fields 索引偏移uint64FField Index OffsetFields 索引偏移uint64FDVField DocValue Offset字段 DocValues 偏移uint64CFChunk Factor分块因子uint32VVersion版本号uint32CCCRC32文件 CRC 校验uint32其含义在源码中得到精确印证。FooterSize常量在 write.go 中被明确注释为// FooterSize is the size of the footer record in bytes // crc ver chunk field offset stored offset num docs docValueOffset const FooterSize 4 4 4 8 8 8 8即 44 字节而 persistFooter 函数逐字段完成写入依次写入numDocs、storedIndexOffset、fieldsIndexOffset、docValueOffset均为 BigEndian uint64、chunkModeBigEndian uint32、VersionBigEndian uint32最后写入不包含本字段之前所有字节的 CRC-32 校验值。由于版本号固定位于距文件末尾固定位置处读者可以先读取V字段判断格式版本再决定如何解析 footer 的其余部分——这正是文档footer 格式版本相关解析前必须检查 V 字段的原因。Stored Fields原始字段值的随机访问Stored Fields Index定长偏移表Stored Fields Index 由D#个连续的 64 位无符号整数构成每个整数是某篇文档document的 Stored Fields Data 记录在文件中的起始偏移量0 [SF] [SF D# * 8] | Stored Fields | Stored Fields Index | ||| | | | | |--------------------| ||--------|--------|. . .|--------|| | |- | Stored Fields Data | || 0 | 1 | | D# - 1 || | | |--------------------| ||--------|----|---|. . .|--------|| | | | | | ||||| | | |-------------------------------------------|由于每个槽位定长 8 字节给定文档号docNum时其 Stored Fields 偏移即位于SF docNum * 8。这一点在 read.go 的getDocStoredOffsets中直接体现indexOffset : s.storedIndexOffset (8 * docNum) storedOffset : binary.BigEndian.Uint64(s.mem[indexOffset : indexOffset8])先读出数据区偏移storedOffset随后在该地址处依次解码两个 varintmetaLen元数据长度与dataLen压缩数据长度据此界定元数据与数据的边界。Stored Fields Data元数据 Snappy 压缩负载每一条 Stored Fields Data 是任意大小的记录由元数据和 Snappy 压缩后的数据两部分组成Stored Fields Data |~~~~~~~~|~~~~~~~~|~~~~~~~~...~~~~~~~~|~~~~~~~~...~~~~~~~~| | MDS | CDS | MD | CD | |~~~~~~~~|~~~~~~~~|~~~~~~~~...~~~~~~~~|~~~~~~~~...~~~~~~~~| MDS. Metadata size.元数据长度 CDS. Compressed data size.压缩数据长度 MD. Metadata.元数据 CD. Snappy-compressed data.Snappy 压缩数据写入侧的完整流程记录在 README.md 的 stored fields section 中可分两个阶段准备阶段对每篇文档生成一段元数据字节与一段数据字节字段按 field id 顺序排列字段值追加进数据切片元数据切片对每个字段值以 varint 编码以下信息——字段 iduint16、字段类型1 字节、字段值在未压缩数据切片中的起始偏移uint64、字段值长度uint64、数组位置数量uint64以及每个数组位置各一个 uint64最后对数据切片做 Snappy 压缩。写盘阶段记录本文档数据的起始偏移依次写出元数据长度varint uint64、压缩数据长度varint uint64、元数据字节、压缩数据字节。配合 Stored Fields Index只要知道文档号就能对任意文档的原始字段值做 O(1) 直接访问这是搜索结果中高亮片段、原始字段回显等能力的基础。Fields字段名与字段元信息的登记区Fields 区域位于地址F与len(file) - len(footer)之间由 Fields Index 与若干条 Fields 记录组成。Fields Index 由uint64值F1, F2, ...构成每个值指向 Fields 区中一条记录的偏移(...) [F] [F F#] | Fields | Fields Index. | ||| | | | | |~~~~~~~~|~~~~~~~~|---...---|||--------|--------|...|--------|| ||-| Dict | Length | Name ||| 0 | 1 | | F# - 1 || || |~~~~~~~~|~~~~~~~~|---...---|||--------|----|---|...|--------|| || | | | ||||| | | |----------------------------------------------|字段数量由公式F# (len(file) - len(footer) - F) / sizeof(uint64)计算得出——即 Fields Index 的总字节数除以每个槽位的 8 字节。每条 Fields 记录包含Dictvarint该字段词项词典dictionary所在位置Lengthvarint字段名的字节长度Name任意长度字段名字符串本身。写入侧同样记录在 README.md 的 fields section 与 fields idx写 Fields 时先记住每个字段的起始偏移再写入词典地址varint、字段名长度varint、字段名字节随后写 Fields Index按字段顺序写大端 uint64 偏移。一个值得注意的细节是目前格式不记录 Fields Index 的长度而是依赖它紧邻已知大小的 footer 之前这一事实来推导——这也是 README.md 明确标注的 NOTE。源码 persistFields 完整复现了每条字段记录dictLoc 名称长度 varint 名称字节→ 再统一写 Fields IndexBigEndian uint64 偏移数组的顺序。Dictionaries Postings倒排索引的核心每个字段拥有独立的词项词典词典以Vellum格式编码一种 FST 有限状态转换器内容是(term, offset)二元组其中offset指向该词项对应 Postings文档列表在文件中的位置||- Dictionaries | | Postings | | DocValues | Freq/Norm (chunked) | | [~~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] | | |-[ Freq | Norm (float32 under varint) ] | | | [~~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] | | | | | |------------------------------------------------------------| | | Location Details (chunked) | | | [~~~~~~|~~~~~|~~~~~~~|~~~~~|~~~~~~|~~~~~~~~|~~~~~] | | | |-[ Size | Pos | Start | End | Arr# | ArrPos | ... ] | | | | [~~~~~~|~~~~~|~~~~~~~|~~~~~|~~~~~~|~~~~~~~~|~~~~~] | | | | | | | |----------------------| | | | Postings List | | | | |~~~~~~~~|~~~~~|~~|~~~~~~~~|-----------...--| | | | |-| F/N | LD | Length | ROARING BITMAP | | | | | |~~~~~|~~|~~~~~~~~|~~~~~~~~|-----------...--| | | | | |----------------------------------------------| | | |--------------------------------------| | | Dictionary | | | |~~~~~~~~|--------------------------|-...-| | | |-| Length | VELLUM DATA : (TERM - OFFSET) | | | | |~~~~~~~~|----------------------------...-| | | | | |||- DocValues Index | | | |||- Fields | | | | |~~~~|~~~|~~~~~~~~|---...---| | | | Dict | Length | Name | | | |~~~~~~~~|~~~~~~~~|---...---| | | | ||Postings ListRoaring Bitmap 承载文档集合每条 Postings List 依次包含F/NvarintFreq/Norm 细节数据块的偏移LDvarintLocation 细节数据块的偏移Lengthvarint后续 roaring bitmap 序列化后的字节长度ROARING BITMAP任意长度以 Roaring Bitmap 编码的命中文档号集合。源码 writeRoaringWithLen 与此一一对应先将 bitmap 序列化为字节、以 varint 写出长度再写出 bitmap 字节。Freq/Norm分块词频与归一化因子Freq/Norm 数据采用 chunked 布局每个 chunk 是 varint 流。对 Postings 中的每个命中若该命中属于下一个 chunk则结束当前 chunk 编码并记录下一个 chunk 的起始偏移编码词频term frequencyuint64编码归一化因子norm factorfloat32以 varint 形式存放。写盘时先记录该 Postings 细节数据的起始位置再依次写出 chunk 数量varint uint64、每个 chunk 的长度各一个 varint uint64、包含全部 chunk 数据的字节切片。得益于分块设计已知文档号时可以直接跳到docNum / chunkFactor对应的 chunk再在 chunk 内顺序寻找目标命中——这也是 footer 中 Chunk Factor 字段的用途。Location Details分块词项位置信息同样采用 chunked 布局为每个命中编码Size后续数组元素的数量信息varint 编码整体大小Pos字段内位置uint64Start起始偏移uint64End结束偏移uint64Arr#数组位置数量uint64ArrPos每个数组位置各一个 uint64。Location 信息支撑了短语查询、邻近查询与高亮等功能文档同时提示若需要位置信息先查询位置 bitmap 判断其是否存在见 README.md。DocValues面向排序聚合的列式存储DocValues Index每字段一对 varintDocValues Index 位于 DocValues 区域之后由F#对 varint 组成每字段一对每对 varint 给出该字段 DocValues 切片在文件中的起始与结束位置|| | |------...--| | | |-| DocValues |-| | | | |------...--| | | ||||- DocValues Index ||~|~~~~~~~~~|~~~~~~~|~~| |~~~~~~~~~~~~~~|~~~~~~~~~~~~|| || DV1 START | DV1 STOP | . . . . . | DV(F#) START | DV(F#) END || ||~~~~~~~~~~~|~~~~~~~~~~| |~~~~~~~~~~~~~~|~~~~~~~~~~~~|| ||DocValues 数据分块 Snappy 压缩的列式值每个字段的 DocValues 是对文档 × 字段取值的分块压缩存储每个 chunk 的结构为[~~~~~~~~~~~~~~~|~~~~~~|~~~~~~~~~|-...-|~~~~~~|~~~~~~~~~|--------------------...-] [ Doc# in Chunk | Doc1 | Offset1 | ... | DocN | OffsetN | SNAPPY COMPRESSED DATA ] [~~~~~~~~~~~~~~~|~~~~~~|~~~~~~~~~|-...-|~~~~~~|~~~~~~~~~|--------------------...-]chunk 头部列出 chunk 内的文档号列表及每个文档值的偏移随后是 Snappy 压缩后的实际取值数据。而整个 DocValues 数据区的最后 16 字节是 chunk 的描述信息|~~~~~~~~~~~~...~|----------------|----------------| | Chunk Sizes | Chunk Size Arr | Chunk# | |~~~~~~~~~~~~...~|----------------|----------------|写入侧流程见 README.md 的 fields DocValue先为每个字段生成若干连续 chunk每个 chunk 由 meta 段 压缩后的列式字段数据组成并记录每个 chunk 的长度写盘时先记住该字段首个 DocValue 偏移在 footer 中的位置再写出 chunk 数量varint、每个 chunk 长度varint、全部 chunk 数据。文档特别标注chunk 内的 meta 头部包含了指定 docID 数据的偏移与大小线索任何读取操作都依赖这份 meta 信息从文件中提取对应文档的数据——这正是 DocValues 能够按文档号高效定位列值的机制也是排序sort、聚合facet等操作在扫描时不必解压全列的根基。单遍写入策略为什么文件是倒着组织的zap.md呈现的布局看似复杂实则服务于一个简单目标——单遍顺序写入。README 对此解释得很直白文件以我们访问数据的相反顺序写出。这有助于单遍写入因为文件中靠后的区域需要引用已经写好的内容的文件偏移量。结合上文各区域的写入顺序可以串出完整链条先写每篇文档的 Stored Fields Data此刻即可记录各自偏移写 Stored Fields Index引用第 1 步的偏移写每个字段的 Freq/Norm 与 Location 细节块记录偏移→ Postings List引用细节块偏移内含 Roaring Bitmap→ DictionaryVellum FST 指向 Postings List 偏移写 DocValues记录每字段偏移→ DocValues Index写 Fields 记录引用词典偏移→ Fields Index最后写 footer一次性回填文档数、三个关键偏移、chunk factor、版本号与 CRC-32。每一层都只引用已经在文件中更靠前位置写完的数据偏移因此全程只需一次顺序写盘。读取侧则完全反向从 footer 出发按需沿着偏移链下钻。这一写入顺序即访问顺序之镜像的设计配合 mmap 随机访问与 Snappy 压缩构成了 OpenCloud 全文搜索索引在磁盘上紧凑、自描述且可快速重建的底层基础。在 OpenCloud 中的实际位置与延伸阅读在 OpenCloud 中ZAP 段文件并非被直接触碰而是作为 Bleve/Scorch 索引引擎的落盘格式被间接使用搜索服务在 services/search/pkg/bleve/index.go 中构建索引映射并通过bleve.NewIndex打开索引在 services/search/pkg/bleve/backend.go 中以bleve.NewSearchRequest执行查询索引数据最终以 ZAP 段文件形式持久化。对该格式的读取路径可从 read.goStored Fields 定位与 write.gofooter 与字段区写入继续深入配合 segment.go、posting.go、docvalues.go 等实现文件即可完整还原footer → Fields Index → 字段 → 词典 → Postings / DocValues的整个索引导航链路。【免费下载链接】opencloud️ OpenCloud is the open source platform for file management, sharing and collaboration. Simple and sovereign.项目地址: https://gitcode.com/GitHub_Trending/op/opencloud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
深入解析 ZAP 段文件格式：OpenCloud 搜索引擎底层索引的二进制布局
深入解析 ZAP 段文件格式OpenCloud 搜索引擎底层索引的二进制布局【免费下载链接】opencloud️ OpenCloud is the open source platform for file management, sharing and collaboration. Simple and sovereign.项目地址: https://gitcode.com/GitHub_Trending/op/opencloudZAPZap Advanced Postings是 Bleve 搜索引擎家族scorch 索引引擎使用的不可变段文件segment格式本指南以当前仓库 vendored 的zapx/v12实现及其官方格式文档 zap.md 为主线逐字节剖析其文件布局、footer 解析入口、Stored Fields、倒排词典与 Postings、DocValues 五大核心区域。读完本文你将能够理解一个 ZAP 段文件在磁盘上的完整组织方式并结合 write.go 与 read.go 的源码印证先写数据、后写索引、最后写 footer的单遍写入策略以及它在 OpenCloud 搜索服务中的实际落地位置。ZAP 格式的背景从 bleve 到 zapx/v12zapx模块是经典 zap。在 OpenCloud 仓库中该模块被 vendored 在 vendor/github.com/blevesearch/zapx/v12与主项目 go.mod 中的github.com/blevesearch/bleve/v2 v2.6.1、github.com/blevesearch/scorch_segment_api/v2 v2.4.10配套见 go.mod。OpenCloud 的全文搜索服务在 services/search/pkg/bleve 中通过bleve.NewIndexindex.go与bleve.NewSearchRequestbackend.go构建索引并执行查询而 ZAP 正是这一层索引落盘时所使用的底层段文件格式——理解 ZAP 布局就等于理解 OpenCloud 搜索索引文件的内部构造。格式图例五种基本约定zap.md文档首先用一套 ASCII 图例统一定义了后续所有结构图中出现的基本元素是阅读本文后续所有布局图的前提图例含义\|\|Section区域一个完整的功能区块如 Stored Fields、Fields、DocValues 等\|----\|Fixed-size field定长字段宽度即类型如uint64(8B)、uint32(4B)、uint16(2B)、uint8(1B)均为大端big endian编码\|~~~~\|Varint变长整数编码范围可达uint64长度不定用于压缩数值空间\|----...---\|Arbitrary-length field任意长度字段字符串、vellum FST 数据、roaring bitmap 等[----]Chunked data分块数据以若干 chunk 连续排布配合独立的 chunk 偏移表实现按文档号随机定位文件总览footer 驱动的自底向上布局ZAP 文件整体采用自底向上、由 footer 统领的布局。整个文件的物理排布从文件末尾向文件头方向依次是|| | Stored Fields | || |----- | Stored Fields Index | | || | | Dictionaries Postings DocValues | | || | |--- | DocValues Index | | | || | | | Fields | | | || | | |- | Fields Index | | | | |||||||| | | | | D# | SF | F | FDV | CF | V | CC | (Footer) | | | ||||||||||| | | | | | | |-------------------| | | | |--------------------------| | |-------------------------------------|文件末尾的Footer是进入整个文件的唯一入口它记录了其他所有区域的位置因此解析任何 ZAP 文件的第一个动作都是先读 footer、再顺着其中的偏移量导航到目标区域。在 README.md 的Current usage一节中官方进一步明确了读取惯例整个文件被mmap映射到内存CRC-32 校验值与版本号固定在文件末尾的固定位置footer 的剩余部分按版本解析即zap.mdOverview 中强调的footer 格式版本相关footer 提供 3 个关键偏移量DocValue 偏移、Fields Index 偏移、Stored Fields Index 偏移与 2 个关键值文档数、chunk factor字段数据field data只处理一次并被缓存到堆上此后不再回读磁盘按文档号访问 Stored Fields 时先进入 Stored Fields Index再读取定长偏移槽位定位实际数据地址数据段开头的长度字段用于界定数据边界。这一footer 定天下的设计直接决定了 ZAP 文件可以单遍顺序写出因为 footer 中记录的偏移量全部指向已经写完的数据写盘过程可以一路向前最后再回填 footer。Footer版本依赖的解析入口Footer 占据文件最末的固定 44 字节各字段按大端序依次排布缩写含义宽度D#Number of Docs文档总数uint64SFStored Fields Index OffsetStored Fields 索引偏移uint64FField Index OffsetFields 索引偏移uint64FDVField DocValue Offset字段 DocValues 偏移uint64CFChunk Factor分块因子uint32VVersion版本号uint32CCCRC32文件 CRC 校验uint32其含义在源码中得到精确印证。FooterSize常量在 write.go 中被明确注释为// FooterSize is the size of the footer record in bytes // crc ver chunk field offset stored offset num docs docValueOffset const FooterSize 4 4 4 8 8 8 8即 44 字节而 persistFooter 函数逐字段完成写入依次写入numDocs、storedIndexOffset、fieldsIndexOffset、docValueOffset均为 BigEndian uint64、chunkModeBigEndian uint32、VersionBigEndian uint32最后写入不包含本字段之前所有字节的 CRC-32 校验值。由于版本号固定位于距文件末尾固定位置处读者可以先读取V字段判断格式版本再决定如何解析 footer 的其余部分——这正是文档footer 格式版本相关解析前必须检查 V 字段的原因。Stored Fields原始字段值的随机访问Stored Fields Index定长偏移表Stored Fields Index 由D#个连续的 64 位无符号整数构成每个整数是某篇文档document的 Stored Fields Data 记录在文件中的起始偏移量0 [SF] [SF D# * 8] | Stored Fields | Stored Fields Index | ||| | | | | |--------------------| ||--------|--------|. . .|--------|| | |- | Stored Fields Data | || 0 | 1 | | D# - 1 || | | |--------------------| ||--------|----|---|. . .|--------|| | | | | | ||||| | | |-------------------------------------------|由于每个槽位定长 8 字节给定文档号docNum时其 Stored Fields 偏移即位于SF docNum * 8。这一点在 read.go 的getDocStoredOffsets中直接体现indexOffset : s.storedIndexOffset (8 * docNum) storedOffset : binary.BigEndian.Uint64(s.mem[indexOffset : indexOffset8])先读出数据区偏移storedOffset随后在该地址处依次解码两个 varintmetaLen元数据长度与dataLen压缩数据长度据此界定元数据与数据的边界。Stored Fields Data元数据 Snappy 压缩负载每一条 Stored Fields Data 是任意大小的记录由元数据和 Snappy 压缩后的数据两部分组成Stored Fields Data |~~~~~~~~|~~~~~~~~|~~~~~~~~...~~~~~~~~|~~~~~~~~...~~~~~~~~| | MDS | CDS | MD | CD | |~~~~~~~~|~~~~~~~~|~~~~~~~~...~~~~~~~~|~~~~~~~~...~~~~~~~~| MDS. Metadata size.元数据长度 CDS. Compressed data size.压缩数据长度 MD. Metadata.元数据 CD. Snappy-compressed data.Snappy 压缩数据写入侧的完整流程记录在 README.md 的 stored fields section 中可分两个阶段准备阶段对每篇文档生成一段元数据字节与一段数据字节字段按 field id 顺序排列字段值追加进数据切片元数据切片对每个字段值以 varint 编码以下信息——字段 iduint16、字段类型1 字节、字段值在未压缩数据切片中的起始偏移uint64、字段值长度uint64、数组位置数量uint64以及每个数组位置各一个 uint64最后对数据切片做 Snappy 压缩。写盘阶段记录本文档数据的起始偏移依次写出元数据长度varint uint64、压缩数据长度varint uint64、元数据字节、压缩数据字节。配合 Stored Fields Index只要知道文档号就能对任意文档的原始字段值做 O(1) 直接访问这是搜索结果中高亮片段、原始字段回显等能力的基础。Fields字段名与字段元信息的登记区Fields 区域位于地址F与len(file) - len(footer)之间由 Fields Index 与若干条 Fields 记录组成。Fields Index 由uint64值F1, F2, ...构成每个值指向 Fields 区中一条记录的偏移(...) [F] [F F#] | Fields | Fields Index. | ||| | | | | |~~~~~~~~|~~~~~~~~|---...---|||--------|--------|...|--------|| ||-| Dict | Length | Name ||| 0 | 1 | | F# - 1 || || |~~~~~~~~|~~~~~~~~|---...---|||--------|----|---|...|--------|| || | | | ||||| | | |----------------------------------------------|字段数量由公式F# (len(file) - len(footer) - F) / sizeof(uint64)计算得出——即 Fields Index 的总字节数除以每个槽位的 8 字节。每条 Fields 记录包含Dictvarint该字段词项词典dictionary所在位置Lengthvarint字段名的字节长度Name任意长度字段名字符串本身。写入侧同样记录在 README.md 的 fields section 与 fields idx写 Fields 时先记住每个字段的起始偏移再写入词典地址varint、字段名长度varint、字段名字节随后写 Fields Index按字段顺序写大端 uint64 偏移。一个值得注意的细节是目前格式不记录 Fields Index 的长度而是依赖它紧邻已知大小的 footer 之前这一事实来推导——这也是 README.md 明确标注的 NOTE。源码 persistFields 完整复现了每条字段记录dictLoc 名称长度 varint 名称字节→ 再统一写 Fields IndexBigEndian uint64 偏移数组的顺序。Dictionaries Postings倒排索引的核心每个字段拥有独立的词项词典词典以Vellum格式编码一种 FST 有限状态转换器内容是(term, offset)二元组其中offset指向该词项对应 Postings文档列表在文件中的位置||- Dictionaries | | Postings | | DocValues | Freq/Norm (chunked) | | [~~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] | | |-[ Freq | Norm (float32 under varint) ] | | | [~~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] | | | | | |------------------------------------------------------------| | | Location Details (chunked) | | | [~~~~~~|~~~~~|~~~~~~~|~~~~~|~~~~~~|~~~~~~~~|~~~~~] | | | |-[ Size | Pos | Start | End | Arr# | ArrPos | ... ] | | | | [~~~~~~|~~~~~|~~~~~~~|~~~~~|~~~~~~|~~~~~~~~|~~~~~] | | | | | | | |----------------------| | | | Postings List | | | | |~~~~~~~~|~~~~~|~~|~~~~~~~~|-----------...--| | | | |-| F/N | LD | Length | ROARING BITMAP | | | | | |~~~~~|~~|~~~~~~~~|~~~~~~~~|-----------...--| | | | | |----------------------------------------------| | | |--------------------------------------| | | Dictionary | | | |~~~~~~~~|--------------------------|-...-| | | |-| Length | VELLUM DATA : (TERM - OFFSET) | | | | |~~~~~~~~|----------------------------...-| | | | | |||- DocValues Index | | | |||- Fields | | | | |~~~~|~~~|~~~~~~~~|---...---| | | | Dict | Length | Name | | | |~~~~~~~~|~~~~~~~~|---...---| | | | ||Postings ListRoaring Bitmap 承载文档集合每条 Postings List 依次包含F/NvarintFreq/Norm 细节数据块的偏移LDvarintLocation 细节数据块的偏移Lengthvarint后续 roaring bitmap 序列化后的字节长度ROARING BITMAP任意长度以 Roaring Bitmap 编码的命中文档号集合。源码 writeRoaringWithLen 与此一一对应先将 bitmap 序列化为字节、以 varint 写出长度再写出 bitmap 字节。Freq/Norm分块词频与归一化因子Freq/Norm 数据采用 chunked 布局每个 chunk 是 varint 流。对 Postings 中的每个命中若该命中属于下一个 chunk则结束当前 chunk 编码并记录下一个 chunk 的起始偏移编码词频term frequencyuint64编码归一化因子norm factorfloat32以 varint 形式存放。写盘时先记录该 Postings 细节数据的起始位置再依次写出 chunk 数量varint uint64、每个 chunk 的长度各一个 varint uint64、包含全部 chunk 数据的字节切片。得益于分块设计已知文档号时可以直接跳到docNum / chunkFactor对应的 chunk再在 chunk 内顺序寻找目标命中——这也是 footer 中 Chunk Factor 字段的用途。Location Details分块词项位置信息同样采用 chunked 布局为每个命中编码Size后续数组元素的数量信息varint 编码整体大小Pos字段内位置uint64Start起始偏移uint64End结束偏移uint64Arr#数组位置数量uint64ArrPos每个数组位置各一个 uint64。Location 信息支撑了短语查询、邻近查询与高亮等功能文档同时提示若需要位置信息先查询位置 bitmap 判断其是否存在见 README.md。DocValues面向排序聚合的列式存储DocValues Index每字段一对 varintDocValues Index 位于 DocValues 区域之后由F#对 varint 组成每字段一对每对 varint 给出该字段 DocValues 切片在文件中的起始与结束位置|| | |------...--| | | |-| DocValues |-| | | | |------...--| | | ||||- DocValues Index ||~|~~~~~~~~~|~~~~~~~|~~| |~~~~~~~~~~~~~~|~~~~~~~~~~~~|| || DV1 START | DV1 STOP | . . . . . | DV(F#) START | DV(F#) END || ||~~~~~~~~~~~|~~~~~~~~~~| |~~~~~~~~~~~~~~|~~~~~~~~~~~~|| ||DocValues 数据分块 Snappy 压缩的列式值每个字段的 DocValues 是对文档 × 字段取值的分块压缩存储每个 chunk 的结构为[~~~~~~~~~~~~~~~|~~~~~~|~~~~~~~~~|-...-|~~~~~~|~~~~~~~~~|--------------------...-] [ Doc# in Chunk | Doc1 | Offset1 | ... | DocN | OffsetN | SNAPPY COMPRESSED DATA ] [~~~~~~~~~~~~~~~|~~~~~~|~~~~~~~~~|-...-|~~~~~~|~~~~~~~~~|--------------------...-]chunk 头部列出 chunk 内的文档号列表及每个文档值的偏移随后是 Snappy 压缩后的实际取值数据。而整个 DocValues 数据区的最后 16 字节是 chunk 的描述信息|~~~~~~~~~~~~...~|----------------|----------------| | Chunk Sizes | Chunk Size Arr | Chunk# | |~~~~~~~~~~~~...~|----------------|----------------|写入侧流程见 README.md 的 fields DocValue先为每个字段生成若干连续 chunk每个 chunk 由 meta 段 压缩后的列式字段数据组成并记录每个 chunk 的长度写盘时先记住该字段首个 DocValue 偏移在 footer 中的位置再写出 chunk 数量varint、每个 chunk 长度varint、全部 chunk 数据。文档特别标注chunk 内的 meta 头部包含了指定 docID 数据的偏移与大小线索任何读取操作都依赖这份 meta 信息从文件中提取对应文档的数据——这正是 DocValues 能够按文档号高效定位列值的机制也是排序sort、聚合facet等操作在扫描时不必解压全列的根基。单遍写入策略为什么文件是倒着组织的zap.md呈现的布局看似复杂实则服务于一个简单目标——单遍顺序写入。README 对此解释得很直白文件以我们访问数据的相反顺序写出。这有助于单遍写入因为文件中靠后的区域需要引用已经写好的内容的文件偏移量。结合上文各区域的写入顺序可以串出完整链条先写每篇文档的 Stored Fields Data此刻即可记录各自偏移写 Stored Fields Index引用第 1 步的偏移写每个字段的 Freq/Norm 与 Location 细节块记录偏移→ Postings List引用细节块偏移内含 Roaring Bitmap→ DictionaryVellum FST 指向 Postings List 偏移写 DocValues记录每字段偏移→ DocValues Index写 Fields 记录引用词典偏移→ Fields Index最后写 footer一次性回填文档数、三个关键偏移、chunk factor、版本号与 CRC-32。每一层都只引用已经在文件中更靠前位置写完的数据偏移因此全程只需一次顺序写盘。读取侧则完全反向从 footer 出发按需沿着偏移链下钻。这一写入顺序即访问顺序之镜像的设计配合 mmap 随机访问与 Snappy 压缩构成了 OpenCloud 全文搜索索引在磁盘上紧凑、自描述且可快速重建的底层基础。在 OpenCloud 中的实际位置与延伸阅读在 OpenCloud 中ZAP 段文件并非被直接触碰而是作为 Bleve/Scorch 索引引擎的落盘格式被间接使用搜索服务在 services/search/pkg/bleve/index.go 中构建索引映射并通过bleve.NewIndex打开索引在 services/search/pkg/bleve/backend.go 中以bleve.NewSearchRequest执行查询索引数据最终以 ZAP 段文件形式持久化。对该格式的读取路径可从 read.goStored Fields 定位与 write.gofooter 与字段区写入继续深入配合 segment.go、posting.go、docvalues.go 等实现文件即可完整还原footer → Fields Index → 字段 → 词典 → Postings / DocValues的整个索引导航链路。【免费下载链接】opencloud️ OpenCloud is the open source platform for file management, sharing and collaboration. Simple and sovereign.项目地址: https://gitcode.com/GitHub_Trending/op/opencloud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
