helix_ir.types

helix_ir.types — type system for Helix IR.

class helix_ir.types.HelixType(arrow_type: DataType, null_ratio: float = 0.0, cardinality_estimate: int | None = None, sample_count: int = 0, confidence: float = 1.0, semantic: str | None = None, pii_class: str | None = None, source_path: str | None = None, min_value: Any = None, max_value: Any = None, description: str | None = None, tags: frozenset[str] = <factory>)

Bases: object

Immutable type descriptor for a single field in a Helix schema.

Carries both the Arrow physical type and rich metadata such as null ratio, cardinality estimate, semantic tag, and PII class.

arrow_type: DataType

null_ratio: float = 0.0

cardinality_estimate: int | None = None

sample_count: int = 0

confidence: float = 1.0

semantic: str | None = None

pii_class: str | None = None

source_path: str | None = None

min_value: Any = None

max_value: Any = None

description: str | None = None

tags: frozenset[str]

evolve(**changes: Any) → HelixType

Return a new HelixType with the given fields changed.

is_nullable() → bool

Return True if this field ever observed nulls.

is_list() → bool

Return True if the Arrow type is a list type.

is_struct() → bool

Return True if the Arrow type is a struct type.

is_null() → bool

Return True if the Arrow type is null (all-null column).

helix_ir.types.join(a: HelixType, b: HelixType) → HelixType

Least upper bound. The narrowest type that subsumes both a and b.

helix_ir.types.meet(a: HelixType, b: HelixType) → HelixType

Greatest lower bound — the widest type that fits within both a and b.

helix_ir.types.subsumes(a: HelixType, b: HelixType) → bool

Return True if any value of type b can be stored in a column of type a.

In lattice terms: a subsumes b iff join(a, b) == a.

helix_ir.types.helix_type_to_arrow(ht: HelixType) → DataType

Return the Arrow DataType for this HelixType.

helix_ir.types.arrow_to_helix_type(arrow_type: DataType) → HelixType

Wrap an Arrow DataType in a HelixType with default metadata.