Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt

Use this file to discover all available pages before exploring further.

StreamNative Ursa supports dynamic configuration at the cluster, namespace, and topic levels. This guide explains the supported configuration keys, the cluster-name prefix requirement, and how to apply them with pulsar-admin.

​
Configuration Key Format

All dynamic configuration keys must be prefixed with the cluster name.
ScopeKey formatExample (cluster name private-cloud)
Cluster<cluster-name>.cluster.<key>private-cloud.cluster.sdt.enabled
Namespace<cluster-name>.<key>private-cloud.sdt.enabled
Topic<cluster-name>.<key>private-cloud.sdt.enabled

​
Finding the Cluster Name

The cluster name is the value of the clusterName property in the Pulsar broker configuration (conf/broker.conf): 
# conf/broker.conf
clusterName=private-cloud
You can also retrieve it from a running broker pod: 
kubectl exec -n pulsar <broker-pod> -- grep '^clusterName' /pulsar/conf/broker.conf
Use this exact value as the <cluster-name> prefix in all the keys below.

​
Backward Compatibility

For existing clusters that do not use the cluster-name prefix, disable the prefix check by setting the following property in the broker configuration: 
checkClusterName=false

​
Override Priority

Settings at a more specific level override broader settings: 
Topic properties
    ↓ (overrides)
Namespace properties
    ↓ (overrides)
Cluster properties (sn/system)

​
Supported Dynamic Configuration Keys

​
Cluster-Level Keys

Cluster-level keys are applied via the sn/system namespace.
KeyDescription
<cluster-name>.cluster.sdt.enabledEnable External Table (SDT) for the cluster
<cluster-name>.cluster.sbt.enabledEnable Internal Table (SBT) — Coming Soon
<cluster-name>.cluster.sdt.catalog.nameDefault catalog name for SDT
<cluster-name>.cluster.tail.compact.data.visibility.interval.in.secondsData visibility delay (seconds)

​
Namespace-Level and Topic-Level Keys

These keys can be applied at either the namespace or topic level. Topic-level values override namespace-level values.

​
Enablement and Catalog Selection

KeyDescription
<cluster-name>.sdt.enabledEnable SDT for the namespace or topic
<cluster-name>.sbt.enabledEnable SBT — Coming Soon
<cluster-name>.sdt.catalog.nameCatalog name to use for the namespace or topic
<cluster-name>.tail.compact.data.visibility.interval.in.secondsData visibility delay (seconds)
Compaction task publishing is enabled when either sdt.enabled or sbt.enabled is true.

​
Topic-Level Feature Configuration

These keys configure feature behavior for individual topics:
KeyScopeDescription
<cluster-name>.partition.keyTopic onlyJSON-encoded partition specification for Iceberg tables. Setting this at cluster or namespace level has no effect.
<cluster-name>.upsert.mode.enabledCluster / Namespace / TopicEnable upsert mode (true / false)
<cluster-name>.identifier.fieldsTopic onlyComma-separated list of identifier fields used as the primary key. Setting this at cluster or namespace level has no effect.
<cluster-name>.iceberg.write-props.<property>Namespace / TopicIceberg write properties
<cluster-name>.iceberg.table-props.<property>Namespace / TopicIceberg table properties
For the detailed semantics of each feature key, see:

​
Apply Dynamic Configuration

The examples below assume a cluster named private-cloud.

​
Cluster Level

Cluster-level properties are stored in the sn/system namespace. 
bin/pulsar-admin namespaces set-properties \
  -p private-cloud.cluster.sdt.enabled=true \
  sn/system

​
Namespace Level

bin/pulsar-admin namespaces set-properties \
  -p private-cloud.sdt.enabled=true \
  <tenant>/<namespace>

​
Topic Level

bin/pulsar-admin topics update-properties \
  -p private-cloud.sdt.enabled=true \
  persistent://<tenant>/<namespace>/<topic>

​
Apply Multiple Keys at Once

You can specify -p key=value multiple times in a single command: 
bin/pulsar-admin topics update-properties \
  -p private-cloud.sdt.enabled=true \
  -p private-cloud.sdt.catalog.name=polaris-prod \
  -p private-cloud.upsertModeEnabled=true \
  -p private-cloud.identifierFields=userId,email \
  persistent://public/default/users

​
Extending Valid Dynamic Configuration Keys

By default, only the keys listed above are accepted. To add additional keys, set the following environment variable when starting the Pulsar broker: 
LAKEHOUSE_DYNAMIC_EXTRA_VALID_KEYS_IN_CONF_FILE=<key1>,<key2>,<key3>
Example: 
LAKEHOUSE_DYNAMIC_EXTRA_VALID_KEYS_IN_CONF_FILE=clusterSdtEnabled,clusterSbtEnabled,clusterSdtCatalogName

​
Next Steps