Implementation:Apache Paimon MapType

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

Overview

MapType represents an associative array data type that maps keys to values, where both keys and values can include NULL in Apache Paimon.

Description

MapType is a public class extending DataType that represents key-value pair collections similar to hash maps or dictionaries. Unlike standard SQL maps which may restrict NULL keys, Paimon's MapType explicitly allows both NULL keys and NULL values, providing flexibility for real-world data scenarios. The implementation does not enforce key uniqueness constraints; it is the user's responsibility to ensure keys are unique when semantic correctness requires it.

The class is parameterized with two DataType instances: keyType and valueType, allowing any valid Paimon types for both components. This enables rich nested structures like Map<String, Array<Int>> or Map<Int, Row<...>>. The default storage size is computed as the sum of key and value type sizes, though this is a simplification used for internal estimation.

MapType provides constructors with optional nullability configuration and methods to access key and value types. The newKeyValueType() method creates a new map with different key or value types while preserving nullability. The class supports comprehensive equality checking including field ID comparisons and pruning checks, JSON serialization with separate key and value fields, and SQL string generation in format "MAP<key_type, value_type>". As an extension to the SQL standard, it is categorized in the EXTENSION family. Available since version 0.4.0 as @Public API.

Usage

Use MapType for representing configuration dictionaries, metadata key-value pairs, tag collections, or any associative data structure where keys map to values. It is particularly useful for semi-structured data and flexible schema patterns.

Code Reference

Source Location

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

Signature

@Public
public class MapType extends DataType {

    public static final String FORMAT = "MAP<%s, %s>";

    public MapType(boolean isNullable, DataType keyType, DataType valueType)

    public MapType(DataType keyType, DataType valueType)

    public DataType getKeyType()

    public DataType getValueType()

    @Override
    public int defaultSize()

    @Override
    public DataType copy(boolean isNullable)

    public DataType newKeyValueType(DataType newKeyType, DataType newValueType)

    @Override
    public String asSQLString()

    @Override
    public <R> R accept(DataTypeVisitor<R> visitor)
}

Import

import org.apache.paimon.types.MapType;

I/O Contract

Inputs

Name	Type	Required	Description
keyType	DataType	Yes	Data type for map keys
valueType	DataType	Yes	Data type for map values
isNullable	boolean	No (default: true)	Whether the map itself can be null

Outputs

Name	Type	Description
MapType	MapType	Configured map type instance
Key type	DataType	The type of keys in the map
Value type	DataType	The type of values in the map
SQL string	String	Format "MAP<key_type, value_type>" with optional "NOT NULL"

Usage Examples

// Simple string to int map
DataType simpleMap = new MapType(
    DataTypes.STRING(),
    DataTypes.INT()
);

// Using factory method
DataType configMap = DataTypes.MAP(
    DataTypes.STRING(),
    DataTypes.STRING()
);

// Non-nullable map
DataType requiredMap = new MapType(
    false,
    DataTypes.INT(),
    DataTypes.STRING()
);

// Complex value type - map to arrays
DataType tagMap = DataTypes.MAP(
    DataTypes.STRING(),
    DataTypes.ARRAY(DataTypes.STRING())
);

// Nested maps
DataType nestedMap = DataTypes.MAP(
    DataTypes.STRING(),
    DataTypes.MAP(DataTypes.STRING(), DataTypes.INT())
);

// Map with row value type
DataType userMetadata = DataTypes.MAP(
    DataTypes.STRING(),
    DataTypes.ROW(
        DataTypes.FIELD(0, "value", DataTypes.STRING()),
        DataTypes.FIELD(1, "timestamp", DataTypes.TIMESTAMP())
    )
);

// Access map properties
MapType map = new MapType(DataTypes.STRING(), DataTypes.INT());
DataType keyType = map.getKeyType(); // STRING
DataType valueType = map.getValueType(); // INT
int size = map.defaultSize(); // key size + value size

// Create new map with different types
MapType original = new MapType(DataTypes.STRING(), DataTypes.INT());
DataType modified = original.newKeyValueType(
    DataTypes.INT(),
    DataTypes.BIGINT()
);

// SQL representation
String sql = map.asSQLString(); // "MAP<STRING, INT>"

// Use in table schema
DataType row = DataTypes.ROW(
    DataTypes.FIELD(0, "id", DataTypes.INT()),
    DataTypes.FIELD(1, "properties", DataTypes.MAP(
        DataTypes.STRING(),
        DataTypes.STRING()
    )),
    DataTypes.FIELD(2, "tags", DataTypes.MAP(
        DataTypes.STRING(),
        DataTypes.ARRAY(DataTypes.STRING())
    ))
);

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment