Lance v7 参考文档

Lance 是一种面向多模态 AI 的开源列式数据格式——“一种随机访问速度比 Parquet 快 100 倍的列式数据格式”。它并非单一格式，而是一套相互协作的规范栈：包括文件格式、表格式、索引格式、目录规范以及命名空间客户端规范。位于 lance-format/lance 的 Rust 工作区实现了全部规范，并提供 Python（pylance）和 Java 绑定。

本技能跟踪v7.2.0-beta.5版本（对应 lance-format/lance 仓库的 Git tag）。请始终基于 tag 进行固定依赖，而非 main 分支——Lance 每隔数日即发布 beta tag，且 next-format 编码可能随时变更。

深度参考文档为 references/lance-reference.md。针对任何具体 schema、参数、proto 或约束，均可加载该文件查阅。本文档是整体定位入口：请先通读本节，再跳转至你需要的具体参考章节。

Lance 与 LanceDB 的区别

二者为完全不同的概念，混淆将导致错误结论。

• Lance —— 格式与引擎本身。lance-format/lance 仓库；lance/lance-* Rust crate；pylance。它提供数据集、文件/表格式、索引、提交（commits）、扫描（scans）等能力。可被 DuckDB、Polars、Ray、Spark、PyTorch、DataFusion 或你自己的 Rust/Python 代码直接消费。本技能聚焦于 Lance。
• LanceDB —— 一个构建在 Lance 之上的独立数据库产品（lancedb/lancedb）。它额外提供了查询构建器 API、嵌入注册中心、作为 API 的重排序器（rerankers-as-API）、多语言 SDK 功能对齐，以及托管的 Cloud / Enterprise 服务层级。本文档不涵盖 LanceDB。

若你在 Cargo.toml 中直接依赖 lance crate，则属于直接使用 Lance —— 应使用本技能。若问题涉及 LanceDB 内部实现，其底层存储层仍为 Lance，因此本技能对格式本身的描述仍具权威性。

Crate 工作区结构

共包含 24 个位于 rust/ 下的 crate 目录。lance 是公共入口点；其余均为其下层模块。含完整说明与引用的表格见 references/lance-reference.md 第 2 节。

除 lance-arrow-scalar 固定绑定 Arrow 版本 58.0.0 外，其余 crate 均声明 version = "7.2.0-beta.5"。工作区配置：edition 2024、rust-version = 1.91.0、resolver = "3"。

文件格式版本

文件格式仅携带一个 major.minor 版本号。创建数据集时通过 data_storage_version 参数选定，且一旦数据集建立即不可更改（如需变更，必须重写整个数据集）。

stable 解析为默认版本（2.1）；next 在当前运行的 Lance 发布版中解析为2.3（非 2.2）——如需确定性行为，请显式指定版本号。在版本演进阶梯中，2.2 位于 next 的下方，因此代码逻辑不会将 2.2 标记为 unstable，尽管文档将其列为 unstable；实际承载实验特性的正是 2.2 版本。

v7 版本新增内容

v6 → v7 的边界仅含一项破坏性变更：feat!: make dataset object store access base-aware (#6647) —— 对象存储（object-store）的访问范围现以数据集 base 为作用域，而非扁平化的全局路径。该变更支撑了多 base 存储能力（热/冷分层、浅克隆）。

v7 各 beta 版本的主线主题是MemWAL —— 一种实验性的 LSM / 写前日志（WAL）架构，专为高吞吐流式写入设计（含 WAL 追加器/尾部读取器（appender/tailer）基元、分片写入器（shard writers）、Lance 原生内存 HNSW 索引、shared-memory:// 对象存储协议）。v7 时代还引入了：分支（branches）（类 Git，与 tags 并存）、分段式与分布式索引构建（FTS、位图、BTree）、更新的标量索引（zonemap、布隆过滤器、ngram）、地理空间 / RTree 索引及 lance-geo crate、用于快速获取最新版本的清单版本提示（manifest version hints），以及目录 / 命名空间 / 表 / 索引规范的正式解耦。标签 v7.1.0-beta.1 开启 v7.1 分支并添加了物化视图命名空间 API。v7.1.0-beta.2 随后将掩码（mask）代码抽离为新的lance-select crate（#6879），并修复两项 MemWAL 正确性问题：刷新后的 memtable 现可构建其二级索引，使向量行对 fast_search 可见（#6901）；每数据源的主键哈希块黑名单（per-source PK-hash block-list）后置过滤器，可抑制因新鲜行未落入其数据源 top-k 范围而导致的陈旧 LSM 向量读取（#6899）。v7.2 分支（当前固定版本 v7.2.0-beta.5）新增了：ICU 全文检索分词器（#6956）、标量索引快速搜索（#6784）、批处理向量查询（#6828）和流式 IVF k-means（#6913）——无破坏性变更、无新增 crate（仍为 24 个）、无新增事务操作（仍为 15 种）。详情参见 references/lance-reference.md 第 14 节。

参考文档导航

references/lance-reference.md 是完整的 v7 参考文档，所有内容均基于 v7.2.0-beta.5 源码重新校准。请根据任务需求加载对应章节：

1. Lance 是什么 —— 数据湖仓（lakehouse）规范栈
2. Crate 工作区 —— 全部 24 个 crate 及其职责、公共入口点
3. 文件格式 —— 版本、容器布局、结构化编码（mini-block / full-zip / constant / blob page 类型）、压缩方案、blob 编码
4. 数据类型 —— Arrow 类型覆盖、向量使用的 FixedSizeList、JSON（JSONB）、blob、机器学习扩展数组（bfloat16、图像类型）
5. 表格式 —— 数据集目录结构、清单内容、碎片（fragments）、删除文件、base 路径
6. Schema 演进 —— 字段 ID、零拷贝列增/删/改、为何旧行读取返回 NULL
7. 版本控制、tags、分支 —— 清单版本、时间旅行（time travel）、tag 固定、分支
8. 行 ID —— 行地址（row address）vs 稳定行 ID（stable row ID）、血缘（lineage）、变更数据流（change-data-feed）列
9. 事务与并发 —— 15 种事务操作、乐观并发控制（OCC）重试/变基、提交处理器（conditional-put、DynamoDB）、冲突解决矩阵
10. MemWAL —— 分片（shards）、MemTable/WAL/flush、appender/tailer/flusher 模型、围栏机制（fencing）
11. 索引 —— 向量（IVF/HNSW/PQ/SQ/RQ）、标量（BTree/位图/布隆过滤器/标签列表/ngram/区域映射 zonemap）、全文检索（BM25、分词器）、地理空间/RTree
12. 分布式写入与索引构建 —— 两阶段提交、分段索引构建
13. 对象存储 —— URI 协议、存储选项、各后端专属配置
14. v7 的变更内容 —— 完整的 v7 差异清单
15. 能力矩阵 —— Lance 支持与不支持的功能
16. 源码映射 —— 各规范与 proto 在仓库中的具体位置

维护说明

references/lance-reference.md 中的引用格式为相对于 lance-format/lance 仓库的 path:line；可通过 https://github.com/lance-format/lance/blob/v7.2.0-beta.5/ 构建永久链接。

如需更新参考文档：执行 git -C ~/pjv/lance-format/lance fetch --tags 获取全部 tag，检出最新的 v7* tag，重新阅读 docs/src/format/ 下的格式规范与 docs/src/guide/ 下的用户指南，重新验证 crate 工作区，并更新 metadata.upstream 及所有 v7.2.0-beta.5 引用。引用中的行号在不同 tag 间会漂移，请视其为近似值。