Implementation:Apache Paimon CoreOptions

Knowledge Sources	Apache_Paimon
Domains	Configuration Management, Table Options, Storage Configuration
Last Updated	2026-02-08 00:00 GMT

Overview

CoreOptions is the central configuration class that defines all core table-level options for Apache Paimon, covering bucket configuration, file formats, compaction, merge engines, snapshot management, and many other table behaviors.

Description

This class serves as both the configuration schema and the runtime accessor for Paimon table options. It declares hundreds of ConfigOption static fields using the builder pattern from ConfigOptions.key(), each with a type, default value, and description. The class wraps an Options instance and provides typed getter methods for each option.

CoreOptions also defines numerous inner enums that represent the valid values for enum-typed options, including MergeEngine (deduplicate, partial-update, aggregate, first-row), ChangelogProducer, StartupMode, LogConsistency, OrderType, BucketFunctionType, and ExternalPathStrategy. Key configuration areas include bucket assignment (-1 dynamic, -2 postpone, >0 fixed), file format (ORC/Parquet/Avro), compaction strategies, merge engines, snapshot expiration, changelog production, scan modes, and data file external paths.

This is the most critical configuration class in the Paimon API. Nearly every table behavior is controlled through options defined here. All documentation generation for table options flows from the annotations and descriptions on these fields.

Usage

Use CoreOptions to configure table-level behavior when creating or altering Paimon tables. Access configuration values through the typed getter methods by wrapping an Options instance.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/CoreOptions.java
• Lines: 1-4100

Signature

public class CoreOptions implements Serializable {

    // Configuration option declarations
    public static final ConfigOption<Integer> BUCKET =
        key("bucket").intType().defaultValue(-1).withDescription(...);

    public static final ConfigOption<String> BUCKET_KEY =
        key("bucket-key").stringType().noDefaultValue().withDescription(...);

    public static final ConfigOption<String> FILE_FORMAT =
        key("file.format").stringType().defaultValue("orc").withDescription(...);

    // Inner enums for typed options
    public enum MergeEngine implements DescribedEnum {
        DEDUPLICATE, PARTIAL_UPDATE, AGGREGATE, FIRST_ROW
    }

    public enum ChangelogProducer implements DescribedEnum {
        NONE, INPUT, FULL_COMPACTION, LOOKUP
    }

    // Instance fields and getters
    private final Options options;

    public CoreOptions(Options options) {
        this.options = options;
    }

    public int bucket() {
        return options.get(BUCKET);
    }
}

Import

import org.apache.paimon.CoreOptions;

I/O Contract

Inputs

Name	Type	Required	Description
options	Options	yes	Options map containing configuration key-value pairs

Outputs

Name	Type	Description
bucket	int	Number of buckets for the table (-1 dynamic, -2 postpone, >0 fixed)
bucketKey	Optional<List<String>>	Fields used for bucket assignment
fileFormat	String	File format (orc, parquet, avro)
mergeEngine	MergeEngine	Merge engine type for primary key tables
changelogProducer	ChangelogProducer	Changelog production strategy

Usage Examples

Configuring Table Options

import org.apache.paimon.CoreOptions;
import org.apache.paimon.options.Options;

// Create options for a table
Options options = new Options();
options.set(CoreOptions.BUCKET, 4);
options.set(CoreOptions.FILE_FORMAT, "parquet");
options.set(CoreOptions.MERGE_ENGINE, CoreOptions.MergeEngine.DEDUPLICATE);

// Access configuration through CoreOptions
CoreOptions coreOptions = new CoreOptions(options);
int bucketCount = coreOptions.bucket();
String format = coreOptions.formatType().toString();
CoreOptions.MergeEngine mergeEngine = coreOptions.mergeEngine();

System.out.println("Buckets: " + bucketCount);
System.out.println("Format: " + format);
System.out.println("Merge Engine: " + mergeEngine);

Configuring Compaction

import org.apache.paimon.CoreOptions;
import org.apache.paimon.options.Options;
import org.apache.paimon.options.MemorySize;
import java.time.Duration;

Options options = new Options();
options.set(CoreOptions.COMPACTION_MIN_FILE_NUM, 5);
options.set(CoreOptions.COMPACTION_MAX_FILE_NUM, 50);
options.set(CoreOptions.TARGET_FILE_SIZE, MemorySize.ofMebiBytes(128));
options.set(CoreOptions.SNAPSHOT_EXPIRE_TIME, Duration.ofDays(7));

CoreOptions coreOptions = new CoreOptions(options);
int minFiles = coreOptions.compactionMinFileNum();
MemorySize targetSize = coreOptions.targetFileSize();

System.out.println("Min files for compaction: " + minFiles);
System.out.println("Target file size: " + targetSize);

Related Pages

• Principle:Apache_Paimon_Table_Configuration