`iceberg.transforms`

Partition transforms and partition specs.

Every transform in the spec's transform table is here: identity, bucket[N], truncate[W], year, month, day, hour and void. A transform spelling this build does not recognise becomes T_UNKNOWN, which keeps its original text, produces an unknown result type and reports can_project() == False — the spec requires readers to ignore such a partition field when filtering rather than fail, and requires that behaviour outright in v3.

day is the only time transform whose result is a date; year, month and hour produce plain int counts from the epoch. Nanosecond timestamps are truncated to microseconds before hashing (Appendix B note 3) so that a value buckets the same however its column is typed.

Structs

`Transform`

struct Transform

A partition transform: a kind plus the [N]/[W] parameter.

Implements Copyable, Movable, Writable

Fields: kind: UInt8; param: Int; raw: String: Original spelling — the only thing kept for T_UNKNOWN.

`identity`

def identity() -> Self

`bucket`

def bucket(n: Int) -> Self

`truncate`

def truncate(w: Int) -> Self

`void`

def void() -> Self

`name`

def name(self) -> String

`write_to`

def write_to(self, mut writer: T)

`can_project`

def can_project(self) -> Bool

False when a predicate cannot be pushed through this transform.

`is_time`

def is_time(self) -> Bool

`preserves_order`

def preserves_order(self) -> Bool

True when a <= b implies T(a) <= T(b) — the projection rules for </> only hold for these.

`result_type`

def result_type(self, mut store: TypeStore, source: Int) -> Int

The type a partition value of this transform has.

`apply`

def apply(self, v: Datum) -> Datum

Transform one value. All transforms map null to null.

`PartitionField`

struct PartitionField

One field of a partition spec.

Implements Copyable, Movable, Writable

Fields: source_id: Int; source_ids: List[Int]: V3 multi-argument transforms. Single-source specs mirror source_id.; field_id: Int; name: String; transform: Transform

`single`

def single(source_id: Int, field_id: Int, var name: String, var t: Transform) -> Self

`write_to`

def write_to(self, mut writer: T)

`PartitionSpec`

struct PartitionSpec

A partition spec: an id and an ordered list of partition fields.

Implements Copyable, Movable

Fields: spec_id: Int; fields: List[PartitionField]

`init`

def __init__(out self, spec_id: Int, var fields: List[PartitionField])

`unpartitioned`

def unpartitioned(spec_id: Int = Int(0)) -> Self

`is_unpartitioned`

def is_unpartitioned(self) -> Bool

`field_index`

def field_index(self, field_id: Int) -> Int

`fields_for_source`

def fields_for_source(self, source_id: Int) -> List[Int]

Positions of every partition field derived from source_id.

`partition_type`

def partition_type(self, schema: Schema) -> Schema

The struct type of a partition tuple under this spec.

Field ids are the partition field ids (1000+), matching how manifest files type their partition column. Every field is optional: a transform may legitimately produce null.

`from_json`

def from_json(doc: Json, i: Int, default_spec_id: Int = Int(0)) -> Self

`from_fields_json`

def from_fields_json(doc: Json, i: Int, spec_id: Int) -> Self

V1's bare partition-spec array (no wrapping object).

`to_json`

def to_json(self) -> String

`SortField`

struct SortField

Implements Copyable, Movable

Fields: source_id: Int; source_ids: List[Int]; transform: Transform; direction: UInt8; null_order: UInt8

`SortOrder`

struct SortOrder

Implements Copyable, Movable

Fields: order_id: Int; fields: List[SortField]

`init`

def __init__(out self, order_id: Int, var fields: List[SortField])

`from_json`

def from_json(doc: Json, i: Int) -> Self

`to_json`

def to_json(self) -> String

Functions

`iceberg_hash`

def iceberg_hash(v: Datum) -> Int32

Appendix B's 32-bit hash of a typed value.

`bucket_of`

def bucket_of(v: Datum, n: Int) -> Int

`truncate_of`

def truncate_of(v: Datum, w: Int) -> Datum

`truncate_codepoints`

def truncate_codepoints(s: String, w: Int) -> String

First w Unicode code points — the spec truncates strings by code point, never mid-character.

`time_of`

def time_of(v: Datum, kind: UInt8) -> Datum

`parse_transform`

def parse_transform(s: String) -> Transform

Aliases

comptime T_IDENTITY = UInt8(0)

comptime T_BUCKET = UInt8(1)

comptime T_TRUNCATE = UInt8(2)

comptime T_YEAR = UInt8(3)

comptime T_MONTH = UInt8(4)

comptime T_DAY = UInt8(5)

comptime T_HOUR = UInt8(6)

comptime T_VOID = UInt8(7)

comptime T_UNKNOWN = UInt8(255)

comptime PARTITION_DATA_ID_START = Int(1000)

V1 assigned partition field ids sequentially from 1000 with no record.

comptime SORT_ASC = UInt8(0)

comptime SORT_DESC = UInt8(1)

comptime NULLS_FIRST = UInt8(0)

comptime NULLS_LAST = UInt8(1)