Partitioning

Altertable catalog tables can be partitioned by a user-defined set of partition keys. When partition keys are set, new data is written into separate data files grouped by those keys.

During query planning, Altertable uses file-level zone maps — per-column min/max statistics stored in catalog metadata — to decide which files to scan. For order-preserving partition transforms (identity, year, month, day, hour), partitioned writes produce tight zone maps on the partition column, so file-level pruning narrows scans to the matching partition files.

Partition keys only affect new data written to a table. Data written before a layout change keeps the partitioning keys that were active at write time. That lets the partition layout evolve over time without rewriting historical files.

Partition key values are stored in catalog metadata. They do not need to appear inside the data files or in object storage paths.

Run the statements below through Altertable's SQL engine against an Altertable catalog you own.

Set partition keys

Partition new writes on a column:

Copy
ALTER TABLE my_catalog.main.shipments SET PARTITIONED BY (destination_region);

Partition on time transforms:

Copy
ALTER TABLE my_catalog.main.shipments SET PARTITIONED BY (year(departed_at), month(departed_at));

Distribute rows into a fixed number of buckets using an Iceberg-compatible Murmur3 hash:

Copy
ALTER TABLE my_catalog.main.shipments SET PARTITIONED BY (bucket(8, order_id));

Combine bucket partitioning with other transforms:

Copy
ALTER TABLE my_catalog.main.shipments SET PARTITIONED BY (bucket(8, order_id), month(departed_at));

Remove partition keys

Stop partitioning new writes:

Copy
ALTER TABLE my_catalog.main.shipments RESET PARTITIONED BY;

Existing files keep their prior layout until you rewrite or compact them through maintenance operations.

Supported transforms

When to partition

Partition when queries repeatedly filter on the same columns — especially high-cardinality IDs combined with time, or date/time columns used in range filters. Partitioning trades more files and metadata for smaller, targeted scans.

Skip partitioning when filters are unpredictable, tables stay small, or write throughput matters more than read pruning. You can add or change partition keys later; only new data follows the updated layout.

Learn more

• Altertable Catalogs: Create and manage managed catalogs
• SQL Engine: DuckDB dialect and federated queries
• Buckets: Object storage that backs catalog data files