概述

数据表（Table）是湖管理中最细粒度的管理单元，对应 BOS 上一个以 .lance 结尾的 Lance 数据目录。完成建表后，可在控制台查看表结构、版本差异、存储优化任务与数据血缘，无需跳转 BOS。

湖管理当前支持三种建表方式：

创建方式	说明	适用场景
从数据集导入	选择一个数据格式为 Lance 的百舸数据集	数据已经通过百舸数据集管理
从 BOS 导入	直接填写 Lance 表所在的 BOS 目录	数据已经在 BOS 上以 Lance 格式存放
新建空表	指定一个尚未写入数据的 BOS 路径，先登记元数据	需要先建表、后续再由训练或写入任务写入数据

从 BOS 导入时，目标目录需为合法的 Lance 数据集：目录名以 .lance 结尾，且包含 Lance 的 _versions、data 等元数据文件。从数据集导入时，仅需选择已关联有效 Lance 文件的数据集，页面提示“请确保数据集已关联有效的 Lance 文件”。新建空表则要求路径下没有数据，首次写入后由后台自动识别字段。

前提条件

已完成服务开通，并已创建数据目录与数据库。

进入数据库

在数据目录详情页单击数据库名称，进入库内页面。页面顶部展示 目录 / 库 面包屑，下方依次为：

• 库信息区：数据库名称、存储路径、描述信息、创建人、创建时间、更新时间；页面右上角提供【删除】【编辑】按钮。
• 数据表区：左上角为【创建数据表】入口，右上角为表名搜索与刷新按钮。
• 数据表列表：列为数据表名称、创建方式、存储路径、格式、当前版本、行数、创建人、创建时间、更新时间、操作。

数据表列表为空时显示“暂无数据表”。单击列表左上角的【创建数据表】，开始建表。

创建数据表

在创建数据表弹窗中完成以下配置。

选择创建方式

创建数据表弹窗包含以下字段：数据表名称、表格式、创建方式、数据集或存储路径、描述信息。其中【表格式】当前固定为 Lance，【创建方式】提供三个选项：

• 从数据集导入：选择百舸中 Lance 格式的数据集，建表并绑定该数据集。
• 从 BOS 导入：登记 BOS 上已有的 Lance 数据，路径下必须已有数据。
• 新建空表：为还没写入的数据预先建表，路径下必须为空，首次写入后自动识别字段。

切换到【从 BOS 导入】后，弹窗会增加【存储路径】和【数据校验】按钮，并给出提示：

请选择 Lance 表所在目录（以 .lance 结尾），并单击【数据校验】确认数据可用后方可创建

切换到【新建空表】后，需要填写一个尚未写入数据的新路径，页面给出【存储路径建议】（bos://<数据库路径>/<数据表名称>.lance）。校验规则为确认路径下没有数据：

请填写一个还没有数据的新路径（以 .lance 结尾），并单击【数据校验】确认路径下没有数据后方可创建

填写参数

字段	说明
数据表名称	必填，以字母开头，支持字母、数字、下划线（_）、中划线（-），长度 1～64 位。输入后实时提示“当前名称可用”
表格式	必填，固定为 Lance
创建方式	必填，从数据集导入 / 从 BOS 导入 / 新建空表
存储路径（BOS 导入、新建空表）	必填，Lance 表所在目录，形如 bos://<桶名>/<路径>/<表名>.lance。从 BOS 导入时路径下必须已有数据；新建空表时路径下必须为空
存储路径建议（新建空表）	系统根据数据库路径和表名生成 bos://<数据库路径>/<表名>.lance，单击【使用建议路径】可填入
数据集（数据集导入）	必填，仅列出数据格式为 Lance 的数据集；下拉中展示数据集名称、ID、所有者与创建时间
描述信息	选填，最长 1024 个字符

存储路径可以直接输入，也可以单击【浏览】在桶树中逐级选择。从 BOS 导入或新建空表时，【确定】按钮在数据校验完成前保持不可用。

数据校验

三种创建方式的校验方式不同：

• 从数据集导入：选择数据集后自动解析字段，无需手动校验。解析成功时显示“成功解析 N 个字段”，并在【字段信息】中列出字段。
• 从 BOS 导入：单击【数据校验】读取目录元数据并解析 Schema。校验通过后，路径下方显示“已完成数据校验”，弹窗内展示【字段信息】表，底部提示“数据校验通过，解析到 N 个字段”。
• 新建空表：单击【数据校验】确认路径下没有数据。校验通过后，路径下方显示“路径为空，可新建空表，首次写入数据后自动识别字段”，不展示字段信息。

校验通过后，【确定】按钮变为可用。

从 BOS 导入时，字段信息表包含序号、字段名、字段类型三列；从数据集导入时还会展示 Metadata 列（如 bos-dataset-field:modality、lance-encoding:blob）。字段较多时可在弹窗内滚动查看。

校验不通过时，按页面提示处理：

