feat: recursive query result/walk filters, __depth, via!both, embedding

BREAKING: plain filters on recursive queries now filter the result; the
prune-the-walk behavior is now opt-in via the walk. prefix.

Author: sted

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Change Log
 
+## 0.7.0 - 2026-06-15
+
+### Added
+* `__depth` selectable pseudo-column on recursive queries — reports each row's traversal depth (seed = 0); in `via` mode it reports the shallowest depth at which a node is reached
+* `walk.` filter prefix to prune the traversal — skips a non-matching node and everything beyond it
+* Bidirectional graph traversal with `via!both(src,dst)` — follows edges in either direction
+* Resource embedding now composes with single-table recursion (not supported together with `via()` traversal)
+
+### Changed
+* **Breaking:** plain filters on recursive queries now filter the *result* instead of pruning the traversal; the previous prune-the-walk behavior is now opt-in via the `walk.` prefix
+
+## 0.6.1 - 2026-06-12
+
+### Fixed
+* JSONB filter behavior now matches PostgREST (#19): JSON-path filters with quoted string values, containment against JSON string arrays, and whole-column JSONB equality/inequality
+
+### Improved
+* Improved release process (goreleaser config and `make release` target)
+* Updated Go and UI dependencies
+
 ## 0.6.0 - 2026-04-17
 
 ### Added

Makefile

@@ -18,6 +18,7 @@ test:
 	$(GO) test $(TEST_FLAGS) ./database
 	$(GO) test $(TEST_FLAGS) ./test/api
 	$(GO) test $(TEST_FLAGS) ./test/postgrest
+	$(GO) test $(TEST_FLAGS) ./test/recursive
 
 # This is used to recreate PostgREST fixtures
 prepare-postgrest-tests:

README.md

@@ -397,65 +397,37 @@ When disabled, attempts to use aggregate functions will return an error.
 ### Recursive Queries
 
 > [!NOTE]
-> This is a SmoothDB extension to PostgREST syntax. We plan to propose it upstream to PostgREST.
+> This is a SmoothDB extension to PostgREST syntax. We plan to propose it to PostgREST.
 
-SmoothDB supports recursive queries on self-referential tables and views using the `start` and `recurse` operators. These generate PostgreSQL recursive CTEs with automatic cycle detection.
-
-#### Basic Usage
-
-Given a table with a parent pointer (e.g. `employees.manager_id → employees.id`):
+SmoothDB walks self-referential tables (and separate edge tables) with the `start`/`recurse` operators, generating PostgreSQL recursive CTEs with automatic cycle detection.
 
 ```http
 GET /api/testdb/employees?id=start.1&manager_id=recurse.3 HTTP/1.1
 ```
 
-This returns the row with `id=1` and all descendants up to 3 levels deep, following `manager_id` back to `id`.
+Returns row `id=1` and its descendants up to 3 levels deep, following `manager_id → id`. Use `recurse.all` (or bare `recurse`) for unlimited depth (capped by `MaxRecursiveDepth`), and `after` instead of `start` to exclude the seed row.
 
-Use `recurse.all` (or bare `recurse`) for unlimited depth (capped by `MaxRecursiveDepth`):
+**Result vs. traversal filters.** A plain filter restricts the *result*: the whole subtree is walked, then non-matching rows are dropped. Prefix a filter with `walk.` to prune the *traversal* instead — a non-matching node, and everything beyond it, is skipped:
 
 ```http
-GET /api/testdb/employees?id=start.1&manager_id=recurse.all HTTP/1.1
+GET /api/testdb/employees?id=start.1&manager_id=recurse.all&is_active=is.true       HTTP/1.1   # keep only active rows
+GET /api/testdb/employees?id=start.1&manager_id=recurse.all&walk.is_active=is.true  HTTP/1.1   # stop walking at inactive nodes
 ```
 
-#### Excluding the Root
-
-Use `after` instead of `start` to exclude the seed row from results:
+Standard parameters (`select`, `order`, `limit`, …) apply to the result set. The pseudo-column `__depth` is selectable to get each row's traversal depth (seed = 0), and related resources can be embedded:
 
 ```http
-GET /api/testdb/employees?id=after.1&manager_id=recurse.all HTTP/1.1
+GET /api/testdb/employees?id=start.1&manager_id=recurse.all&select=id,name,__depth,tasks(title)&order=__depth HTTP/1.1
 ```
 
-#### Combining with Standard Parameters
-
-All standard query parameters work on the recursive result set:
-
-```http
-GET /api/testdb/employees?id=start.1&manager_id=recurse.all&is_active=is.true&select=id,name&order=name.asc&limit=10 HTTP/1.1
-```
-
-Filters are applied at every level of the recursion, pruning entire branches.
-
-#### Multi-Table Traversal with `via`
-
-For graph traversal through a separate edge/relationship table, use the `via` operator. Given a `documents` table and a `relationships` table with `src_id` and `dst_id` columns:
+**Edge tables (`via`).** Traverse a graph through a separate edge table with source/target columns. Add the `!both` hint to follow edges in either direction; filter which edges to follow with the standard `table.column` syntax (`eq`, `in`, `or`, …):
 
 ```http
 GET /api/testdb/documents?id=after.1&id=recurse.all&relationships=via(src_id,dst_id) HTTP/1.1
+GET /api/testdb/documents?id=after.1&id=recurse.all&relationships=via!both(src_id,dst_id)&relationships.rel_type=in.(contains,references) HTTP/1.1
 ```
 
-This traverses all documents reachable from document 1 through the `relationships` table, excluding the root.
-
-Filter which edges to follow using the standard PostgREST `table.column` prefix syntax:
-
-```http
-GET /api/testdb/documents?id=after.1&id=recurse.all&relationships=via(src_id,dst_id)&relationships.rel_type=eq.contains HTTP/1.1
-```
-
-Full PostgREST filter syntax is supported on the edge table, including `or` and `in`:
-
-```http
-GET /api/testdb/documents?id=after.1&id=recurse.all&relationships=via(src_id,dst_id)&relationships.rel_type=in.(contains,references) HTTP/1.1
-```
+Embedding is not supported together with `via` traversal.
 
 ## Example for using SmoothDB in your application
 

database/querybuilder.go

@@ -1046,7 +1046,7 @@ func buildAfterSelect(query, from, joins, whereClause, groupByClause, orderClaus
 const defaultMaxRecursiveDepth = 100
 
 func buildRecursiveSelect(table, schema string, parts *QueryParts, options *QueryOptions,
-	selectClause, mainWhere, orderClause string,
+	selectClause, mainWhere, orderClause, joins string,
 	valueList []any, info *SchemaInfo) (string, []any, error) {
 
 	rec := parts.recursive
@@ -1060,6 +1060,26 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 	if dbe != nil && dbe.config.MaxRecursiveDepth == 0 {
 		return "", nil, &ParseError{"recursive queries are disabled"}
 	}
+
+	// Embedding (LEFT JOIN LATERAL) composes with single-table recursion only.
+	// Via-mode embedding would fight the DISTINCT/min-depth dedup, so reject it cleanly.
+	if joins != "" && rec.ViaTable != "" {
+		return "", nil, &ParseError{"embedding is not supported with via() recursion"}
+	}
+
+	// Reject __path (internal cycle-tracking array) as a selected field; __depth is selectable.
+	for _, sf := range parts.selectFields {
+		if sf.field.name == "__path" {
+			return "", nil, &ParseError{"__path is internal"}
+		}
+	}
+	depthSelected := false
+	for _, sf := range parts.selectFields {
+		if sf.field.name == "__depth" {
+			depthSelected = true
+			break
+		}
+	}
 	maxDepth := rec.MaxDepth
 	serverMax := defaultMaxRecursiveDepth
 	if dbe != nil && dbe.config.MaxRecursiveDepth > 0 {
@@ -1085,6 +1105,16 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 		nmarker = len(valueList)
 	}
 
+	// Build the walk-prune WHERE (walk.* filters) against the main table.
+	// Marker order stays via -> walk -> start -> depth.
+	var walkWhere string
+	if rec.WalkConditions != nil {
+		var walkValues []any
+		walkWhere, walkValues = whereClause(table, schema, "", rec.WalkConditions, nmarker, BuildStack{info: info})
+		valueList = append(valueList, walkValues...)
+		nmarker = len(valueList)
+	}
+
 	var q strings.Builder
 
 	// --- CTE ---
@@ -1093,15 +1123,15 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 	if rec.ViaTable == "" {
 		// --- Single-table mode ---
 
-		// Base case — when ExcludeStart is true (after operator), skip mainWhere on the
-		// seed row so it remains a traversal anchor even if it doesn't match the filter.
+		// Base case — when ExcludeStart is true (after operator), skip walk filters on
+		// the seed row so it remains a traversal anchor even if it doesn't match them.
 		q.WriteString("SELECT " + qtable + ".*, 0 AS __depth, ARRAY[" + qtable + "." + startField + "] AS __path")
 		q.WriteString(" FROM " + qtable)
 		nmarker++
 		q.WriteString(" WHERE " + qtable + "." + startField + " = $" + strconv.Itoa(nmarker))
 		valueList = append(valueList, rec.StartValue)
-		if mainWhere != "" && !rec.ExcludeStart {
-			q.WriteString(" AND " + mainWhere)
+		if walkWhere != "" && !rec.ExcludeStart {
+			q.WriteString(" AND " + walkWhere)
 		}
 
 		q.WriteString(" UNION ALL ")
@@ -1114,8 +1144,8 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 		q.WriteString(" WHERE " + cteName + ".__depth < $" + strconv.Itoa(nmarker))
 		valueList = append(valueList, maxDepth)
 		q.WriteString(" AND NOT " + qtable + "." + startField + " = ANY(" + cteName + ".__path)")
-		if mainWhere != "" {
-			q.WriteString(" AND " + mainWhere)
+		if walkWhere != "" {
+			q.WriteString(" AND " + walkWhere)
 		}
 	} else {
 		// --- Multi-table (via) mode ---
@@ -1127,32 +1157,39 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 		viaTo := quote(rec.ViaToCol)
 
 		// Base case: the start node itself — when ExcludeStart is true (after operator),
-		// skip mainWhere so the seed remains a traversal anchor.
+		// skip walk filters so the seed remains a traversal anchor.
 		q.WriteString("SELECT " + qtable + ".*, 0 AS __depth, ARRAY[" + qtable + "." + startField + "] AS __path")
 		q.WriteString(" FROM " + qtable)
 		nmarker++
 		q.WriteString(" WHERE " + qtable + "." + startField + " = $" + strconv.Itoa(nmarker))
 		valueList = append(valueList, rec.StartValue)
-		if mainWhere != "" && !rec.ExcludeStart {
-			q.WriteString(" AND " + mainWhere)
+		if walkWhere != "" && !rec.ExcludeStart {
+			q.WriteString(" AND " + walkWhere)
 		}
 
 		q.WriteString(" UNION ALL ")
 
 		// Recursive step: follow edges from previously found docs
 		q.WriteString("SELECT " + qtable + ".*, " + cteName + ".__depth + 1, " + cteName + ".__path || " + qtable + "." + startField)
 		q.WriteString(" FROM " + qtable)
-		q.WriteString(" INNER JOIN " + qvia + " ON " + qvia + "." + viaTo + " = " + qtable + "." + startField)
-		q.WriteString(" INNER JOIN " + cteName + " ON " + qvia + "." + viaFrom + " = " + cteName + "." + startField)
+		if rec.ViaBidirectional {
+			// via!both: follow edges in either direction. The new node (qtable) sits on
+			// one end of the edge, the known node (cte) on the opposite end.
+			q.WriteString(" INNER JOIN " + qvia + " ON " + qvia + "." + viaTo + " = " + qtable + "." + startField + " OR " + qvia + "." + viaFrom + " = " + qtable + "." + startField)
+			q.WriteString(" INNER JOIN " + cteName + " ON (" + qvia + "." + viaFrom + " = " + cteName + "." + startField + " AND " + qvia + "." + viaTo + " = " + qtable + "." + startField + ") OR (" + qvia + "." + viaTo + " = " + cteName + "." + startField + " AND " + qvia + "." + viaFrom + " = " + qtable + "." + startField + ")")
+		} else {
+			q.WriteString(" INNER JOIN " + qvia + " ON " + qvia + "." + viaTo + " = " + qtable + "." + startField)
+			q.WriteString(" INNER JOIN " + cteName + " ON " + qvia + "." + viaFrom + " = " + cteName + "." + startField)
+		}
 		nmarker++
 		q.WriteString(" WHERE " + cteName + ".__depth < $" + strconv.Itoa(nmarker))
 		valueList = append(valueList, maxDepth)
 		q.WriteString(" AND NOT " + qtable + "." + startField + " = ANY(" + cteName + ".__path)")
 		if viaWhere != "" {
 			q.WriteString(" AND " + viaWhere)
 		}
-		if mainWhere != "" {
-			q.WriteString(" AND " + mainWhere)
+		if walkWhere != "" {
+			q.WriteString(" AND " + walkWhere)
 		}
 	}
 
@@ -1163,12 +1200,8 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 	tablePrefix := qtable + "."
 	ctePrefix := cteName + "."
 
-	// In via mode, use DISTINCT to deduplicate nodes reachable by multiple paths
-	selectKeyword := "SELECT "
-	if rec.ViaTable != "" {
-		selectKeyword = "SELECT DISTINCT "
-	}
-
+	// Build the SELECT list (without keyword); remember whether it was "*".
+	var sel string
 	if selectClause == "*" {
 		// Enumerate actual table columns to exclude internal __depth/__path
 		ftable := _s(table, schema)
@@ -1179,25 +1212,72 @@ func buildRecursiveSelect(table, schema string, parts *QueryParts, options *Quer
 					cols = append(cols, cteName+"."+quote(colName))
 				}
 				sort.Strings(cols)
-				q.WriteString(selectKeyword + strings.Join(cols, ", ") + " FROM " + cteName)
+				sel = strings.Join(cols, ", ")
 			} else {
-				q.WriteString(selectKeyword + cteName + ".* FROM " + cteName)
+				sel = cteName + ".*"
 			}
 		} else {
-			q.WriteString(selectKeyword + cteName + ".* FROM " + cteName)
+			sel = cteName + ".*"
 		}
 	} else {
-		outerSelect := strings.ReplaceAll(selectClause, tablePrefix, ctePrefix)
-		q.WriteString(selectKeyword + outerSelect + " FROM " + cteName)
+		sel = strings.ReplaceAll(selectClause, tablePrefix, ctePrefix)
+	}
+
+	// Embed joins (LEFT JOIN LATERAL) correlate to the base-table alias; rewrite
+	// the top-level "table". -> "__recursive". correlation. The lateral's own numbered
+	// alias (relationship_1.) is untouched, so the rewrite is surgical. via+embed is
+	// rejected by the guard above, so joinsClause is only ever set in single-table mode.
+	var joinsClause string
+	if joins != "" {
+		joinsClause = " " + strings.ReplaceAll(joins, tablePrefix, ctePrefix)
 	}
 
-	// Optionally exclude the seed row
+	// Plain filters become a result WHERE on the outer query (composed with the
+	// ExcludeStart seed-skip); walk.* filters already pruned the CTE arms above.
+	var outerWhere string
 	if rec.ExcludeStart {
-		q.WriteString(" WHERE __depth > 0")
+		outerWhere = "__depth > 0"
+	}
+	if mainWhere != "" {
+		resultWhere := strings.ReplaceAll(mainWhere, tablePrefix, ctePrefix)
+		if outerWhere != "" {
+			outerWhere += " AND "
+		}
+		outerWhere += resultWhere
+	}
+
+	if depthSelected && rec.ViaTable != "" {
+		// via min-depth dedup: SELECT DISTINCT ON (node) ... ORDER BY node, __depth
+		// reports the shallowest depth per node. Single-table trees skip this — they
+		// can't reach a node at two depths (the __path guard keeps edges unique), so a
+		// plain SELECT below is fine. The wrapper also isolates min-depth selection from
+		// any user ORDER BY appended below.
+		q.WriteString("SELECT * FROM (SELECT DISTINCT ON (" + ctePrefix + startField + ") " + sel + " FROM " + cteName)
+		if outerWhere != "" {
+			q.WriteString(" WHERE " + outerWhere)
+		}
+		q.WriteString(" ORDER BY " + ctePrefix + startField + ", " + cteName + ".__depth) \"__dedup\"")
+	} else {
+		// In via mode, DISTINCT deduplicates nodes reachable by multiple paths.
+		selectKeyword := "SELECT "
+		if rec.ViaTable != "" {
+			selectKeyword = "SELECT DISTINCT "
+		}
+		q.WriteString(selectKeyword + sel + " FROM " + cteName + joinsClause)
+		if outerWhere != "" {
+			q.WriteString(" WHERE " + outerWhere)
+		}
 	}
 
 	if orderClause != "" {
-		outerOrder := strings.ReplaceAll(orderClause, tablePrefix, ctePrefix)
+		// When the min-depth dedup wrapper is in play the outer query selects from the
+		// "__dedup" subquery, so a user ORDER BY must target that alias (and the column
+		// must be in the select list); otherwise it references the CTE directly.
+		orderPrefix := ctePrefix
+		if depthSelected && rec.ViaTable != "" {
+			orderPrefix = quote("__dedup") + "."
+		}
+		outerOrder := strings.ReplaceAll(orderClause, tablePrefix, orderPrefix)
 		q.WriteString(" ORDER BY " + outerOrder)
 	}
 
@@ -1345,7 +1425,7 @@ func (DirectQueryBuilder) BuildSelect(table string, parts *QueryParts, options *
 			return "", nil, &ParseError{"aggregate functions cannot be used with recursive queries"}
 		}
 		return buildRecursiveSelect(table, schema, parts, options,
-			selectClause, whereClause, orderClause, valueList, info)
+			selectClause, whereClause, orderClause, joins, valueList, info)
 	}
 
 	query := "SELECT " + selectClause
@@ -1381,7 +1461,7 @@ func (QueryWithJSON) BuildSelect(table string, parts *QueryParts, options *Query
 			return "", nil, &ParseError{"aggregate functions cannot be used with recursive queries"}
 		}
 		return buildRecursiveSelect(table, schema, parts, options,
-			selectClause, whereClause, orderClause, valueList, info)
+			selectClause, whereClause, orderClause, joins, valueList, info)
 	}
 
 	query := "SELECT "