Table Maintenance

MinIO AIStor Tables performs background maintenance on Iceberg warehouses to reclaim storage and keep table metadata compact. Maintenance runs continuously through a cluster-coordinated catalog scanner and can also be triggered by an administrator.

MinIO AIStor Tables supports three maintenance types:

Snapshot management and unreferenced file removal are configured per warehouse. Compaction is coordinated automatically by the cluster and cannot be configured through the command line in this release.

Snapshot expiration (icebergSnapshotManagement) removes old Iceberg snapshots from a table’s history so that expired snapshots no longer pin the data files they reference.

You configure snapshot expiration at the warehouse level with two settings:

• Maximum snapshot age (--max-age-hours): snapshots older than this age become eligible for expiration.
• Minimum snapshots to keep (--min-snapshots): the number of most-recent snapshots always retained, regardless of age.

A snapshot is only expired when it is both older than the maximum age and not among the minimum number of snapshots to keep.

Unreferenced Files Removal (icebergUnreferencedFileRemoval) reclaims data files that are no longer referenced by any live snapshot, such as files left behind by expired snapshots or interrupted writes.

UFR uses a two-stage retention model configured at the warehouse level:

• Unreferenced days (--unreferenced-days): the number of days a file must remain unreferenced before it is marked noncurrent.
• Noncurrent days (--noncurrent-days): the number of days a noncurrent file is retained before it is permanently deleted.

The staged model gives you a grace period to recover from an accidental snapshot expiration before data files are removed permanently.

UFR runs on the primary site only.

Compaction (icebergCompaction) rewrites the small data files produced by frequent writes into fewer, larger files, which reduces metadata overhead and improves query performance.

Compaction is coordinated across the cluster automatically and can be triggered by an administrator. It is not configurable through mc table warehouse maintenance in this release; the set and update commands reject --type icebergCompaction.

Use the mc table warehouse maintenance commands to configure snapshot expiration and unreferenced file removal for a warehouse:

• mc table warehouse maintenance set enables a maintenance type with a complete set of values.
• mc table warehouse maintenance update changes individual settings or enables/disables an existing configuration.
• mc table warehouse maintenance info shows the current configuration.

For example, enable snapshot expiration on the analytics warehouse:

mc table warehouse maintenance set myaistor analytics \
   --type icebergSnapshotManagement                   \
   --max-age-hours 168                                 \
   --min-snapshots 5

Enable unreferenced file removal on the same warehouse:

mc table warehouse maintenance set myaistor analytics \
   --type icebergUnreferencedFileRemoval              \
   --unreferenced-days 7                               \
   --noncurrent-days 7

You can also configure snapshot expiration from the MinIO AIStor Console.

Use mc table maintenance status to view the outcome of the most recent maintenance run for a table:

mc table maintenance status myaistor analytics sales orders

The status for each maintenance type is one of Successful, Failed, Disabled, or Not_Yet_Run, along with the last run time and any failure message.

• Configuring warehouse maintenance requires the warehouse-level maintenance actions in the caller’s policy.
• Reading maintenance job status requires the s3tables:GetTableMaintenanceJobStatus action.

Maintenance configuration and job-status records are encrypted at rest, and the internal .namespaces, .warehouse, and .maintenance paths within a warehouse bucket cannot be accessed directly.

See Controlling access to MinIO AIStor Tables for the full list of MinIO AIStor Tables actions.