These configuration parameters are used when creating Iceberg sources, sinks, or connections to specify the Iceberg catalog. The catalog is responsible for managing table metadata (schema, partitioning, location). RisingWave supports several catalog types. These parameters are used in the WITH clause of CREATE SOURCE, CREATE SINK, and CREATE CONNECTION statements.

​
Catalog parameters

ParameterDescriptionRequired (Conditional)
catalog.nameThe name of the Iceberg catalog. This is a user-defined identifier. Optional for the storage catalog, but required for all other catalog types.Conditional
catalog.typeThe type of Iceberg catalog to use. Supported values:
  • 'storage': Uses the underlying file system (e.g., S3) directly for metadata.
  • 'rest': Uses the Iceberg REST catalog.
  • 'hive': Uses a Hive Metastore.
  • 'jdbc': Uses a JDBC catalog.
  • 'glue': Uses AWS Glue Data Catalog
  • 'snowflake': Uses Snowflake catalog
If not specified, defaults to 'storage'.		No (defaults to storage)
catalog.uriThe URI of the catalog. The required format depends on the catalog.type:
  • rest: The base URL of the REST catalog server (e.g., 'http://rest-catalog:8181').
  • hive: The Hive Metastore URI (e.g., 'thrift://hive-metastore:9083').
  • jdbc: The JDBC connection string (e.g., 'jdbc:postgresql://postgres:5432/iceberg').
  • snowflake: The Snowflake JDBC connection string (e.g., 'jdbc:snowflake://<account_identifier>.snowflakecomputing.com/').
Conditional
catalog.credentialCredential for accessing the Iceberg catalog, used to exchange for a token in the OAuth2 client credentials flow. Applicable only in the rest catalog.No
catalog.tokenA Bearer token for accessing the Iceberg catalog, used for interaction with the server. Applicable only in the rest catalog.No
catalog.oauth2_server_uriThe oauth2_server_uri for accessing the Iceberg catalog, serving as the token endpoint URI to fetch a token if the rest catalog is not the authorization server. Applicable only in the rest catalog.No
catalog.scopeScope for accessing the Iceberg catalog, providing additional scope for OAuth2. Applicable only in the rest catalog.No
catalog.jdbc.userUsername for JDBC catalog.No
catalog.jdbc.passwordPassword for JDBC catalog.No
hosted_catalogConditional. Set to true when creating an Iceberg connection to use RisingWave’s built-in hosted catalog. This is only applicable when creating tables with the Iceberg table engine.

​
Hosted Iceberg catalog

For scenarios where you create and manage Iceberg tables natively within RisingWave using the Iceberg table engine, you have the option to use the Hosted Iceberg Catalog. This is a built-in catalog service that simplifies setup by eliminating the need to configure and manage an external catalog service. For a complete guide on how it works, its benefits, and how to use it, see Hosted Iceberg catalog.

​
External catalogs

External catalogs are required when you read from or write to existing Iceberg tables that are managed outside of RisingWave. They can also be used with the Iceberg table engine if you need to integrate with an existing catalog infrastructure. RisingWave supports the following external catalog types:

​
Storage catalog

The storage catalog stores all metadata in the underlying file system, such as Hadoop or S3. Currently, we only support S3 as the underlying file system.
Example
CREATE SINK sink_demo_storage FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    s3.endpoint = 'http://minio-0:9301',
    s3.access.key = 'xxxxxxxxxx',
    s3.secret.key = 'xxxxxxxxxx',
    s3.region = 'ap-southeast-1',
    catalog.type = 'storage',
    catalog.name = 'demo',
    warehouse.path = 's3://icebergdata/demo',
    database.name = 's1',
    table.name = 't1'
);
Example
CREATE SOURCE source_demo_storage
WITH (
    connector = 'iceberg',
    s3.endpoint = 'http://minio-0:9301',
    s3.access.key = 'xxxxxxxxxx',
    s3.secret.key = 'xxxxxxxxxx',
    s3.region = 'ap-southeast-1',
    catalog.type = 'storage',
    catalog.name = 'demo',
    warehouse.path = 's3://icebergdata/demo',
    database.name = 's1',
    table.name = 't1'
);

​
REST catalog

The REST catalog uses a RESTful interface to manage table metadata.
Example
CREATE SINK sink_demo_rest FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    s3.endpoint = 'https://s3.ap-southeast-2.amazonaws.com',
    s3.region = 'ap-southeast-2',
    s3.access.key = 'xxxx',
    s3.secret.key = 'xxxx',
    s3.path.style.access = 'true',
    catalog.type = 'rest',
    catalog.uri = 'http://localhost:8181/api/catalog',
    warehouse.path = 'quickstart_catalog',
    database.name = 'ns',
    table.name = 't1',
    catalog.credential='123456:123456',
    catalog.scope='PRINCIPAL_ROLE:ALL',
    catalog.oauth2_server_uri='xxx'
);

​
JDBC catalog

The JDBC catalog stores metadata in a relational database like PostgreSQL.
Example
CREATE SINK sink_demo_jdbc FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    s3.endpoint = 'http://minio-0:9301',
    s3.access.key = 'xxxxxxxxxx',
    s3.secret.key = 'xxxxxxxxxx',
    s3.region = 'ap-southeast-1',
    catalog.type = 'jdbc',
    catalog.uri = 'jdbc:postgresql://127.0.0.1:8432/metadata',
    catalog.jdbc.user = 'postgres',
    catalog.jdbc.password = '123',
    catalog.name = 'dev',
    warehouse.path = 's3://icebergdata/demo',
    database.name = 's1',
    table.name = 't1'
);

​
Glue catalog

AWS Glue Data Catalog provides a centralized metadata store for table definitions.
Example
CREATE SINK sink_demo_glue FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    s3.endpoint = 'https://s3.ap-southeast-2.amazonaws.com',
    s3.region = 'ap-southeast-2',
    s3.access.key = 'xxxx',
    s3.secret.key = 'xxxx',
    catalog.type = 'glue',
    catalog.name = 'demo',
    warehouse.path = 's3://icebergdata/demo',
    database.name = 's1',
    table.name = 't1'
);

​
Snowflake catalog

The Snowflake catalog uses Snowflake’s built-in Iceberg catalog functionality.
Example
CREATE SINK sink_demo_snowflake FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    catalog.type = 'snowflake',
    catalog.name = 'SNOWFLAKE',
    catalog.uri = 'jdbc:snowflake://<account_identifier>.snowflakecomputing.com/',
    catalog.jdbc.user = '<your_username>',
    catalog.jdbc.password = '<your_password>',
    warehouse.path = '<warehouse_path>',
    database.name = '<your_database>',
    table.name = '<your_table>'
);

​
Hive Metastore catalog

The Hive Metastore catalog stores metadata using a Hive Metastore backend.
Example
CREATE SINK sink_demo_hive FROM t
WITH (
    connector = 'iceberg',
    type = 'append-only',
    force_append_only = true,
    s3.endpoint = 'http://minio-0:9301',
    s3.access.key = 'xxxxxxxxxx',
    s3.secret.key = 'xxxxxxxxxx',
    s3.region = 'ap-southeast-1',
    catalog.type = 'hive',
    catalog.uri = 'thrift://hive-metastore:9083',
    warehouse.path = 's3://icebergdata/demo',
    database.name = 's1',
    table.name = 't1'
);

​
Choosing the right catalog

  • For reading from or writing to existing Iceberg tables, you must use an external catalog that matches the one used by the external system.
  • When creating new Iceberg tables with RisingWave’s table engine:
    • The hosted catalog is recommended for new projects, rapid prototyping, and simpler setups.
    • An external catalog is suitable when you need to integrate with existing enterprise catalog infrastructure (like AWS Glue) or share the catalog with other systems.

​
Next steps