Alter Standard Table - Clustering

Last updated: January 27, 2026

Modifies clustering key configuration for a standard table. Clustering helps optimize query performance by co-locating similar data.

Known limitations:

This change type does not support automatic rollback.
Snowflake snapshots created with Liquibase Secure 5.1 are incompatible with earlier versions due to enhanced object type detection for TABLES and VIEWS. Regenerate all snapshots with 5.1 after upgrading to avoid false differences in diff and diff-changelog operations.

Available attributes

Attribute	Type	Description	Required
`catalogName`	String	Name of the catalog (database) containing the table	No
`schemaName`	String	Name of the schema containing the table	No
`tableName`	String	Name of the table to alter	Yes
`ifExists`	Boolean	Only execute if the table exists	No

alterClustering nested attributes

Attribute	Type	Description	Required
`clusterBy`	String	New clustering key (comma-separated columns)	No*
`suspendRecluster`	Boolean	If true, suspends automatic reclustering	No*
`resumeRecluster`	Boolean	If true, resumes automatic reclustering	No*
`dropClusteringKey`	Boolean	If true, drops the clustering key	No*

*Exactly one of these options must be specified.

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:pro-snowflake="http://www.liquibase.org/xml/ns/pro-snowflake"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/pro-snowflake
        http://www.liquibase.org/xml/ns/pro-snowflake/liquibase-pro-snowflake-latest.xsd">

    <!-- Set clustering key -->
    <changeSet id="alter-clustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="EVENT_STREAM">
            <pro-snowflake:alterClustering clusterBy="EVENT_TIMESTAMP, USER_ID"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Suspend automatic reclustering -->
    <changeSet id="suspend-reclustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="LARGE_TABLE">
            <pro-snowflake:alterClustering suspendRecluster="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Resume automatic reclustering -->
    <changeSet id="resume-reclustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="LARGE_TABLE">
            <pro-snowflake:alterClustering resumeRecluster="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Drop clustering key -->
    <changeSet id="drop-clustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="SIMPLE_TABLE">
            <pro-snowflake:alterClustering dropClusteringKey="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "alter-clustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "EVENT_STREAM",
              "alterClustering": {
                "clusterBy": "EVENT_TIMESTAMP, USER_ID"
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "suspend-reclustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "LARGE_TABLE",
              "alterClustering": {
                "suspendRecluster": true
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "resume-reclustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "LARGE_TABLE",
              "alterClustering": {
                "resumeRecluster": true
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "drop-clustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "SIMPLE_TABLE",
              "alterClustering": {
                "dropClusteringKey": true
              }
            }
          }
        ]
      }
    }
  ]
}

databaseChangeLog:
  # Set clustering key
  - changeSet:
      id: alter-clustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: EVENT_STREAM
            alterClustering:
              clusterBy: "EVENT_TIMESTAMP, USER_ID"

  # Suspend automatic reclustering
  - changeSet:
      id: suspend-reclustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: LARGE_TABLE
            alterClustering:
              suspendRecluster: true

  # Resume automatic reclustering
  - changeSet:
      id: resume-reclustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: LARGE_TABLE
            alterClustering:
              resumeRecluster: true

  # Drop clustering key
  - changeSet:
      id: drop-clustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: SIMPLE_TABLE
            alterClustering:
              dropClusteringKey: true

--liquibase formatted sql

--changeset examples:set-clustering-key
-- Set clustering key
ALTER TABLE MYDB.PUBLIC.EVENT_STREAM CLUSTER BY (EVENT_TIMESTAMP, USER_ID);

--changeset examples:suspend-automatic-reclustering
-- Suspend automatic reclustering
ALTER TABLE MYDB.PUBLIC.LARGE_TABLE SUSPEND RECLUSTER;

--changeset examples:resume-automatic-reclustering
-- Resume automatic reclustering
ALTER TABLE MYDB.PUBLIC.LARGE_TABLE RESUME RECLUSTER;

--changeset examples:drop-clustering-key
-- Drop clustering key
ALTER TABLE MYDB.PUBLIC.SIMPLE_TABLE DROP CLUSTERING KEY;

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:pro-snowflake="http://www.liquibase.org/xml/ns/pro-snowflake"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/pro-snowflake
        http://www.liquibase.org/xml/ns/pro-snowflake/liquibase-pro-snowflake-latest.xsd">

    <!-- Set clustering key -->
    <changeSet id="alter-clustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="EVENT_STREAM">
            <pro-snowflake:alterClustering clusterBy="EVENT_TIMESTAMP, USER_ID"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Suspend automatic reclustering -->
    <changeSet id="suspend-reclustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="LARGE_TABLE">
            <pro-snowflake:alterClustering suspendRecluster="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Resume automatic reclustering -->
    <changeSet id="resume-reclustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="LARGE_TABLE">
            <pro-snowflake:alterClustering resumeRecluster="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

    <!-- Drop clustering key -->
    <changeSet id="drop-clustering" author="examples">
        <pro-snowflake:alterStandardTable tableName="SIMPLE_TABLE">
            <pro-snowflake:alterClustering dropClusteringKey="true"/>
        </pro-snowflake:alterStandardTable>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "alter-clustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "EVENT_STREAM",
              "alterClustering": {
                "clusterBy": "EVENT_TIMESTAMP, USER_ID"
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "suspend-reclustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "LARGE_TABLE",
              "alterClustering": {
                "suspendRecluster": true
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "resume-reclustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "LARGE_TABLE",
              "alterClustering": {
                "resumeRecluster": true
              }
            }
          }
        ]
      }
    },
    {
      "changeSet": {
        "id": "drop-clustering",
        "author": "examples",
        "changes": [
          {
            "alterStandardTable": {
              "tableName": "SIMPLE_TABLE",
              "alterClustering": {
                "dropClusteringKey": true
              }
            }
          }
        ]
      }
    }
  ]
}

databaseChangeLog:
  # Set clustering key
  - changeSet:
      id: alter-clustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: EVENT_STREAM
            alterClustering:
              clusterBy: "EVENT_TIMESTAMP, USER_ID"

  # Suspend automatic reclustering
  - changeSet:
      id: suspend-reclustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: LARGE_TABLE
            alterClustering:
              suspendRecluster: true

  # Resume automatic reclustering
  - changeSet:
      id: resume-reclustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: LARGE_TABLE
            alterClustering:
              resumeRecluster: true

  # Drop clustering key
  - changeSet:
      id: drop-clustering
      author: examples
      changes:
        - alterStandardTable:
            tableName: SIMPLE_TABLE
            alterClustering:
              dropClusteringKey: true

--liquibase formatted sql

--changeset examples:set-clustering-key
-- Set clustering key
ALTER TABLE MYDB.PUBLIC.EVENT_STREAM CLUSTER BY (EVENT_TIMESTAMP, USER_ID);

--changeset examples:suspend-automatic-reclustering
-- Suspend automatic reclustering
ALTER TABLE MYDB.PUBLIC.LARGE_TABLE SUSPEND RECLUSTER;

--changeset examples:resume-automatic-reclustering
-- Resume automatic reclustering
ALTER TABLE MYDB.PUBLIC.LARGE_TABLE RESUME RECLUSTER;

--changeset examples:drop-clustering-key
-- Drop clustering key
ALTER TABLE MYDB.PUBLIC.SIMPLE_TABLE DROP CLUSTERING KEY;

Alter Standard Table - Clustering

Available attributes

alterClustering nested attributes

XML

JSON

YAML

SQL

More like this

alterDynamicTable alterClustering

Snowflake: ALTER TABLE