页面提示	处理方式
路径需以 .lance 结尾	补全目录名，确保以 .lance 结尾
存储路径不能以“/”结尾	去掉路径末尾的斜杠
该路径下还没有数据，无法从 BOS 导入。如需先建表、等作业首次写入，请改用「新建空表」	该路径尚无数据；如需先建表、后续由作业写入，单击提示条右侧的按钮切换到新建空表方式
服务读取超时或失败	稍后重试；持续失败时检查该路径是否可被数据湖管理服务角色访问

完成创建

单击【确定】后，列表中出现新表，列包括：数据表名称、创建方式、存储路径、格式、当前版本、行数、创建人、创建时间、更新时间、操作（编辑 / 删除）。

从 BOS 导入或从数据集导入的新表，在后台扫描回填完成前，【当前版本】显示“待写入”、行数为 0；刷新页面即可看到实际版本号与行数。新建空表在首次写入前没有字段信息，首次写入后由后台自动识别并回填 Schema；版本号以页面显示为准。

数据表详情

单击表名进入详情页。页面顶部为面包屑 目录 / 库 / 表，右上角提供【删除】【编辑】，下方分为四个页签：基本信息、版本管理、存储优化、数据血缘。

基本信息

基本信息区展示：

字段	示例值
创建人	PASSPORT:***
存储路径	bos://<bucket>/<path>/lance-compare-new.lance
创建时间 / 更新时间	2026-10-27 15:36:20
格式	Lance
创建方式	从 BOS 导入
当前版本	v28
行数	2,600
存储大小	1.8 GB
分片数	5（平均 368.3 MB/分片）
描述信息	建表时填写的描述

说明：当前版本、分片数与存储大小会随写入和存储优化持续变化，上表数值及版本相关截图仅为示例，实际以控制台显示为准。

【字段信息】区说明：字段来自表文件，Lance 不按列分目录，向量列以 vector(n) 表示。区域右上角显示最近更新时间，区域左侧提供【同步元数据】按钮，用于在表结构变化后重新拉取字段。字段表按序号列出字段名与字段类型，例如 fixed_size_list<item: float>[768] 表示 768 维向量列。

版本管理

版本管理页左侧是该表的版本时间线，每个版本标注版本号、操作类型与提交时间，当前版本带“当前”标记。示例数据中可见的操作类型包括：覆写、追加、合并 / 加列、未知。

右侧展示选中版本的详情：

指标	说明
操作类型	该版本的写入类型
分片数	该版本的数据分片（fragment）数量
行数 / 删除行数	该版本的总行数与删除行数
大小	该版本数据大小
存储格式版本	Lance 存储格式版本，例如 2.1
引擎	写入该版本的引擎，未上报时显示 --
提交时间	版本提交时间
Manifest 文件	该版本对应的 manifest 路径
事务文件 / Commit 信息	未上报时显示 -

字段信息区域支持在【字段信息】与【相对上一版】之间切换，用于查看当前版本的完整 Schema 或相对上一版本的变化。两个版本 Schema 一致时，页面提示“相对 vN 无 Schema 变化”（N 为上一版本号）。

版本对比

单击【版本对比】，在弹窗中选择【源版本】和【目标版本】后单击【对比】。

对比结果按“字段名 / 变更 / 原类型 / 新类型”展示差异。例如 v1 → v8 的对比结果显示 image_vec 为“新增”，原类型为 -，新类型为 fixed_size_list<item: float>[768]；若两个版本 Schema 完全一致，则提示“两个版本 Schema 一致”。

存储优化

存储优化页包含【小文件合并】与【清理历史版本】两个子页签。每个子功能提供功能说明、右上角的启用开关（开启后显示【配置】入口）以及下方的【运行记录】列表。运行记录列为：任务 ID、触发方式、状态、开始时间、耗时、说明、操作；开关未开启时，【立即执行】按钮不可用。

小文件合并

将碎片化的 fragment 合并为更大的 fragment，减少文件数量与元数据开销，提升扫描效率。合并按行数进行，不按文件大小。

首次开启时，单击右上角开关会打开【开启小文件合并】配置抽屉，单击【确定】后开关置为开启；已开启后，通过【配置】按钮打开的是【编辑小文件合并配置】，两者字段一致：

分组	字段	说明
基础配置	目标每分片行数	target_rows_per_fragment，合并后每个分片的目标行数，已达到该行数的分片会被跳过，默认 1048576
基础配置	输出文件大小上限	max_bytes_per_file，单个输出数据文件的大小上限，默认 128 MB，留空沿用引擎默认
调度配置	定时调度	关闭时采用不定时调度策略，调度周期显示为“不定时”，仅能手动执行
调度配置	调度周期	开启定时调度后按“每 N 时/天执行一次”的周期自动执行，单周期不超过 365 天
调度配置	调度触发条件	到点调度时按阈值判断是否执行，需先开启定时调度
高级配置	添加参数	最多可添加 11 个参数，数值留空即不下发，使用引擎默认值；固化软删除阈值需先开启固化软删除

开启后，页面展示调度周期、下次执行时间（未开启定时调度时不显示）、目标每分片行数、输出文件大小上限与最后修改人，【配置】入口常驻，【立即执行】变为可用。

