CREATE ICEBERG CATALOG¶

CREATE ICEBERG CATALOG registers an Apache Iceberg REST catalog with a name and connection options. Access and modification require the configuration and policies described below.

Description¶

CREATE ICEBERG CATALOG registers an Apache Iceberg REST catalog in MatrixOne. Registration alone does not grant access. After a catalog is registered and the required access policies are configured, you can create an external table that references it. Writes and row-level MERGE INTO require additional write and DML flags.

A catalog requires a uri option pointing to the Iceberg REST catalog endpoint. The type option defaults to rest when omitted. Authentication is configured with auth_mode (or its alias auth) and an optional token_secret_ref (alias token_secret) for token-based credentials.

To change an existing catalog, use ALTER ICEBERG CATALOG ... SET (...). To remove one, use DROP ICEBERG CATALOG.

Prerequisites¶

Registering catalog metadata does not contact the remote service and succeeds even when Iceberg access is disabled. Before querying an external Iceberg table:

Enable the Iceberg integration in the MatrixOne configuration.
Configure a principal mapping for the accessing user.
Configure a residency policy for the external data.
Enable write, DML, and delete operations if the catalog will be modified.

For read-only access, only the read configuration is required. MERGE INTO additionally requires write, DML, and delete capabilities. Enable Iceberg on every CN that can execute an Iceberg query:

[cn.frontend.iceberg]
enable = true

For writes, also set enable-write = true. MERGE INTO, UPDATE, and DELETE additionally require both enable-dml = true and enable-delete = true; the external table must use a compatible non-read_only write_mode.

Before querying a catalog, an administrator must register a principal mapping and residency policy. iceberg_register_access creates both records, but the named catalog must already exist. Create the catalog first, then call the procedure as one ordered flow, as shown in the example below. Replace the endpoint, region, bucket, and external principal with the exact values allowed by your deployment.

If either the principal mapping or the residency policy is missing, MatrixOne rejects access instead of contacting the remote catalog or object store.

Syntax¶

CREATE ICEBERG CATALOG [IF NOT EXISTS] catalog_name WITH (option = value [, option = value] ...)

Arguments¶

Option	Description
`uri`	Required. The Iceberg REST catalog endpoint URL, such as `https://catalog.example.com/rest`.
`type`	Optional. The catalog type. Defaults to `rest`.
`warehouse`	Optional. The warehouse location, such as `s3://warehouse`.
`auth_mode`	Optional. The authentication mode. Alias `auth`. Defaults to `none`.
`token_secret_ref`	Optional. A reference to a stored token secret for authenticated catalogs. Alias `token_secret`.
`capabilities_json`	Optional. A JSON document describing catalog capabilities.

Examples¶

CREATE ICEBERG CATALOG dist_iceberg_cat WITH (
    'uri' = 'https://catalog.example.com/rest',
    'type' = 'rest',
    'warehouse' = 's3://warehouse',
    'auth_mode' = 'none'
);

CALL iceberg_register_access(
    'dist_iceberg_cat',
    'scope=cluster,account_id=0,external_principal=local,endpoint=catalog.example.com,region=*,bucket=*'
);