DuckLake specifies multiple different data types for field values, and also supports nested types. The types of columns are defined in the column_type field of the ducklake_column table.

Primitive Types

Nested Types

DuckLake supports nested types and primitive types. Nested types are defined recursively using the parent_column field in the ducklake_column table. For example, a column of type INT[] is stored as two rows: a parent column of type list, and a child column of type int32 whose parent_column points to the parent.

The following nested types are supported:

Semi-Structured Types

The variant type is similar to JSON but is more strongly typed internally, supports a wider range of types (e.g., date, timestamp, decimal), and is stored in a binary-encoded format rather than as a string. Variants are stored in Parquet files according to the Parquet variant encoding specification.

Variants can be shredded into their constituent primitive types when all rows share a consistent schema for a given sub-field. Shredded fields are stored and queried with the same efficiency as native primitive columns. Per-file statistics for shredded sub-fields are recorded in the ducklake_file_variant_stats table.

Note The variant type is natively supported in DuckDB. For catalog databases that do not have a native variant type (e.g., PostgreSQL, SQLite), variants cannot yet be stored as inline values in those catalogs.

Geometry Types

DuckLake supports geometry types using the geometry type of the Parquet format. The geometry type can store different types of spatial representations called geometry primitives, of which DuckLake supports the following:

Type Encoding for Statistics

Statistics values are string-encoded, as they must be stored as VARCHAR, since thatallows storing types that are not native to the catalog database system (e.g., PostgreSQL does not support VARIANT natively). Statistics are stored in both ducklake_file_column_stats and ducklake_table_column_stats. Most types follow a straightforward encoding, however some do not. The following table describes the encoding of each type:

The following types do not currently have min/max statistics, as they are not supported by the underlying Parquet format:

1. int128
2. uint128
3. timetz
4. interval

Nested Types

Nested types (list, struct, map) do not have min/max statistics themselves, statistics are collected recursively for their child columns instead. For example:

Given the following table:

CREATE TABLE nested_types (
    col_list INT[],
    col_struct STRUCT(a INT, b VARCHAR),
    col_map MAP(VARCHAR, INT)
);
INSERT INTO nested_types VALUES
    ([1, 2, 3], {'a': 10, 'b': 'hello'}, MAP {'x': 1}),
    ([4, 5, 6], {'a': 20, 'b': 'world'}, MAP {'y': 2});

The parent columns (col_list, col_struct, col_map) have no min/max statistics. Instead, the child columns store:

Extra Statistics

The geometry and variant types do not use string-encoded min/max values. Instead, their statistics are stored as JSON in the extra_stats column of the statistics tables.

Geometry

Geometry statistics contain a bounding box (bbox) and a list of geometry primitive types present in the column (types). For example:

{
    "bbox": {
        "xmin": 0.000000,
        "xmax": 5.000000,
        "ymin": 0.000000,
        "ymax": 5.000000,
        "zmin": null,
        "zmax": null,
        "mmin": null,
        "mmax": null
    },
    "types": ["point"]
}

Variant

Variant statistics contain a JSON array with one entry per shredded sub-field. Each entry records the field path, its shredded type, and min/max statistics for that sub-field. If the variant cannot be shredded (i.e., has inconsistent types across rows), extra_stats is NULL. An example of a Variant extra_stats:

[
    {
        "field_name": "root",
        "shredded_type": "int32",
        "null_count": 0,
        "min": "42",
        "max": "99",
        "num_values": 3,
        "column_size_bytes": 37,
        "any_valid": true
    }
]

Type Encoding for Data Inlining

When storing columns for data inlining, a table is created in the catalog to store small inserts and updates in the database. Since DuckDB supports all DuckDB types, inlining types in a DuckDB catalog is straightforward. However, other catalogs might require encodings for non-native types.

PostgreSQL

PostgreSQL does not natively support all DuckDB types. The following table describes how each DuckDB type is mapped to a PostgreSQL type for inlined data storage. Types not listed below (e.g., BOOLEAN, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE, DECIMAL, TIME, TIMETZ, INTERVAL, UUID) are stored using their native PostgreSQL equivalents.

SQLite

SQLite has a flexible type system with only five storage classes: INTEGER, REAL, TEXT, BLOB, and NULL. DuckDB's SQLite scanner maps all integer types to BIGINT (i.e., SQLite's INTEGER type) and most other types to VARCHAR (SQLite's TEXT type). Only BLOB is stored as BLOB. The following table describes the non-trivial type mappings: