This table contains column-level statistics for an entire table.

Snapshot Validity

These statistics are mutable and describe the latest committed snapshot. A commit that removes data files may recompute the statistics from the surviving data. In particular, the resulting bounds need not contain values visible in older snapshots.

A reader may use these statistics to prune a snapshot only when they were read from a consistent metadata view in which that snapshot was the latest, or when it has retained cached statistics known to be valid for that snapshot. Otherwise, the reader must use statistics valid for the files in its snapshot or scan without table-level statistics.

A commit that narrows these statistics must advance next_file_id in the ducklake_snapshot table, even if it creates no data or deletion files. This prevents readers that cache table statistics by next_file_id from reusing narrower bounds for an older snapshot.

Columns

• table_id refers to a table_id from the ducklake_table table.
• column_id refers to a column_id from the ducklake_column table.
• contains_null is a flag whether the column contains any NULL values.
• contains_nan is a flag whether the column contains any NaN values. This is only relevant for floating-point types.
• min_value contains the minimum value for the column, encoded as a string. This does not have to be exact but has to be a lower bound. The value has to be decoded as the actual type for accurate comparison, e.g., on integer types.
• max_value contains the maximum value for the column, encoded as a string. This does not have to be exact but has to be an upper bound. The value has to be decoded as the actual type for accurate comparison, e.g., on integer types.
• extra_stats contains additional type-specific statistics, such as bounding box information for geometry types or global shredded-field statistics for variant columns encoded as JSON. Variant global stats are populated only for sub-fields that are consistently shredded across every data file; if any file contains inconsistent data for a field, global stats for that field are omitted.
• min_is_exact indicates whether min_value is exact rather than a conservative lower bound. NULL means that exactness is unknown.
• max_is_exact indicates whether max_value is exact rather than a conservative upper bound. NULL means that exactness is unknown.

Exactness flags describe the stored bounds, which can still include values deleted from the table.