Implementation:Apache Paimon SchemaChange

Knowledge Sources	Apache_Paimon
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");

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment