Implementation:Lance format Lance Java Ref

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

Overview

Description

Ref is an immutable value class that represents a reference to a specific point in a Lance dataset's version history. A Ref can identify a version by number on the main branch, a named branch (optionally at a specific version), or a named tag. The class provides static factory methods for constructing each type of reference with built-in input validation via Guava Preconditions.

Usage

Ref instances are created using the static factory methods ofMain(), ofBranch(), and ofTag(). The internal representation uses three Optional fields (versionNumber, branchName, tagName), where the combination of present/empty values determines the reference type. All factory methods validate their inputs and throw IllegalArgumentException for invalid values.

Code Reference

Source Location

java/src/main/java/org/lance/Ref.java

Signature

public class Ref {
    public Ref(Optional<Long> versionNumber, Optional<String> branchName,
               Optional<String> tagName);
    public Optional<Long> getVersionNumber();
    public Optional<String> getBranchName();
    public Optional<String> getTagName();
    public static Ref ofMain(long versionNumber);
    public static Ref ofMain();
    public static Ref ofBranch(String branchName);
    public static Ref ofBranch(String branchName, long versionNumber);
    public static Ref ofTag(String tagName);
    public String toString();
}

Import

import org.lance.Ref;

I/O Contract

**Factory Methods**
Method	Parameters	Description
ofMain()	none	Reference to the latest version on main
ofMain(long)	versionNumber > 0	Reference to a specific version on main
ofBranch(String)	non-null, non-empty branchName	Reference to the latest version on a named branch
ofBranch(String, long)	non-null, non-empty branchName; versionNumber > 0	Reference to a specific version on a named branch
ofTag(String)	non-null, non-empty tagName	Reference to a named tag

**Getter Return Values**
Method	Return Type	Description
getVersionNumber()	`Optional<Long>`	The version number, or empty for latest
getBranchName()	`Optional<String>`	The branch name, or empty if referencing main or a tag
getTagName()	`Optional<String>`	The tag name, or empty if not a tag reference

**Exceptions**
Method	Exception	Condition
ofMain(long)	`IllegalArgumentException`	versionNumber <= 0
ofBranch(String)	`IllegalArgumentException`	branchName is null or empty
ofBranch(String, long)	`IllegalArgumentException`	branchName is null/empty or versionNumber <= 0
ofTag(String)	`IllegalArgumentException`	tagName is null or empty

Usage Examples

import org.lance.Ref;

// Reference to the latest version on main
Ref latestMain = Ref.ofMain();

// Reference to version 5 on main
Ref version5 = Ref.ofMain(5);

// Reference to the latest version on a named branch
Ref devBranch = Ref.ofBranch("development");

// Reference to a specific version on a named branch
Ref branchV3 = Ref.ofBranch("feature-embeddings", 3);

// Reference to a named tag
Ref releaseTag = Ref.ofTag("v1.0-release");

// Inspect a reference
System.out.println(version5.getVersionNumber());  // Optional[5]
System.out.println(version5.getBranchName());      // Optional.empty
System.out.println(devBranch.getBranchName());     // Optional[development]

Related Pages

Lance_format_Lance_Java_Branch - Branch metadata that Ref can reference by name
Lance_format_Lance_Java_ReadOptions - ReadOptions can specify a version to read, complementing Ref
Lance_format_Lance_Java_OpenDatasetBuilder - Opens datasets that may be accessed via version references

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment