Configures or disables liquid clustering on a Delta table.
ALTER TABLE <table> CLUSTER BY (<columns>) | CLUSTER BY NONE## Overview Configures liquid clustering on an existing Delta table. Liquid clustering replaces traditional ZORDER BY with an incremental, automatic clustering strategy. When clustering columns are defined, OPTIMIZE operations will co-locate data by those columns using Hilbert curves, significantly improving query performance for predicates on the clustering keys. ## Behavior - When CLUSTER BY (columns) is specified, the clustering columns are stored as Delta table metadata. Subsequent OPTIMIZE operations will use these columns to cluster new and modified data files. - When CLUSTER BY NONE is specified, clustering is disabled. The clustering column metadata is removed. Previously clustered files are not affected, but new OPTIMIZE operations will not apply clustering. - Changing the clustering columns replaces the previous configuration entirely. There is no incremental add/remove of clustering keys. - The operation writes a metadata-only commit to the Delta log. No data files are rewritten at the time of the ALTER; actual clustering happens during the next OPTIMIZE run. - Column names are normalized to lowercase to match DeltaForge's schema normalization behavior. ## Compatibility Liquid clustering is a DeltaForge extension. The clustering metadata is stored as table properties. Tables with liquid clustering enabled require Delta readers that support the liquid clustering protocol feature.
| Name | Type | Description |
|---|---|---|
table | Fully qualified table name or registered table name. The table must be registered in the current session. | |
columns | Clustering columns. Empty = disable clustering. |
-- Enable liquid clustering on a single column
ALTER TABLE warehouse.sales.orders CLUSTER BY (order_date);-- Enable multi-column clustering
ALTER TABLE warehouse.sales.events CLUSTER BY (event_type, event_date);-- Change clustering columns
ALTER TABLE warehouse.sales.orders CLUSTER BY (customer_id, order_date);-- Disable clustering
ALTER TABLE warehouse.sales.orders CLUSTER BY NONE;