---
title: "CLUSTER"
id: sql-cluster
pg_version: "20devel"
---

<a id="sql-cluster"></a>

# CLUSTER — cluster a table according to an index

## Synopsis

```
CLUSTER [ ( option [, ...] ) ] [ table_name [ USING index_name ] ]

where option can be one of:

    VERBOSE [ boolean ]
```

<a id="id-1.9.3.52.5"></a>

## Description

The `CLUSTER` command is equivalent to [REPACK](sql-repack.md) with a `USING INDEX` clause. See there for more details. 

<a id="id-1.9.3.52.6"></a>

## Parameters

**`table_name`**

 The name (possibly schema-qualified) of a table. **`index_name`**

 The name of an index. **`VERBOSE`**

 Prints a progress report as each table is clustered at `INFO` level. **`boolean`**

 Specifies whether the selected option should be turned on or off. You can write `TRUE`, `ON`, or `1` to enable the option, and `FALSE`, `OFF`, or `0` to disable it. The `boolean` value can also be omitted, in which case `TRUE` is assumed. <a id="id-1.9.3.52.7"></a>

## Notes

To cluster a table, one must have the `MAINTAIN` privilege on the table. 

While `CLUSTER` is running, the [`search_path` (`string`)](runtime-config-client.md#guc-search-path) is temporarily changed to `pg_catalog, pg_temp`. 

Because `CLUSTER` remembers which indexes are clustered, one can cluster the tables one wants clustered manually the first time, then set up a periodic maintenance script that executes `CLUSTER` without any parameters, so that the desired tables are periodically reclustered. 

Each backend running `CLUSTER` will report its progress in the pg_stat_progress_cluster view. See [Section 27.4.2](progress-reporting.md#cluster-progress-reporting) for details. 

Clustering a partitioned table clusters each of its partitions using the partition of the specified partitioned index. When clustering a partitioned table, the index may not be omitted. `CLUSTER` on a partitioned table cannot be executed inside a transaction block. 

<a id="id-1.9.3.52.8"></a>

## Examples

Cluster the table employees on the basis of its index `employees_ind`: 
CLUSTER employees USING employees_ind;
 

Cluster the employees table using the same index that was used before: 
CLUSTER employees;
 

Cluster all tables in the database that have previously been clustered: 
CLUSTER;


<a id="id-1.9.3.52.9"></a>

## Compatibility

There is no `CLUSTER` statement in the SQL standard. 

The following syntax was used before PostgreSQL 17 and is still supported: ```
CLUSTER [ VERBOSE ] [ table_name [ USING index_name ] ]
```

 

The following syntax was used before PostgreSQL 8.3 and is still supported: ```
CLUSTER index_name ON table_name
```

 

<a id="id-1.9.3.52.10"></a>

## See Also

[REPACK](sql-repack.md), [clusterdb](app-clusterdb.md), [Section 27.4.2](progress-reporting.md#cluster-progress-reporting)