Skip to content

feat: add table branch operations and branch parameter#350

Merged
jackye1995 merged 1 commit into
lance-format:mainfrom
brendanclement:feat/table-branches
Jun 5, 2026
Merged

feat: add table branch operations and branch parameter#350
jackye1995 merged 1 commit into
lance-format:mainfrom
brendanclement:feat/table-branches

Conversation

@brendanclement

Copy link
Copy Markdown
Collaborator

Summary

Adds first-class table branch support to the namespace spec: three branch lifecycle operations plus an optional branch parameter on the branch-scoped table operations. Branches are already a first-class ref in the Lance table format (alongside tags and versions), and this brings the namespace API in line with that model. An absent branch always means the main branch, so the change is fully backward compatible.

New operations

  • CreateTableBranch (POST /v1/table/{id}/branches/create): name is required; optional from_branch and from_version create the branch from a specific point (defaulting to the latest version of main).
  • ListTableBranches (POST /v1/table/{id}/branches/list): returns a map of branch name to BranchContents.
  • DeleteTableBranch (POST /v1/table/{id}/branches/delete): name is required.

New BranchContents schema (modeled on TagContents): parentBranch (absent when the branch came from main), parentVersion, createAt, manifestSize, and optional metadata.

The branch parameter

A branch selects which ref a branch-scoped operation targets, so it is the natural sibling of the existing version parameter and is carried wherever each operation already passes its parameters:

  • Operations with a JSON request body get a branch field in the body, placed alongside version where the operation already has one (describe, count, query, stats, update, delete, the alter and backfill-column operations, the index operations, the version operations, and the tag operations).
  • Operations with no JSON parameter body get branch as a query parameter, the same way delimiter is already passed:
    • Arrow-stream bodies: InsertIntoTable, MergeInsertIntoTable
    • bodyless or raw-body: ListTableVersions, UpdateTableSchemaMetadata, DropTableIndex

@github-actions github-actions Bot added the enhancement New feature or request label Jun 4, 2026

@jackye1995 jackye1995 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good to me!

@jackye1995 jackye1995 merged commit fa0fe85 into lance-format:main Jun 5, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants