Implementation:Lance format Lance Java Branch

Knowledge Sources	Lance
Domains	Java_SDK, Dataset_Management
Last Updated	2026-02-08 19:33 GMT

Overview

Description

Branch is an immutable value class in the Lance Java SDK that holds branch metadata aligned with the Rust BranchContents struct. A branch represents a named divergent line of dataset versions, enabling concurrent development on different data evolution paths. Each Branch stores its name, optional parent branch, the version on which it was created, a creation timestamp (as a Unix epoch in seconds), and the size of the referenced manifest file in bytes.

Usage

Branch objects are returned by the Lance Java SDK when querying dataset version metadata. They implement equals() and hashCode() based on all fields, making them suitable for use in collections and comparison operations. A null parentBranch in the constructor is automatically wrapped as Optional.empty(), indicating the main branch.

Code Reference

Source Location

java/src/main/java/org/lance/Branch.java

Signature

public class Branch {
    public Branch(String name, String parentBranch, long parentVersion,
                  long createAt, int manifestSize);
    public String getName();
    public Optional<String> getParentBranch();
    public long getParentVersion();
    public long getCreateAt();
    public int getManifestSize();
    public String toString();
    public boolean equals(Object o);
    public int hashCode();
}

Import

import org.lance.Branch;

I/O Contract

Constructor Parameters

Name	Type	Description
name	String	The branch name
parentBranch	String	The parent branch name; null indicates the main branch
parentVersion	long	The version number on which this branch was created
createAt	long	Unix timestamp in seconds when the branch was created
manifestSize	int	Size of the referenced manifest file in bytes

Return Values

Method	Return Type	Description
getName()	String	Returns the branch name
getParentBranch()	Optional<String>	Returns the parent branch name, or empty if main
getParentVersion()	long	Returns the parent version number
getCreateAt()	long	Returns creation timestamp as Unix epoch seconds
getManifestSize()	int	Returns the manifest file size in bytes

Usage Examples

import org.lance.Branch;

// Branch created from main (parentBranch is null)
Branch featureBranch = new Branch("feature-vectors", null, 5, 1700000000L, 4096);

System.out.println(featureBranch.getName());           // feature-vectors
System.out.println(featureBranch.getParentBranch());   // Optional.empty
System.out.println(featureBranch.getParentVersion());  // 5
System.out.println(featureBranch.getCreateAt());       // 1700000000

// Branch created from another branch
Branch childBranch = new Branch("experiment-1", "feature-vectors", 8, 1700100000L, 2048);

System.out.println(childBranch.getParentBranch());     // Optional[feature-vectors]

// Equality comparison
Branch sameBranch = new Branch("feature-vectors", null, 5, 1700000000L, 4096);
System.out.println(featureBranch.equals(sameBranch));  // true

Related Pages

• Lance_format_Lance_Java_Ref - References branches, tags, and versions for dataset access
• Lance_format_Lance_Java_Transaction - Transactions that may operate on specific branches