helix_ir.schema

helix_ir.schema — schema representation.

class helix_ir.schema.Schema(name: str, fields: tuple[tuple[str, ~helix_ir.types.core.HelixType], ...] = <factory>)

Bases: object

Immutable schema descriptor.

Fields are stored as a tuple of (name, HelixType) pairs to preserve order while remaining hashable.

name: str

fields: tuple[tuple[str, HelixType], ...]

field(name: str) → HelixType

Return the HelixType for a top-level field by name.

get_field(name: str) → HelixType | None

Return the HelixType for a top-level field, or None if not found.

field_names() → list[str]

Return a list of top-level field names.

path(path: str) → HelixType

Return the HelixType at the given dotted path.

Example: schema.path(“customer.address.city”)

walk() → Iterable[tuple[Path, HelixType]]

Yield (path, HelixType) for every leaf field in the schema.

walk_arrays() → Iterable[tuple[Path, HelixType]]

Yield (path, HelixType) for every array field in the schema.

to_arrow() → Schema

Convert this schema to a PyArrow Schema.

classmethod from_arrow(name: str, schema: Schema) → Schema

Create a Schema from a PyArrow Schema.

to_json() → dict[str, Any]

Serialize this schema to a JSON-compatible dict.

classmethod from_json(data: dict[str, Any]) → Schema

Deserialize a Schema from a JSON-compatible dict.

add_field(name: str, ftype: HelixType) → Schema

Return a new Schema with the given field added (or replaced).

drop_field(name: str) → Schema

Return a new Schema with the given field removed.

rename(new_name: str) → Schema

Return a new Schema with a different name.

class helix_ir.schema.Path(segments: tuple[PathSegment, ...])

Bases: object

Immutable dotted path into a nested schema.

Examples

Path.parse(“customer.address.city”) Path.parse(“items[].sku”)

segments: tuple[PathSegment, ...]

classmethod parse(path: str) → Path

Parse a dotted path string into a Path.

Supports:

“customer.address.city” “items[].sku” “items[].tags[]”

append(name: str) → Path

Return a new Path with a field segment appended.

array_element() → Path

Return a new Path with an array_element segment appended.

is_descendant_of(other: Path) → bool

Return True if self is a descendant (longer) path of other.

is_root() → bool

Return True if this is the root (empty) path.

parent() → Path

Return the parent path (remove last segment).

depth() → int

Return the number of segments in this path.

classmethod root() → Path

Return the root (empty) path.

ROOT = Path(segments=())

class helix_ir.schema.PathSegment(kind: str, name: str | None = None)

Bases: object

A single segment of a schema path.

kind=’field’ with name=’foo’ represents a struct field named ‘foo’. kind=’array_element’ represents descending into an array’s element type.

kind: str

name: str | None = None

helix_ir.schema.helix_type_to_json(ht: HelixType) → dict[str, Any]

Serialize a HelixType to a JSON-compatible dict.

helix_ir.schema.helix_type_from_json(data: dict[str, Any]) → HelixType

Deserialize a HelixType from a JSON-compatible dict.