Implementation:Lance format Lance Java FragmentMetadata

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

Overview

Description

FragmentMetadata is a serializable value class that represents the metadata of a single fragment within a Lance dataset. It corresponds to the Rust Fragment struct. Each fragment contains one or more data files, a count of physical rows, an optional deletion file tracking deleted rows, and optional row ID metadata. FragmentMetadata provides convenience methods to compute the number of active (non-deleted) rows and the number of deletions.

Usage

FragmentMetadata objects are returned by fragment write operations (via WriteFragmentBuilder or Fragment.create()) and are passed into commit operations (FragmentOperation, Transaction). The class implements Serializable for distributed computing scenarios where fragment metadata must be transmitted across network boundaries.

Code Reference

Source Location

java/src/main/java/org/lance/FragmentMetadata.java

Signature

public class FragmentMetadata implements Serializable {
    public FragmentMetadata(int id, List<DataFile> files, Long physicalRows,
                            DeletionFile deletionFile, RowIdMeta rowIdMeta);
    public int getId();
    public List<DataFile> getFiles();
    public long getPhysicalRows();
    public DeletionFile getDeletionFile();
    public long getNumDeletions();
    public long getNumRows();
    public RowIdMeta getRowIdMeta();
    public boolean equals(Object o);
    public String toString();
}

Import

import org.lance.FragmentMetadata;

I/O Contract

Constructor Parameters

Name	Type	Description
id	int	Unique fragment identifier within the dataset
files	List<DataFile>	List of data files composing the fragment
physicalRows	Long	Total number of physical rows (including deleted)
deletionFile	DeletionFile	Optional deletion file tracking removed rows (may be null)
rowIdMeta	RowIdMeta	Optional row ID metadata (may be null)

Return Values

Method	Return Type	Description
getId()	int	Returns the fragment identifier
getFiles()	List<DataFile>	Returns the list of data files
getPhysicalRows()	long	Returns total physical row count
getDeletionFile()	DeletionFile	Returns the deletion file or null
getNumDeletions()	long	Returns the count of deleted rows (0 if no deletion file)
getNumRows()	long	Returns active row count (physicalRows minus deletions)
getRowIdMeta()	RowIdMeta	Returns row ID metadata or null

Usage Examples

import org.lance.FragmentMetadata;
import org.lance.WriteFragmentBuilder;
import java.util.List;

// Write fragments and get their metadata
List<FragmentMetadata> fragments = Fragment.write()
    .datasetUri("s3://bucket/dataset.lance")
    .allocator(allocator)
    .data(vectorSchemaRoot)
    .execute();

// Inspect fragment metadata
for (FragmentMetadata fragment : fragments) {
    System.out.println("Fragment ID: " + fragment.getId());
    System.out.println("Physical rows: " + fragment.getPhysicalRows());
    System.out.println("Active rows: " + fragment.getNumRows());
    System.out.println("Deletions: " + fragment.getNumDeletions());
    System.out.println("Data files: " + fragment.getFiles().size());
}

Related Pages

• Lance_format_Lance_Java_WriteFragmentBuilder - Builder that produces FragmentMetadata upon writing fragments
• Lance_format_Lance_Java_FragmentOperation - Deprecated commit operations that consume FragmentMetadata lists
• Lance_format_Lance_Java_Transaction - Modern transaction API that uses FragmentMetadata
• Lance_format_Lance_Java_CompactionTask - Compaction tasks that rewrite fragments