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/lancedbFunctionErrors 是 LanceDB Node.js SDKlancedb/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 侧。其字段包括字段类型含义jobIdstring记录该错误的刷新任务 IDfragmentIdnumber承载该行的数据片段fragmentIDrowOffsetnumber | undefined行在片段内的偏移量当片段细节被封顶、仅剩片段摘要时该字段为undefinedcolumnstring正在计算的列名functionstring执行失败的 Function 名称functionVersionstring该 Function 的版本号tableVersionnumber刷新任务读取的表版本errorTypestring执行器报告的异常类别errorMessagestring错误文本createdAtMillisnumber错误被记录的 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 条。此时有两种处理思路提高limit服务端上限 100000使用jobId/column过滤条件缩小查询范围分任务、分列地拉取完整错误集。调用链与 FunctionErrorsOptions 的配合functionErrors()是读取该接口的唯一入口声明于 nodejs/lancedb/table.tsasync functionErrors(options?: FunctionErrorsOptions): PromiseFunctionErrors;请求参数FunctionErrorsOptions文档见 docs/src/js/interfaces/FunctionErrorsOptions.md在 nodejs/src/table.rs 中定义为三个可选过滤条件参数类型含义jobIdstring | undefined只列出该任务记录的错误columnstring | undefined只列出该列上的错误limitnumber | undefined最多返回多少条记录服务端默认 10000上限 100000三个过滤条件全部可选当全部省略时返回的是表上所有刷新任务 × 所有计算列的完整错误列表见 rust/lancedb/src/function.rs 中FunctionErrorsRequest的注释列表以表为寻址单位。完整的调用链为JS 层Table.functionErrors(options)nodejs/lancedb/table.ts先对options.limit做非负整数校验再透传给内部实现N-API 层function_errorsnodejs/src/table.rs将FunctionErrorsOptions组装为FunctionErrorsRequest并调用 Rust 核心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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考