Implementation:Apache Paimon Instant

Knowledge Sources	Apache_Paimon
Domains	Table Management, Time Travel
Last Updated	2026-02-08 00:00 GMT

Overview

Instant represents a point-in-time reference for table rollback operations, supporting both snapshot IDs and tag names.

Description

Instant is a public interface providing a type-safe representation of time points for table rollback operations in Apache Paimon. It uses Jackson polymorphic serialization to support two concrete implementations: SnapshotInstant for referencing a specific snapshot by its numeric ID, and TagInstant for referencing a named tag. This design allows rollback operations to target either explicit snapshot numbers or semantic tags like "release-1.0" or "last-known-good".

The interface provides factory methods snapshot(Long snapshotId) and tag(String tagName) for creating instances, abstracting the concrete implementation details. Both implementations are final inner classes that are serializable and include proper JSON annotations for persistence and API communication. The SnapshotInstant holds a long snapshotId field, while TagInstant holds a String tagName field, each accessible via respective getter methods.

The Types inner class defines constants for Jackson type discrimination, using "snapshot" and "tag" as type identifiers in JSON representations. This enables round-trip serialization where the correct concrete type is reconstructed during deserialization. The @JsonIgnoreProperties annotation ensures forward compatibility by ignoring unknown fields during deserialization.

Usage

Use Instant when implementing table rollback features, time travel queries, or version management operations. It provides a clean API for specifying rollback targets either by numeric snapshot ID or by semantic tag name.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/table/Instant.java

Signature

@Public
public interface Instant extends Serializable {

    static Instant snapshot(Long snapshotId)

    static Instant tag(String tagName)

    final class SnapshotInstant implements Instant {
        public SnapshotInstant(long snapshotId)
        public long getSnapshotId()
    }

    final class TagInstant implements Instant {
        public TagInstant(String tagName)
        public String getTagName()
    }

    class Types {
        public static final String FIELD_TYPE = "type";
        public static final String SNAPSHOT = "snapshot";
        public static final String TAG = "tag";
    }
}

Import

import org.apache.paimon.table.Instant;

I/O Contract

Inputs

Name	Type	Required	Description
snapshotId	Long	For snapshot instant	Numeric snapshot identifier
tagName	String	For tag instant	Named tag identifier

Outputs

Name	Type	Description
Instant	Instant	Polymorphic instant reference (SnapshotInstant or TagInstant)
Snapshot ID	long	The snapshot number (if SnapshotInstant)
Tag name	String	The tag name (if TagInstant)

Usage Examples

// Create instant from snapshot ID
Instant snapshotInstant = Instant.snapshot(12345L);

// Create instant from tag name
Instant tagInstant = Instant.tag("release-1.0");

// Use in rollback operation
public void rollbackTable(Table table, Instant instant) {
    if (instant instanceof Instant.SnapshotInstant) {
        Instant.SnapshotInstant snapshot = (Instant.SnapshotInstant) instant;
        long id = snapshot.getSnapshotId();
        rollbackToSnapshot(table, id);
    } else if (instant instanceof Instant.TagInstant) {
        Instant.TagInstant tag = (Instant.TagInstant) instant;
        String tagName = tag.getTagName();
        rollbackToTag(table, tagName);
    }
}

// Example: Time travel query
Instant timePoint = Instant.snapshot(100L);
Table historicalTable = table.asOf(timePoint);

// Example: Rollback to last stable release
Instant stableVersion = Instant.tag("stable");
table.rollback(stableVersion);

// Example: Rollback to specific snapshot
Instant specificPoint = Instant.snapshot(9876L);
table.rollback(specificPoint);

// Pattern matching (Java 17+)
public void processInstant(Instant instant) {
    switch (instant) {
        case Instant.SnapshotInstant s -> {
            System.out.println("Snapshot: " + s.getSnapshotId());
        }
        case Instant.TagInstant t -> {
            System.out.println("Tag: " + t.getTagName());
        }
    }
}

// JSON serialization example
// SnapshotInstant serializes as:
// {"type": "snapshot", "snapshotId": 12345}
//
// TagInstant serializes as:
// {"type": "tag", "tagName": "release-1.0"}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment