LanceDB JS SDK 的 CherryPickResult 接口详解分支 Cherry-Pick 的结果契约与实战解析【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedb导读LanceDB 的版本控制能力中分支Branch与 Cherry-Pick 是管理数据表变更的核心机制。CherryPickResult是 JavaScript/TypeScript SDK 中描述预览或执行一次 cherry-pick 后返回结果的接口它统一承载了操作状态、分支差异快照、将被提升的列变更以及提升后的主分支版本号四类信息。读完本文你将完整掌握CherryPickResult的每个字段含义、五种status状态的语义、与BranchDiff、CherryPickPreview等关联接口的协作关系以及如何结合table.branches.cherryPick()在真实项目中落地先预览、再执行、后核验的安全变更流程。接口总览一次 Cherry-Pick 操作返回什么CherryPickResult在 TypeScript 中定义为一个普通接口位于 nodejs/lancedb/table.ts文档化页面为 CherryPickResult.md。其完整定义如下/** Result of previewing or attempting a cherry-pick. */ export interface CherryPickResult { status: ready | failed | notImplemented | cherryPicked | unknown; diff: BranchDiff; preview: CherryPickPreview; mainVersionAfter?: number; }接口的 JSDoc 注释点明了它的定位Result of previewing or attempting a cherry-pick即无论是dryRun预览还是实际执行返回的都是同一个结构。这意味着调用方可以用一套解析逻辑同时处理预览与执行两种场景——这正是指引先预览、再提交安全流程得以成立的设计基础。该接口包含四个字段其中三个必填、一个可选各自承担不同职责字段类型必填职责status字符串字面量联合是本次 cherry-pick 的最终状态diffBranchDiff是分支与 main 的只读差异快照previewCherryPickPreview是将被或已经被提升的列变更清单mainVersionAfternumber否成功提升后 main 的新版本号status五种状态精确刻画操作结局status是该接口中信息量最大的字段它是一个字符串字面量联合类型只允许以下五个取值status: | failed | unknown | ready | notImplemented | cherryPicked;从 Rust 核心层的定义可以确认这五种状态一一对应 rust/lancedb/src/table/cherry_pick.rs 中的CherryPickStatus枚举pub enum CherryPickStatus { Ready, Failed, NotImplemented, CherryPicked, #[serde(other)] Unknown, }各状态的语义如下ready已通过所有冲突检查随时可以真正落地执行。对应 Rust 层CherryPickStatus::Ready。在dryRun预览模式下这是最理想的返回值代表确认无误可以执行。failed本次 cherry-pick 无法落地原因细节在diff.errors中给出。需要特别注意的是Node.js 侧的 Branches.cherryPick() 的 JSDoc 明确写道A failed cherry-pick resolves withstatus: failedinstead of throwing.——失败不会抛出异常而是以正常 resolve 的方式返回status: failed这要求调用方必须主动检查status字段而不是依赖 try/catch。unknown服务端返回了当前 SDK 无法识别的状态。Rust 层通过#[serde(other)]兜底反序列化保证未来新增状态时旧客户端不会崩溃。notImplemented当前存储后端不支持 cherry-pick 能力。Rust 层的默认实现如原生本地表路径会返回此状态见 rust/lancedb/src/table.rs 附近的 trait 默认实现。cherryPicked操作已成功执行分支变更已提升到 main。从源码结构看远程实现中对 HTTP 409 冲突响应也会归一化为CherryPickStatus::Failed并以正常Ok返回参见 rust/lancedb/src/remote/table.rs 的注释 HTTP 409 is CherryPickStatus::Failed with a body, not a transport error.进一步印证了失败不抛异常、以状态码表达这一约定贯穿全链路。diff失败原因与变更内容的唯一事实来源diff字段的类型是BranchDiff文档注释将其描述为 Read-only comparison of a branch against main即分支与 main 的只读差异。它是CherryPickResult中最复杂、信息量最大的成员完整定义见 BranchDiff.md 与 nodejs/lancedb/table.tsexport interface BranchDiff { fromBranch: string; parentVersion: number; mainVersion: number; branchVersion: number; baseMoved: boolean; rowCountMain: number; rowCountBranch: number; rowSummary: BranchRowCountSummary; addedColumns: BranchColumnSummary[]; removedColumns: BranchColumnSummary[]; changedColumns: BranchColumnChange[]; addedIndexes: BranchIndexSummary[]; removedIndexes: BranchIndexSummary[]; errors: CherryPickError[]; }版本坐标定位分支在历史中的位置fromBranch、parentVersion、mainVersion、branchVersion四个字段共同构成一次差异比较的坐标系统fromBranch被比较即作为 cherry-pick 来源的分支名parentVersion分支 fork 时的父版本号mainVersion比较发生时 main 的当前版本号branchVersion比较发生时分支的最新版本号。通过对比parentVersion与mainVersion即可判断baseMoved是否成立——即 main 在分支创建之后是否又前进了这直接影响 cherry-pick 是否安全。行列统计量化差异规模rowCountMain与rowCountBranch给出两侧的行数。rowSummary类型BranchRowCountSummary则进一步把行级差异细分为六类见 nodejs/lancedb/table.tsexport interface BranchRowCountSummary { unchanged: number; // 两侧内容相同的行 newOnBase: number; // 仅在 mainbase侧新增的行 newOnBranch: number; // 仅在分支侧新增的行 staleRecompute: number; // 需要重新计算的行 inputsChanged: number; // 输入发生变化的行 deltaAvailable: boolean; // 是否可获取增量 }Rust 侧对应的RowCountSummary结构体见 rust/lancedb/src/table/cherry_pick.rs。结构与索引变更columns 与 indexesBranchDiff用三类字段描述 Schema 与索引的演变addedColumns/removedColumns类型为BranchColumnSummary[]每项包含name、dataType、nullable三个属性见 nodejs/lancedb/table.ts描述列的新增与删除changedColumns类型为BranchColumnChange[]每项同时携带main与branch两侧的列摘要用于对比同名列的定义差异见 nodejs/lancedb/table.tsaddedIndexes/removedIndexes类型为BranchIndexSummary[]包含indexName、columns、可选的indexType与status见 nodejs/lancedb/table.ts。errors失败原因的结构化载体errors的类型是CherryPickError[]文档注释为 A reason why a cherry-pick cannot currently land即本次 cherry-pick 当前无法落地的原因集合。每个错误项仅含两个字段export interface CherryPickError { code: string; message: string; }code的取值在 Rust 层由CherryPickErrorCode枚举约束见 rust/lancedb/src/table/cherry_pick.rs主要包括BaseMoved分支的父版本已不是 main 的最新版本RowCountMismatch两侧行数不匹配RowsChanged存在行内容冲突ColumnRemoved/ColumnChanged分支依赖的列被移除或定义被修改NothingToApply/NoColumnChanges没有可提升的变更InputColumnDependency存在输入列依赖问题ParentNotMain分支的父分支不是 mainUnknown无法识别的错误码serde 兜底。实际使用中当status failed时应当遍历result.diff.errors依据code决定是同步 main 后重试对应BaseMoved、解决行冲突对应RowsChanged还是重建分支对应ParentNotMain。preview 与 mainVersionAfter预览什么、变成什么preview将被提升的列preview字段的类型是CherryPickPreview文档注释为 Changes that would be, or were, promoted by a cherry-pick即将要被或已经被提升的变更。它的结构极其精简仅含一个字段export interface CherryPickPreview { promotedColumns: string[]; }promotedColumns是被提升到 main 的列名数组。Rust 层的实现为promoted_columns序列化为 camelCase并通过#[serde(default)]保证缺失时默认为空数组见 rust/lancedb/src/table/cherry_pick.rs。注意preview只描述列级别的提升行级数据的变化需要结合diff.rowSummary理解。mainVersionAfter唯一可选字段mainVersionAfter是接口中唯一可选的字段optional mainVersionAfter: number表示cherry-pick 成功之后 main 的新版本号。之所以可选可以从 Rust 层实现推断该字段被标注为#[serde(default, skip_serializing_if Option::is_none)]见 rust/lancedb/src/table/cherry_pick.rs即仅在成功落地status cherryPicked时才有值在dryRun预览或失败场景下该字段不出现因此访问前必须做空值判断。if (result.status cherryPicked result.mainVersionAfter ! undefined) { console.log(main 已前进到版本 ${result.mainVersionAfter}); }获取 CherryPickResultBranches.cherryPick 调用链CherryPickResult是Branches类中cherryPick()方法的返回值。Branches是 Table 的分支管理器其定义与实现位于 nodejs/lancedb/table.tsexport class Branches { // ... /** * Cherry-pick a branch onto main. * * Set dryRun to true to preview. A failed cherry-pick resolves * with status: failed instead of throwing. * * param fromBranch Branch to cherry-pick from. * param dryRun When true, only preview. Defaults to false. */ async cherryPick( fromBranch: string, dryRun: boolean false, ): PromiseCherryPickResult { return (await this.#inner.cherryPick( fromBranch, dryRun, )) as unknown as CherryPickResult; } }方法签名有两个参数fromBranchcherry-pick 的来源分支与dryRun是否仅预览默认false。调用后返回的正是本文主角CherryPickResult。跨语言调用链cherryPick()的完整链路可以梳理为三层TypeScript 层Branches.cherryPick()调用原生绑定this.#innerNAPI 绑定层nodejs/src/table.rs中的cherry_pick方法将dry_run.unwrap_or(false)传入 Rust 核心并把结果序列化为 JSON见 nodejs/src/table.rs#[napi(ts_return_type PromiseRecordstring, unknown)] pub async fn cherry_pick( self, from_branch: String, dry_run: Optionbool, ) - napi::Resultserde_json::Value { let result self.inner.cherry_pick(from_branch, dry_run.unwrap_or(false)).await.default_error()?; serde_json::to_value(result).map_err(|err| { napi::Error::from_reason(format!(failed to serialize cherry-pick result: {err})) }) }Rust 核心层远程表实现中通过 HTTP 调用服务端并对 409 冲突归一化为Failed状态正常返回见 rust/lancedb/src/remote/table.rs。Rust 侧的测试用例也直接验证了各状态与字段语义例如在 rust/lancedb/src/remote/table.rs 附近分别断言了Ready、CherryPicked与Failed三种状态可作为理解行为契约的参考。完整实战示例以下示例演示预览 → 检查 → 执行的标准三段式流程import { connect } from lancedb/lancedb; const db await connect(s3://your-bucket/path); const table await db.openTable(my_table); // 1. 预览dryRun 模式不修改任何数据 const previewResult: CherryPickResult await table.branches.cherryPick( feature-branch, true, // dryRun ); if (previewResult.status ready) { console.log(预览通过将提升以下列, previewResult.preview.promotedColumns); console.log(分支差异, previewResult.diff); // 2. 执行真正落地 const result await table.branches.cherryPick(feature-branch); if (result.status cherryPicked) { console.log(Cherry-pick 成功main 新版本${result.mainVersionAfter}); } } else if (previewResult.status failed) { // 3. 失败处理遍历结构化错误 for (const err of previewResult.diff.errors) { console.error([${err.code}] ${err.message}); } }需要强调的是由于dryRun默认值为false不带第二参数调用即表示真实执行生产环境中务必先以dryRun: true预览。关联接口与邻近 APICherryPickResult并非孤立存在它与Branches分支管理族的其他 API 共同构成完整的工作流branches.list()列出所有分支branches.create(name, fromRef?, fromVersion?)创建分支并返回作用域于该分支的Table句柄见 nodejs/lancedb/table.tsbranches.checkout(name, version?)检出分支可指定版本得到只读的 detached 视图见 nodejs/lancedb/table.tsbranches.diff(fromBranch)仅比较分支与 main 的差异返回BranchDiff不修改任何分支见 nodejs/lancedb/table.tsbranches.cherryPick(fromBranch, dryRun?)预览或执行 cherry-pick返回CherryPickResult。其中diff()与cherryPick(dryRuntrue)都返回差异信息但前者完全不产生任何状态适合纯粹的只读审查后者则带着能否落地、落地后变成什么的完整结论。推荐在 CI 或数据评审流程中先用diff()审查再通过cherryPick(dryRuntrue)做最终预演。Python SDK 也提供了同名的cherry_pick(from_branch, dry_runFalse)方法并返回Dict[str, Any]见 python/python/lancedb/table.py 与 python/python/lancedb/_lancedb.pyi字段结构与本文介绍的 TypeScript 接口一一对应方便多语言团队对齐心智模型。小结把 CherryPickResult 当作流程状态机来用CherryPickResult的本质是一次 cherry-pick 操作的完整状态快照status告诉你到了哪一步diff告诉你为什么与差在哪preview告诉你会改什么mainVersionAfter告诉你改完变成什么。开发者在接入时应牢牢把握三条实践准则永远先检查status因为失败不会抛异常而是以failed正常返回失败时读取diff.errors的code用结构化错误码驱动重试策略而不是解析人读文本先dryRun: true预览再真实执行并结合mainVersionAfter校验 main 的版本推进是否符合预期。理解了这份结果契约你就能把 LanceDB 的分支 Cherry-Pick 能力安全地编排进数据变更审批、灰度实验和可回溯的数据管线之中。【免费下载链接】lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.项目地址: https://gitcode.com/gh_mirrors/la/lancedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考