Iceberg table data types¶

This topic provides information about how data types work for Iceberg tables in Snowflake.

Snowflake supports most of the data types defined by the Apache Iceberg specification, and writes Iceberg data types to table files so that your Iceberg tables remain interoperable across different compute engines when you use Snowflake as the catalog.

For an overview of the Iceberg data types that Snowflake supports, see Supported data types for Iceberg tables.

Approximate types¶

If your table uses an Iceberg data type that Snowflake doesn’t support an exact match for, Snowflake uses an approximate Snowflake type. This type mapping affects column values for converted tables and Iceberg tables that use Snowflake as the catalog.

For example, consider a table with a column of Iceberg type int. Snowflake processes the column values using the Snowflake data type NUMBER(10,0).

NUMBER(10,0) has a range of (-9,999,999,999, +9,999,999,999), but int has a more limited range of (-2,147,483,648, +2,147,483,647). If you try to insert a value of 3,000,000,000 into that column, Snowflake returns an out-of-range error message.

For details about approximate types, see the notes in the Supported data types for Iceberg tables table.

Supported data types for Iceberg tables¶

The tables in this section show the relationship between Iceberg data types and Snowflake data types. They use the following columns:

Iceberg type:: The data type defined in the Apache Iceberg specification. When you use Snowflake as the catalog, Snowflake writes the Iceberg type to your table data files so that your tables remain interoperable across different compute engines.
Snowflake type:: The Snowflake data type that is used to process and return table data. For example, if your schema specifies the Iceberg type timestamp, Snowflake processes and returns values using the Snowflake data type TIMESTAMP_NTZ(6) with microsecond precision.
Notes:: Additional usage notes, including notes for working with approximate types.

Numeric types¶

Snowflake as the catalog¶

The following table shows how Iceberg numeric data types map to Snowflake numeric data types for tables that use Snowflake as the Iceberg catalog (Snowflake-managed tables). When you create Snowflake-managed Iceberg table, you can use Iceberg data types to define numeric columns.

Iceberg data type	Snowflake data type	Notes
`int` (32-bit signed integer)	NUMBER(10,0)	Inserting a 10-digit number smaller than the minimum or larger than the maximum 32-bit signed integer value results in an out-of-range error.
`long` (64-bit signed integer)	NUMBER(19,0)	Inserting a 19-digit number smaller than the minimum or larger than the maximum 64-bit signed integer value results in an out-of-range error.
`float` (single-precision 32-bit IEEE 754 floating point)	FLOAT	Synonymous with the Snowflake DOUBLE data type. Snowflake treats all floating-point numbers as double-precision 64-bit floating-point numbers, but writes Iceberg floats as 32-bit floating-point numbers in table data files. Narrowing conversions from 64 bits to 32 bits results in precision loss. You can’t use `float` or `double` as primary keys (in accordance with the Apache Iceberg spec).
`double` (double-precision 64-bit IEEE 754 floating point)	FLOAT	Synonymous with the Snowflake DOUBLE data type. Snowflake treats all floating-point numbers as double-precision 64-bit floating-point numbers. Narrowing conversions from 64 bits to 32 bits results in precision loss. You can’t use `float` or `double` as primary keys (in accordance with the Apache Iceberg spec).
`decimal(P,S)`	NUMBER(P,S)	Specifying `decimal(10,0)` instead of `int` creates a decimal type in Iceberg. The same applies when you specify `decimal(19,0)`.

External catalog¶

When you create an Iceberg table that uses an external Iceberg catalog, Iceberg numeric types are mapped to Snowflake numeric types according to the following table.

Iceberg data type	Snowflake data type
`int` (32-bit signed integer)	NUMBER(10,0)
`long` (64-bit signed integer)	NUMBER(19,0)
`float` (single-precision 32-bit IEEE 754 floating point)	FLOAT
`double` (double-precision 64-bit IEEE 754 floating point)	FLOAT
`decimal(P,S)`	NUMBER(P,S)

Note

You can’t use float or double as primary keys (in accordance with the Apache Iceberg spec).

Other data types¶

Iceberg data type	Snowflake data type	Notes
`boolean`	BOOLEAN
`date`	DATE
`time`	TIME(6)	Microsecond precision per the Apache Iceberg table specification.
`timestamp`	TIMESTAMP_NTZ(6) or TIMESTAMP_LTZ(6), depending on the value of the Snowflake parameter TIMESTAMP_TYPE_MAPPING.	Microsecond precision per the Apache Iceberg table specification. You can also use the Parquet physical type `int96` for timestamps. Snowflake translates `timestamp` to microseconds (per the Apache Iceberg table specification).
`timestamptz`	TIMESTAMP_LTZ(6)	Microsecond precision per the Apache Iceberg table specification. You can also use the Parquet physical type `int96` for timestamps. Snowflake translates `timestamp` to microseconds (per the Apache Iceberg table specification).
`string`	VARCHAR(16777216)
`uuid`	BINARY(16)	The `uuid` data type isn’t supported for tables that use Snowflake as the catalog, or for converted tables. When you use an external catalog or create a table from files in object storage, Snowflake maps the `uuid` Iceberg type to the BINARY(16) Snowflake type.
`struct`	Structured OBJECT	Structured type columns support a maximum of 1000 sub-columns.
`list`	Structured ARRAY	Structured type columns support a maximum of 1000 sub-columns.
`map`	MAP	Structured type columns support a maximum of 1000 sub-columns.

Considerations¶

Consider the following items when you work with data types for Iceberg tables:

Converting a table with columns that use the following Iceberg data types is not supported:
- uuid
- fixed(L)
For tables that use Snowflake as the catalog, creating a table that uses the Iceberg uuid data type is not supported.
For all Iceberg table types:
- Structured type columns support a maximum of 1000 sub-columns.
- Iceberg supports microsecond precision for time and timestamp types. As a result, you can’t create an Iceberg table in Snowflake that uses another precision like millisecond or nanosecond.
- You can’t use float or double as primary keys (in accordance with the Apache Iceberg spec).