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/v2.2/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java#L470-L506","documentation":"FlinkCatalog validates that partition keys are unchanged in both alterTable APIs; partition spec evolution is not implemented for this catalog. If the proposed CatalogTable has different partition keys than the stored table, UnsupportedOperationException is thrown.","triggerScenarios":"Calling either `alterTable(tablePath, ct, ignoreIfNotExists)` or `alterTable(tablePath, changes, ignoreIfNotExists)` where `ct.getPartitionKeys()` differs from the current table's partition keys (Flink path rebuilds and compares), e.g. changing `PARTITIONED BY (a)` to `PARTITIONED BY (a, b)` on an existing Iceberg table.","commonSituations":"Running Flink SQL `ALTER TABLE ... SET PARTITIONED BY` or re-creating DDL with modified PARTITIONED BY clause and applying it through the catalog; migration scripts that carry modified partitioning.","solutions":["Drop and recreate the table with the desired partition spec (copy data with INSERT INTO ... SELECT).","Do not alter partition keys; keep the original `PARTITIONED BY` clause when altering properties.","If repartitioning is required, use a new table and migrate data with a batch job."],"exampleFix":"// before\nsql(\"ALTER TABLE iceberg_db.t SET ('key'='v') PARTITIONED BY (dt)\");\n\n// after\nsql(\"ALTER TABLE iceberg_db.t SET ('key'='v')\"); // keep partition spec unchanged","handlingStrategy":"validation","validationCode":"// ensure partition keys are unchanged\nif (!oldCt.getPartitionKeys().equals(newCt.getPartitionKeys())) {\n throw new IllegalArgumentException(\"partition keys must remain unchanged; recreate the table instead\");\n}","typeGuard":null,"tryCatchPattern":"try {\n catalog.alterTable(tablePath, ct, false);\n} catch (UnsupportedOperationException e) {\n // handle partition-change attempt: recreate table or keep original spec\n}","preventionTips":["Never modify PARTITIONED BY in ALTER/CREATE-OR-REPLACE DDL against Iceberg tables","Recreate the table and backfill data if partitioning must change","Automate DDL diffs against the current table before applying"],"tags":["flink","partitioning","unsupported"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}