Drew Gallardo
e98d8ac685
This PR is a **breaking** rename of #3686. merge reads like git merge w/ three-way, replay history, combine two lines of work. That is not this API. This call takes one additive change on a branch and lands it on main. New column, including a blob column. Main's existing columns are not rewritten. If it cannot land, you get `status="failed"` and `diff.errors`, not a merge conflict to resolve. Cherry-pick is terminology that aligns more with that. ```python table = db.open_table("images") table.branches.create("exp") exp = table.branches.checkout("exp") exp.add_columns({"tag": "cast('draft' as string)"}) diff = table.branches.diff("exp") preview = table.branches.cherry_pick("exp", dry_run=True) result = table.branches.cherry_pick("exp") if result["status"] == "cherryPicked": print("landed at", result["mainVersionAfter"]) elif result["status"] == "failed": print(result["diff"]["errors"]) ``` ### Behavior - Remote / Enterprise only. Local still NotSupported. - HTTP 409 is not an exception. It is Ok with status="failed" and diff.errors (CherryPickError). - Unknown error / status codes still parse as Unknown. - Requests are not retried. 409 is final and carries the body. - Endpoint is POST /v1/table/{id}/branches/cherry_pick/. - merge_insert and Table.merge are unchanged. ### Testing - `cargo test -p lancedb --features remote diff_branch` - `cargo test -p lancedb --features remote cherry_pick` - `pytest python/python/tests/test_remote_db.py -k cherry_pick` - node `remote.test.ts` diffs / cherry-picks path
2.2 KiB
@lancedb/lancedb • Docs
@lancedb/lancedb / Branches
Class: Branches
Branch manager for a Table.
Unlike tags, create and checkout return a new Table handle scoped
to the branch; writes on it do not affect main.
Methods
checkout()
checkout(name, version?): Promise<Table>
Check out an existing branch and return a handle scoped to it.
With version set, the returned handle is pinned to that version of the
branch (a read-only, detached view); otherwise it tracks the branch's
latest and stays writable.
Parameters
-
name:
string -
version?:
number
Returns
Promise<Table>
cherryPick()
cherryPick(fromBranch, dryRun): Promise<CherryPickResult>
Cherry-pick a branch onto main.
Set dryRun to true to preview. A failed cherry-pick resolves
with status: "failed" instead of throwing.
Parameters
-
fromBranch:
stringBranch to cherry-pick from. -
dryRun:
boolean=falseWhen true, only preview. Defaults to false.
Returns
Promise<CherryPickResult>
create()
create(
name,
fromRef?,
fromVersion?): Promise<Table>
Create a branch and return a handle scoped to it.
Parameters
-
name:
stringName of the new branch. -
fromRef?:
stringSource branch to fork from. Defaults tomain. -
fromVersion?:
numberA specific version onfromRef. Defaults to latest.
Returns
Promise<Table>
delete()
delete(name): Promise<void>
Delete a branch.
Parameters
- name:
string
Returns
Promise<void>
diff()
diff(fromBranch): Promise<BranchDiff>
Compare a branch against main without modifying either branch.
Parameters
- fromBranch:
string
Returns
Promise<BranchDiff>
list()
list(): Promise<Record<string, BranchContents>>
List all branches, mapping name to branch metadata.
Returns
Promise<Record<string, BranchContents>>