Implementation:Apache Paimon CatalogOptions

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

Overview

CatalogOptions defines all configuration options available for Apache Paimon catalog implementations.

Description

CatalogOptions is a comprehensive configuration class that declares all available options for configuring Paimon catalogs. It uses the ConfigOption pattern to define strongly-typed configuration parameters with default values, descriptions, and validation.

The class covers several major configuration areas: basic catalog setup (warehouse location, metastore type, URI), locking mechanisms for concurrent access control, connection pooling for metastore clients, and extensive caching configuration for metadata, manifests, snapshots, and deletion vectors.

Key configuration categories include metastore selection (filesystem, hive, jdbc), catalog-level table type defaults, locking strategies for consistency, client pool sizing for performance, and multi-level caching with configurable expiration policies. The caching system supports both time-based expiration (after access or write) and size-based limits for different metadata types.

Special-purpose options control case sensitivity, property synchronization with external metastores, format table support, and FileIO implementation choices. These options allow fine-tuning of catalog behavior for different deployment scenarios and integration requirements.

All options use descriptive keys following Paimon's naming conventions and include detailed documentation strings that appear in configuration guides and error messages. Fallback keys maintain backward compatibility with older configuration names.

Usage

Use CatalogOptions when configuring a Paimon catalog programmatically or when implementing catalog factories that need to parse user-provided configuration. These options should be set in catalog properties or passed through framework-specific configuration mechanisms. The strongly-typed ConfigOption objects provide validation and default values automatically.

Code Reference

Source Location

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

Signature

public class CatalogOptions {
    // Core catalog options
    public static final ConfigOption<String> WAREHOUSE;
    public static final ConfigOption<String> METASTORE;
    public static final ConfigOption<String> URI;
    public static final ConfigOption<CatalogTableType> TABLE_TYPE;

    // Locking options
    public static final ConfigOption<Boolean> LOCK_ENABLED;
    public static final ConfigOption<String> LOCK_TYPE;
    public static final ConfigOption<Duration> LOCK_CHECK_MAX_SLEEP;
    public static final ConfigOption<Duration> LOCK_ACQUIRE_TIMEOUT;

    // Connection options
    public static final ConfigOption<Integer> CLIENT_POOL_SIZE;

    // Caching options
    public static final ConfigOption<Boolean> CACHE_ENABLED;
    public static final ConfigOption<Duration> CACHE_EXPIRE_AFTER_ACCESS;
    public static final ConfigOption<Duration> CACHE_EXPIRE_AFTER_WRITE;
    public static final ConfigOption<Long> CACHE_PARTITION_MAX_NUM;
    public static final ConfigOption<MemorySize> CACHE_MANIFEST_SMALL_FILE_MEMORY;
    public static final ConfigOption<MemorySize> CACHE_MANIFEST_SMALL_FILE_THRESHOLD;
    public static final ConfigOption<MemorySize> CACHE_MANIFEST_MAX_MEMORY;
    public static final ConfigOption<Integer> CACHE_SNAPSHOT_MAX_NUM_PER_TABLE;
    public static final ConfigOption<Integer> CACHE_DV_MAX_NUM;

    // Behavior options
    public static final ConfigOption<Boolean> CASE_SENSITIVE;
    public static final ConfigOption<Boolean> SYNC_ALL_PROPERTIES;
    public static final ConfigOption<Boolean> FORMAT_TABLE_ENABLED;
    public static final ConfigOption<Boolean> RESOLVING_FILE_IO_ENABLED;
    public static final ConfigOption<Boolean> FILE_IO_ALLOW_CACHE;
}

Import

import org.apache.paimon.options.CatalogOptions;

I/O Contract

Inputs

Name	Type	Required	Description
Configuration values	Various	Mixed	Each ConfigOption has its own type and requirement

Outputs

Name	Type	Description
ConfigOption objects	ConfigOption<T>	Strongly-typed configuration option declarations

Usage Examples

// Basic catalog configuration
Map<String, String> catalogConf = new HashMap<>();
catalogConf.put(CatalogOptions.WAREHOUSE.key(), "/path/to/warehouse");
catalogConf.put(CatalogOptions.METASTORE.key(), "hive");
catalogConf.put(CatalogOptions.URI.key(), "thrift://localhost:9083");

Options options = new Options(catalogConf);
String warehouse = options.get(CatalogOptions.WAREHOUSE);
String metastore = options.get(CatalogOptions.METASTORE);

// Configuring catalog locking
catalogConf.put(CatalogOptions.LOCK_ENABLED.key(), "true");
catalogConf.put(CatalogOptions.LOCK_TYPE.key(), "hive");
catalogConf.put(
    CatalogOptions.LOCK_ACQUIRE_TIMEOUT.key(),
    "5 min"
);

// Configuring catalog cache
catalogConf.put(CatalogOptions.CACHE_ENABLED.key(), "true");
catalogConf.put(
    CatalogOptions.CACHE_EXPIRE_AFTER_ACCESS.key(),
    "10 min"
);
catalogConf.put(
    CatalogOptions.CACHE_MANIFEST_SMALL_FILE_MEMORY.key(),
    "256mb"
);
catalogConf.put(
    CatalogOptions.CACHE_SNAPSHOT_MAX_NUM_PER_TABLE.key(),
    "50"
);

// Reading configuration with defaults
Options opts = new Options(catalogConf);
boolean cacheEnabled = opts.get(CatalogOptions.CACHE_ENABLED); // true by default
int poolSize = opts.get(CatalogOptions.CLIENT_POOL_SIZE); // 2 by default
Duration lockTimeout = opts.get(CatalogOptions.LOCK_ACQUIRE_TIMEOUT);

// Case sensitivity configuration
catalogConf.put(CatalogOptions.CASE_SENSITIVE.key(), "false");

// Format table support
catalogConf.put(CatalogOptions.FORMAT_TABLE_ENABLED.key(), "true");

// Fine-tuning cache limits
catalogConf.put(
    CatalogOptions.CACHE_PARTITION_MAX_NUM.key(),
    "10000"
);
catalogConf.put(
    CatalogOptions.CACHE_DV_MAX_NUM.key(),
    "50000"
);

// Disabling cache for specific use case
catalogConf.put(CatalogOptions.CACHE_ENABLED.key(), "false");

// Using in catalog factory
public class HiveCatalogFactory implements CatalogFactory {
    @Override
    public Catalog createCatalog(Context context) {
        Options options = Options.fromMap(context.getOptions());

        String warehouse = options.get(CatalogOptions.WAREHOUSE);
        String uri = options.get(CatalogOptions.URI);
        boolean lockEnabled = options.get(CatalogOptions.LOCK_ENABLED);

        return new HiveCatalog(warehouse, uri, lockEnabled);
    }
}

// FileIO configuration
catalogConf.put(
    CatalogOptions.RESOLVING_FILE_IO_ENABLED.key(),
    "true"
);
catalogConf.put(
    CatalogOptions.FILE_IO_ALLOW_CACHE.key(),
    "false"
);

Related Pages

• Principle:Apache_Paimon_Table_Configuration