Table Interface

The Table interface is the primary entry point for interacting with Apache Iceberg tables. It provides access to table metadata, scan operations, and write APIs. Package: org.apache.iceberg

Overview

The Table interface represents an Iceberg table and provides methods for:

Accessing table metadata (schema, partition spec, sort order)
Creating scans to read data
Performing write operations (append, rewrite, overwrite, delete)
Managing snapshots and history
Evolving table structure

Metadata Access

name()

default String name()

Returns the full name for this table. Returns: The table’s name

schema()

Schema schema()

Returns the current Schema for this table. Returns: This table’s schema See also: Schema API

schemas()

Map<Integer, Schema> schemas()

Returns a map of all schemas for this table, keyed by schema ID. Returns: Map of schema ID to Schema

spec()

PartitionSpec spec()

Returns the current PartitionSpec for this table. Returns: This table’s partition spec See also: PartitionSpec API

specs()

Map<Integer, PartitionSpec> specs()

Returns a map of all partition specs for this table, keyed by spec ID. Returns: Map of spec ID to PartitionSpec

sortOrder()

SortOrder sortOrder()

Returns the current SortOrder for this table. Returns: This table’s sort order See also: SortOrder API

sortOrders()

Map<Integer, SortOrder> sortOrders()

Returns a map of all sort orders for this table, keyed by order ID. Returns: Map of order ID to SortOrder

properties()

Map<String, String> properties()

Returns table properties as a string map. Returns: This table’s properties map

location()

String location()

