Implementation:Apache Paimon RESTCatalogOptions
| Knowledge Sources | |
|---|---|
| Domains | Configuration, REST API, Authentication |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
RESTCatalogOptions defines all configuration options available for Apache Paimon's REST Catalog, including URI, authentication, and DLF-specific settings.
Description
RESTCatalogOptions is a configuration class that centralizes all available options for configuring the REST Catalog in Apache Paimon. It uses Paimon's ConfigOption framework to define strongly-typed configuration parameters with descriptions and default values where applicable.
The options cover several key areas: basic REST catalog configuration (URI), general authentication (token and token provider), Alibaba Cloud DLF-specific authentication (region, access keys, security tokens, signing algorithms), HTTP client settings (user agent), and file I/O cache configuration for optimizing data access patterns.
The DLF authentication options support multiple authentication methods including file-based tokens, access key pairs, ECS metadata service credentials, and configurable token loaders. The signing algorithm option allows selecting between different DLF authentication protocols (default VPC endpoint vs. OpenAPI), with automatic selection based on endpoint hostname if not explicitly configured.
The I/O cache options enable table-level caching policies for file access, which can significantly improve performance when using supported file I/O implementations like JindoFileIO. Cache policies can be configured for metadata, read operations, and write operations independently.
Usage
Use RESTCatalogOptions when configuring a Paimon REST Catalog to define connection parameters, authentication credentials, and performance optimization settings. These options are typically set in catalog properties or configuration files when initializing a REST catalog instance.
Code Reference
Source Location
- Repository: Apache_Paimon
- File: paimon-api/src/main/java/org/apache/paimon/rest/RESTCatalogOptions.java
Signature
public class RESTCatalogOptions {
// Basic configuration
public static final ConfigOption<String> URI;
// General authentication
public static final ConfigOption<String> TOKEN;
public static final ConfigOption<String> TOKEN_PROVIDER;
// DLF authentication
public static final ConfigOption<String> DLF_REGION;
public static final ConfigOption<String> DLF_TOKEN_PATH;
public static final ConfigOption<String> DLF_ACCESS_KEY_ID;
public static final ConfigOption<String> DLF_ACCESS_KEY_SECRET;
public static final ConfigOption<String> DLF_SECURITY_TOKEN;
public static final ConfigOption<String> DLF_TOKEN_LOADER;
public static final ConfigOption<String> DLF_TOKEN_ECS_METADATA_URL;
public static final ConfigOption<String> DLF_TOKEN_ECS_ROLE_NAME;
public static final ConfigOption<String> DLF_OSS_ENDPOINT;
public static final ConfigOption<String> DLF_SIGNING_ALGORITHM;
// HTTP client configuration
public static final ConfigOption<String> HTTP_USER_AGENT;
// I/O cache configuration
public static final ConfigOption<Boolean> IO_CACHE_ENABLED;
public static final ConfigOption<String> IO_CACHE_WHITELIST_PATH;
public static final ConfigOption<String> IO_CACHE_POLICY;
}
Import
import org.apache.paimon.rest.RESTCatalogOptions;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| uri | String | Yes | REST Catalog server's URI |
| token | String | No | REST Catalog auth bearer token |
| token.provider | String | No | REST Catalog auth token provider identifier |
| dlf.region | String | No | DLF region (auto-detected from URI if not set) |
| dlf.token-path | String | No | DLF token file path for file-based authentication |
| dlf.access-key-id | String | No | DLF access key ID for AK/SK authentication |
| dlf.access-key-secret | String | No | DLF access key secret for AK/SK authentication |
| dlf.security-token | String | No | DLF security token for temporary credentials |
| dlf.token-loader | String | No | DLF token loader implementation identifier |
| dlf.token-ecs-metadata-url | String | No | DLF ECS metadata URL (default: http://100.100.100.200/latest/meta-data/Ram/security-credentials/) |
| dlf.token-ecs-role-name | String | No | DLF ECS role name for ECS metadata authentication |
| dlf.oss-endpoint | String | No | DLF OSS endpoint |
| dlf.signing-algorithm | String | No | DLF signing algorithm: 'default' or 'openapi' (default: 'default') |
| header.User-Agent | String | No | User agent for HTTP client |
| io-cache.enabled | Boolean | No | Enable file I/O cache (default: false) |
| io-cache.whitelist-path | String | No | Cache path patterns (default: "bucket,manifest,index") |
| io-cache.policy | String | No | Cache policy: meta, read, write, or none |
Outputs
| Name | Type | Description |
|---|---|---|
| ConfigOption instances | ConfigOption<T> | Strongly-typed configuration option definitions |
Usage Examples
import org.apache.paimon.options.Options;
import org.apache.paimon.rest.RESTCatalogOptions;
// Example 1: Basic REST catalog configuration
Options options = new Options();
options.set(RESTCatalogOptions.URI, "https://catalog.example.com");
options.set(RESTCatalogOptions.TOKEN, "my-bearer-token");
// Example 2: DLF authentication with access keys
Options dlfOptions = new Options();
dlfOptions.set(RESTCatalogOptions.URI, "https://dlf.cn-hangzhou.aliyuncs.com");
dlfOptions.set(RESTCatalogOptions.TOKEN_PROVIDER, "dlf");
dlfOptions.set(RESTCatalogOptions.DLF_REGION, "cn-hangzhou");
dlfOptions.set(RESTCatalogOptions.DLF_ACCESS_KEY_ID, "LTAI***");
dlfOptions.set(RESTCatalogOptions.DLF_ACCESS_KEY_SECRET, "secret***");
// Example 3: DLF with ECS metadata authentication
Options ecsOptions = new Options();
ecsOptions.set(RESTCatalogOptions.URI, "https://dlf.cn-beijing.aliyuncs.com");
ecsOptions.set(RESTCatalogOptions.TOKEN_PROVIDER, "dlf");
ecsOptions.set(RESTCatalogOptions.DLF_TOKEN_LOADER, "ecs");
ecsOptions.set(RESTCatalogOptions.DLF_TOKEN_ECS_ROLE_NAME, "my-ecs-role");
// Example 4: DLF with file-based token
Options fileTokenOptions = new Options();
fileTokenOptions.set(RESTCatalogOptions.URI, "https://dlf.cn-shanghai.aliyuncs.com");
fileTokenOptions.set(RESTCatalogOptions.TOKEN_PROVIDER, "dlf");
fileTokenOptions.set(RESTCatalogOptions.DLF_TOKEN_PATH, "/path/to/token.json");
// Example 5: DLF OpenAPI signing algorithm
Options openapiOptions = new Options();
openapiOptions.set(RESTCatalogOptions.URI,
"https://dlfnext.cn-hangzhou.aliyuncs.com");
openapiOptions.set(RESTCatalogOptions.TOKEN_PROVIDER, "dlf");
openapiOptions.set(RESTCatalogOptions.DLF_ACCESS_KEY_ID, "LTAI***");
openapiOptions.set(RESTCatalogOptions.DLF_ACCESS_KEY_SECRET, "secret***");
// Signing algorithm auto-detected as 'openapi' from URI containing 'dlfnext'
// Or explicitly set:
openapiOptions.set(RESTCatalogOptions.DLF_SIGNING_ALGORITHM, "openapi");
// Example 6: Enable I/O caching
Options cacheOptions = new Options();
cacheOptions.set(RESTCatalogOptions.URI, "https://catalog.example.com");
cacheOptions.set(RESTCatalogOptions.IO_CACHE_ENABLED, true);
cacheOptions.set(RESTCatalogOptions.IO_CACHE_WHITELIST_PATH, "bucket,manifest,index");
cacheOptions.set(RESTCatalogOptions.IO_CACHE_POLICY, "meta,read");
// Example 7: Custom HTTP user agent
Options agentOptions = new Options();
agentOptions.set(RESTCatalogOptions.URI, "https://catalog.example.com");
agentOptions.set(RESTCatalogOptions.HTTP_USER_AGENT, "MyApp/1.0");
// Access option values
String uri = options.get(RESTCatalogOptions.URI);
boolean cacheEnabled = cacheOptions.get(RESTCatalogOptions.IO_CACHE_ENABLED);