Implementation:Apache Paimon TableSnapshot
| Knowledge Sources | |
|---|---|
| Domains | Snapshot Management, Table Statistics |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
TableSnapshot represents a point-in-time snapshot of a table, including the snapshot metadata and aggregated table statistics.
Description
TableSnapshot is a public, serializable class that combines a Paimon Snapshot object with computed statistical information about the table at that snapshot. It encapsulates five key pieces of information: the snapshot itself (containing commit ID, timestamp, and file manifests), record count (total number of rows), file size in bytes (total storage footprint), file count (number of data files), and last file creation time (timestamp of the most recently created file). This aggregation provides a comprehensive view of table state and growth over time.
The class uses Jackson annotations for JSON serialization, making it suitable for REST APIs, monitoring systems, and metadata storage. The @JsonIgnoreProperties(ignoreUnknown = true) annotation ensures forward compatibility when new fields are added. All fields are marked with @JsonProperty for explicit JSON mapping, and getters are annotated with @JsonGetter for consistent serialization.
TableSnapshot is immutable with all fields declared final, ensuring thread safety and preventing accidental modification. It provides standard equals(), hashCode(), and toString() implementations based on all five fields, supporting proper usage in collections and debugging. The statistics enable monitoring table growth, storage utilization, and data ingestion patterns without scanning the actual data files.
Usage
Use TableSnapshot for tracking table evolution over time, monitoring storage growth, implementing data lifecycle policies, displaying table statistics in UIs, or building observability and alerting systems around table health metrics.
Code Reference
Source Location
Signature
@JsonIgnoreProperties(ignoreUnknown = true)
@Public
public class TableSnapshot implements Serializable {
public static final String FIELD_SNAPSHOT = "snapshot";
public static final String FIELD_RECORD_COUNT = "recordCount";
public static final String FIELD_FILE_SIZE_IN_BYTES = "fileSizeInBytes";
public static final String FIELD_FILE_COUNT = "fileCount";
public static final String FIELD_LAST_FILE_CREATION_TIME = "lastFileCreationTime";
public TableSnapshot(Snapshot snapshot,
long recordCount,
long fileSizeInBytes,
long fileCount,
long lastFileCreationTime)
public Snapshot snapshot()
public long recordCount()
public long fileSizeInBytes()
public long fileCount()
public long lastFileCreationTime()
@Override
public boolean equals(Object o)
@Override
public int hashCode()
@Override
public String toString()
}
Import
import org.apache.paimon.table.TableSnapshot;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| snapshot | Snapshot | Yes | The underlying Paimon snapshot |
| recordCount | long | Yes | Total number of records in the table |
| fileSizeInBytes | long | Yes | Total storage size in bytes |
| fileCount | long | Yes | Number of data files |
| lastFileCreationTime | long | Yes | Timestamp of most recent file creation |
Outputs
| Name | Type | Description |
|---|---|---|
| TableSnapshot | TableSnapshot | Immutable snapshot with statistics |
| Statistics | long values | Record count, file size, file count, last creation time |
| JSON | JsonObject | Serialized representation with all fields |
Usage Examples
// Create a table snapshot
Snapshot snapshot = table.latestSnapshot();
TableSnapshot tableSnapshot = new TableSnapshot(
snapshot,
1000000L, // 1 million records
5368709120L, // 5 GB
100L, // 100 files
1706832000000L // Feb 2, 2024 timestamp
);
// Access snapshot information
Snapshot snap = tableSnapshot.snapshot();
long snapshotId = snap.id();
long commitTime = snap.timeMillis();
// Access statistics
long records = tableSnapshot.recordCount(); // 1000000
long sizeBytes = tableSnapshot.fileSizeInBytes(); // 5368709120
long files = tableSnapshot.fileCount(); // 100
long lastCreation = tableSnapshot.lastFileCreationTime(); // 1706832000000
// Calculate derived metrics
double avgFileSize = (double) sizeBytes / files; // Average bytes per file
long recordsPerFile = records / files; // Average records per file
// Monitor table growth over time
List<TableSnapshot> history = getSnapshotHistory();
for (TableSnapshot ts : history) {
System.out.printf("Snapshot %d: %d records, %.2f GB, %d files%n",
ts.snapshot().id(),
ts.recordCount(),
ts.fileSizeInBytes() / (1024.0 * 1024 * 1024),
ts.fileCount()
);
}
// Compare snapshots
TableSnapshot current = getCurrentSnapshot();
TableSnapshot previous = getPreviousSnapshot();
long recordsAdded = current.recordCount() - previous.recordCount();
long storageGrown = current.fileSizeInBytes() - previous.fileSizeInBytes();
long filesAdded = current.fileCount() - previous.fileCount();
// Alert on storage thresholds
if (tableSnapshot.fileSizeInBytes() > 1_000_000_000_000L) { // 1 TB
alertStorageLimit(tableSnapshot);
}
// Check equality
boolean same = tableSnapshot.equals(otherSnapshot);
// String representation for logging
String info = tableSnapshot.toString();
// Prints: {snapshot=..., recordCount=1000000, fileSizeInBytes=5368709120, ...}
// JSON serialization (automatic with Jackson)
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(tableSnapshot);
// JSON deserialization
TableSnapshot restored = mapper.readValue(json, TableSnapshot.class);