Implementation:Apache Paimon ConfigOptions Python

Knowledge Sources	Apache_Paimon
Domains	Configuration, Builder Pattern
Last Updated	2026-02-08 00:00 GMT

Overview

ConfigOptions provides a fluent builder API for creating type-safe ConfigOption instances with support for primitive types, collections, durations, memory sizes, and enums.

Description

The ConfigOptions class serves as the entry point for building ConfigOption instances through a fluent builder pattern. The static key() method initiates the building process by creating an OptionBuilder, which then provides type-specific methods like string_type(), int_type(), boolean_type(), duration_type(), memory_type(), and enum_type() to specify the expected value type.

After selecting a type, the resulting TypedConfigOptionBuilder provides methods to set either a default_value() or mark the option as having no_default_value(). This two-stage builder pattern ensures type safety while providing a clean, readable API for configuration definition. The builder supports all common configuration value types including primitives (bool, int, float, str), complex types (timedelta for durations, MemorySize for memory values), and user-defined enums.

The class includes both modern typed methods (int_type(), string_type()) and legacy convenience methods (default_value(), no_default_value() on OptionBuilder) for backward compatibility. The typed approach is preferred as it makes type constraints explicit and enables better IDE support and static analysis. Special support for enum_type() validates that the provided class is actually an Enum subclass, and map_type() handles dictionary-style configuration properties.

Usage

Use ConfigOptions when defining configuration schemas for Paimon components, creating type-safe configuration parameters with clear defaults, or building configuration systems that need validation and documentation.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/common/options/config_options.py

Signature

T = TypeVar('T')

class ConfigOptions:
    """
    ConfigOptions are used to build a ConfigOption. The option is typically built in
    one of the following pattern:

    Examples:
        # simple string-valued option with a default value
        temp_dirs = ConfigOptions.key("tmp.dir").string_type().default_value("/tmp")

        # simple integer-valued option with a default value
        parallelism = ConfigOptions.key("application.parallelism").int_type().default_value(100)

        # option with no default value
        user_name = ConfigOptions.key("user.name").string_type().no_default_value()
    """

    @staticmethod
    def key(key: str) -> 'OptionBuilder':
        pass

    class OptionBuilder:
        """
        The option builder is used to create a ConfigOption. It is instantiated via
        ConfigOptions.key(String).
        """

        def __init__(self, key: str):
            pass

        def boolean_type(self) -> 'TypedConfigOptionBuilder[bool]':
            pass

        def int_type(self) -> 'TypedConfigOptionBuilder[int]':
            pass

        def long_type(self) -> 'TypedConfigOptionBuilder[int]':
            pass

        def float_type(self) -> 'TypedConfigOptionBuilder[float]':
            pass

        def double_type(self) -> 'TypedConfigOptionBuilder[float]':
            pass

        def string_type(self) -> 'TypedConfigOptionBuilder[str]':
            pass

        def duration_type(self) -> 'TypedConfigOptionBuilder[timedelta]':
            pass

        def memory_type(self) -> 'TypedConfigOptionBuilder[MemorySize]':
            pass

        def enum_type(self, enum_class: Type[T]) -> 'TypedConfigOptionBuilder[T]':
            pass

        def map_type(self) -> 'TypedConfigOptionBuilder[Dict[str, str]]':
            pass

    class TypedConfigOptionBuilder(Generic[T]):
        """
        Builder for ConfigOption with a defined atomic type.
        """

        def __init__(self, key: str, clazz: Type[T]):
            pass

        def default_value(self, value: T) -> ConfigOption[T]:
            pass

        def no_default_value(self) -> ConfigOption[T]:
            pass

Import

from pypaimon.common.options.config_options import ConfigOptions

I/O Contract

Inputs

Name	Type	Required	Description
key	str	Yes	Configuration key name
value	T	Yes	Default value matching the declared type
enum_class	Type[Enum]	Yes	Enum class for enum_type()

Outputs

Name	Type	Description
option_builder	OptionBuilder	Initial builder for specifying type
typed_builder	TypedConfigOptionBuilder[T]	Typed builder for specifying default
config_option	ConfigOption[T]	Final immutable configuration option

Usage Examples

from pypaimon.common.options.config_options import ConfigOptions
from pypaimon.common.memory_size import MemorySize
from datetime import timedelta
from enum import Enum

# String option with default
catalog_name = ConfigOptions.key("catalog.name") \
    .string_type() \
    .default_value("default")

# Integer option with default
max_retries = ConfigOptions.key("max.retries") \
    .int_type() \
    .default_value(3)

# Boolean option
enable_compression = ConfigOptions.key("table.compression.enabled") \
    .boolean_type() \
    .default_value(True)

# Memory size option
buffer_size = ConfigOptions.key("write.buffer.size") \
    .memory_type() \
    .default_value(MemorySize.of_mebi_bytes(256))

# Duration option
timeout = ConfigOptions.key("connection.timeout") \
    .duration_type() \
    .default_value(timedelta(seconds=30))

# Float option
sampling_rate = ConfigOptions.key("sampling.rate") \
    .double_type() \
    .default_value(0.1)

# String option without default
table_path = ConfigOptions.key("table.path") \
    .string_type() \
    .no_default_value()

# Enum option
class CompressionType(Enum):
    NONE = "none"
    SNAPPY = "snappy"
    GZIP = "gzip"
    ZSTD = "zstd"

compression_type = ConfigOptions.key("table.compression.type") \
    .enum_type(CompressionType) \
    .default_value(CompressionType.ZSTD)

# Map/dictionary option
custom_properties = ConfigOptions.key("table.custom.properties") \
    .map_type() \
    .default_value({})

# Long (integer) option
max_file_size = ConfigOptions.key("file.max.size") \
    .long_type() \
    .default_value(134217728)  # 128 MB in bytes

# Use options to retrieve values from configuration
from pypaimon.common.options import Options

options = Options({
    "catalog.name": "production",
    "max.retries": "5",
    "table.compression.enabled": "true",
    "write.buffer.size": "512mb"
})

catalog = options.get(catalog_name)  # "production"
retries = options.get(max_retries)  # 5
compression = options.get(enable_compression)  # True
buffer = options.get(buffer_size)  # MemorySize(512 MB)

# With defaults
warehouse_path = ConfigOptions.key("warehouse.path") \
    .string_type() \
    .default_value("/tmp/warehouse")

# If not in options, uses default
path = options.get(warehouse_path)  # "/tmp/warehouse" (default)

# Chain configuration definitions
class TableConfig:
    BUCKET_NUM = ConfigOptions.key("bucket") \
        .int_type() \
        .default_value(1)

    FILE_FORMAT = ConfigOptions.key("file.format") \
        .string_type() \
        .default_value("orc")

    COMPACTION_MIN_SIZE = ConfigOptions.key("compaction.min.file-num") \
        .int_type() \
        .default_value(4)

Related Pages

• Principle:Apache_Paimon_Utility_Infrastructure