feat: recurse!up ancestor walk; fix via order-by __depth

Author: sted

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 0.7.2 - 2026-06-30
+
+### Added
+* `recurse!up` operator for single-table recursion — walks the FK toward ancestors instead of descendants (e.g. `parent_id=recurse!up.all` returns a node's ancestor chain). Rejected with `via()`, where the same reversal is done by swapping the edge columns.
+
+### Fixed
+* Ordering a `via()` recursive query by `__depth` without selecting it no longer 500s with "ORDER BY expressions must appear in select list"; `__depth` is now surfaced in the projection and routed through the min-depth dedup wrapper.
+
 ## 0.7.1 - 2026-06-18
 
 ### Fixed

database/querybuilder.go

@@ -1094,6 +1094,22 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 			break
 		}
 	}
+	// via's min-depth dedup emits SELECT DISTINCT, whose ORDER BY columns must all appear in
+	// the select list. If the caller orders by __depth without selecting it we surface __depth
+	// in the projection (below) and route through the dedup wrapper — otherwise Postgres 500s
+	// with "ORDER BY expressions must appear in select list". Single-table mode uses a plain
+	// SELECT and can already order by an unselected __depth, so it needs no such handling.
+	depthOrdered := false
+	for _, of := range parts.orderFields {
+		if of.field.name == "__depth" {
+			depthOrdered = true
+			break
+		}
+	}
+	exposeDepth := rec.ViaTable != "" && depthOrdered && !depthSelected
+	if exposeDepth {
+		depthSelected = true
+	}
 	maxDepth := rec.MaxDepth
 	serverMax := defaultMaxRecursiveDepth
 	if dbe != nil && dbe.config.MaxRecursiveDepth > 0 {
@@ -1150,10 +1166,19 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 
 		q.WriteString(" UNION ALL ")
 
-		// Recursive step
+		// Recursive step. Default (down): join new.recurseField = prev.startField - follow the
+		// FK backwards to descendants (rows whose FK points at a known node). recurse!up reverses
+		// the same two fields to new.startField = prev.recurseField — follow the FK forwards to
+		// ancestors (the row the known node's FK points at). Base case and the __path cycle guard
+		// (keyed on startField) are identical for both directions.
 		q.WriteString("SELECT " + qtable + ".*" + rowCol + ", " + cteName + ".__depth + 1, " + cteName + ".__path || " + qtable + "." + startField)
 		q.WriteString(" FROM " + qtable)
-		q.WriteString(" INNER JOIN " + cteName + " ON " + qtable + "." + recurseField + " = " + cteName + "." + startField)
+		// down: new.recurseField = prev.startField; up swaps the two fields.
+		newField, prevField := recurseField, startField
+		if rec.RecurseUp {
+			newField, prevField = startField, recurseField
+		}
+		q.WriteString(" INNER JOIN " + cteName + " ON " + qtable + "." + newField + " = " + cteName + "." + prevField)
 		nmarker++
 		q.WriteString(" WHERE " + cteName + ".__depth < $" + strconv.Itoa(nmarker))
 		valueList = append(valueList, maxDepth)
@@ -1236,6 +1261,17 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 	} else {
 		sel = strings.ReplaceAll(selectClause, tablePrefix, ctePrefix)
 	}
+	// Surface __depth for an order-by that didn't select it (see exposeDepth above). The
+	// cteName.* form already carries __depth, so only the enumerated/explicit lists need it.
+	// NOTE: this deliberately leaks __depth into the result projection — a `via(...)` walk
+	// ordered by an unselected __depth (or `select=*`, whose enumeration otherwise excludes
+	// __depth) returns it as an extra column. Single-table mode uses a plain SELECT that can
+	// order by an unselected column without surfacing it, so the two modes are asymmetric
+	// here. The leak is the price of routing via through the min-depth dedup wrapper, which
+	// requires every ORDER BY column to be in the DISTINCT select list.
+	if exposeDepth && sel != cteName+".*" {
+		sel += ", " + ctePrefix + quote("__depth")
+	}
 
 	// Embed joins (LEFT JOIN LATERAL) correlate to the base-table alias; rewrite
 	// the top-level "table". -> "__recursive". correlation. The lateral's own numbered

database/requestparser.go

@@ -81,6 +81,7 @@ type RecursiveInfo struct {
 	RecurseField string // FK column to follow (e.g. "manager_id")
 	MaxDepth     int    // max depth; -1 = unlimited (capped by server max)
 	ExcludeStart bool   // true when "after" operator is used instead of "start"
+	RecurseUp    bool   // true for recurse!up — follow the FK toward ancestors (single-table only)
 	ViaTable         string              // edge table for multi-table recursion (empty = single-table)
 	ViaFromCol       string              // edge table column matching the start value (e.g. "src_id")
 	ViaToCol         string              // edge table column linking to main table's start field (e.g. "dst_id")
@@ -1146,15 +1147,18 @@ func (p PostgRestParser) parse(mainTable string, filters Filters) (parts *QueryP
 		for _, v := range vv {
 			prefix, rest, ok := strings.Cut(v, ".")
 			if !ok {
-				if v == "recurse" {
-					// recurse without depth value — treat as "all"
+				if v == "recurse" || v == "recurse!up" {
+					// recurse without depth value — treat as "all". The "!up" hint reverses
+					// the walk to follow the FK toward ancestors (single-table only); mirrors
+					// the via!both grammar.
 					if recInfo == nil {
 						recInfo = &RecursiveInfo{MaxDepth: -1}
 					}
 					if recInfo.RecurseField != "" {
 						return nil, &ParseError{"only one 'recurse' operator is allowed"}
 					}
 					recInfo.RecurseField = k
+					recInfo.RecurseUp = (v == "recurse!up")
 				} else if (strings.HasPrefix(v, "via(") || strings.HasPrefix(v, "via!")) && strings.HasSuffix(v, ")") {
 					// via(from_col,to_col) — directed (default)
 					// via!both(from_col,to_col) — undirected (follow edges either way).
@@ -1184,6 +1188,17 @@ func (p PostgRestParser) parse(mainTable string, filters Filters) (parts *QueryP
 				}
 				continue
 			}
+			// "!up" hint reverses the walk toward ancestors (single-table only). It is
+			// only meaningful on 'recurse'; reject it elsewhere so a typo like
+			// "start!up.5" fails loudly instead of silently parsing as "start.5".
+			recurseUp := false
+			if strings.HasSuffix(prefix, "!up") {
+				prefix = strings.TrimSuffix(prefix, "!up")
+				recurseUp = true
+				if prefix != "recurse" {
+					return nil, &ParseError{"'!up' is only valid on 'recurse'"}
+				}
+			}
 			switch prefix {
 			case "start", "after":
 				if recInfo == nil {
@@ -1203,6 +1218,7 @@ func (p PostgRestParser) parse(mainTable string, filters Filters) (parts *QueryP
 					return nil, &ParseError{"only one 'recurse' operator is allowed"}
 				}
 				recInfo.RecurseField = k
+				recInfo.RecurseUp = recurseUp
 				if rest == "all" {
 					recInfo.MaxDepth = -1
 				} else {
@@ -1225,6 +1241,9 @@ func (p PostgRestParser) parse(mainTable string, filters Filters) (parts *QueryP
 		if recInfo.ViaTable != "" && recInfo.StartField != recInfo.RecurseField {
 			return nil, &ParseError{"'via' requires 'start' and 'recurse' to use the same field"}
 		}
+		if recInfo.ViaTable != "" && recInfo.RecurseUp {
+			return nil, &ParseError{"'recurse!up' is single-table only; reverse a 'via' walk by swapping its columns"}
+		}
 		// Remove start/recurse/via from filters so they don't become WHERE clauses
 		delete(filters, recInfo.StartField)
 		if recInfo.StartField != recInfo.RecurseField {

test/recursive/recursive_test.go

@@ -376,3 +376,76 @@ func TestViaEmbedRejected(t *testing.T) {
 	}
 	test.Execute(t, testConfig(), tests)
 }
+
+// TestRecurseUp checks recurse!up — the single-table walk reversed to follow the FK
+// toward ANCESTORS. Junior Dev(5) -> Senior Dev(4) -> VP Eng(2) -> CEO(1).
+func TestRecurseUp(t *testing.T) {
+	tests := []test.Test{
+		{
+			Description: "recurse!up.all from a leaf — the full ancestor chain to the root",
+			Query:       "/tree_node?id=start.5&parent_id=recurse!up.all&select=id,name&order=__depth",
+			Expected:    `[{"id":5,"name":"Junior Dev"},{"id":4,"name":"Senior Dev"},{"id":2,"name":"VP Eng"},{"id":1,"name":"CEO"}]`,
+			Status:      200,
+		},
+		{
+			Description: "recurse!up depth cap — only two levels up",
+			Query:       "/tree_node?id=start.5&parent_id=recurse!up.2&select=id,name&order=__depth",
+			Expected:    `[{"id":5,"name":"Junior Dev"},{"id":4,"name":"Senior Dev"},{"id":2,"name":"VP Eng"}]`,
+			Status:      200,
+		},
+		{
+			Description: "recurse!up from the root — just the root itself",
+			Query:       "/tree_node?id=start.1&parent_id=recurse!up.all&select=id,name",
+			Expected:    `[{"id":1,"name":"CEO"}]`,
+			Status:      200,
+		},
+		{
+			Description: "recurse!up with after — excludes the seed, returns its ancestors",
+			Query:       "/tree_node?id=after.5&parent_id=recurse!up.all&select=id,name&order=__depth",
+			Expected:    `[{"id":4,"name":"Senior Dev"},{"id":2,"name":"VP Eng"},{"id":1,"name":"CEO"}]`,
+			Status:      200,
+		},
+		{
+			// Result filter keeps only active ancestors; the walk still passes THROUGH the
+			// inactive 101 to reach 100. Mirrors the down-walk result-filter test.
+			Description: "recurse!up with is_active result filter keeps active ancestors past an inactive one",
+			Query:       "/tree_node?id=start.102&parent_id=recurse!up.all&is_active=is.true&select=id,name&order=__depth",
+			Expected:    `[{"id":102,"name":"Remote Worker"},{"id":100,"name":"Region"}]`,
+			Status:      200,
+		},
+		{
+			Description: "recurse!up __depth reports distance to each ancestor",
+			Query:       "/tree_node?id=start.5&parent_id=recurse!up.all&select=id,__depth&order=__depth",
+			Expected:    `[{"id":5,"__depth":0},{"id":4,"__depth":1},{"id":2,"__depth":2},{"id":1,"__depth":3}]`,
+			Status:      200,
+		},
+		{
+			Description: "'!up' on start is rejected (only valid on recurse)",
+			Query:       "/tree_node?id=start!up.5&parent_id=recurse.all&select=id",
+			Expected:    `{"code":"","details":null,"hint":"","message":"'!up' is only valid on 'recurse'","position":0,"subsystem":"network"}`,
+			Status:      400,
+		},
+		{
+			Description: "recurse!up is rejected with via (reverse a via walk by swapping its columns)",
+			Query:       "/doc?id=start.1&id=recurse!up.all&doc_rel=via(src_id,dst_id)&select=id",
+			Expected:    `{"code":"","details":null,"hint":"","message":"'recurse!up' is single-table only; reverse a 'via' walk by swapping its columns","position":0,"subsystem":"network"}`,
+			Status:      400,
+		},
+	}
+	test.Execute(t, testConfig(), tests)
+}
+
+// TestViaOrderByDepthUnselected checks that ordering a via() walk by __depth WITHOUT
+// selecting it works (surfacing __depth in the projection) instead of 500ing with
+// "ORDER BY expressions must appear in select list" from the min-depth SELECT DISTINCT.
+func TestViaOrderByDepthUnselected(t *testing.T) {
+	tests := []test.Test{
+		{
+			Description: "via order=__depth without selecting __depth — surfaces __depth, no 500",
+			Query:       "/doc?id=start.1&id=recurse.all&doc_rel=via(src_id,dst_id)&select=id&order=__depth,id",
+			Expected:    `[{"id":1,"__depth":0},{"id":2,"__depth":1},{"id":3,"__depth":1},{"id":4,"__depth":1},{"id":5,"__depth":2},{"id":6,"__depth":2}]`,
+			Status:      200,
+		},
+	}
+	test.Execute(t, testConfig(), tests)
+}