Support for adding/removing/renaming columns cannot be done by comparing CatalogTable\n * instances, unless the Flink schema contains Iceberg column IDs.\n *\n *
To alter columns, use the other alterTable API and provide a list of TableChange's.\n *\n * @param tablePath path of the table or view to be modified\n * @param newTable the new table definition\n * @param ignoreIfNotExists flag to specify behavior when the table or view does not exist: if set\n * to false, throw an exception, if set to true, do nothing.\n * @throws CatalogException in case of any runtime exception\n * @throws TableNotExistException if the table does not exist\n */","sourceCodeStart":470,"sourceCodeEnd":506,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java#L470-L506","documentation":"FlinkCatalog does not support changing a table's partition keys. validateTablePartition compares the partition keys of the existing and replacement CatalogTable in the legacy alterTable path and throws UnsupportedOperationException if they differ. Partitioning is fixed at table creation in Iceberg via its PartitionSpec.","triggerScenarios":"Calling legacy alterTable(tablePath, catalogTable, ignoreIfNotExists) where the new CatalogTable's getPartitionKeys() list differs from the current table's — adding, removing, or reordering partition columns.","commonSituations":"Trying to repartition an existing table via full CatalogTable replacement; DDL generators that always emit partition keys; copying a table definition with different partitioning onto an existing table.","solutions":["Drop and recreate the table with the desired partition spec (migrating data), since Iceberg cannot alter partitioning in place.","Keep partition keys identical and only change properties through the alterTable path.","Use Flink/Iceberg rewrite-datafiles or migration tooling (e.g. Iceberg's stored-procedure/rewrite workflow in a Spark engine) to change layout instead of altering partition keys."],"exampleFix":"// before\ncatalog.alterTable(path, tableWithNewPartitionKeys, false);\n// after\n// recreate instead:\ncatalog.dropTable(path, false);\ncatalog.createTable(path, tableWithNewPartitionKeys);","handlingStrategy":"validation","validationCode":"if (!current.getPartitionKeys().equals(proposed.getPartitionKeys())) {\n throw new IllegalArgumentException(\"Recreate the table to change partitioning\");\n}","typeGuard":"boolean partitionKeysUnchanged(CatalogTable a, CatalogTable b) {\n return a.getPartitionKeys().equals(b.getPartitionKeys());\n}","tryCatchPattern":"try { catalog.alterTable(path, proposed, false); }\ncatch (UnsupportedOperationException e) { /* plan drop+recreate migration instead */ }","preventionTips":["Fix partitioning at CREATE TABLE time; treat it as immutable","Never include partition-key differences in replacement CatalogTables","Use Iceberg data rewrite/migration tools to change layout rather than altering partition keys"],"tags":["flink","partitioning","unsupported-operation","ddl"],"backgroundTag":"operation-not-supported","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}