Implementation:Apache Paimon ConfigOption

Knowledge Sources	Apache_Paimon
Domains	Configuration, Type Safety
Last Updated	2026-02-08 00:00 GMT

Overview

ConfigOption is an immutable, type-safe descriptor for configuration parameters in Apache Paimon.

Description

ConfigOption encapsulates all metadata needed to define a configuration parameter in Paimon. It provides a strongly-typed approach to configuration that enables compile-time type checking, default value specification, and automatic validation. Each ConfigOption includes a primary key, optional fallback keys for backward compatibility, a type specification, an optional default value, and a human-readable description.

The class supports a wide range of types through its generic parameter, from primitive types (Integer, Boolean, String) to complex types (Duration, MemorySize, Enum, Map). The type is captured at construction time using a Class object, enabling runtime type conversion and validation when configuration values are read from string-based sources.

Fallback keys allow configuration options to be renamed or reorganized while maintaining compatibility with existing configurations. When a value is requested, the primary key is checked first, followed by each fallback key in order until a value is found. The deprecated API methods maintain compatibility but are superseded by the more general fallback key mechanism.

ConfigOption instances are immutable and can be safely shared across threads. The class provides builder methods like withFallbackKeys and withDescription that return new instances rather than modifying the original, supporting a fluent configuration style. Proper equals and hashCode implementations make ConfigOption suitable for use as map keys or in collections.

Usage

Use ConfigOption to define configuration parameters in your Paimon modules. Instead of using raw string keys throughout the code, declare ConfigOption constants that provide type safety, default values, and documentation. Users of the configuration can then use these constants with the Options class to get strongly-typed values with automatic conversion and validation.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/options/ConfigOption.java

Signature

@Public
public class ConfigOption<T> {
    private final String key;
    private final FallbackKey[] fallbackKeys;
    private final T defaultValue;
    private final Description description;
    private final Class<?> clazz;

    ConfigOption(
        String key,
        Class<?> clazz,
        Description description,
        T defaultValue,
        FallbackKey... fallbackKeys)

    public ConfigOption<T> withFallbackKeys(String... fallbackKeys)
    public ConfigOption<T> withDescription(String description)
    public ConfigOption<T> withDescription(Description description)

    public String key()
    public boolean hasDefaultValue()
    public T defaultValue()
    public boolean hasFallbackKeys()
    public Iterable<FallbackKey> fallbackKeys()
    public Description description()

    @Deprecated public boolean hasDeprecatedKeys()
    @Deprecated public Iterable<String> deprecatedKeys()
}

Import

import org.apache.paimon.options.ConfigOption;

I/O Contract

Inputs

Name	Type	Required	Description
key	String	Yes	Primary configuration key
clazz	Class<?>	Yes	Type of the configuration value
description	Description	No	Human-readable description
defaultValue	T	No	Default value (null for no default)
fallbackKeys	FallbackKey[]	No	Alternate keys to check

Outputs

Name	Type	Description
configOption	ConfigOption<T>	Immutable configuration option descriptor
key	String	The primary configuration key
defaultValue	T	Default value or null
hasDefaultValue	boolean	Whether a default value is set
fallbackKeys	Iterable<FallbackKey>	Alternate keys for compatibility
description	Description	Configuration description

Usage Examples

// Define a simple string option with default
ConfigOption<String> CATALOG_TYPE = ConfigOptions
    .key("catalog.type")
    .stringType()
    .defaultValue("filesystem")
    .withDescription("Type of catalog to use");

// Define an integer option without default
ConfigOption<Integer> PARALLELISM = ConfigOptions
    .key("execution.parallelism")
    .intType()
    .noDefaultValue()
    .withDescription("Parallelism for execution");

// Define an option with fallback keys for compatibility
ConfigOption<Long> CACHE_SIZE = ConfigOptions
    .key("cache.size")
    .longType()
    .defaultValue(1000L)
    .withFallbackKeys("old.cache.size", "legacy.cache-size")
    .withDescription("Maximum cache size");

// Using the option to read configuration
Options options = new Options(configMap);
String catalogType = options.get(CATALOG_TYPE);
Integer parallelism = options.get(PARALLELISM);

// Checking if option has value
if (PARALLELISM.hasDefaultValue()) {
    int defaultPar = PARALLELISM.defaultValue();
}

// Accessing option metadata
String key = CATALOG_TYPE.key(); // "catalog.type"
Description desc = CATALOG_TYPE.description();
boolean hasDefault = CATALOG_TYPE.hasDefaultValue(); // true

// Complex option with enum type
ConfigOption<LogLevel> LOG_LEVEL = ConfigOptions
    .key("logging.level")
    .enumType(LogLevel.class)
    .defaultValue(LogLevel.INFO)
    .withDescription("Logging level");

// Duration option
ConfigOption<Duration> TIMEOUT = ConfigOptions
    .key("request.timeout")
    .durationType()
    .defaultValue(Duration.ofSeconds(30))
    .withDescription("Request timeout duration");

// Memory size option
ConfigOption<MemorySize> BUFFER_SIZE = ConfigOptions
    .key("buffer.size")
    .memoryType()
    .defaultValue(MemorySize.ofMebiBytes(64))
    .withDescription("Buffer size for data processing");

// Map option for properties
ConfigOption<Map<String, String>> PROPS = ConfigOptions
    .key("custom.properties")
    .mapType()
    .noDefaultValue()
    .withDescription("Custom key-value properties");

// Using options in configuration validation
public void validateConfig(Options options) {
    if (!options.contains(PARALLELISM)) {
        throw new IllegalArgumentException(
            "Required option not set: " + PARALLELISM.key()
        );
    }
}

// Building configuration programmatically
Options config = new Options();
config.set(CATALOG_TYPE, "hive");
config.set(PARALLELISM, 10);
config.set(CACHE_SIZE, 5000L);

Related Pages

• Principle:Apache_Paimon_Table_Configuration