深入解析 @lancedb/lancedb 的 FunctionErrorsOptions:查询表上逐行 Function 错误的过滤配置

原创2026-09-22 20:04:091,853 阅读
文章标签:向量数据库数据库全文检索数据湖多模态嵌入式数据库列式数据库

深入解析 @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 端点

从源码可以梳理出完整的调用链:

  1. TS 层:table.ts functionErrors 先做 limit 非负整数校验(校验逻辑在 materialized_view.ts 的 validateNonNegativeInteger,用于阻止 N-API 对 Infinity、1.5 等数值的静默强转),再转发给 N-API 绑定;
  2. 绑定层:nodejs/src/table.rs function_errors 将 FunctionErrorsOptions 映射为 Rust 核心的 FunctionErrorsRequest;
  3. 核心层:rust/lancedb/src/table.rs function_errors 将请求委托给具体的表实现;
  4. 远程实现: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 上可用,且读取本身需要表读权限。

登录后查看全文
lancedb