Lance 仓库 Protobuf 指南持久化格式与执行计划 Schema 的设计、兼容性与变更流程【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lanceprotos/ 目录是 Lance 开放湖仓格式Open Lakehouse Format for Multimodal AI所有 Protobuf 契约的唯一权威来源它同时承载两类截然不同的协议持久化的磁盘格式如table.proto、file.proto、transaction.proto与跨进程/跨版本的执行计划线缆协议如ann.proto、filtered_read.proto、table_identifier.proto。本文基于 protos/CLAUDE.md 梳理 Lance 对 Protobuf 变更流程、兼容性契约、Schema 设计与注释风格的全部硬性要求并逐一对照 protos/ 目录下的真实.proto文件与 ci/check_proto_comments.py 检查器帮助你理解哪些改动必须走 PMC 投票、何时可以破坏兼容、optional字段的正确打开方式以及多行注释为何必须写成/* ... */块。两类 Protobuf 契约持久化格式与执行计划线缆Lance 仓库中的所有.proto文件并非同一性质protos/CLAUDE.md 开篇就做了关键区分这是理解后续所有规则的前提类别代表性文件性质变更是否要求格式投票持久化 Lance 格式table.proto、file.proto、file2.proto、encodings_v2_0.proto、encodings_v2_1.proto、rowids.proto、index.proto、index_old.proto、transaction.proto写入磁盘、长期留存的文件/表格式契约是需要 PMC 投票执行计划线缆协议ann.proto、filtered_read.proto、table_identifier.proto仅用于分布式执行时跨进程/跨版本传输查询计划否随实现一起变更判断标准非常直接凡是定义了持久化 Lance 格式的 schema 变更都需要 PMC 投票凡是纯执行计划wire contract的 schema 变更则不需要格式投票也不需要配套的docs/src/format/文档改动它们天然属于实现的一部分应当与其实现代码放在同一个 PR 中。从仓库结构看这种区分同样体现在protos/之外rust/lance/protos/、rust/lance-encoding/protos/、rust/lance-file/protos/、rust/lance-index/protos/、rust/lance-table/protos/、rust/lance-datafusion/protos/各自维护着与protos/同步的 proto 副本而 docs/src/format/AGENTS.md 则规定格式规格文档中的 schema 必须以pyarrowschema 定义来表达且必须是语言无关的定义JSON Schema、protobuf不能使用 Rust struct 之类的语言特定代码。变更流程投票门槛、PR 拆分与执行计划例外format-spec-vote CI 门禁与 PMC 投票对持久化格式的 proto 变更protos/CLAUDE.md 明确规定需要 PMC 对 PR 本身投票并由format-spec-voteCI 门禁强制实施。投票的具体机制记录在 docs/src/community/voting.mdPR 即提案没有独立的设计文档PMC 直接在 PR 上投票投票期 72 小时不含周末自动标记只要 PR 修改了protos/**/*.proto或docs/src/format/**就会被自动标记为format-change三票门槛需要 3 名 PMC 成员不含提案者的 binding 1 批准且只有针对最新提交的 approval 才有效——推送新提交会使此前的批准失效草案先行PR 成型期间以 draft 形式打开标记为 ready for review 时才开始计时投票。这样设计的原因在 voting 文档中写得很清楚格式是比任何单一实现都长寿的兼容性契约PMC 成员应当能读完他们投票的全部内容。因此投票的对象必须是契约本身而不是被实现细节淹没的 PR。持久化格式变更的 PR 拆分原则针对持久化格式的 proto 改动必须遵守严格的 PR 拆分纪律独立 PR一个持久化格式的 proto 变更独占一个 PR最小配套该 PR 只包含 proto 定义变更、匹配的 docs/src/format/ 文档改动以及足以让项目编译通过的最小库代码修改例如同步改名后的生成字段实现后置真正的读写逻辑放在后续的 follow-up PR 中。用原文档的话说voters need to read the contract, not its implementation——投票者读的是契约不是它的实现。如果 PR 同时携带 reader、writer 和测试改动契约就会被实现细节淹没还会让一次普通代码评审被迫经历本不需要的 72 小时投票期。讨论以 PR 评审意见的形式进行评审者可以直接针对规格的特定行回应。执行计划 Schema随实现变更protos/CLAUDE.md 明确点名了三个执行计划 schemaprotos/ann.proto向量查询参数与 ANN 执行节点的序列化形式包含VectorQueryProto、ANNIvfSubIndexExecProto、ANNIvfPartitionExecProtoprotos/filtered_read.protoFilteredReadExec的序列化形式含FilteredReadOptionsProto、FilteredReadPlanProto分布式 plan-then-execute 模式等protos/table_identifier.proto远程重建 Lance dataset 的标识支持uri serialized_manifest快速远端跳过 manifest 读取与uri version etag轻量远端从存储加载 manifest两种模式。这些是线缆协议wire contract而非持久化格式因此其变更与实现代码放一起不要求格式投票也不需要docs/src/format/文档变更。兼容性契约稳定格式、不稳定格式与线缆协议protos/CLAUDE.md 的 Compatibility 一节把兼容性义务分成三档而 根目录 AGENTS.md 的 File Format Stability and Compatibility 一节提供了总纲稳定持久化格式绝不破坏属于稳定文件格式或任何其他稳定持久化契约的 Protobuf schema必须保持向后兼容永远不要重用或更改已有字段编号。根 AGENTS.md 进一步明确所有被标记为 stable 的文件格式都是持久化的兼容性契约对稳定格式的一切更改都必须同时保持向后兼容和向前兼容评估兼容性时对照最近发布的稳定版本当前分支或main上才存在的中转状态不构成兼容性约束。不稳定持久化格式可以破坏但先验证只被不稳定文件格式独占使用的 schema遵循根级文件格式稳定性契约不保留与先前不稳定版本的兼容性。但在做破坏性 protobuf 变更之前必须先验证该 schema 没有被稳定格式或其他持久化契约共享——这是最常见的踩坑点一个 proto 消息可能同时被稳定与不稳定的格式引用。执行计划线缆谨慎保留字段编号执行计划 wire schema 仍然可能跨越进程或版本边界传输因此除非所有生产者和消费者能够原子化同步升级否则必须保留其字段编号兼容性。这条规则意味着分布式部署中不同版本的 executor 可能同时存在随意改动字段编号会让老版本节点无法解析新协议。遗留兼容边界根 AGENTS.md 还补充了遗留兼容边界Legacy Compatibility Boundaries原则当前 writer 不再生成的格式与代码路径被视为冻结的兼容表面保留其既有读取行为但新功能一律在当前格式与写入路径上实现不扩展遗留 writer也不把遗留实现作为新代码的基础。protos/中index_old.proto这类文件即属于此类冻结表面。Schema 设计原则optional、结构化消息与反重复protos/CLAUDE.md 的 Schema Design 一节给出了三条直接可落地的设计规则仓库中的真实 proto 文件即为最佳范例。用 optional 表达未设置与零值的区别规则的核心是 proto3 的 presence semanticsoptional字段启用 presence 跟踪生成has_*方法在 Rust 中映射为OptionT可以区分发送方没有显式设置与显式设置为零值两种状态裸 proto3 字段没有 presence 语义它们永远持有值缺省为零值你无法判断发送方是否显式设置了它。仓库中有大量optional的应用实例。例如 protos/table.proto 中Manifest.WriterVersion的prerelease与build_metadata字段optional string prerelease 3; optional string build_metadata 4;其注释明确说明如果prerelease缺失version字段原样使用——这是可选语义的经典场景缺失本身携带信息。IndexMetadata.created_atprotos/table.proto则说明另一个原因该字段为向后兼容而可选对于字段引入前创建的旧索引此值为 None/null。再看 protos/filtered_read.proto 中的materialization_readahead_bytes如果缺失Blob v2 物化没有独立的内存上限——缺失与 0 是两种完全不同的语义必须用optional表达。用结构化消息类型替代裸标量规则要求使用结构化消息类型如BasePath而不是裸标量把字段限定在操作专属的消息中如InsertTransaction而不是放进通用的顶层消息。这一点在 protos/table.proto 中体现得淋漓尽致BasePath不是一个字符串列表而是一个携带id、可选name、is_dataset_root标志与绝对path的结构化消息配合Manifest.base_paths字段解决浅克隆、文件导入等多层存储场景下的真实路径解析DeletionFile使用枚举DeletionFileTypeARROW_ARRAY与BITMAP来表达删除行的存储效率取舍DataFile通过fields、column_indices、file_major_version、file_minor_version等结构化字段完整描述一个列文件的元数据。不要跨消息重复数据每条事实只存一份关系通过派生获得是第三条原则。规则特别提示当键已经存在于另一个字段中时优先使用并行序列parallel sequences而不是 map。例如 protos/filtered_read.proto 的FilteredReadPlanProto中fragment_filter_ids是mapuint32, uint32fragment id → filter 列表索引而filter_expressions是去重后的 Substrait 编码过滤表达式列表——多个拥有相同过滤器的 fragment 共享同一个列表索引避免了为每个 fragment 重复编码 Substrait 表达式。这就是一次存储、按引用共享的典型设计。注释与文档规范语义、术语与可折叠注释语义层面状态的含义必须写清楚protos/CLAUDE.md 要求对optional字段同时记录存在与缺失两种状态的语义含义说明各自适用场景字段描述使用精确的领域术语避免歧义缩写或与领域概念冲突的用词。仓库中的注释堪称典范。例如 protos/table.proto 中Manifest.reader_feature_flags的注释详细列出了已知的每一位标志含义1 0删除文件存在、1 1行 ID 稳定、1 6存在数据覆盖文件且不理解 overlays 的 reader 必须拒绝读取……。SsTable.in_memory_bytes的注释则精确声明了它的语义边界payload 的估算值不是读取该 SSTable 代价的上界读者从它预算内存时必须自行增加余量在字段出现之前写入的 SSTable 上缺失因此读者不能把缺失值读成零。形式层面多行注释必须是 /* ... */ 块这是最容易被自动化执行的一条规则也是 protos/CLAUDE.md 中唯一直接给出工具链的规范多行注释写成/* text/* text/*/块使编辑器可以折叠它们单行注释保持//该规范由 ci/check_proto_comments.py 强制执行同时接入 pre-commit hook 和Protobuf lintworkflow。ci/check_proto_comments.py 的实现细节值得展开它递归收集所有*.proto文件跳过.git、.venv、node_modules、target目录用正则^(\s*)(///?)(.*)$识别注释行把缩进相同的连续//注释行聚合成一个多行注释运行凡是内容超过 1 行的都视为违规SPDX 许可证头// SPDX-...被显式豁免因为 license-header-check 要求它原样保留。运行时有两种模式不带参数打印每个违规位置文件:行号: multi-line comment must use /* ... */ (N lines)退出码为 1--fix自动把违规的多行//注释重写为/* ... */块并保持每行内容列位置不变。注释风格检查器之所以要求保持列位置不变注释头部的说明揭示了深层原因/* text* text的布局让每个内容列恰好落在//形式原本的位置上因此protoc提取出的leading_comments完全相同生成的 Rust、Python、Java 文档注释不会发生变化——一次格式化重写不会意外改动生成代码的输出。检查器的使用方式为# 检查违反时退出码非 0供 CI 使用 python ci/check_proto_comments.py # 自动修复 python ci/check_proto_comments.py --fix仓库 Proto 全景契约分层速览为了在真实场景中应用上面的规则下面梳理protos/目录下各文件的定位消息/枚举数量可由源码确认protos/file.proto单文件描述符与字段元数据Field消息定义了PARENT/REPEATED/LEAF三种类型与logical_type字符串如decimal:128:{precision}:{scale}、timestamp:{unit}并保留了已废弃的storage_class字段槽位protos/file2.proto 与 protos/encodings_v2_0.proto、protos/encodings_v2_1.protoV2 文件格式与按页编码的契约其中encodings_v2_1.proto是当前主要演进对象protos/table.proto数据集级契约Manifest承载版本号、fragment 列表、索引元数据、feature flags、writer_version、base_paths、配置与表元数据DataOverlayFile实现不重写基础数据文件的高效局部更新MemWalIndexDetails等消息支撑内存 WALMemWAL索引protos/transaction.proto事务契约oneof operation覆盖Append、Delete、Overwrite、CreateIndex、Rewrite、Merge、Restore、Update、Project、UpdateConfig、Clone等 16 种操作并预留了已被移除的blob_append/blob_overwrite字段号protos/rowids.proto、protos/index.proto、protos/index_old.proto行 ID 序列与索引元数据新旧两个版本并存protos/ann.proto、protos/filtered_read.proto、protos/table_identifier.proto前文已述的执行计划线缆协议。检查清单修改 proto 前的自查综合 protos/CLAUDE.md、根 AGENTS.md 与 docs/src/format/AGENTS.md在提交任何 proto 变更前逐项确认分类这份 schema 是持久化格式还是执行计划线缆持久化格式 → 独立 PR docs/src/format/配套 最小编译改动 PMC 投票72 小时、3 票门槛、format-spec-vote门禁执行计划线缆 → 与实现同 PR无投票要求。兼容性稳定格式 → 绝不重用/更改字段编号不稳定格式 → 确认未被稳定格式或持久化契约共享后再做破坏性变更线缆协议 → 除非全链路原子升级否则保留字段编号。设计需要区分未设置与零值时用optional用结构化消息替代裸标量不跨消息重复数据。注释为optional字段写清存在/缺失两种状态的语义使用精确领域术语多行注释用/* ... */块改动前运行python ci/check_proto_comments.py违规时用--fix自动重写。遵循这套流程既能保证 Lance 格式契约的长期稳定性也能让执行计划协议保持跨版本可用同时让代码评审与 PMC 投票聚焦在真正需要审查的契约本身。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考