The given name is used to name the new column and names containing \".\" are not handled\n * differently.\n *\n *
If type is a nested type, its field IDs are reassigned when added to the existing schema.\n *\n * @param parent name of the parent struct to the column will be added to\n * @param name name for the new column\n * @param type type for the new column\n * @param doc documentation string for the new column\n * @param defaultValue a default value for the column in existing rows\n * @return this for method chaining\n * @throws IllegalArgumentException If parent doesn't identify a struct\n */\n default UpdateSchema addColumn(\n String parent, String name, Type type, String doc, Literal defaultValue) {\n throw new UnsupportedOperationException(\"Default values are not supported\");\n }\n\n /**\n * Add a new required top-level column.\n *\n *
Adding a required column without a default is an incompatible change that can break reading\n * older data. To make this a compatible change, add a default value by calling {@link\n * #updateColumnDefault(String, Literal)} or use {@link #addRequiredColumn(String, Type, String,\n * Literal)} instead. To suppress exceptions thrown when an incompatible change is detected, call\n * {@link #allowIncompatibleChanges()}.\n *\n *
Because \".\" may be interpreted as a column path separator or may be used in field names, it\n * is not allowed in names passed to this method. To add to nested structures or to add fields\n * with names that contain \".\", use {@link #addRequiredColumn(String, String, Type)}.\n *\n *
If type is a nested type, its field IDs are reassigned when added to the existing schema.\n *\n * @param name name for the new column","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/UpdateSchema.java#L221-L257","documentation":"UpdateSchema.addColumn(parent, name, type, doc, defaultValue) is a default API method that throws UnsupportedOperationException because the concrete implementation does not support initial default values on new columns. Default-value support is optional; only implementations capable of writing defaults override this overload.","triggerScenarios":"Calling the five-argument addColumn overload with a non-null (or any) Literal default value on an UpdateSchema implementation that has not overridden it, e.g. table.updateSchema().addColumn(null, \"col\", Types.IntegerType.get(), \"doc\", Literals.from(5)).","commonSituations":"Adding a column with an initial default value through a transaction or catalog path lacking default-write support; porting code written against newer Iceberg versions to an implementation that predates default values.","solutions":["Use the overload without a default value: addColumn(parent, name, type, doc).","Add the column as optional with no default and backfill values in a separate rewrite step.","Verify the UpdateSchema implementation (class name in the message) supports defaults before using the overload.","Upgrade to an Iceberg version/implementation with schema default-value support (requires format version 3 features)."],"exampleFix":"// before\nupdateSchema.addColumn(null, \"count\", Types.IntegerType.get(), \"doc\", Literals.from(0));\n\n// after\nupdateSchema.addOptionalColumn(\"count\", Types.IntegerType.get(), \"doc\");","handlingStrategy":"try-catch","validationCode":"// pass null default to avoid the unsupported overload:\n// updateSchema.addColumn(parent, name, type, doc) instead of the 5-arg overload","typeGuard":"boolean supportsDefaults = updateSchema instanceof SupportsDefaults; // check implementation capability","tryCatchPattern":"try {\n updateSchema.addColumn(parent, name, type, doc, defaultValue);\n} catch (UnsupportedOperationException e) {\n updateSchema.addOptionalColumn(name, type, doc); // add without default\n}","preventionTips":["Use the addColumn overload without a defaultValue unless defaults are required.","Confirm format-version/implementation default-value support before using defaults.","Backfill new-column values via rewrite jobs instead of initial defaults."],"tags":["unsupported-operation","schema","default-values","api"],"backgroundTag":"unsupported-operation","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"}