Milvus Binlog 存储格式完全解析：Insert/Delete/DDL 三类日志的文件结构、事件编码与读写实现

Milvus Binlog 存储格式完全解析：Insert/Delete/DDL 三类日志的文件结构、事件编码与读写实现

【免费下载链接】milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search项目地址: https://gitcode.com/GitHub_Trending/mi/milvus

导读

本文基于 Milvus 开源仓库中的官方开发者指南《Binlog》章节，系统讲解 Milvus 中InsertBinlog、DeleteBinlog、DDLBinlog三类二进制日志文件的磁盘存储格式：从"列式存储、一列一个文件"的整体布局，到 4 字节魔数、事件头、Descriptor 描述事件、JSON 格式ExtraBytes扩展信息，再到各类事件类型码的合法组合，最后结合仓库中 internal/storage 下的 Go 实现与测试，给出可在工程实践中复用的字节级读写与 C++ Payload 接口参考。读完本文，你将能够读懂任意一个 binlog 文件的字节布局，理解数据插入、删除与 DDL 记录在底层是如何落盘与回放的。

关联原始文档：docs/archive/milvus-2.0/developer_guides/chap08_binlog.md

一、Binlog 在 Milvus 存储体系中的定位

在 Milvus 的数据链路中，每个数据段（segment）最终落盘的对象存储文件主要分为三类，正好对应文档开篇给出的三个概念：

• InsertBinlog：保存插入的数据记录，是所有列数据的主体载体；
• DeleteBinlog：保存按主键删除的记录，用于查询时过滤掉已被删除的行；
• DDLBinlog：保存集合/分区的 DDL（建集合、删集合、建分区、删分区）操作记录。

在仓库当前的 binlog_writer.go 中，这一分类被进一步扩展为BinlogType枚举，且枚举从 0 起依次递增，前三个值正好对应本文的三类日志：

1.1 列式存储：Schema 中每一列单独一个文件

Binlog 采用列式（columnar）存储格式，Schema 中声明的每个字段都会被写入各自独立的文件中。这样设计带来的直接收益是：读取某一列参与过滤/投影时不需要扫描整行数据，也便于对单列做独立的压缩与编码。

文档强调，除用户自定义字段外，还有四个由系统分配的特殊列：

• Timestamp：记录行的写入时间戳；
• Schema：记录该集合的 DDL（建表结构），是结构演进的源头信息；
• Row ID：系统为每行分配的唯一内部自增 ID（即 rowid）；
• Primary Key：用户声明的主键（Milvus 目前只支持按主键删除）。

也就是说，一个"看起来只有几个字段"的集合，落盘后的 binlog 文件集会包含上述特殊列的独立文件。这一点在本文第五章的"Example"中会通过实际例子直观呈现。

二、文件总体结构：魔数 + 事件流

一个 binlog 文件的整体结构非常简单统一：

+============================+=================================================+ | 4 bytes Magic Number | 用于识别文件是否为合法 binlog | +----------------------------+-------------------------------------------------+ | Descriptor Event | 首个事件，必须存在，描述整个文件与数据 schema | +----------------------------+-------------------------------------------------+ | Event 1..N | 一系列数据事件（如 INSERT_EVENT / DELETE_EVENT） | +============================+=================================================+

当前仓库将魔数定义为MagicNumber int32 = 0xfffabc，见 binlog_writer.go。在读取侧 binlog_reader.go 中，readMagicNumber会逐字节读出该值并与MagicNumber比对，若不匹配则直接报错parse magic number failed, expected: ..., actual: ...，用于快速识别损坏或非 binlog 文件。

一个合法的 binlog 文件必须满足两条硬性约束：

1. Descriptor Event 必须在所有列文件中出现，且永远是第一个事件；
2. 紧随其后的是数量不定的普通数据事件，事件之间首尾相接，通过事件头中的NextPosition实现顺序遍历。

三、事件格式（Event Format）

文档将事件划分为**事件头（event header）与事件数据（event data）**两部分。事件头是 17 字节的定长结构，字段布局如下（offset : length，单位为字节）：

+=====================================+=====================================================================+ | event | Timestamp 0 : 8 | create timestamp（事件创建/写入时间戳） | | header +----------------------------+---------------------------------------------------------------------+ | | TypeCode 8 : 1 | 事件类型码 | | +----------------------------+---------------------------------------------------------------------+ | | EventLength 9 : 4 | 事件总长度，包含 header 与 data | | +----------------------------+---------------------------------------------------------------------+ | | NextPosition 13 : 4 | 下一个事件相对文件起始位置的偏移量 | +=====================================+=====================================================================+ | event | fixed part 17 : x | 事件数据定长部分 | | data +----------------------------+---------------------------------------------------------------------+ | | variable part | 事件数据变长部分（payload） | +=====================================+=====================================================================+

在仓库当前实现 event_header.go 中，该头部被建模为baseEventHeader结构体，四个字段与文档一一对应：

type baseEventHeader struct { Timestamp typeutil.Timestamp // 8 字节时间戳 TypeCode EventTypeCode // 1 字节类型码 EventLength int32 // 4 字节事件总长度 NextPosition int32 // 4 字节下一事件偏移 }

其中Timestamp由tsoutil.ComposeTS生成，是一个高 40 位物理毫秒时间、低 24 位逻辑序号的混合时间戳（见 event_header.go，新建普通事件时长度与偏移先被置为-1，待Finish后再回填，见 event_writer.go）。

事件头的作用：EventLength让读者可以安全地跳过或校验一个事件；NextPosition则串起事件流，给出严格递增的定位锚点，是顺序回放 binlog 的基础。仓库测试 binlog_test.go 中专门断言了"第一个事件之后NextPosition == DescriptorEventLen + MagicNumber 大小"这一不变量，印证了偏移量是以文件起始为基准计算的。

3.1 TypeCode 完整取值

文档给出的事件类型码如下，并在当前仓库 event_writer.go 中以连续 iota 方式枚举：

DESCRIPTOR_EVENT INSERT_EVENT DELETE_EVENT CREATE_COLLECTION_EVENT DROP_COLLECTION_EVENT CREATE_PARTITION_EVENT DROP_PARTITION_EVENT INDEX_FILE_EVENT

Go 侧对应常量名依次为DescriptorEventType、InsertEventType、DeleteEventType、CreateCollectionEventType、DropCollectionEventType、CreatePartitionEventType、DropPartitionEventType、IndexFileEventType，并以EventTypeEnd作为迭代终止哨兵——构造 Descriptor 时正是靠它遍历计算出每种事件的定长头部大小并写入PostHeaderLengths。

四、Descriptor Event：文件的"自描述"头部

Descriptor Event 是理解 binlog 的关键。它除 17 字节公共事件头外，还带一段定长的固定数据部分以及变长的扩展信息，整体布局如下：

+=====================================+=====================================================================+ | event | Timestamp 0 : 8 | create timestamp | | header +----------------------------+---------------------------------------------------------------------+ | | TypeCode 8 : 1 | event type code（此处应为 DESCRIPTOR_EVENT） | | +----------------------------+---------------------------------------------------------------------+ | | EventLength 9 : 4 | 事件总长度，包含 header 与 data | | +----------------------------+---------------------------------------------------------------------+ | | NextPosition 13 : 4 | 下一事件偏移 | +=====================================+=====================================================================+ | event | CollectionID 17 : 8 | collection id | | data +----------------------------+---------------------------------------------------------------------+ | | PartitionID 25 : 8 | partition id（schema 列文件不需要） | | +----------------------------+---------------------------------------------------------------------+ | | SegmentID 33 : 8 | segment id（schema 列文件不需要） | | +----------------------------+---------------------------------------------------------------------+ | | FieldID 41 : 8 | field id（schema 列文件不需要） | | +----------------------------+---------------------------------------------------------------------+ | | StartTimestamp 49 : 8 | 本文件所有事件中最小的（由 master 分配的）时间戳 | | +----------------------------+---------------------------------------------------------------------+ | | EndTimestamp 57 : 8 | 本文件所有事件中最大的（由 master 分配的）时间戳 | | +----------------------------+---------------------------------------------------------------------+ | | PayloadDataType 65 : 4 | payload 的数据类型（对应 schemapb.DataType） | | +----------------------------+---------------------------------------------------------------------+ | | PostHeaderLengths n : n | 所有事件类型的定长 data 头长度表 | | +----------------------------+---------------------------------------------------------------------+ | | ExtraLength 69 : 4 | ExtraBytes 的长度（n） | | +----------------------------+---------------------------------------------------------------------+ | | ExtraBytes 73 : n | 扩展信息，JSON 格式 | +=====================================+=====================================================================+

对应到当前仓库 event_data.go，固定部分被建模为DescriptorEventDataFixPart，字段完全一致：

type DescriptorEventDataFixPart struct { CollectionID int64 PartitionID int64 SegmentID int64 FieldID int64 StartTimestamp typeutil.Timestamp EndTimestamp typeutil.Timestamp PayloadDataType schemapb.DataType }

几个值得注意的实现细节：

• PostHeaderLengths是一张"每种事件类型的 data 定长头大小"查表，由构造函数遍历DescriptorEventType至EventTypeEnd自动生成（见 event_data.go）。读者拿到 Descriptor 后即可据此推算出后续每个事件的定长部分边界；
• newDescriptorEventData会将CollectionID/PartitionID/SegmentID/FieldID预置为-1、PayloadDataType预置为-1，表示"未知"，后续由上层写入者填充（event_data.go）；
• 写入侧构造InsertBinlogWriter等对象时，会把这些 ID、数据类型以及可空性（nullable）写入 Descriptor（见 binlog_writer.go）。

4.1 ExtraBytes：JSON 扩展机制与兼容性设计

ExtraBytes以 JSON 格式保存 binlog 文件的扩展信息。为什么需要它？因为 Descriptor 的固定部分只能承载CollectionID/PartitionID/...这类"所有 binlog 共有的信息"，而不同用途的 binlog 往往携带彼此不同的附加元数据：

• 例如索引 binlog（IndexFileBinlog），会在ExtraBytes中记录indexID、indexBuildID等索引相关字段；
• 例如记录了字段是否**可空（nullable）**的标记，让老版本 reader 也能兼容新写的可空列文件；
• 例如字段级加密场景下的edek与encryption_zone（详见下文源码佐证）。

ExtraBytes的第二重使命是为格式演进预留兼容通道：后续想给 binlog 增加新特性时，只需向 JSON 中追加新 key，而不必破坏既有文件的二进制布局。文档以"把编码前原始内容的内存大小写入ExtraBytes，key 为original_size"为例，并强调：在当时的版本中original_size是必填而非可选的。

这一约束在当前代码中仍然保留：FinishExtra在序列化前强制校验Extras中必须存在original_size，且其值必须是字符串形式的可解析整数——注释中解释了原因：若直接存大整数，Go 的 JSON 序列化可能输出科学计数法导致回读为 float，因此统一用字符串规避（见 event_data.go）。

从源码看，如今仓库实际用到的 Extra key 集合已扩展为（event_data.go）：

读取侧readDescriptorEventData在读完ExtraBytes后立即json.Unmarshal成Extras字典，若 JSON 解析失败会抛出数据完整性错误（event_data.go）。AddExtra/FinishExtra的组合构成了"先收集、后序列化、再定长"的标准写入时序，上层通过descriptorEvent.AddExtra(...)注入自定义信息。

五、各事件类型的合法分布与事件数据（data）部分

5.1 事件类型使用规则

文档对八种事件类型的使用范围给出明确约束：

• DESCRIPTOR_EVENT：必须出现在所有列文件中，且始终是第一个事件；
• INSERT_EVENT：可出现在除 DDL binlog 之外的任何列 binlog 中；
• DELETE_EVENT：只能出现在主键列的 binlog 文件中（当前 Milvus 只能按主键删除）；
• CREATE_COLLECTION_EVENT / DROP_COLLECTION_EVENT / CREATE_PARTITION_EVENT / DROP_PARTITION_EVENT：只出现在 DDL binlog 文件中；
• INDEX_FILE_EVENT：用于索引文件日志。

5.2 事件数据部分格式

所有普通事件的数据部分结构"相似于" INSERT_EVENT，即"定长时间戳对 + 变长 payload"：

INSERT_EVENT data part: +================================================+==========================================================+ | event | fixed | StartTimestamp x : 8 | 本事件内最小时间戳 | | data | part +------------------------------+----------------------------------------------------------+ | | | EndTimestamp x+8 : 8 | 本事件内最大时间戳 | | +--------+------------------------------+----------------------------------------------------------+ | |variable| payload | 变长 payload（列数据主体） | | |part | | | +================================================+==========================================================+

在 event_data.go 中可以看到对应校验逻辑：insertEventData（以及deleteEventData等各类事件）在写盘前强制要求StartTimestamp与EndTimestamp均非 0，否则返回内部错误——保证任何事件都携带明确的时间范围，这是后续按时间戳做增量同步 / 一致性读的基础。

一个重要的演进点：文档写作时的 payload 描述为"parquet payload"，即 payload 部分以 Parquet 编码的列数据存放；在当前的 Milvus 中，payload 序列化已演进为存储格式版本控制（StorageV1等见 rw.go），底层大量使用 Apache Arrow/Parquet 体系（参见 payload.go 中的 parquet 依赖），但"Descriptor 自描述 + 事件头 + 变长列数据 payload"的总体框架保持一致。

5.3 典型 Schema 下的完整文件清单（官方 Example）

文档给出了一个非常直观的完整示例，假设集合 Schema 为：

string | int | float(可选，可空) | vector(512 维)

连续执行三类请求：

1. InsertRequest写入 1 万行（rows 1W）
2. DeleteRequest pk=1
3. DropPartition partitionTag="abc"

Insert binlogs（插入）—— 共 6 个文件：

rowid, pk, ts, string, int, float, vector ← 列式存储的体现

对应的实际分布是：rowid、pk、ts 三个系统特殊列加上 string、int、float、vector 四个用户字段（文档书写为 6 文件，实际枚举列名含 7 项，可理解为 6 个用户可见数据文件加时间戳列）。要点：

• 所有这些文件的事件类型都是 INSERT_EVENT；
• float 列为可选列，因此其文件内含有 NULL 值，读取时需要依赖 Descriptor 中的 nullable 标记按位图还原空值。

Delete binlogs（删除）—— pk 与 ts 两个文件：

• pk 文件中的事件是 DELETE_EVENT（记录被删除的主键）；
• ts 文件中的事件是INSERT_EVENT（时间戳列属于全量追加的列，删除语义通过 pk 表达）。

DDL binlogs—— ddl 与 ts 两个文件：

• ddl 文件中的事件是DROP_PARTITION_EVENT（记录"删除了名为 abc 的分区"这一操作）；
• ts 文件中的事件是 INSERT_EVENT。

5.4 事件合法组合速查表

六、面向 C++ 的 Payload 读写接口

文档为跨语言边界（C++ 内核与上层）设计了基于"句柄"的 C 风格接口。其核心抽象为三类句柄/结构：

typedef void* CPayloadWriter; // 列数据写入器句柄 typedef struct CBuffer { char* data; // 二进制缓冲区指针 int length; // 缓冲区长度 } CBuffer; typedef struct CStatus { // 统一的错误状态返回 int error_code; // 错误码，0 表示成功 const char* error_msg; // 错误信息 } CStatus;

6.1 Writer（写入侧）

// 按列类型创建 payload 写入器 CPayloadWriter NewPayloadWriter(int columnType); // 按列类型追加批量数据（类型与入参一一对应） CStatus AddBooleanToPayload(CPayloadWriter payloadWriter, bool *values, int length); CStatus AddInt8ToPayload(CPayloadWriter payloadWriter, int8_t *values, int length); CStatus AddInt16ToPayload(CPayloadWriter payloadWriter, int16_t *values, int length); CStatus AddInt32ToPayload(CPayloadWriter payloadWriter, int32_t *values, int length); CStatus AddInt64ToPayload(CPayloadWriter payloadWriter, int64_t *values, int length); CStatus AddFloatToPayload(CPayloadWriter payloadWriter, float *values, int length); CStatus AddDoubleToPayload(CPayloadWriter payloadWriter, double *values, int length); CStatus AddOneStringToPayload(CPayloadWriter payloadWriter, char *cstr, int str_size); CStatus AddBinaryVectorToPayload(CPayloadWriter payloadWriter, uint8_t *values, int dimension, int length); CStatus AddFloatVectorToPayload(CPayloadWriter payloadWriter, float *values, int dimension, int length); // 结束写入，得到最终二进制 buffer，随后释放句柄 CStatus FinishPayloadWriter(CPayloadWriter payloadWriter); CBuffer GetPayloadBufferFromWriter(CPayloadWriter payloadWriter); int GetPayloadLengthFromWriter(CPayloadWriter payloadWriter); CStatus ReleasePayloadWriter(CPayloadWriter handler);

写入的典型调用顺序是：NewPayloadWriter(columnType)→ 重复调用AddXxxToPayload(...)追加该列多行的值（字符串逐条AddOneStringToPayload，向量则一次给入values/dimension/length）→FinishPayloadWriter→ 取GetPayloadBufferFromWriter得到可直接塞入事件变长部分的字节 →ReleasePayloadWriter回收。

6.2 Reader（读取侧）

// 按列类型 + 缓冲区创建 payload 读取器 CPayloadReader NewPayloadReader(int columnType, uint8_t *buffer, int64_t buf_size); // 按列类型批量读出，values/长度由实现分配并回填 CStatus GetBoolFromPayload(CPayloadReader payloadReader, bool **values, int *length); CStatus GetInt8FromPayload(CPayloadReader payloadReader, int8_t **values, int *length); CStatus GetInt16FromPayload(CPayloadReader payloadReader, int16_t **values, int *length); CStatus GetInt32FromPayload(CPayloadReader payloadReader, int32_t **values, int *length); CStatus GetInt64FromPayload(CPayloadReader payloadReader, int64_t **values, int *length); CStatus GetFloatFromPayload(CPayloadReader payloadReader, float **values, int *length); CStatus GetDoubleFromPayload(CPayloadReader payloadReader, double **values, int *length); CStatus GetOneStringFromPayload(CPayloadReader payloadReader, int idx, char **cstr, int *str_size); CStatus GetBinaryVectorFromPayload(CPayloadReader payloadReader, uint8_t **values, int *dimension, int *length); CStatus GetFloatVectorFromPayload(CPayloadReader payloadReader, float **values, int *dimension, int *length); int GetPayloadLengthFromReader(CPayloadReader payloadReader); CStatus ReleasePayloadReader(CPayloadReader payloadReader);

读取侧值得注意的是GetOneStringFromPayload按行索引idx读取单条字符串（因为字符串是变长的），而数值/向量类型直接一次取出整块values数组与长度。这套接口是文档写作时（Milvus 2.0 时代）C++ 内核与上层交互的真实约定；当前仓库中同一职责已由 internal/storage 下的 Go 实现承担——PayloadWriterInterface提供等价的 Add/Get 系列方法并内聚在EventWriter接口中（见 event_writer.go），语义一一对应，可供对照阅读。

七、从文档到源码：仓库中的真实读写链路

为了印证文档格式描述与实现的对应关系，可以在当前仓库中沿着"写入 → 落盘 → 读取"完整走一遍：

写入侧（Writer 工厂）：binlog_writer.go 提供了三件套构造函数：

• NewInsertBinlogWriter(dataType, collectionID, partitionID, segmentID, fieldID, nullable, opts...)→ 返回InsertBinlogWriter，可通过NextInsertEventWriter追加 INSERT 事件（并顺带把 nullable 标记写入 Descriptor 的 Extra，见 binlog_writer.go）；
• NewDeleteBinlogWriter(...)→ 返回DeleteBinlogWriter，用于产出主键删除文件；
• IndexFileBinlogWriter对应索引文件。

baseBinlogWriter.Finish()（binlog_writer.go）完整实现了文档描述的文件骨架：先写 4 字节MagicNumber，随后写入 Descriptor 事件，再逐事件SetOffset → Finish → Write依次落盘并累计NextPosition与总行数。若配置了加密器，事件区还会整体加密后再写入（与 Descriptor 中edek/encryption_zone两 key 呼应）。

读取侧（Reader）：binlog_reader.go 的NewBinlogReader严格按格式顺序解析：readMagicNumber校验魔数 →ReadDescriptorEvent读出 Descriptor（含 Extra 的 JSON 反序列化）→ 通过NextEventReader逐个迭代后续事件。若文件带加密上下文，可通过WithReaderDecryptionContext(ezID, collectionID)选项自动解密（其内部依据 Descriptor 中的edek获取解密器）。nullable标记也会被取出并传给下层 EventReader，用于正确解析可空列。

数据编码封装：internal/storage/data_codec.go 在更上层把 rowid/pk/timestamp 等系统列与用户字段统一编码为上述各类 binlog 文件，是连接"内存行数据"与"磁盘列文件"的枢纽。

工程佐证（测试）：binlog_test.go 与 event_writer_test.go 用大量断言验证了格式关键点：魔数大小与首事件偏移关系（descNxtPos == descEventLen + sizeof(MagicNumber)）、ExtraLength回读一致性等。这些测试同时是"按文档手写一个 binlog 解析器"时最直观的对照样例。

实用工具：仓库的 cmd/tools/binlogv2 提供了基于 Python 的 MinIO/Parquet 分析脚本（minio_parquet_analyzer.py、export_to_json.py），可结合本文的格式知识直接查看某个 segment 的 binlog/parquet 实际内容，适合做学习与排障验证。

八、小结与延伸阅读

至此，可以完整回答"Milvus 的 binlog 到底长什么样"：

1. 每个文件 =0xfffabc魔数 + 一个必然位于首位的 Descriptor 事件 + 一串普通数据事件；
2. 每类事件 = 17 字节定长头（Timestamp / TypeCode / EventLength / NextPosition）+ 定长 data 头（StartTimestamp / EndTimestamp 等）+ 变长 payload；
3. Descriptor 通过固定字段 +PostHeaderLengths+ JSONExtraBytes让文件具备自描述与向前兼容能力；
4. Insert/Delete/DDL 三类日志分别以 INSERT / DELETE / 建删集合与分区事件承载语义，删除文件与 DDL 文件仅存在于主键列与 DDL 列，是 Milvus "只按主键删除、结构演进可回放"的实现基石。

进一步探索建议：

• 阅读关联文档原文 docs/archive/milvus-2.0/developer_guides/chap08_binlog.md；
• 对照 Go 实现细节：binlog_writer.go、binlog_reader.go、event_header.go、event_data.go；
• 关注 payload 层编码演进：payload.go 与 rw.go（存储格式版本控制）；
• 如需动手验证，可阅读测试 binlog_test.go 并结合 cmd/tools/binlogv2 分析实际对象存储中的 binlog 文件。

【免费下载链接】milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search项目地址: https://gitcode.com/GitHub_Trending/mi/milvus