Enum ShapeNode 

pub enum ShapeNode {
    Scalar {
        name: String,
        position: usize,
    },
    RawScalar,
    JsonScalar,
    Object {
        name: String,
        type_name: Option<String>,
        position: usize,
        cardinality: Cardinality,
        pointers: Vec<ShapeNode>,
        has_implicit_id: bool,
    },
    Array {
        name: String,
        position: usize,
        element: Box<ShapeNode>,
    },
    Tuple {
        name: String,
        position: usize,
        elements: Vec<ShapeNode>,
        names: Option<Vec<String>>,
        type_name: Option<String>,
    },
    NamedTuple {
        name: String,
        position: usize,
        type_name: Option<String>,
        members: Option<Vec<JsonMember>>,
        is_free_object: bool,
    },
    Enum {
        name: String,
        position: usize,
        enum_type: String,
    },
    VectorSearch {
        object_position: usize,
        distance_position: usize,
        object_node: Box<ShapeNode>,
    },
    FtsSearch {
        object_position: usize,
        rank_position: usize,
        object_node: Box<ShapeNode>,
    },
    Group {
        key_nodes: Vec<ShapeNode>,
        grouping_position: usize,
        elements_position: usize,
        element: Box<ShapeNode>,
    },
}

Internal tree describing one position in the query output shape. Opaque to Python — only the Rust deserializer inspects it.

Variants

Scalar

Leaf value; native PG type.

Fields

name: String

position: usize

RawScalar

The result column IS the value — not wrapped in ROW(). Used for array literals where an array is returned as its own top-level column.

JsonScalar

Like RawScalar but the value is a decoded JSON object (from a cast). REPL displays it as Json("...").

Object

Object shape. type_name = Some(s) → named schema type decoded to a registered dataclass. type_name = None → free type decoded to Pylon’s generic Object dataclass. name is the pointer name within the parent (empty string for the root).

Fields

name: String

type_name: Option<String>

position: usize

cardinality: Cardinality

pointers: Vec<ShapeNode>

has_implicit_id: bool

True when pointers[0] is an id the compiler added to a shape that did not select one — see IrScalarPointer::implicit_id. Every decoder hands it to the caller like any other property; only JSON output drops it.

Array

record[] column decoded to a Python list.

Fields

name: String

position: usize

element: Box<ShapeNode>

Tuple

A tuple read as the composite row it is: each element at its own position, carrying its own PostgreSQL type, rather than out of a jsonb value where every number is one type (see NamedTuple).

position follows the same convention as every other node — the index of this value inside the row that holds it — except at the root, where the row is the tuple and there is nothing to index out of. Decoders dispatch those two cases separately (decode_row / decode_at_root against decode in the hydrators).

names is None for a positional tuple, which hydrates to a plain tuple; Some for a named one, which hydrates to a NamedTupleValue — or, when type_name names a registered @pylon.named_tuple class, to that class.

Fields

name: String

The pointer name within the parent object, empty at the root — the same convention Scalar/Object/Array follow, and what lets a tuple-typed property name itself in a shape.

position: usize

elements: Vec<ShapeNode>

names: Option<Vec<String>>

type_name: Option<String>

NamedTuple

Named tuple decoded from jsonb. When type_name is Some, hydrated to the registered class. members carries the full per-member decode plan when statically known (a registered NamedTupleDescriptor’s members, a structural pylon.Tuple[...] property’s tuple_members, or a <tuple<...>>/nominal cast’s own target type) — None falls back to decoding the raw jsonb value generically (dict/list, no per-member typing).

Fields

name: String

position: usize

type_name: Option<String>

members: Option<Vec<JsonMember>>

is_free_object: bool

True when this value came from { x := 1.0 } (curly-brace free- object syntax) rather than (x := 1.0) (paren tuple syntax) — decoded identically either way (both are jsonb), but the frontend’s own value-shape-tag tree (pylon/query.py’s shape_value_tags) uses this to tell the Python API layer to describe it as an “object” rather than a “namedTuple”, so JsonTree renders an expandable Object {x: 1.0} instead of a non-expandable (x := 1.0) tuple literal.

Enum

Enum value arrived as text; hydrated to the Python enum class keyed by enum_type.

Fields

name: String

position: usize

enum_type: String

Pylon-qualified name, e.g. default::Gender.

VectorSearch

Result of a vector::search statement. The outer result tuple has three slots: 0 → NULL (virtual type, no registry lookup) object_position → the object sub-tuple (decoded as a Pylon object) distance_position → the distance scalar (float64)

Fields

object_position: usize

distance_position: usize

object_node: Box<ShapeNode>

FtsSearch

Result of a fts::search statement. Outer tuple layout mirrors VectorSearch: pos 0 = NULL, pos 1 = object, pos 2 = score.

Fields

object_position: usize

rank_position: usize

object_node: Box<ShapeNode>

Group

Result of a group statement: each row is a free object with key/grouping/elements.

Fields

key_nodes: Vec<ShapeNode>

One ShapeNode per grouping key (carries name, position, and type). Positions are 1-based in the outer tuple (pos 0 is the NULL type slot).

grouping_position: usize

Position of the ARRAY[key_names...]::text[] in the outer tuple.

elements_position: usize

Position of the array_agg(elements) in the outer tuple.

element: Box<ShapeNode>

Shape node for each element in the elements array.

Trait Implementations

impl Clone for ShapeNode

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ShapeNode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.