Implementation:Apache Paimon SchemaChange
| Knowledge Sources | |
|---|---|
| Domains | Schema Management, DDL Operations |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
SchemaChange is a sealed interface hierarchy that defines all possible schema modification operations that can be applied to Paimon tables.
Description
SchemaChange represents the contract for table schema evolution in Apache Paimon. It uses Jackson JSON polymorphic type annotations to enable serialization and deserialization of schema changes, making it suitable for REST APIs, catalog operations, and DDL execution. The interface provides static factory methods for creating each type of schema change, including operations on table options (SetOption, RemoveOption), table metadata (UpdateComment), column operations (AddColumn, RenameColumn, DropColumn), and column property modifications (UpdateColumnType, UpdateColumnNullability, UpdateColumnComment, UpdateColumnDefaultValue, UpdateColumnPosition).
Each schema change type is implemented as a final inner class with immutable fields, ensuring thread-safety and predictability. The Move inner class supports column repositioning with FIRST, AFTER, BEFORE, and LAST positioning strategies. This design pattern creates a type-safe, extensible framework for schema evolution that can be easily serialized to JSON and transmitted across distributed systems.
The interface is marked with @Public annotation (since 0.4.0), indicating its stability as part of the Paimon public API. This ensures backward compatibility and makes it suitable for use by external tools, catalog implementations, and REST endpoints.
Usage
Use SchemaChange when implementing DDL operations (ALTER TABLE), schema evolution logic in catalogs, or when serializing schema modifications for storage or transmission. Each static factory method creates an appropriate SchemaChange instance that can be applied to a table schema.
Code Reference
Source Location
- Repository: Apache_Paimon
- File: paimon-api/src/main/java/org/apache/paimon/schema/SchemaChange.java
- Lines: 37-830
Signature
@Public
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY,
property = SchemaChange.Actions.FIELD_ACTION)
@JsonSubTypes({
@JsonSubTypes.Type(value = SchemaChange.SetOption.class, name = "setOption"),
@JsonSubTypes.Type(value = SchemaChange.RemoveOption.class, name = "removeOption"),
@JsonSubTypes.Type(value = SchemaChange.UpdateComment.class, name = "updateComment"),
@JsonSubTypes.Type(value = SchemaChange.AddColumn.class, name = "addColumn"),
@JsonSubTypes.Type(value = SchemaChange.RenameColumn.class, name = "renameColumn"),
@JsonSubTypes.Type(value = SchemaChange.DropColumn.class, name = "dropColumn"),
@JsonSubTypes.Type(value = SchemaChange.UpdateColumnType.class, name = "updateColumnType"),
@JsonSubTypes.Type(value = SchemaChange.UpdateColumnNullability.class, name = "updateColumnNullability"),
@JsonSubTypes.Type(value = SchemaChange.UpdateColumnComment.class, name = "updateColumnComment"),
@JsonSubTypes.Type(value = SchemaChange.UpdateColumnDefaultValue.class, name = "updateColumnDefaultValue"),
@JsonSubTypes.Type(value = SchemaChange.UpdateColumnPosition.class, name = "updateColumnPosition")
})
public interface SchemaChange extends Serializable {
static SchemaChange setOption(String key, String value);
static SchemaChange removeOption(String key);
static SchemaChange updateComment(@Nullable String comment);
static SchemaChange addColumn(String fieldName, DataType dataType);
static SchemaChange addColumn(String fieldName, DataType dataType, String comment, Move move);
static SchemaChange renameColumn(String fieldName, String newName);
static SchemaChange dropColumn(String fieldName);
static SchemaChange updateColumnType(String fieldName, DataType newDataType);
static SchemaChange updateColumnNullability(String fieldName, boolean newNullability);
static SchemaChange updateColumnComment(String fieldName, String comment);
static SchemaChange updateColumnPosition(Move move);
}
Import
import org.apache.paimon.schema.SchemaChange;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| key | String | yes | Configuration key for SetOption/RemoveOption |
| value | String | yes | Configuration value for SetOption |
| comment | String | no | Comment text for UpdateComment/UpdateColumnComment |
| fieldName | String or String[] | yes | Name of field(s) to modify |
| dataType | DataType | yes | Data type for AddColumn/UpdateColumnType |
| newName | String | yes | New name for RenameColumn |
| newNullability | boolean | yes | New nullability flag for UpdateColumnNullability |
| move | Move | no | Position specification for AddColumn/UpdateColumnPosition |
Outputs
| Name | Type | Description |
|---|---|---|
| schemaChange | SchemaChange | Immutable schema change instance representing the operation |
Usage Examples
Adding a Column
// Add a simple column
SchemaChange addCol = SchemaChange.addColumn("age", DataTypes.INT());
// Add a column with comment and position
SchemaChange addColWithPos = SchemaChange.addColumn(
"email",
DataTypes.STRING(),
"User email address",
SchemaChange.Move.after("age", "name")
);
Modifying Column Properties
// Rename a column
SchemaChange rename = SchemaChange.renameColumn("old_name", "new_name");
// Change column type
SchemaChange changeType = SchemaChange.updateColumnType(
"amount",
DataTypes.DECIMAL(18, 2)
);
// Update column nullability
SchemaChange makeNullable = SchemaChange.updateColumnNullability(
"optional_field",
true
);
// Update column comment
SchemaChange updateComment = SchemaChange.updateColumnComment(
"status",
"Updated status description"
);
Managing Table Options
// Set a table option
SchemaChange setOpt = SchemaChange.setOption(
"write-only",
"true"
);
// Remove a table option
SchemaChange removeOpt = SchemaChange.removeOption("write-only");
// Update table comment
SchemaChange updateTableComment = SchemaChange.updateComment(
"Updated table description"
);
Column Positioning
// Move column to first position
SchemaChange.Move moveFirst = SchemaChange.Move.first("id");
// Move column after another column
SchemaChange.Move moveAfter = SchemaChange.Move.after(
"created_at",
"updated_at"
);
// Move column before another column
SchemaChange.Move moveBefore = SchemaChange.Move.before(
"status",
"category"
);
// Move column to last position
SchemaChange.Move moveLast = SchemaChange.Move.last("notes");