CLUSTER BY

The CLUSTER BY command is used for changing clustering keys in a table.

For more information, see DROP CLUSTERING KEY, CREATE TABLE

Syntax

ALTER TABLE [schema_name.]table_name CLUSTER BY column_name [, ...]


create_table_statement ::=
CREATE [ OR REPLACE ] TABLE [schema_name.]table_name (
 { column_def [, ...] }
  )
 [ CLUSTER BY { column_name [, ...] } ]

column_def :: = { column_name type_name [ default ] [ column_constraint ] }

table_name ::= identifier

column_name ::= identifier

Parameters

Parameter	Description
`schema_name`	The schema name for the table. Defaults to `public` if not specified
`OR REPLACE`	Creates a new tables and overwrites any existing table by the same name. Does not return an error if the table already exists. `CREATE OR REPLACE` does not check the table contents or structure, only the table name
`column_def`	A comma separated list of column definitions. A minimal column definition includes a name identifier and a datatype. Other column constraints and default values can be added optionally
`table_name`	The table name to apply the change to
`column_name [, ... ]`	Comma separated list of columns to create clustering keys for

Usage Notes

Clustering by TEXT columns is not supported
Removing clustering keys does not affect existing data
To force data to re-cluster, the table has to be recreated (i.e. with CREATE TABLE).

Example

Reclustering a Table

ALTER TABLE
  public.users CLUSTER BY start_date;

Permissions

The role must have the DDL permission at the database or table level.