LanceDB Node.js SDK 中 FunctionErrors 接口详解：函数刷新任务的逐行错误审计

LanceDB Node.js SDK 中 FunctionErrors 接口详解：函数刷新任务的逐行错误审计

【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedb

FunctionErrors 是 LanceDB Node.js SDK（@lancedb/lancedb）中用于承载表级 Function 刷新（refresh）逐行错误的返回结构。当表上的计算列（computed column）在刷新过程中因某行输入导致 Function 调用失败时，处于 skip 策略下的刷新任务会记录下每一行被跳过的具体原因，而Table.functionErrors()正是读取这些记录的入口。读完本文，你将掌握 FunctionErrors 的完整字段语义、records与fragments两种错误表示的区别、底层 Rust 实现与调用链，以及在实际工程中如何结合FunctionErrorsOptions精准排查 embedding 或自定义 Function 的失败数据。

接口定义与定位

FunctionErrors 接口定义于 nodejs/lancedb/table.ts（方法签名见functionErrors()的返回类型声明），其 TypeScript 声明为：

interface FunctionErrors { /** Fragments whose detail was capped. */ fragments: FunctionErrorFragment[]; /** The recorded rows, newest job first. */ records: FunctionErrorRecord[]; /** Whether the listing stopped at its limit. */ truncated: boolean; }

它同时被 nodejs/lancedb/index.ts 作为包级公共类型导出，是Table.functionErrors()方法的唯一返回类型。完整接口文档可参阅 docs/src/js/interfaces/FunctionErrors.md。

接口只包含三个属性，但语义上覆盖了错误审计的两个层面：

• records：逐行的详细错误记录，按"最新任务在前"（newest job first）排序；
• fragments：因单片段错误行数过多而被"封顶"（capped）的片段摘要；
• truncated：本次查询是否因为达到 limit 限制而提前停止。

三者配合使用，才能得到一张完整的错误全景图：既有精确到行的错误明细，又有总量级的片段汇总，还能判断结果是否被截断。

records：逐行错误明细，最新任务优先

records: FunctionErrorRecord[]是接口的核心字段，存放刷新任务为每一行跳过的行所记录的详细错误。它的元素类型FunctionErrorRecord（文档见 docs/src/js/interfaces/FunctionErrorRecord.md）在 Rust 侧定义为 rust/lancedb/src/function.rs 中的FunctionErrorRecord结构体，并通过 nodejs/src/table.rs 中的 N-API 对象映射到 JS 侧。其字段包括：

字段	类型	含义
jobId	string	记录该错误的刷新任务 ID
fragmentId	number	承载该行的数据片段（fragment）ID
rowOffset	number | undefined	行在片段内的偏移量；当片段细节被封顶、仅剩片段摘要时该字段为undefined
column	string	正在计算的列名
function	string	执行失败的 Function 名称
functionVersion	string	该 Function 的版本号
tableVersion	number	刷新任务读取的表版本
errorType	string	执行器报告的异常类别
errorMessage	string	错误文本
createdAtMillis	number	错误被记录的 Unix 毫秒时间戳

从 Rust 源码注释（rust/lancedb/src/function.rs）可以看出一个关键设计：errorMessage 携带了导致失败的那一行输入值。这意味着读取错误本身需要表的读权限——这是functionErrors()在 LanceDB Cloud 与 Enterprise 上要求读权限的根本原因（见 nodejs/lancedb/table.ts 中functionErrors()的 JSDoc）。

利用rowOffset与fragmentId，你可以精确定位失败行在物理存储中的位置；利用createdAtMillis则可以按时间倒序追踪某次刷新任务的失败窗口。

fragments：被封顶片段的汇总摘要

fragments: FunctionErrorFragment[]解决的是"错误行过多"的审计开销问题。当一个片段（fragment）内的失败行数超过服务端允许记录明细的上限时，服务端会停止为该片段逐行记录，转而只保留一个摘要。对应的FunctionErrorFragment（文档见 docs/src/js/interfaces/FunctionErrorFragment.md）在 rust/lancedb/src/function.rs 中定义：

