lance-format_开发编程 skill-PHP中文网

lance-format

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

Lance v7 参考文档 —— 面向多模态 AI 的开源列式湖仓格式，及其 Rust crate 工作区（`lance`、`lance-table`、`lance-file`、`lance-encoding`、`lance-index`、`lance-io`、`lance-namespace` 等）。适用于直接基于 Lance crates 进行开发的场景：创建或读取 `.lance` 数据集、清单（manifest）、数据块（fragment）、删除文件（deletion file）、2.x 文件格式

Lance v7 参考件 : Lance 是多模式AI的开放式专栏格式 - "一个专栏数据格式,它比 Parquet 更方便随机访问",它不是一个格式而是一叠互

功能概述

Lance v7 参考件 : Lance 是多模式AI的开放式专栏格式 - "一个专栏数据格式,它比 Parquet 更方便随机访问",它不是一个格式而是一叠互是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

核心要点

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

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 节。

Crate	角色
`lance`	公共入口点 —— `Dataset`、扫描器（scanner）、索引、提交（commits）
`lance-table`	表格式 —— 清单（manifest）、特性开关（feature flags）、提交处理器（commit handlers）、行 ID
`lance-file`	文件格式 —— 文件读写器（file reader/writer）
`lance-encoding`	结构化编码、压缩（内部使用，不对外暴露）
`lance-index`	标量 / 向量 / 全文检索（FTS）/ 系统索引
`lance-io`	对象存储（Object store）、I/O 调度器
`lance-core`	共享的 `Error`/`Result`、缓存、数据类型
`lance-datafusion`	DataFusion 集成胶水层（exec、expr、planner、UDF）
`lance-linalg`	SIMD 加速的 L2 / 点积 / 余弦 / 汉明距离计算内核
`lance-select`	行选择基元（row-selection primitives）—— `RowAddrMask`、`RowIdMask`、`IndexExprResult`（自 v7.1.0-beta.2 起从 `lance-core`/`lance-index` 中拆出）
`lance-tokenizer`	全文检索分词器栈（simple、ngram、jieba、lindera、stemmers）
`lance-geo`	地理空间 UDF（由 `geo` feature-gate 控制）
`lance-namespace` / `-impls` / `-datafusion`	命名空间 trait、Directory/REST 实现、DataFusion 目录桥接器
`lance-arrow`、`lance-tools`、`fsst`、`lance-bitpacking`、…	Arrow 扩展、CLI 工具、压缩子 crate

除 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 参数选定，且一旦数据集建立即不可更改（如需变更，必须重写整个数据集）。

版本	状态	说明
`0.1`（`legacy`）	只读	原始格式；已不可写入
`2.0`	稳定版（`stable`）	移除行组（row groups）；支持列表（lists）/ FSL / 基础类型中的空值（null）
`2.1`	当前默认版本（`stable`）	自适应结构化编码；改进的整型/字符串压缩；结构体字段中支持空值；增强嵌套结构的随机访问性能。自 Lance 5.0.0 起成为默认版本
`2.2`	不稳定版（`unstable`）	新增 Map 类型、Blob v2、`VariablePackedStruct`、更大的 mini-block。Map 和 Blob v2 的必需版本；真正的实验前沿——编码方式仍可能变动
`2.3`	不稳定版（`next`）	当前 `next` 别名所指向的版本（枚举中为 `V2_3`）。目前仅为脚手架（scaffolding）——尚无专属编码（`lance-encoding` 中仅 6 处引用 vs 2.2 的 98 处）；文档中的版本对照表仍仅列出 2.2

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 源码重新校准。请根据任务需求加载对应章节：

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