Implementation:Lance format Lance Java CleanupPolicy

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

Overview

Description

CleanupPolicy is an immutable configuration class that defines the policy for cleaning up old dataset versions and unreferenced data files. It supports filtering by timestamp threshold, version threshold, handling of unverified data files, and behavior when tagged versions match the cleanup criteria. All fields are intentionally Optional to avoid overriding default values defined in the Rust implementation.

Usage

CleanupPolicy is constructed via its static builder() method and inner Builder class. It is passed to dataset cleanup operations to control which versions and files are eligible for removal. The builder methods allow selective configuration -- only the parameters explicitly set will override the Rust-side defaults.

Code Reference

Source Location

java/src/main/java/org/lance/cleanup/CleanupPolicy.java

Signature

public class CleanupPolicy {
    public static Builder builder();
    public Optional<Long> getBeforeTimestampMillis();
    public Optional<Long> getBeforeVersion();
    public Optional<Boolean> getDeleteUnverified();
    public Optional<Boolean> getErrorIfTaggedOldVersions();

    public static class Builder {
        public Builder withBeforeTimestampMillis(long beforeTimestampMillis);
        public Builder withBeforeVersion(long beforeVersion);
        public Builder withDeleteUnverified(boolean deleteUnverified);
        public Builder withErrorIfTaggedOldVersions(boolean errorIfTaggedOldVersions);
        public CleanupPolicy build();
    }
}

Import

import org.lance.cleanup.CleanupPolicy;

I/O Contract

**Builder Parameters**
Method	Type	Description
withBeforeTimestampMillis()	`long`	Timestamp threshold in milliseconds since UNIX epoch (UTC); versions older than this are eligible for cleanup
withBeforeVersion()	`long`	Version threshold; versions older than this number are eligible for cleanup
withDeleteUnverified()	`boolean`	If true, delete unverified data files even if they are recent
withErrorIfTaggedOldVersions()	`boolean`	If true, raise an error when tagged versions match the cleanup policy

**Getter Return Values**
Method	Return Type	Description
getBeforeTimestampMillis()	`Optional<Long>`	Timestamp threshold or empty if not set
getBeforeVersion()	`Optional<Long>`	Version threshold or empty if not set
getDeleteUnverified()	`Optional<Boolean>`	Unverified deletion flag or empty if not set
getErrorIfTaggedOldVersions()	`Optional<Boolean>`	Tagged version error flag or empty if not set

Usage Examples

import org.lance.cleanup.CleanupPolicy;

// Clean up versions older than 7 days
long sevenDaysAgo = System.currentTimeMillis() - (7L * 24 * 60 * 60 * 1000);
CleanupPolicy policy = CleanupPolicy.builder()
    .withBeforeTimestampMillis(sevenDaysAgo)
    .build();

// Clean up versions before version 10, erroring on tagged versions
CleanupPolicy policy = CleanupPolicy.builder()
    .withBeforeVersion(10)
    .withErrorIfTaggedOldVersions(true)
    .build();

// Aggressive cleanup: delete unverified files too
CleanupPolicy policy = CleanupPolicy.builder()
    .withBeforeTimestampMillis(sevenDaysAgo)
    .withDeleteUnverified(true)
    .build();

// Minimal policy using only Rust defaults
CleanupPolicy defaultPolicy = CleanupPolicy.builder().build();

Related Pages

Lance_format_Lance_Java_Compaction - Compaction operations that may produce versions eligible for cleanup
Lance_format_Lance_Java_CompactionOptions - Compaction configuration that is complementary to cleanup

Page Connections

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

Principle

Implementation

Heuristic

Environment