深入解析 @lancedb/lancedb 的 FunctionErrorsOptions:查询表上逐行 Function 错误的过滤配置
深入解析 @lancedb/lancedb 的 FunctionErrorsOptions:查询表上逐行 Function 错误的过滤配置
FunctionErrorsOptions 是 LanceDB JavaScript SDK(@lancedb/lancedb)中用于查询"逐行 Function 错误"(per-row Function errors)的可选过滤配置接口。它通过 column、jobId、limit 三个可选参数,让你精准定位批量计算列(computed column)刷新过程中被跳过的失败行。读完本文,你将掌握该接口每个字段的语义与默认值、与 FunctionErrors 返回结构的关系,以及它在本地表与 LanceDB Cloud/Enterprise 环境下的行为差异。
接口定位:它服务于哪个 API
FunctionErrorsOptions 是 Table.functionErrors(options?) 方法的参数类型,该方法用于列出"Function 刷新(refresh)在表上记录的逐行错误"。
从 Table 抽象类源码 的 JSDoc 可以确认它的完整语义:
在 skip 策略下运行的刷新(refresh)会为每一行被跳过的记录保存导致失败(failed)的输入及错误。此方法按"最新 job 优先"的顺序列出这些记录,并附带对任何逐行细节被截断(capped)的 fragment 的汇总。该功能仅适用于 LanceDB Cloud 和 Enterprise;由于错误消息携带导致失败的值,读取错误需要表的读权限。
对应的实现位于 table.ts 的 functionErrors 方法:
async functionErrors(options?: FunctionErrorsOptions): Promise<FunctionErrors> {
validateNonNegativeInteger(options?.limit, "limit");
return await this.inner.functionErrors(options);
}
可以看到,JS 层在转发给底层绑定之前,会先对 limit 做一次非负整数校验。
三个可选过滤器:字段、语义与默认值
接口定义位于 FunctionErrorsOptions 文档,全部字段均可选:
| 字段 | 类型 | 是否必填 | 语义 |
|---|---|---|---|
column |
string |
可选 | 只返回该列上的错误(Only errors on this column) |
jobId |
string |
可选 | 只返回该 job 记录的错误(Only errors recorded by this job) |
limit |
number |
可选 | 最多返回这么多条记录,服务器默认 10000,上限 100000(At most this many records, server default 10000, cap 100000) |
对应的底层 Rust 绑定结构位于 nodejs/src/table.rs,注释与接口文档一一对应:
/// Which per-row Function errors to list; every filter is optional.
#[napi(object)]
#[derive(Clone, Debug, Default)]
pub struct FunctionErrorsOptions {
/// Only errors recorded by this job.
pub job_id: Option<String>,
/// Only errors on this column.
pub column: Option<String>,
/// At most this many records (server default 10000, cap 100000).
pub limit: Option<i64>,
}
在 nodejs/src/table.rs 的 function_errors 方法 中,这三个字段被逐项转换为内部请求结构;其中 limit 会先做 usize 转换,非法值(如负数)会抛出 "limit must be a non-negative integer" 错误。
三个过滤器的组合语义
所有过滤器都是可选的,且可以任意组合,彼此为"与"(AND)关系:
- 不传任何参数:
table.functionErrors()列出该表上所有 Function 刷新记录的错误——Rust 核心中的 FunctionErrorsRequest 文档注释 明确指出"该列表以表为寻址单位,因此不设置任何过滤器时,它覆盖每一列的每一次刷新"; - 只传
jobId:聚焦某一次刷新任务,例如refreshColumnAsync返回的 Job; - 只传
column:只看某一列(如embedding这类由函数计算生成的列)的失败; - 同时传多个:如
{ jobId: "j-7", column: "embedding", limit: 2 },精确定位某个 job 在某列上的前几条错误。
理解 limit 的关键:返回结构 FunctionErrors
functionErrors 的返回类型是 FunctionErrors,理解它的三个字段才能真正理解 limit 的作用。完整定义见 FunctionErrors 接口文档:
interface FunctionErrors {
/** 已记录的失败行,最新 job 优先 */
records: FunctionErrorRecord[];
/** 逐行细节被截断的 fragment 汇总 */
fragments: FunctionErrorFragment[];
/** 列表是否在达到 limit 时停止 */
truncated: boolean;
}
records:逐行错误明细
FunctionErrorRecord(见 接口文档 与 nodejs/src/table.rs)记录单行失败信息,包含:
jobId:记录该错误的刷新 job;fragmentId:该行所在的数据 fragment;rowOffset?:行在 fragment 内的偏移;当该 fragment 的细节被截断时该字段缺失;column:正在计算的列;function:失败的 Function 名称;functionVersion:Function 的版本;tableVersion:刷新所读取的表版本;errorType:执行器报告的错误类别;errorMessage:错误文本(可能携带导致失败的具体输入值);createdAtMillis:错误记录的 Unix 毫秒时间戳。
fragments:被截断的汇总
当某个 fragment 失败行过多、触发了记录上限时,服务端不会无限保存逐行明细,而是给出汇总:FunctionErrorFragment(见 接口文档 与 nodejs/src/table.rs)包含 jobId、fragmentId、rowsSkipped(该 fragment 中被跳过的行数)和 rowsRecorded(其中拥有独立记录的行数)。
truncated:是否触顶
truncated 为 true 表示列表在到达 limit 时被截断。这意味着:limit 控制的只是返回明细的行数上限,而非错误的总量。当返回被截断时,fragments 汇总恰好用于呈现那些明细已被丢弃的 fragment 的整体失败规模。
实际使用示例
基本用法
结合 table.ts 的 JSDoc 示例,只按列过滤:
const { records, truncated } = await table.functionErrors({ column: "embedding" });
完整参数过滤(与 remote.test.ts 测试 中的用法一致):
const table = await db.openTable("docs");
const errors = await table.functionErrors({
jobId: "j-7",
column: "embedding",
limit: 2,
});
if (errors.truncated) {
console.warn("结果被截断,仅展示部分明细");
}
for (const record of errors.records) {
console.log(`${record.errorType}: ${record.errorMessage}`, {
jobId: record.jobId,
fragmentId: record.fragmentId,
rowOffset: record.rowOffset,
column: record.column,
function: record.function,
functionVersion: record.functionVersion,
tableVersion: record.tableVersion,
createdAtMillis: record.createdAtMillis,
});
}
for (const fragment of errors.fragments) {
console.log(
`fragment ${fragment.fragmentId} 共跳过 ${fragment.rowsSkipped} 行,其中 ${fragment.rowsRecorded} 行有独立记录`,
);
}
在 Rust SDK 中,等价调用使用 FunctionErrorsRequest 的 builder 方法:
let errors = table
.function_errors(FunctionErrorsRequest::new().column("embedding"))
.await?;
for record in &errors.records {
println!("{}: {}", record.error_type, record.error_message);
}
组合刷新流程排查错误
jobId 过滤器最常见的用途是配合 refreshColumnAsync 使用——后者返回一个 Job 句柄(见 table.ts 相关 JSDoc)。当 Job 完成后,可以用它返回的 jobId 定向查询这次刷新产生了哪些跳过行,从而把"失败任务"与"失败明细"精确关联起来。
底层实现链路:从 TypeScript 到 REST 端点
从源码可以梳理出完整的调用链:
- TS 层:table.ts
functionErrors先做limit非负整数校验(校验逻辑在 materialized_view.ts 的validateNonNegativeInteger,用于阻止 N-API 对Infinity、1.5等数值的静默强转),再转发给 N-API 绑定; - 绑定层:nodejs/src/table.rs
function_errors将FunctionErrorsOptions映射为 Rust 核心的FunctionErrorsRequest; - 核心层:rust/lancedb/src/table.rs
function_errors将请求委托给具体的表实现; - 远程实现:rust/lancedb/src/remote/table.rs
function_errors将job_id、column、limit序列化为 JSON 请求体(只有设置了对应字段才会写入 body),发送POST /v1/table/{table_name}/errors,并把响应反序列化为FunctionErrors。
测试 remote.test.ts 验证了请求体的实际形状:传 { jobId: "j-7", column: "embedding", limit: 2 } 时,发出的 body 为 {"job_id": "j-7", "column": "embedding", "limit": 2};不传任何参数时 body 为 {}。
边界与限制
仅限 LanceDB Cloud 和 Enterprise
本地表(嵌入式 LanceDB)不支持此功能。Rust 核心中 BaseTable trait 的默认实现直接返回 NotSupported,错误消息为 "per-row Function errors are recorded only on LanceDB Cloud and Enterprise"(见 rust/lancedb/src/table.rs)。对应的 JS 测试也验证了这一点——table.test.ts 在本地连接上调用 table.functionErrors() 期望其 reject,并抛出包含 "LanceDB Cloud and Enterprise" 的错误。
limit 的取值规则
- 默认值:不传时服务器默认返回 10000 条;
- 上限:服务器上限 100000,超出会触发截断;
- JS 层校验:
limit必须是安全非负整数,负数、Infinity、非整数都会抛错(测试中table.functionErrors({ limit: -1 })期望 reject,错误信息为"limit must be a non-negative integer",见 remote.test.ts); - 语义:
limit只约束records明细条数,被截断时通过truncated标志和fragments汇总来提示与兜底。
权限要求
由于 errorMessage 可能携带导致失败的具体输入值(例如测试中模拟的 "bad input 'x'"),读取错误记录需要表读权限——这一点在 table.ts 的 JSDoc 与 rust 侧 FunctionErrorRecord 注释 中均有明确说明。
小结
FunctionErrorsOptions 虽然只有三个可选字段,却是 LanceDB 计算列/Function 刷新链路中"错误观测"的入口配置:column 定位列、jobId 定位任务、limit 控制明细规模。配合返回值中的 truncated 标志与 fragments 汇总,你可以在大批量失败场景下既拿到可操作的明细,又不丢失整体规模信息。在使用时请务必记住:该接口只在 LanceDB Cloud/Enterprise 上可用,且读取本身需要表读权限。