Docs: Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Here, you will find the configuration properties for the Apache Iceberg extension.

Configuration

The Apache Iceberg extension connects to an Iceberg catalog. You configure it through the Jikkou client configuration property jikkou.provider.iceberg.

Example (JDBC catalog with PostgreSQL):

jikkou {
provider.iceberg {
enabled = true
type = io.streamthoughts.jikkou.iceberg.IcebergExtensionProvider
config = {
# Required — type of Iceberg catalog.
# Accepted values: rest, hive, jdbc, glue, nessie, hadoop
catalogType = "jdbc"
# The catalog name used to identify this catalog instance.
catalogName = "default"
# The URI of the catalog endpoint (REST URL, Hive Metastore URI, JDBC URL, etc.)
catalogUri = "jdbc:postgresql://localhost:5432/iceberg"
# The warehouse root location (e.g., local path, S3 bucket path, HDFS path)
warehouse = "/tmp/iceberg-warehouse"
# Extra catalog-specific properties passed directly to CatalogUtil.buildIcebergCatalog()
catalogProperties {
jdbc.user = "iceberg"
jdbc.password = "iceberg"
}
# Enable verbose debug logging for catalog operations (default: false)
debugLoggingEnabled = false
}
}
}

Configuration Properties

Property	Type	Required	Default	Description
`catalogType`	String	yes	—	Iceberg catalog type: `rest`, `hive`, `jdbc`, `glue`, `nessie`, `hadoop`
`catalogName`	String	no	`default`	The catalog instance name
`catalogUri`	String	no	—	Catalog endpoint URI (REST API URL, Hive Metastore thrift URI, JDBC URL, Nessie server URL)
`warehouse`	String	no	—	Warehouse root location (e.g., `s3://bucket/warehouse`, `/tmp/iceberg`)
`catalogProperties`	Map	no	—	Additional catalog properties forwarded verbatim to the Iceberg `CatalogUtil`
`debugLoggingEnabled`	Boolean	no	`false`	Enable debug-level logging for catalog operations

Catalog Types

JDBC Catalog (PostgreSQL)

Stores catalog metadata (namespaces, table specs) in a relational database. The PostgreSQL JDBC driver is bundled in the Jikkou CLI distribution.

config = {
catalogType = "jdbc"
catalogUri = "jdbc:postgresql://localhost:5432/iceberg"
warehouse = "/tmp/iceberg-warehouse"
catalogProperties {
jdbc.user = "iceberg"
jdbc.password = "iceberg"
}
}

REST Catalog

Connects to any Iceberg REST Catalog API (e.g., Polaris, Gravitino, Unity Catalog):

config = {
catalogType = "rest"
catalogUri = "https://polaris.example.com/api/catalog"
warehouse = "s3://my-bucket/warehouse"
catalogProperties {
rest.signing-name = "execute-api"
rest.signing-region = "us-east-1"
}
}

Hive Metastore

Connects to an Apache Hive Metastore (requires iceberg-hive-metastore on the classpath):

config = {
catalogType = "hive"
catalogUri = "thrift://hive-metastore:9083"
warehouse = "hdfs://namenode:8020/user/hive/warehouse"
}

AWS Glue

Connects to AWS Glue Data Catalog (requires iceberg-aws on the classpath):

config = {
catalogType = "glue"
warehouse = "s3://my-bucket/warehouse"
catalogProperties {
glue.region = "us-east-1"
}
}

Nessie

Nessie exposes a standard Iceberg REST catalog endpoint at /iceberg. Using catalogType = "rest" is recommended because it relies only on iceberg-core (always bundled in the Jikkou CLI). The catalogType = "nessie" variant requires the optional iceberg-nessie JAR on the classpath.

# Recommended: use Nessie's built-in Iceberg REST endpoint
config = {
catalogType = "rest"
catalogUri = "http://nessie:19120/iceberg"
warehouse = "s3://my-bucket/warehouse"
catalogProperties {
prefix = "main" # Nessie branch
}
}

Controller Settings

The table and view controllers expose additional options to control reconciliation behaviour. These are set inside the provider config block.

Table Controller

