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-catalog or hive-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 3-6)	timestamp
TIMESTAMP_LTZ (precision 3-6)	timestamptz
TIMESTAMP (precision 7-9)	timestamp_ns
TIMESTAMP_LTZ (precision 7-9)	timestamptz_ns
GEOMETRY(crs)	geometry(crs)
GEOGRAPHY(crs, algorithm)	geography(crs, algorithm)
ARRAY	list
MAP	map
ROW	struct

info

Note on Timestamp Types:

• TIMESTAMP and TIMESTAMP_LTZ types with precision from 3 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

Note on Geospatial Types:

• GEOMETRY and GEOGRAPHY values use OGC Well-Known Binary (WKB). The default CRS is OGC:CRS84, and the default geography edge algorithm is spherical.
• Geospatial columns require Parquet for data, per-level, and changelog files. When Iceberg metadata is enabled, set metadata.iceberg.format-version to 3.
• Spark SQL supports geospatial columns in Spark 4.1 when spark.sql.geospatial.enabled=true, for CRSs recognized by Spark, with the spherical geography edge algorithm. Spark 3.x, Spark 4.0, and Flink SQL reject these columns instead of exposing them as binary and losing the CRS or edge algorithm.
• When Iceberg metadata is enabled, a GEOGRAPHY CRS cannot contain a comma, including in nested columns, because Iceberg's geospatial type grammar uses commas to separate parameters.
• Iceberg REST catalog publication does not yet support geospatial columns. Use table-location, hadoop-catalog, or hive-catalog metadata storage instead.