Shapes of a result

5 / 11 · trees, shared values, graphs in the full document · PDF

The field types of a view decide what a load returns. Plain fields make a tree of owned values, which can be cloned, compared and saved like any struct. Arc<T> shares one decoded value between everything that references the same row. Ref<T> makes the view a graph, held in an arena with each entity once, so cyclic data needs no depth limit. Recursive collections load a fixed number of levels, or every level in one recursive query.

Four panels. A tree: task 1 and task 2 each own a copy of the person Ada. Shared values: task 1 and task 2 both point to one Arc of Ada, decoded once per load. A graph: Graph of T holds each entity once; Ada and Grace reference each other as manager and report, a cycle that ends by itself, with typed references and generated navigation. Recursion: depth = 2 runs one query per level, children and children.children; recursive = cte loads every level with one WITH RECURSIVE query whose path guard stops at cycles. Rows below give, for each, the field types, the terminals, and whether saving is supported.

Trees and shared values. By default a reference or element is an owned value: two tasks with the same assignee hold two equal copies. An Arc<T> reference or element is decoded once per entity of a load and shared by everything that references it MPA-LOAD-13, which saves memory and decoding where the same rows recur. Collections are Vec, BTreeMap or HashMap of a view, of Arc or of Ref MPA-VIEW-10; a list placed by an index column fails on a NULL or repeated index MPA-VIEW-9.

Graphs. A view with Ref<T> fields is a graph and must be loaded with graph, else Error::GraphRequired. It returns a Graph<T> holding each entity once, with typed references and generated navigation methods such as task.manager(&graph); cycles end by themselves MPA-LOAD-14. A graph can be served as JSON only through a selection, whose finite depth unrolls it into a tree MPA-JSON-5. A graph is saved with save_graph: every entity, each after the entities it references, with the optional references of a cycle set afterwards MPA-WRITE-14 MPA-WRITE-15.

Recursion. A collection with depth = n runs its query again for each level, at most n levels; with recursive = "cte" every level comes from one WITH RECURSIVE query whose path guard stops at cycles, for a collection that contains its own view directly MPA-PLAN-4. A cycle in the data of a cte collection fails with Error::Cycle MPA-LOAD-12. A recursive view without either is a planning error: the depth of a tree must be known.