Property	Type	Default	Description
`delete-orphans`	Boolean	`false`	Drop tables that exist in the catalog but are not defined in any resource
`delete-orphan-columns`	Boolean	`false`	Drop columns present in the live table but absent from the spec
`delete-purge`	Boolean	`false`	Purge underlying data files when dropping a table (irreversible)
`tables.deletion.exclude`	List<Pattern>	`[]`	Regex patterns — matching table names are never deleted

View Controller

Property	Type	Default	Description
`delete-orphans`	Boolean	`false`	Drop views that exist in the catalog but are not defined in any resource
`views.deletion.exclude`	List<Pattern>	`[]`	Regex patterns — matching view names are never deleted

Note

The delete-orphans property applies independently to tables and views. The IcebergNamespaceController always uses delete-orphans = false to prevent accidental deletion of namespaces that may still contain tables. To delete a namespace, use the DELETE reconciliation mode explicitly.

Example:

jikkou {
provider.iceberg {
enabled = true
type = io.streamthoughts.jikkou.iceberg.IcebergExtensionProvider
config = {
catalogType = "rest"
catalogUri = "http://localhost:8181"
warehouse = "s3://my-bucket/warehouse"
# Table reconciliation safety settings
delete-orphans = false
delete-orphan-columns = false
delete-purge = false
# Never delete tables whose name starts with "audit_"
tables.deletion.exclude = ["^audit_.*"]
# Never delete views whose name starts with "v_core_"
views.deletion.exclude = ["^v_core_.*"]
}
}
}

Docs: Resources

Mon, 01 Jan 0001 00:00:00 +0000

Here, you will find the list of resources supported by the extensions for Apache Iceberg.

Iceberg Resources

The Apache Iceberg extension provides the following resource types:

Resource	Description
`IcebergNamespace`	Manage namespaces (databases) in an Iceberg catalog
`IcebergTable`	Manage tables with schema evolution, partitioning, and sort order
`IcebergView`	Manage SQL views backed by one or more dialect-specific queries

More information:

Docs: Annotations

Mon, 01 Jan 0001 00:00:00 +0000

Here, you will find information about the annotations provided by the Apache Iceberg extension for Jikkou.

List of built-in annotations

`iceberg.jikkou.io/allow-incompatible-changes`

Controls whether incompatible schema changes are allowed when reconciling an IcebergTable.

By default, Jikkou rejects type changes that cannot be safely promoted (for example, changing a column from string to int). Setting this annotation to "true" on a specific table resource lifts that restriction for that resource only.

metadata:
 annotations:
 iceberg.jikkou.io/allow-incompatible-changes: "true"

Warning

Incompatible schema changes may break existing readers. Only enable this annotation when you are certain all consumers of the table can handle the new schema.

`iceberg.jikkou.io/namespace-location`

Read-only annotation populated by the namespace collector. Contains the storage location of a namespace as reported by the catalog. This annotation is set automatically when collecting existing namespaces and does not need to be specified in resource files.

`iceberg.jikkou.io/table-location`

Reserved annotation for the storage location of a table. Currently, the table location is stored in the spec.location field rather than as an annotation. This annotation key is defined for future use.

`iceberg.jikkou.io/view-location`

Read-only annotation populated by the view collector. Contains the storage location of a view as reported by the catalog. This annotation is set automatically when collecting existing views and does not need to be specified in resource files.

Jikkou – Apache Iceberg

Docs: Configuration

Configuration

Configuration Properties

Catalog Types

JDBC Catalog (PostgreSQL)

REST Catalog

Hive Metastore

AWS Glue

Nessie

Controller Settings

Table Controller

View Controller

Note

Docs: Resources

Iceberg Resources

Docs: Annotations

List of built-in annotations

iceberg.jikkou.io/allow-incompatible-changes

Warning

iceberg.jikkou.io/namespace-location

iceberg.jikkou.io/table-location

iceberg.jikkou.io/view-location

`iceberg.jikkou.io/allow-incompatible-changes`

`iceberg.jikkou.io/namespace-location`

`iceberg.jikkou.io/table-location`

`iceberg.jikkou.io/view-location`