pub struct FunctionErrorFragment { pub job_id: String, // 记录这些错误的刷新任务 pub fragment_id: u64, // 被封顶的片段 pub rows_skipped: u64, // 该片段中刷新任务跳过的总行数 pub rows_recorded: u64, // 其中仍拥有独立 FunctionErrorRecord 的行数 }

映射到 JS 侧后字段名为jobId、fragmentId、rowsSkipped、rowsRecorded（转换逻辑见 nodejs/src/table.rs）。

它的语义可以概括为：rows_skipped行失败了，但只有rows_recorded行保留了逐行明细。当出现fragments非空时，说明存在"明细被截断"的片段——此时records中的对应行rowOffset为undefined，需要结合片段摘要判断错误规模。

truncated：结果是否被 limit 截断

truncated: boolean是一个简单的告警标志，表示"本次列出的记录是否在达到 limit 时停止"。在 rust/lancedb/src/function.rs 中它默认序列化为false。

当truncated为true时，records并不代表该条件下的全部错误，而只是前 N 条。此时有两种处理思路：

1. 提高limit（服务端上限 100000）；
2. 使用jobId/column过滤条件缩小查询范围，分任务、分列地拉取完整错误集。

调用链与 FunctionErrorsOptions 的配合

functionErrors()是读取该接口的唯一入口，声明于 nodejs/lancedb/table.ts：

async functionErrors(options?: FunctionErrorsOptions): Promise<FunctionErrors>;

请求参数FunctionErrorsOptions（文档见 docs/src/js/interfaces/FunctionErrorsOptions.md）在 nodejs/src/table.rs 中定义为三个可选过滤条件：

参数	类型	含义
jobId	string | undefined	只列出该任务记录的错误
column	string | undefined	只列出该列上的错误
limit	number | undefined	最多返回多少条记录（服务端默认 10000，上限 100000）

三个过滤条件全部可选；当全部省略时，返回的是表上"所有刷新任务 × 所有计算列"的完整错误列表（见 rust/lancedb/src/function.rs 中FunctionErrorsRequest的注释：列表以表为寻址单位）。

完整的调用链为：

1. JS 层Table.functionErrors(options)（nodejs/lancedb/table.ts）先对options.limit做非负整数校验，再透传给内部实现；
2. N-API 层function_errors（nodejs/src/table.rs）将FunctionErrorsOptions组装为FunctionErrorsRequest并调用 Rust 核心；
3. Rust 核心执行查询后，FunctionErrors通过From转换（nodejs/src/table.rs）映射回 JS 对象。

典型使用场景与示例

FunctionErrors 最常见的用途是排查 embedding 或自定义 Function 刷新失败的数据。配合refreshColumnAsync()（跳过策略）使用：一个刷新任务在 skip 策略下运行时，不会因个别行失败而中止整个任务，而是把失败行记录下来供事后审计。

import * as lancedb from "@lancedb/lancedb"; const db = await lancedb.connect("./data"); const table = await db.openTable("documents"); // 1. 触发计算列的后台刷新（skip 策略） const job = await table.refreshColumnAsync("embedding"); await job.wait(); console.log(await job.status()); // "finished" // 2. 读取该任务的逐行错误 const { records, fragments, truncated } = await table.functionErrors({ jobId: job.id, // 或省略，查看全部任务 column: "embedding", // 聚焦到 embedding 列 limit: 10000, // 服务端默认 10000，上限 100000 }); console.log(`records: ${records.length}, truncated: ${truncated}`); for (const rec of records.slice(0, 5)) { console.log( `fragment=${rec.fragmentId} offset=${rec.rowOffset} ` + `fn=${rec.function}@${rec.functionVersion} ` + `error=${rec.errorType}: ${rec.errorMessage}`, ); } // 3. 检查是否有被封顶的片段 for (const frag of fragments) { console.log( `fragment ${frag.fragmentId}: ${frag.rowsSkipped} skipped, ` + `${frag.rowsRecorded} recorded`, ); }

注意事项：

• functionErrors()仅适用于 LanceDB Cloud 与 Enterprise（见 nodejs/lancedb/table.ts 的 JSDoc 说明）；本地表上的刷新任务在进程内执行（in-process）。
• 读取错误需要表的读权限，因为错误消息中携带了失败行输入。
• 单次返回的records上限受limit约束，务必检查truncated，必要时按jobId/column分批拉取。

小结

FunctionErrors 接口是 LanceDB Function 体系（计算列刷新）的可观测性基石：records提供逐行、含失败输入的错误明细，fragments兜底海量错误场景下的片段级汇总，truncated保证结果的可信边界。理解三者配合方式，你就能在 embedding 生成、数据变换等批量计算场景中精准定位失败数据，而不是面对一条笼统的任务失败状态无从下手。相关类型声明与实现可继续查阅 docs/src/js/interfaces/FunctionErrorRecord.md、docs/src/js/interfaces/FunctionErrorFragment.md 以及 nodejs/src/table.rs。

【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedb