magmalake avro

avro · API

avro.resolve

Schema resolution — reading data written with one schema as another.

resolve(writer, reader) walks the two schemas once and builds a plan: a flat list of ResolveNodes that says, for every position in the writer's data, what to decode and where it lands in the reader's shape. Decoding then follows the plan, so the per-record cost has no name lookups in it.

Supported (the common cases from the Avro spec's "Schema Resolution"):

  • field reordering, and writer fields the reader dropped (skipped in place);
  • reader fields the writer never wrote, filled from the field's default;
  • numeric promotions int → long → float → double;
  • string ↔ bytes;
  • union member selection in both directions, plus a non-union writer read into a reader union;
  • enum symbols missing from the reader, falling back to the reader enum's own default;
  • records/enums/fixed matched by unqualified name, and by the reader's aliases.

Structs

ResolveNode

struct ResolveNode

Implements Copyable, Movable

Fields
action: Int
w: Int: Writer schema node index.
r: Int: Reader schema node index (-1 for a skip).
kids: List[Int]: Child plan indices: array items, map values, union branches.
field_plan: List[Int]: Per writer field: the child plan index, or -1 to skip the field.
field_slot: List[Int]: Per writer field: the reader field position, or -1 to skip.
default_slots: List[Int]: Reader field positions filled from the field's default.
default_values: List[Value]
enum_map: List[Int]: Per writer symbol: the reader symbol index, or -1 for the fallback.
enum_fallback: Int
branch: Int: Chosen reader union branch for RA_UNION_READER.
message: String: Why RA_ERROR was planted.

of

def of(action: Int, w: Int, r: Int) -> Self

ResolvedReader

struct ResolvedReader

A decoding plan produced by resolve.

Implements Copyable, Movable

Fields
writer: Schema
reader: Schema
plan: List[ResolveNode]
root: Int

__init__

def __init__(out self, var writer: Schema, var reader: Schema)

read_value

def read_value(self, mut d: Decoder) -> Value

Decode one datum written with writer, shaped as reader.

Functions

resolve

def resolve(writer: Schema, reader: Schema) -> ResolvedReader

Build a decoding plan that reads writer data as reader.

default_value

def default_value(schema: Schema, i: Int, default_json: StringSpan) -> Value

Decode a field's JSON default into a Value shaped by schema.

Aliases

comptime RA_DIRECT = Int(0)

Kinds match exactly — decode with the writer schema.

comptime RA_PROMOTE = Int(1)
comptime RA_RECORD = Int(2)
comptime RA_ENUM = Int(3)
comptime RA_ARRAY = Int(4)
comptime RA_MAP = Int(5)
comptime RA_UNION_WRITER = Int(6)
comptime RA_UNION_READER = Int(7)
comptime RA_SKIP = Int(8)
comptime RA_ERROR = Int(9)

A writer union branch the reader cannot accept — only fatal if it is actually the branch on the wire.