Implementation:Lance format Lance Dataset Checkout Version

Knowledge Sources	Lance
Domains	Data_Engineering, Version_Control
Last Updated	2026-02-08 19:00 GMT

Overview

Concrete tool for checking out a specific version of a Lance dataset by version number, branch-version pair, or tag name, provided by the Lance library.

Description

Dataset::checkout_version() accepts any value that implements Into<Ref> and returns a new Dataset handle pinned to the requested version. The method dispatches on the Ref variant:

• VersionNumber(u64) -- resolves the version on the current branch.
• Version(Option<String>, Option<u64>) -- resolves on the specified branch (or main if None), at the specified version (or latest if None).
• Tag(String) -- fetches the TagContents from storage and resolves the branch and version stored therein.

Related convenience methods include checkout_latest() (mutates the current handle in place to the newest version) and checkout_branch() (checks out the latest version of a named branch).

Usage

Use checkout_version() when you need to read data from a historical version, switch to a different branch, or resolve a named tag to its underlying dataset state.

Code Reference

Source Location

• Repository: Lance
• File: rust/lance/src/dataset.rs
• Lines: L415-L432 (checkout_version), L536-L579 (checkout_by_ref)
• File (Ref enum): rust/lance/src/dataset/refs.rs
• Lines: L28-L38

Signature

impl Dataset {
    /// Check out a dataset version with a ref.
    pub async fn checkout_version(&self, version: impl Into<refs::Ref>) -> Result<Self>
}

Ref enum:

pub enum Ref {
    /// Version number on the current branch.
    VersionNumber(u64),
    /// (branch_name, version_number) -- None means main / latest.
    Version(Option<String>, Option<u64>),
    /// Tag name that resolves to a specific (branch, version).
    Tag(String),
}

Convenience methods:

impl Dataset {
    /// Check out the latest version of the dataset (mutates in place).
    pub async fn checkout_latest(&mut self) -> Result<()>

    /// Check out the latest version of a named branch.
    pub async fn checkout_branch(&self, branch: &str) -> Result<Self>
}

Import

use lance::Dataset;
use lance::dataset::refs::Ref;

I/O Contract

Inputs

Name	Type	Required	Description
self	&Dataset	Yes	The current dataset handle providing the object store, commit handler, and session cache.
version	impl Into<Ref>	Yes	The version reference to check out. Accepts u64, &str (tag name), (&str, u64) (branch, version), or (Option<&str>, Option<u64>).

Outputs

Name	Type	Description
Ok	Dataset	A new Dataset handle pinned to the requested version. Shares the same session cache and object store as the original.
Err	Error	DatasetNotFound if the version does not exist, RefNotFound if a tag is missing, or an I/O error.

Usage Examples

use lance::Dataset;

async fn time_travel_examples(uri: &str) -> lance::Result<()> {
    let dataset = Dataset::open(uri).await?;

    // Check out by version number (u64):
    let v3 = dataset.checkout_version(3u64).await?;
    assert_eq!(v3.version().version, 3);

    // Check out by tag name:
    let tagged = dataset.checkout_version("release-v1").await?;

    // Check out by branch and version tuple:
    let branched = dataset.checkout_version(("feature-branch", 5u64)).await?;

    // Check out latest on a branch:
    let latest_on_branch = dataset.checkout_branch("feature-branch").await?;

    Ok(())
}

Related Pages

Implements Principle

• Principle:Lance_format_Lance_Time_Travel_Queries