Configuration

Ursa library and compactor settings use camelCase Java property names. Kafka broker settings use the separate ursa.* surface documented under Ursa for Apache Kafka (UFK). Broker keys and Ursa keys are different namespaces — do not paste one into the other's properties file.

This reference covers Ursa 1.0, transcribed from the v1.0.0 sources.

How properties are loaded

StorageConfig.fromProperties(Properties) constructs the configuration and then sets each known field by name. Field names are matched exactly and converted to the field's Java type. The supported types are String, boolean, int, long, double, and Set<String> (comma-separated); any other type is rejected.

Two consequences matter in practice:

• Unknown keys are kept, not rejected. They stay available to integration-specific consumers, which is how the Kafka runtime passes its own settings through. A misspelled key is therefore retained and ignored rather than reported as an error.
• Credentials can come from files. iceberg.credentialFile, unityCatalogTokenFile and schemaRegistryHttpHeaderAuthorizationFile each name a file whose contents become the corresponding value, so secrets need not appear in the properties file. These files are read once at startup.

StreamCatalogService and the standalone compactor both load configuration this way.

What "default" means in these tables

Each reference page states the effective default for a properties file — the value in force when the key is absent from your configuration.

This is the value the field initializer produces, because fromProperties constructs through the no-argument constructor rather than the builder. Where a getter computes the value instead of returning the field directly, the table says so and gives the derivation. Where a key falls back to another key, the table names the fallback.

Several keys use -1 as a sentinel meaning unset: the value is not a literal -1 at runtime but an instruction to fall back to a more general key, or to the underlying SDK's own default.

Per-namespace and per-topic overrides

A subset of compaction settings can be overridden per namespace or per topic through DynamicConfigs, so one compactor can apply different table behaviour to different streams. Nine keys participate:

Resolution order is namespace or topic property → cluster property → configuration file, first match wins.

The last three are topic-level only: they describe the shape of one table, so they are read from the namespace or topic property alone — not from a cluster-wide property, and not from the configuration file. clusterIdentifierFields, clusterPartitionKey and clusterUpsertModeEnabled are also passed down to the sink under their short aliases identifierFields, partitionKey and upsertModeEnabled.

LAKEHOUSE_DYNAMIC_EXTRA_VALID_KEYS_IN_CONF_FILE, a comma-separated environment variable, adds further keys to the set that participates in this override mechanism.

A minimal compactor configuration

The smallest properties file that starts a compactor against S3 and writes Iceberg tables:

# Metadata and coordination
metadataStoreUrl=oxia://oxia:6648/default
oxiaStorageUrl=oxia://oxia:6648/default

# WAL objects
backendStorageType=S3
region=us-east-1
bucket=my-ursa-wal
prefix=wal

# Compacted objects and table files
compactionBucket=my-ursa-lakehouse
compactionPrefix=lakehouse

# Record decoding
schemaRegistryUrl=http://schema-registry:8081

# Table destination
lakehouseType=ICEBERG
iceberg.catalog.main.type=rest
iceberg.catalog.main.uri=https://catalog.example.com/api/catalog
iceberg.catalog.main.warehouse=my-warehouse

Credentials are omitted on purpose. When s3AccessKeyId and s3SecretAccessKey are unset, Ursa resolves credentials from the ambient chain — a shared profile, or a projected web-identity token under IRSA or workload identity. See storage backends.

Reference pages

Keys are grouped the way the source groups them, by the category each field declares.

• WAL settings — write buffering, the read cache, the WAL backend and its object names.
• Object storage settings — buckets, regions, endpoints, connection limits, and the lakehouse reader's prefetch cache.
• Compaction settings — scheduling, commit batching, quarantine, catalog connections and cleanup.
• Lakehouse and table settings — table format, catalog bootstrap properties, Iceberg and Delta options.