Implementation:Apache Paimon DataField

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

Overview

DataField defines a field within a row type, encapsulating the field's unique identifier, name, data type, description, and default value.

Description

DataField is a serializable final class that represents the complete specification of a field in a Paimon row type. Each field contains an integer ID for unique identification, a name string, a DataType representing the field's type, and optional metadata including a description and default value. The field ID is particularly important for schema evolution and compatibility, allowing the system to track fields across schema changes.

The class provides an immutable design pattern with methods that return new instances when modifications are needed, such as newId(), newName(), newType(), newDescription(), and newDefaultValue(). This ensures thread safety and prevents accidental modifications. DataField supports various comparison operations including standard equality, field ID-ignoring equality (equalsIgnoreFieldId), and pruning checks (isPrunedFrom) to determine if a field is the result of column pruning operations.

DataField integrates with Paimon's serialization infrastructure, providing asSQLString() for SQL DDL generation and serializeJson() for JSON persistence. The SQL string representation includes the escaped field name, type specification, optional comment, and default value clause. Available since version 0.4.0, DataField is marked as @Public API.

Usage

Use DataField when defining table schemas, creating row types, or performing schema evolution operations. It is essential for specifying column definitions in CREATE TABLE statements, tracking field identities across schema versions, and maintaining metadata about fields including descriptions and default values.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/types/DataField.java

Signature

@Public
public final class DataField implements Serializable {

    public DataField(int id, String name, DataType dataType)

    public DataField(int id, String name, DataType dataType, @Nullable String description)

    public DataField(int id, String name, DataType type, @Nullable String description,
                     @Nullable String defaultValue)

    public int id()

    public String name()

    public DataType type()

    @Nullable
    public String description()

    @Nullable
    public String defaultValue()

    public DataField newId(int newId)

    public DataField newName(String newName)

    public DataField newType(DataType newType)

    public DataField newDescription(String newDescription)

    public DataField newDefaultValue(String newDefaultValue)

    public DataField copy()

    public DataField copy(boolean isNullable)

    public String asSQLString()

    public boolean equalsIgnoreFieldId(DataField other)

    public static boolean dataFieldEqualsIgnoreId(DataField dataField1, DataField dataField2)
}

Import

import org.apache.paimon.types.DataField;

I/O Contract

Inputs

Name	Type	Required	Description
id	int	Yes	Unique identifier for the field
name	String	Yes	Name of the field
type	DataType	Yes	Data type of the field
description	String	No	Optional comment or description
defaultValue	String	No	Optional default value expression

Outputs

Name	Type	Description
DataField instance	DataField	Immutable field definition with all metadata
SQL string	String	DDL-compatible field definition with name, type, comment, and default
JSON	JsonObject	JSON representation with id, name, type, and optional metadata

Usage Examples

// Create a simple field
DataField idField = new DataField(0, "id", DataTypes.INT());

// Create a field with description
DataField nameField = new DataField(
    1,
    "name",
    DataTypes.STRING(),
    "User's full name"
);

// Create a field with description and default value
DataField statusField = new DataField(
    2,
    "status",
    DataTypes.STRING(),
    "Account status",
    "'active'"
);

// Modify field properties (returns new instance)
DataField updatedField = idField.newName("user_id")
                                .newDescription("Unique user identifier");

// Convert to SQL
String sql = nameField.asSQLString();
// Returns: `name` STRING COMMENT 'User's full name'

// Copy with different nullability
DataField nonNullField = idField.copy(false);

// Compare fields ignoring ID
boolean same = field1.equalsIgnoreFieldId(field2);

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment