Implementation:Lance format Lance Dataset Versions

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

Overview

Concrete tool for retrieving all historical versions of a Lance dataset, provided by the Lance library.

Description

Dataset::versions() returns a sorted vector of Version structs representing every committed version of the dataset. Internally it calls CommitHandler::list_manifest_locations() to stream all manifest file locations, reads each manifest, converts it to a Version via From<&Manifest>, collects the results, and sorts them by version number in ascending order.

The Version struct is a lightweight data-transfer object with three fields: the version number, creation timestamp, and a metadata map extracted from the manifest summary.

Usage

Call this method to enumerate all available versions of a dataset for display, auditing, or programmatic selection before performing a checkout or restore operation.

Code Reference

Source Location

• Repository: Lance
• File: rust/lance/src/dataset.rs
• Lines: L1779-L1796 (method), L191-L212 (Version struct)

Signature

impl Dataset {
    /// Get all versions.
    pub async fn versions(&self) -> Result<Vec<Version>>
}

Version struct:

#[derive(Deserialize, Serialize, Debug)]
pub struct Version {
    /// version number
    pub version: u64,

    /// Timestamp of dataset creation in UTC.
    pub timestamp: DateTime<Utc>,

    /// Key-value pairs of metadata.
    pub metadata: BTreeMap<String, String>,
}

Import

use lance::Dataset;
use lance::dataset::Version;

I/O Contract

Inputs

Name	Type	Required	Description
self	&Dataset	Yes	The dataset handle. The method uses the dataset's commit handler and object store to discover manifests.

Outputs

Name	Type	Description
Ok	Vec<Version>	A vector of all versions sorted in ascending order by version number.
Err	Error	An error if manifest listing or reading fails (e.g., object store I/O error, corrupt manifest).

Usage Examples

use lance::Dataset;

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

    for v in &versions {
        println!(
            "Version {} created at {} with metadata: {:?}",
            v.version, v.timestamp, v.metadata
        );
    }

    println!("Total versions: {}", versions.len());
    Ok(())
}

Related Pages

Implements Principle

• Principle:Lance_format_Lance_Version_Listing