Table properties
A table’s contract and maintenance policy live in Iceberg table properties under the timelake. prefix. Other engines ignore them. Set them at creation with --prop key=value (CLI) or properties={…} (Python); the contract flags (--time-column, --series-key, --chunk, --retention, --no-dedup) set the first five.
| Property | Default | Meaning |
|---|---|---|
timelake.time-column | (none) | The time column. Its presence makes the table a time-series table. |
timelake.series-key | (none) | Comma-separated series key columns. |
timelake.chunk-interval | day | Partition size: hour, day or month. |
timelake.dedup | true with a series key, else false | Drop duplicate (series, time) rows during compaction; the latest write wins. |
timelake.retention | forever | Drop partitions that end before now minus this duration, e.g. 90d. |
timelake.auto-maintain | true | Run size-tiered compaction and snapshot expiry inline after appends. |
timelake.compact-min-files | 8 | Inline compaction merges a size tier of a partition once it has this many files. |
timelake.target-file-size-bytes | 268435456 (256 MiB) | Size at which compaction output and writes roll to a new file. |
timelake.row-group-rows | 1048576 | Parquet row group size. Page indexes keep single-series reads selective inside large row groups. |
timelake.snapshot-retention | 1h | Expire snapshots older than this… |
timelake.min-snapshots | 5 | …but always keep at least this many, |
timelake.max-snapshots | 100 | and never keep more than this many (older ones expire even if younger than the retention). |
Durations are a number and a unit: s, m, h, d, w or y.
Iceberg properties set at creation
write.format.default = parquetandwrite.parquet.compression-codec = zstdwrite.metadata.previous-versions-max = 20: keepsmetadata.json, which every query reads, small. Older metadata files are deleted by snapshot expiry.
Schema
Arrow types are mapped to the closest lossless Iceberg type when a table is created:
- 8- and 16-bit integers become
int;UInt32becomeslong;UInt64is rejected. - Timestamps of any unit are stored in microseconds; time-zone-aware timestamps become
timestamptz(UTC). - Dictionary-encoded columns use their value type; large and view string and binary types become string and binary.
- The time column is NOT NULL, and a text time column is stored as a UTC timestamp.
Schema evolution isn’t supported yet: the schema is fixed when the table is created.