Returns the table’s base location. Returns: This table’s location (e.g., s3://bucket/warehouse/db/table)

uuid()

default UUID uuid()

Returns the UUID of the table. Returns: The table’s UUID

refresh()

void refresh()

Refreshes the current table metadata from storage. This method should be called to pick up changes made by other writers.

Snapshot Access

currentSnapshot()

Snapshot currentSnapshot()

Returns the current Snapshot for this table, or null if there are no snapshots. Returns: The current table snapshot, or null See also: Snapshot API

snapshot(long snapshotId)

Snapshot snapshot(long snapshotId)

Returns the snapshot with the given ID, or null if not found.

snapshotId

long

required

The snapshot ID to retrieve

Returns: The snapshot with the given ID, or null

snapshot(String name)

default Snapshot snapshot(String name)

Returns the snapshot referenced by the given name or null if no such reference exists.

name

String

required

The snapshot reference name (e.g., “main”, “audit”)

Returns: The referenced snapshot, or null

snapshots()

Iterable<Snapshot> snapshots()

Returns all snapshots for this table. Returns: An iterable of snapshots

refs()

Map<String, SnapshotRef> refs()

Returns the current snapshot references for the table. Returns: Map of reference name to SnapshotRef

history()

List<HistoryEntry> history()

Returns the snapshot history of this table. Returns: A list of history entries

Scan Operations

newScan()

TableScan newScan()

Creates a new TableScan for this table. Once created, the scan can be refined to project columns and filter data. Returns: A new table scan Example:

TableScan scan = table.newScan()
    .filter(Expressions.equal("status", "active"))
    .select("id", "name");

newBatchScan()

default BatchScan newBatchScan()

Creates a new BatchScan for this table. Returns: A new batch scan

newIncrementalAppendScan()

default IncrementalAppendScan newIncrementalAppendScan()

Creates a new incremental append scan for this table. Returns: An incremental scan for append-only snapshots Throws: UnsupportedOperationException if not supported

newIncrementalChangelogScan()

default IncrementalChangelogScan newIncrementalChangelogScan()

Creates a new incremental changelog scan for this table. Returns: An incremental changelog scan Throws: UnsupportedOperationException if not supported

newPartitionStatisticsScan()

default PartitionStatisticsScan newPartitionStatisticsScan()

Creates a new partition statistics scan for this table. Returns: A partition statistics scan Throws: UnsupportedOperationException if not supported

Write Operations

newAppend()

AppendFiles newAppend()

Creates a new AppendFiles API to add files to this table and commit. Returns: A new AppendFiles instance Example:

table.newAppend()
    .appendFile(dataFile)
    .commit();

newFastAppend()

default AppendFiles newFastAppend()

Creates a new AppendFiles API optimized for fast commits.

Fast appends skip extra work to commit quickly but may cause split planning to slow down over time. Not recommended for normal writes.

Returns: A new AppendFiles instance

newRewrite()

RewriteFiles newRewrite()

Creates a new RewriteFiles API to replace files in this table and commit. Returns: A new RewriteFiles instance

rewriteManifests()

RewriteManifests rewriteManifests()

Creates a new RewriteManifests API to replace manifests for this table and commit. Returns: A new RewriteManifests instance

newOverwrite()

OverwriteFiles newOverwrite()

Creates a new OverwriteFiles API to overwrite files by a filter expression. Returns: A new OverwriteFiles instance Example:

table.newOverwrite()
    .overwriteByRowFilter(Expressions.equal("date", "2024-01-01"))
    .addFile(newDataFile)
    .commit();

newRowDelta()

RowDelta newRowDelta()

Creates a new RowDelta API to remove or replace rows in existing data files. Returns: A new RowDelta instance

newReplacePartitions()

ReplacePartitions newReplacePartitions()

Not recommended. This is provided for Hive SQL compatibility. Use newOverwrite() instead.

Creates a new ReplacePartitions API to dynamically overwrite partitions. Returns: A new ReplacePartitions instance

newDelete()

DeleteFiles newDelete()

Creates a new DeleteFiles API to delete files in this table and commit. Returns: A new DeleteFiles instance

Schema and Metadata Evolution

updateSchema()

UpdateSchema updateSchema()

Creates a new UpdateSchema API to alter the columns of this table and commit the change. Returns: A new UpdateSchema instance Example:

table.updateSchema()
    .addColumn("new_field", Types.StringType.get())
    .commit();

updateSpec()

UpdatePartitionSpec updateSpec()

Creates a new UpdatePartitionSpec API to alter the partition spec and commit the change. Returns: A new UpdatePartitionSpec instance

updateProperties()

UpdateProperties updateProperties()

Creates a new UpdateProperties API to update table properties and commit the changes. Returns: A new UpdateProperties instance Example:

table.updateProperties()
    .set("write.parquet.compression-codec", "zstd")
    .commit();

replaceSortOrder()

ReplaceSortOrder replaceSortOrder()

Creates a new ReplaceSortOrder API to set the table sort order and commit the change. Returns: A new ReplaceSortOrder instance

updateLocation()

UpdateLocation updateLocation()

Creates a new UpdateLocation API to update table location and commit the changes. Returns: A new UpdateLocation instance

Snapshot Management

expireSnapshots()

ExpireSnapshots expireSnapshots()

Creates a new ExpireSnapshots API to expire snapshots in this table and commit. Returns: A new ExpireSnapshots instance Example:

table.expireSnapshots()
    .expireOlderThan(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000)
    .commit();

manageSnapshots()

ManageSnapshots manageSnapshots()

Creates a new ManageSnapshots API to manage snapshots in this table and commit. Returns: A new ManageSnapshots instance

Statistics

statisticsFiles()

List<StatisticsFile> statisticsFiles()

Returns the current statistics files for the table. Returns: List of statistics files

partitionStatisticsFiles()

default List<PartitionStatisticsFile> partitionStatisticsFiles()

Returns the current partition statistics files for the table. Returns: List of partition statistics files

updateStatistics()

default UpdateStatistics updateStatistics()

Creates a new UpdateStatistics API to add or remove statistics files. Returns: A new UpdateStatistics instance Throws: UnsupportedOperationException if not supported

updatePartitionStatistics()

default UpdatePartitionStatistics updatePartitionStatistics()

Creates a new UpdatePartitionStatistics API to add or remove partition statistics files. Returns: A new UpdatePartitionStatistics instance Throws: UnsupportedOperationException if not supported

Transactions

newTransaction()

Transaction newTransaction()

Creates a new Transaction API to commit multiple table operations at once. Returns: A new Transaction instance Example:

Transaction txn = table.newTransaction();

txn.updateSchema()
   .addColumn("new_field", Types.StringType.get())
   .commit();

txn.newAppend()
   .appendFile(dataFile)
   .commit();

txn.commitTransaction();

File I/O and Encryption

io()

FileIO io()

Returns a FileIO instance to read and write table data and metadata files. Returns: The FileIO for this table

encryption()

EncryptionManager encryption()

Returns an EncryptionManager to encrypt and decrypt data files. Returns: The EncryptionManager for this table

locationProvider()

LocationProvider locationProvider()

Returns a LocationProvider to provide locations for new data files. Returns: The LocationProvider for this table

Usage Examples

Reading Table Metadata

Table table = catalog.loadTable(TableIdentifier.of("db", "events"));

System.out.println("Table: " + table.name());
System.out.println("Schema: " + table.schema());
System.out.println("Partition spec: " + table.spec());
System.out.println("Current snapshot: " + table.currentSnapshot().snapshotId());

Scanning with Filters

TableScan scan = table.newScan()
    .filter(Expressions.and(
        Expressions.greaterThan("timestamp", 1234567890),
        Expressions.equal("status", "completed")
    ))
    .select("id", "timestamp", "user_id");

for (CombinedScanTask task : scan.planTasks()) {
    // Process scan tasks
}

Appending Data

DataFile dataFile = DataFiles.builder(table.spec())
    .withPath("/path/to/data.parquet")
    .withFileSizeInBytes(1024 * 1024)
    .withRecordCount(1000)
    .build();

table.newAppend()
    .appendFile(dataFile)
    .commit();

Schema Evolution

// Add a new column
table.updateSchema()
    .addColumn("email", Types.StringType.get())
    .commit();

// Rename a column
table.updateSchema()
    .renameColumn("old_name", "new_name")
    .commit();

// Delete a column
table.updateSchema()
    .deleteColumn("deprecated_field")
    .commit();

Time Travel

// Read from a specific snapshot
long snapshotId = 12345L;
TableScan scan = table.newScan()
    .useSnapshot(snapshotId);

// Read as of a timestamp
long timestamp = System.currentTimeMillis() - 24 * 60 * 60 * 1000; // 1 day ago
TableScan historicalScan = table.newScan()
    .asOfTime(timestamp);

Source Code Reference

Source: org/apache/iceberg/Table.java:30

Core API

Catalog API

Scan API

Write API

Actions API

REST Catalog API

Types & Expressions

​Table Interface

​Overview

​Metadata Access

​name()

​schema()

​schemas()

​spec()

​specs()

​sortOrder()

​sortOrders()

​properties()

​location()

​uuid()

​refresh()

​Snapshot Access

​currentSnapshot()

​snapshot(long snapshotId)

​snapshot(String name)

​snapshots()

​refs()

​history()

​Scan Operations

​newScan()

​newBatchScan()

​newIncrementalAppendScan()

​newIncrementalChangelogScan()

​newPartitionStatisticsScan()

​Write Operations

​newAppend()

​newFastAppend()

​newRewrite()

​rewriteManifests()

​newOverwrite()

​newRowDelta()

​newReplacePartitions()

​newDelete()

​Schema and Metadata Evolution

​updateSchema()

​updateSpec()

​updateProperties()

​replaceSortOrder()

​updateLocation()

​Snapshot Management

​expireSnapshots()

​manageSnapshots()

​Statistics

​statisticsFiles()

​partitionStatisticsFiles()

​updateStatistics()

​updatePartitionStatistics()

​Transactions

​newTransaction()

​File I/O and Encryption

​io()

​encryption()

​locationProvider()

​Usage Examples

​Reading Table Metadata

​Scanning with Filters

​Appending Data

​Schema Evolution

​Time Travel

​Source Code Reference

Table Interface

Overview

Metadata Access

name()

schema()

schemas()

spec()

specs()

sortOrder()

sortOrders()

properties()

location()

uuid()

refresh()

Snapshot Access

currentSnapshot()

snapshot(long snapshotId)

snapshot(String name)

snapshots()

refs()

history()

Scan Operations

newScan()

newBatchScan()

newIncrementalAppendScan()

newIncrementalChangelogScan()

newPartitionStatisticsScan()

Write Operations

newAppend()

newFastAppend()

newRewrite()

rewriteManifests()

newOverwrite()

newRowDelta()

newReplacePartitions()

newDelete()

Schema and Metadata Evolution

updateSchema()

updateSpec()

updateProperties()

replaceSortOrder()

updateLocation()

Snapshot Management

expireSnapshots()

manageSnapshots()

Statistics

statisticsFiles()

partitionStatisticsFiles()

updateStatistics()

updatePartitionStatistics()

Transactions

newTransaction()

File I/O and Encryption

io()

encryption()

locationProvider()

Usage Examples

Reading Table Metadata

Scanning with Filters

Appending Data

Schema Evolution

Time Travel

Source Code Reference