This documentation is for an unreleased version of Apache Paimon. We recommend you use the latest stable version.

Overview #

Paimon supports generating Iceberg compatible metadata, so that Paimon tables can be consumed directly by Iceberg readers.

Set the following table options, so that Paimon tables can generate Iceberg compatible metadata.

Option	Default	Type	Description
metadata.iceberg.storage	disabled	Enum	When set, produce Iceberg metadata after a snapshot is committed, so that Iceberg readers can read Paimon's raw data files. `disabled`: Disable Iceberg compatibility support. `table-location`: Store Iceberg metadata in each table's directory. `hadoop-catalog`: Store Iceberg metadata in a separate directory. This directory can be specified as the warehouse directory of an Iceberg Hadoop catalog. `hive-catalog`: Not only store Iceberg metadata like hadoop-catalog, but also create Iceberg external table in Hive.
metadata.iceberg.storage-location	(none)	Enum	Specifies where to store Iceberg metadata files. If not set, the storage location will default based on the selected metadata.iceberg.storage type. `table-location`: Store Iceberg metadata in each table's directory. Useful for standalone Iceberg tables or Iceberg Java API access. Can also be used with Hive Catalog. `catalog-location`: Store Iceberg metadata in a separate directory. This is the default behavior when using Hive Catalog or Hadoop Catalog.

For most SQL users, we recommend setting 'metadata.iceberg.storage' = 'hadoop-catalog' or ‘metadata.iceberg.storage’ = ‘hive-catalog’, so that all tables can be visited as an Iceberg warehouse. For Iceberg Java API users, you might consider setting ‘metadata.iceberg.storage’ = ‘table-location’, so you can visit each table with its table path. When using metadata.iceberg.storage = hadoop-catalogorhive-catalog, you can optionally configure metadata.iceberg.storage-location` to control where the metadata is stored. If not set, the default behavior depends on the storage type.

Supported Types #

Paimon Iceberg compatibility currently supports the following data types.

Paimon Data Type	Iceberg Data Type
`BOOLEAN`	`boolean`
`INT`	`int`
`BIGINT`	`long`
`FLOAT`	`float`
`DOUBLE`	`double`
`DECIMAL`	`decimal`
`CHAR`	`string`
`VARCHAR`	`string`
`BINARY`	`binary`
`VARBINARY`	`binary`
`DATE`	`date`
`TIMESTAMP` (precision 4-6)	`timestamp`
`TIMESTAMP_LTZ` (precision 4-6)	`timestamptz`
`TIMESTAMP` (precision 7-9)	`timestamp_ns`
`TIMESTAMP_LTZ` (precision 7-9)	`timestamptz_ns`
`ARRAY`	`list`
`MAP`	`map`
`ROW`	`struct`

Note on Timestamp Types:

TIMESTAMP and TIMESTAMP_LTZ types with precision from 4 to 6 are mapped to standard Iceberg timestamp types

TIMESTAMP and TIMESTAMP_LTZ types with precision from 7 to 9 use nanosecond precision and require Iceberg v3 format