Implementation:Apache Paimon Snapshot

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

Overview

Snapshot represents a Paimon table snapshot, the entry point to all data committed at a specific point in time.

Description

Snapshot is a core data model class in the Paimon storage format (public API since 0.9.0). It is a JSON-serializable (via Jackson annotations) and Java-serializable class that stores snapshot metadata including version, id, schemaId, base/delta/changelog manifest lists with their sizes, index manifest, commit user and identifier, commit kind (CommitKind enum), timestamp, record counts (total, delta, changelog), watermark, statistics file reference, properties map, and nextRowId.

The commitIdentifier supports snapshot deduplication where the same identifier means the same table state, and ordering where a smaller identifier indicates older records. The class provides JSON serialization via JsonSerdeUtil and uses @JsonProperty annotations for all fields. The version is currently at 3, allowing for backward compatibility as the format evolves.

This class is fundamental to Paimon's MVCC (Multi-Version Concurrency Control) architecture. Every read operation starts by selecting a snapshot, which then points to manifest lists that describe the actual data files. This enables time-travel queries, streaming reads, and snapshot isolation.

Usage

Use Snapshot to access table data at a specific point in time. Snapshots are created during commit operations and can be queried for time-travel reads.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/Snapshot.java
• Lines: 1-477

Signature

@Public
@JsonIgnoreProperties(ignoreUnknown = true)
public class Snapshot implements Serializable {

    public static final long FIRST_SNAPSHOT_ID = 1;
    protected static final int CURRENT_VERSION = 3;

    @JsonProperty("version")
    protected final int version;

    @JsonProperty("id")
    protected final long id;

    @JsonProperty("schemaId")
    protected final long schemaId;

    @JsonProperty("baseManifestList")
    protected final String baseManifestList;

    @JsonProperty("deltaManifestList")
    protected final String deltaManifestList;

    @JsonProperty("commitKind")
    protected final CommitKind commitKind;

    @JsonProperty("timeMillis")
    protected final long timeMillis;

    public enum CommitKind {
        APPEND, COMPACT, OVERWRITE, ANALYZE
    }

    public long id() { return id; }
    public long schemaId() { return schemaId; }
    public CommitKind commitKind() { return commitKind; }
    public long timeMillis() { return timeMillis; }
    public String toJson() { return JsonSerdeUtil.toJson(this); }

    public static Snapshot fromJson(String json) {
        return JsonSerdeUtil.fromJson(json, Snapshot.class);
    }
}

Import

import org.apache.paimon.Snapshot;

I/O Contract

Inputs

Name	Type	Required	Description
id	long	yes	Snapshot identifier
schemaId	long	yes	Schema version used for this snapshot
baseManifestList	String	yes	Manifest list recording all changes from previous snapshots
deltaManifestList	String	yes	Manifest list recording new changes in this snapshot
commitKind	CommitKind	yes	Type of commit (APPEND, COMPACT, OVERWRITE, ANALYZE)
timeMillis	long	yes	Commit timestamp in milliseconds

Outputs

Name	Type	Description
id	long	Snapshot ID
schemaId	long	Associated schema version
commitKind	CommitKind	Type of changes in this snapshot
totalRecordCount	long	Total records across all files
deltaRecordCount	long	New records in this snapshot
watermark	Long	Watermark for streaming input records (nullable)

Usage Examples

Reading Snapshot from JSON

import org.apache.paimon.Snapshot;
import org.apache.paimon.fs.FileIO;
import org.apache.paimon.fs.Path;

// Read snapshot from file system
FileIO fileIO = FileIO.get(new Path("hdfs://..."));
Path snapshotPath = new Path("table-path/snapshot/snapshot-1");
String json = fileIO.readFileUtf8(snapshotPath);

// Deserialize snapshot
Snapshot snapshot = Snapshot.fromJson(json);

System.out.println("Snapshot ID: " + snapshot.id());
System.out.println("Schema ID: " + snapshot.schemaId());
System.out.println("Commit Kind: " + snapshot.commitKind());
System.out.println("Total Records: " + snapshot.totalRecordCount());
System.out.println("Delta Records: " + snapshot.deltaRecordCount());

Creating and Serializing Snapshot

import org.apache.paimon.Snapshot;
import org.apache.paimon.Snapshot.CommitKind;

Snapshot snapshot = new Snapshot(
    1L,                          // id
    1L,                          // schemaId
    "manifest-list-base-1",      // baseManifestList
    1024L,                       // baseManifestListSize
    "manifest-list-delta-1",     // deltaManifestList
    512L,                        // deltaManifestListSize
    null,                        // changelogManifestList
    null,                        // changelogManifestListSize
    null,                        // indexManifest
    "user-1",                    // commitUser
    System.currentTimeMillis(),  // commitIdentifier
    CommitKind.APPEND,           // commitKind
    System.currentTimeMillis(),  // timeMillis
    10000L,                      // totalRecordCount
    5000L,                       // deltaRecordCount
    null,                        // changelogRecordCount
    null,                        // watermark
    null,                        // statistics
    null,                        // properties
    null                         // nextRowId
);

// Serialize to JSON
String json = snapshot.toJson();
System.out.println(json);

Related Pages

• Principle:Apache_Paimon_Snapshot_Management