单击【立即执行】提交任务，页面提示“已提交执行任务”，运行记录新增一条触发方式为“手动”的记录。任务完成后，状态由执行中变为“成功”，并显示耗时与说明（例如“将 5 个分片合并为 5 个”）。任务执行期间再次单击【立即执行】，提示“已有执行任务进行中（后台检测刷新），无需重复触发”。

清理历史版本

按保留天数清理更早的历史版本以回收存储。平台自动保护当前版本、被数据集引用的版本和打了标签的版本。

删除规则为：仅删除同时满足“早于保留天数、超出最近保留数、未打标记”的版本；满足其中任一条件即保留。保留天数与保留最近版本数两项各自独立，留空即关闭该维度，且至少保留一个维度；填写值需大于等于 1。

已开启后，单击【配置】，打开【编辑清理历史版本配置】抽屉，配置如下：

分组	字段	说明
基础配置	保留天数	早于该天数的历史版本进入清理候选，留空则不启用该维度
基础配置	保留最近版本数	retain_versions，最近保留 N 个现存版本（含当前版本），留空则不启用该维度
基础配置	删除限速	开启后限制清理时的删除速率上限，关闭则不限制
基础配置	限速阈值	每秒删除操作数上限，留空使用默认 100 ops/s
调度配置	定时调度 / 调度周期	与【小文件合并】一致，可设为不定时或按周期自动执行
高级配置	添加参数	最多可添加 2 个参数，数值留空即不下发，使用引擎默认值

页面展示调度周期、保留天数、删除限速、下次执行时间（未开启定时调度时不显示）与最后修改人；运行记录包含任务 ID、触发方式、状态、开始时间、耗时、说明与操作。

说明：小文件合并与清理历史版本会实际改写或删除 BOS 上的数据文件，建议在业务低峰期执行，并在执行前确认没有任务正在读取待清理的版本。

数据血缘

数据血缘页顶部提供版本选择器，作用于页内全部视图。下拉按版本倒序列出全部版本，每项标注操作类型，当前版本带“当前”标记。选择器右侧显示“共 N 个版本”与所选版本的提交时间；切换版本后，页面按所选版本重新加载视图。

视图支持【列级血缘】【摘要】【血缘图】三种展示方式，视图切换区旁提供刷新按钮。

切换到【血缘图】后，页面提供以下筛选：

• 展开方向：上游 / 下游 / 双向；
• 展开层级：如 3 层；
• 显示类型：全部；
• 执行节点：聚合 / 展开；
• 开关：【合并重跑】、【仅看 某版本 相关】。

其中【仅看 某版本 相关】的版本号跟随顶部版本选择器变化，开启后仅保留与所选版本相关的节点。视图右侧支持列表视图、全屏与刷新。

说明：血缘图按版本查看，控制台不支持两个版本并排对比。需要比较版本间的 Schema 变化时，请使用【版本管理】中的【版本对比】。

当上下游关系尚未上报时，摘要视图提示“暂无血缘关系（上下游由 lance 扫描与工作流上报后出现）”。血缘图视图提示“暂无血缘关系（可调整展开方向/展开层级）”。

编辑与删除

表列表的操作列与表详情右上角均提供【编辑】与【删除】：

• 编辑：打开【编辑数据表】弹窗，可修改数据表名称与描述信息；表格式与存储路径只读，不能通过编辑修改。
• 删除：从湖管理中移除该表的元数据记录。

说明：删除表会移除该表的元数据记录，依赖该表元数据的下游配置可能受影响，操作前请确认影响范围。BOS 上的 Lance 数据文件不会因为删除元数据记录而被清理；如需回收存储空间，请前往 BOS 控制台删除对应目录。

使用限制

项目	限制
数据表名称	以字母开头，支持字母、数字、下划线（_）、中划线（-），长度 1～64 位；名称在所属数据库内唯一
描述信息	最长 1024 个字符
表格式	当前固定为 Lance
从 BOS 导入	路径以 .lance 结尾，路径下必须已有数据，且通过【数据校验】
新建空表	路径以 .lance 结尾，路径下必须没有数据，且通过【数据校验】
从数据集导入	仅支持已关联有效 Lance 文件的数据集
小文件合并高级参数	最多 11 个
清理历史版本高级参数	最多 2 个
定时调度周期	单周期不超过 365 天
清理历史版本保留策略	保留天数与保留最近版本数至少启用一个维度，填写值需大于等于 1

注意事项

1. 格式限制：当前表格式仅支持 Lance，其他格式（如 Iceberg）暂不支持。
2. 路径校验：从 BOS 导入或新建空表时，建表前必须通过【数据校验】；校验会实际访问目标路径，大表的首次校验耗时较长。从数据集导入时，选择数据集后由系统自动解析字段。
3. 版本号来源：版本信息来自 Lance 自身的版本目录（_versions），版本管理页只做展示与对比，不修改版本数据；在控制台外写入的新版本，刷新页面后即可看到。
4. 存储优化影响数据：小文件合并与清理历史版本会改写数据文件，执行前请确认上下游任务状态。
5. 血缘依赖上报：血缘关系依赖 Lance 扫描与工作流上报，未接入上报时血缘图为空。