Implementation:Apache Paimon DataTypeCasts

Knowledge Sources	Apache_Paimon
Domains	Type System, Data Conversion
Last Updated	2026-02-08 00:00 GMT

Overview

DataTypeCasts defines the casting rules between Paimon data types, determining which implicit, explicit, and compatible casts are allowed.

Description

DataTypeCasts is a utility class that maintains three static rule maps defining type conversion compatibility in Paimon. The implicitCastingRules map defines safe casts that preserve information (similar to Java widening conversions), the explicitCastingRules map defines SQL CAST-style conversions that may lose information, and the compatibleCastingRules map defines structural compatibility for types with the same underlying representation.

The rules are built during static initialization using a fluent builder pattern. For each target type, the builder specifies which source types can be cast implicitly (e.g., TINYINT to BIGINT), explicitly (e.g., STRING to INT), or compatibly (e.g., CHAR to VARCHAR). Identity casts (type to itself) are automatically added for all types. The rules follow SQL standard semantics with some extensions for Paimon-specific types.

Compatible casts are particularly important for schema evolution, where types like CHAR and VARCHAR can be treated interchangeably because they share the same string representation. However, numeric types like INT and BIGINT are not compatible despite both being numeric, because they have different storage sizes and ranges.

Usage

Use DataTypeCasts when implementing schema evolution logic, query planning, type checking, or data conversion operations. The class provides query methods to check if a cast is supported between two DataType instances.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/types/DataTypeCasts.java
Lines: 54-326

Signature

public final class DataTypeCasts {
    public static boolean supportsCast(
        DataType sourceType,
        DataType targetType,
        boolean allowExplicit
    );

    public static boolean supportsCompatibleCast(
        DataType sourceType,
        DataType targetType
    );
}

Import

import org.apache.paimon.types.DataTypeCasts;

I/O Contract

Inputs

Name	Type	Required	Description
sourceType	DataType	yes	Source data type to cast from
targetType	DataType	yes	Target data type to cast to
allowExplicit	boolean	yes	Whether to allow explicit (lossy) casts

Outputs

Name	Type	Description
supported	boolean	True if the cast is allowed under the specified rules

Usage Examples

Checking Implicit Casts

// Safe widening cast (implicit)
DataType sourceType = DataTypes.INT();
DataType targetType = DataTypes.BIGINT();
boolean canCast = DataTypeCasts.supportsCast(
    sourceType,
    targetType,
    false  // only implicit casts
);
// Returns: true

// Narrowing cast requires explicit
DataType sourceType2 = DataTypes.BIGINT();
DataType targetType2 = DataTypes.INT();
boolean canImplicitCast = DataTypeCasts.supportsCast(
    sourceType2,
    targetType2,
    false  // only implicit casts
);
// Returns: false

Checking Explicit Casts

// String to integer (explicit cast)
DataType stringType = DataTypes.STRING();
DataType intType = DataTypes.INT();
boolean canExplicitCast = DataTypeCasts.supportsCast(
    stringType,
    intType,
    true  // allow explicit casts
);
// Returns: true

// Check if explicit cast is needed
boolean needsExplicit =
    DataTypeCasts.supportsCast(stringType, intType, true) &&
    !DataTypeCasts.supportsCast(stringType, intType, false);
// Returns: true (explicit cast required)

Checking Compatible Casts

// CHAR and VARCHAR are compatible (same underlying structure)
DataType charType = DataTypes.CHAR(10);
DataType varcharType = DataTypes.VARCHAR(20);
boolean compatible = DataTypeCasts.supportsCompatibleCast(
    charType,
    varcharType
);
// Returns: true

// INT and BIGINT are NOT compatible (different storage)
DataType intType = DataTypes.INT();
DataType bigintType = DataTypes.BIGINT();
boolean notCompatible = DataTypeCasts.supportsCompatibleCast(
    intType,
    bigintType
);
// Returns: false

Schema Evolution Validation

// Validate column type change
public boolean canEvolveType(DataType oldType, DataType newType) {
    // Allow if types are compatible or new type supports implicit cast
    return DataTypeCasts.supportsCompatibleCast(oldType, newType) ||
           DataTypeCasts.supportsCast(oldType, newType, false);
}

// Example usage
DataType oldType = DataTypes.INT();
DataType newType = DataTypes.BIGINT();
boolean canEvolve = canEvolveType(oldType, newType);
// Returns: true (safe widening)

Nullability Handling

// Nullability affects implicit casts
DataType nullableInt = DataTypes.INT().nullable();
DataType notNullBigint = DataTypes.BIGINT().notNull();

// Nullable to NOT NULL requires explicit cast
boolean implicitCast = DataTypeCasts.supportsCast(
    nullableInt,
    notNullBigint,
    false
);
// Returns: false

// But explicit cast is allowed
boolean explicitCast = DataTypeCasts.supportsCast(
    nullableInt,
    notNullBigint,
    true
);
// Returns: true

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment