REST Catalog

Use rest-catalog to publish the Iceberg representation to an Iceberg REST catalog service. Paimon first writes Iceberg metadata to its configured filesystem location, then commits the corresponding metadata to the REST catalog.

Dependencies

The Paimon writer needs the paimon-iceberg JAR in addition to its engine connector. The REST module requires JDK 11 or later.

Download the matching paimon-iceberg snapshot JAR.

For Flink, install the JAR on the cluster and SQL client classpaths before starting them. For Spark, include it in --jars alongside the Paimon Spark JAR. Iceberg readers still need their own engine-compatible Iceberg runtime.

To build this module from the repository root with JDK 11 or later, activate its Maven profile:

mvn -Ppaimon-iceberg -pl paimon-iceberg -am -DskipTests package

The bundled JAR is written to paimon-iceberg/target/paimon-iceberg-2.2-SNAPSHOT.jar.

Configure the Service

Paimon passes table options prefixed with metadata.iceberg.rest. to the Iceberg REST client after removing the prefix. For example:

Paimon table option	REST client property
metadata.iceberg.rest.uri	uri
metadata.iceberg.rest.warehouse	warehouse
metadata.iceberg.rest.clients	clients

Set the endpoint and any warehouse or authentication properties required by your service. Configure the reader independently with the corresponding Iceberg catalog properties. Both sides must select the same REST warehouse and namespace.

Publish and Read an Append Table

This Flink example uses an append table so you can verify REST publication without first configuring primary key compaction. Replace the placeholders and add the authentication settings your service requires to both catalogs.

SET 'execution.runtime-mode' = 'batch';
SET 'table.dml-sync' = 'true';

CREATE CATALOG paimon_catalog WITH (
    'type' = 'paimon',
    'warehouse' = '<path-to-paimon-warehouse>'
);

CREATE DATABASE IF NOT EXISTS paimon_catalog.`default`;

CREATE TABLE paimon_catalog.`default`.cities_rest (
    country STRING,
    name STRING
) WITH (
    'metadata.iceberg.storage' = 'rest-catalog',
    'metadata.iceberg.rest.uri' = 'https://<rest-catalog-host>',
    'metadata.iceberg.rest.warehouse' = '<rest-warehouse>'
);

INSERT INTO paimon_catalog.`default`.cities_rest VALUES
    ('germany', 'berlin'), ('germany', 'hamburg');

CREATE CATALOG iceberg_rest WITH (
    'type' = 'iceberg',
    'catalog-type' = 'rest',
    'uri' = 'https://<rest-catalog-host>',
    'warehouse' = '<rest-warehouse>',
    'cache-enabled' = 'false'
);

SELECT country, name FROM iceberg_rest.`default`.cities_rest ORDER BY name;

country  name
germany  berlin
germany  hamburg

For primary key tables, also select a compaction or deletion-vector mode. The REST service does not remove those visibility requirements.

Publication and Recovery

The local metadata uses the separate catalog layout by default. REST publication uses Paimon's generated metadata as its source of truth:

REST table state	Publication behavior
Table is absent	Create or register the table, then publish its state
The same snapshot and commit identity are already published	Treat the retry as complete
Table exists without a snapshot after an incomplete creation	Complete publication without an unnecessary drop/create cycle
Current state matches the expected base	Commit the metadata update
Current state conflicts with the expected base	Rebuild or re-register the Iceberg representation from Paimon's metadata

Recovery can remove and recreate the REST catalog entry. Removal uses non-purging semantics: it does not delete the shared data files. Some v3 recovery paths must register a metadata file directly to preserve row IDs; Paimon checks the service's registration support before removing the existing entry.

Keep writes and table maintenance in Paimon. Independent changes through the Iceberg catalog can conflict with later publication and be replaced during recovery.

Schema and Feature Compatibility

Paimon field IDs start at zero, while Iceberg table creation assigns IDs starting at one. Paimon handles this difference during REST table creation and schema publication. If the first field is also a partition field, creation may require an intermediate unpartitioned schema and partition spec evolution. Do not manually renumber the fields in the Iceberg representation.

Tables containing GEOMETRY or GEOGRAPHY columns cannot use REST publication because the bundled REST client cannot parse those Iceberg v3 types. Use Hadoop, Hive, or table-location storage; see data types.

Paimon tag creation and deletion are not guaranteed to propagate to the REST catalog. See tags and publication limits.