@atscript/db-sql-tools 0.1.145 → 0.1.147

package/dist/index.cjs

@@ -61,6 +61,8 @@ const EMPTY_OR = {
 */
 function createFilterVisitor(dialect, options) {
 	const columnRef = options?.columnRef ?? ((field) => dialect.quoteIdentifier(field));
+	const qualifier = options?.qualifier;
+	const aliasSeq = options?.aliasSeq ?? { n: 0 };
 	return {
 		comparison(field, op, value) {
 			if (op === "$geoWithin") {
@@ -153,9 +155,75 @@ function createFilterVisitor(dialect, options) {
 				sql: `NOT (${child.sql})`,
 				params: child.params
 			};
+		},
+		relation(field, op, operand) {
+			if (!(0, _atscript_db.isResolvedRelationFilter)(operand)) throw new _atscript_db.DbError("REL_FILTER_NOT_SUPPORTED", [{
+				path: field,
+				message: `Relational predicate "${op}" on "${field}" reached the SQL renderer unresolved`
+			}]);
+			return renderRelation(dialect, op, operand, qualifier ?? dialect.quoteTable(operand.source.table), aliasSeq);
 		}
 	};
 }
+/**
+* Renders one resolved relational predicate as a correlated `EXISTS`:
+*
+* ```sql
+* -- to / from
+* EXISTS (SELECT 1 FROM <target> AS "_rf1"
+*         WHERE "_rf1"."<pair.target>" = <outer>."<pair.source>" [AND …] [AND <inner>])
+* -- via
+* EXISTS (SELECT 1 FROM <junction> AS "_rf1" JOIN <target> AS "_rf2"
+*           ON "_rf2"."<toTarget.target>" = "_rf1"."<toTarget.junction>" [AND …]
+*         WHERE "_rf1"."<toSource.junction>" = <outer>."<toSource.source>" [AND …]
+*           [AND <junction filter on _rf1>] [AND <inner on _rf2>])
+* ```
+*
+* `$none` is `NOT EXISTS (…)`. Outer columns are always qualified (a bare
+* column would bind to the subquery's table on a self relation or a
+* same-named column). A NULL foreign-key component never satisfies `=`, so
+* such a row has no related row (`$some` false, `$none` true).
+*/
+function renderRelation(dialect, op, node, outer, aliasSeq) {
+	const q = (name) => dialect.quoteIdentifier(name);
+	const nextAlias = () => q(`_rf${++aliasSeq.n}`);
+	const conditions = [];
+	const params = [];
+	const addFilter = (filter, alias) => {
+		if (!filter || Object.keys(filter).length === 0) return;
+		const fragment = (0, _uniqu_core.walkFilter)(filter, createFilterVisitor(dialect, {
+			columnRef: (field) => `${alias}.${q(field)}`,
+			qualifier: alias,
+			aliasSeq
+		}));
+		if (fragment) {
+			conditions.push(fragment.sql);
+			params.push(...fragment.params);
+		}
+	};
+	let from;
+	if (node.kind === "via") {
+		const junction = node.junction;
+		if (!junction) throw new Error(`Relational predicate on "${node.nav}": a "via" relation needs a junction`);
+		const j = nextAlias();
+		const t = nextAlias();
+		const on = junction.toTarget.map((p) => `${t}.${q(p.target)} = ${j}.${q(p.junction)}`);
+		from = `${dialect.quoteTable(junction.table)} AS ${j} JOIN ${dialect.quoteTable(node.target.table)} AS ${t} ON ${on.join(" AND ")}`;
+		for (const p of junction.toSource) conditions.push(`${j}.${q(p.junction)} = ${outer}.${q(p.source)}`);
+		addFilter(junction.filter, j);
+		addFilter(node.filter, t);
+	} else {
+		const t = nextAlias();
+		from = `${dialect.quoteTable(node.target.table)} AS ${t}`;
+		for (const p of node.pairs) conditions.push(`${t}.${q(p.target)} = ${outer}.${q(p.source)}`);
+		addFilter(node.filter, t);
+	}
+	const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+	return {
+		sql: `${op === "$none" ? "NOT " : ""}EXISTS (SELECT 1 FROM ${from}${where})`,
+		params
+	};
+}
 const visitorCache = /* @__PURE__ */ new WeakMap();
 function getVisitor(dialect) {
 	let visitor = visitorCache.get(dialect);
@@ -167,10 +235,23 @@ function getVisitor(dialect) {
 }
 /**
 * Translates a filter expression into a parameterized SQL WHERE clause.
+*
+* Relational predicates (`{ nav: { $some | $none: … } }`, resolved by the
+* core into `ResolvedRelationFilter` operands) render as correlated
+* `[NOT] EXISTS (…)` subqueries; `opts.qualifier` names the outer table or
+* alias they correlate to (default: the source table — see
+* {@link TFilterVisitorOptions.qualifier}). `opts.columnRef` overrides how
+* the filter's own columns render (e.g. `t."col"` for an aliased FROM).
+* Placeholders stay positional `?` in textual order.
+*
+* @param opts - since 0.1.147
 */
-function buildWhere(dialect, filter) {
+function buildWhere(dialect, filter, opts) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
-	return (0, _uniqu_core.walkFilter)(filter, getVisitor(dialect)) ?? EMPTY_AND;
+	return (0, _uniqu_core.walkFilter)(filter, opts || (0, _atscript_db.containsRelationFilter)(filter) ? createFilterVisitor(dialect, {
+		...opts,
+		aliasSeq: opts?.aliasSeq ?? { n: 0 }
+	}) : getVisitor(dialect)) ?? EMPTY_AND;
 }
 //#endregion
 //#region src/common.ts
@@ -215,6 +296,20 @@ function toSqlValue(value) {
 	if (typeof value === "boolean") return value ? 1 : 0;
 	return value;
 }
+/**
+* `FOREIGN KEY (…) REFERENCES <target> (…)[ ON DELETE …][ ON UPDATE …]` of a
+* foreign key over its physical columns ({@link fkColumns}); the target is
+* schema-qualified when it declares `@db.schema`. `quote` quotes one
+* identifier.
+*/
+function foreignKeySql(quote, fk) {
+	const { fields, targetFields } = (0, _atscript_db.fkColumns)(fk);
+	const target = fk.targetSchema ? `${quote(fk.targetSchema)}.${quote(fk.targetTable)}` : quote(fk.targetTable);
+	let sql = `FOREIGN KEY (${fields.map(quote).join(", ")}) REFERENCES ${target} (${targetFields.map(quote).join(", ")})`;
+	if (fk.onDelete) sql += ` ON DELETE ${refActionToSql(fk.onDelete)}`;
+	if (fk.onUpdate) sql += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+	return sql;
+}
 function refActionToSql(action) {
 	switch (action) {
 		case "cascade": return "CASCADE";
@@ -532,6 +627,80 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
 }
 /**
+* The SQL expression of a computed view column (`@db.compute`), evaluated in
+* IEEE double on every dialect: each field and literal leaf is cast with
+* {@link SqlDialect.castDouble} (a computed leaf is already a double and is
+* inlined); `+ - *` render as `(l op r)`, `/` as `(l / NULLIF(r, 0))` —
+* division by zero is NULL — unary minus as `(-x)`, `coalesce` as
+* `COALESCE(…)`. A leaf reads its column like the SELECT list does: an
+* aggregate's call ({@link viewAggExpr}) or a dimension's source
+* ({@link viewSourceExpr}). `byPath` holds the view's mappings by `viewPath`.
+*
+* In a `grouped` view a JSON-extracted dimension leaf reads `MIN(<extract>)`:
+* the extraction is a GROUP BY key, so every row of a group holds the same
+* value, but MySQL's ONLY_FULL_GROUP_BY rejects an expression over the raw
+* JSON column (which is not itself grouped) — the aggregate form is accepted
+* everywhere and yields that same value.
+*
+* @throws when the dialect has no `castDouble`, or a leaf names no column.
+* @since 0.1.147
+*/
+function viewComputeExpr(dialect, c, byPath, resolveFieldRef, grouped = false, cache = /* @__PURE__ */ new Map()) {
+	const cached = cache.get(c.viewPath);
+	if (cached !== void 0) return cached;
+	const cast = dialect.castDouble?.bind(dialect);
+	if (!cast) throw new Error(`View column "${c.viewColumn}": computed view columns are not supported by this adapter`);
+	const render = (e) => {
+		if (typeof e === "number") {
+			if (!Number.isFinite(e)) throw new Error(`View column "${c.viewColumn}": non-finite literal in @db.compute`);
+			return cast(String(e));
+		}
+		if ("field" in e) {
+			const leaf = byPath.get(e.field);
+			if (!leaf) throw new Error(`View column "${c.viewColumn}": "${e.field}" is not a column of the view`);
+			if (leaf.expr !== void 0) return viewComputeExpr(dialect, leaf, byPath, resolveFieldRef, grouped, cache);
+			if (leaf.aggFn) return cast(viewAggExpr(dialect, leaf, resolveFieldRef));
+			const source = viewSourceExpr(dialect, leaf);
+			return cast(grouped && leaf.json ? `MIN(${source})` : source);
+		}
+		const args = e.args.map(render);
+		switch (e.op) {
+			case "neg": return `(-${args[0]})`;
+			case "coalesce": return `COALESCE(${args.join(", ")})`;
+			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
+			default: return `(${args[0]} ${e.op} ${args[1]})`;
+		}
+	};
+	const sql = render(c.expr);
+	cache.set(c.viewPath, sql);
+	return sql;
+}
+/**
+* The `ON` clause of a first-row join (`join.first`): the joined row is the
+* one whose primary key equals the key of the FIRST matching target row —
+* a correlated scalar subquery
+* `"T"."id" = (SELECT "T"."id" FROM "table" AS "T" WHERE <condition> ORDER BY … LIMIT 1)`.
+* The inner `FROM` repeats the join's own target / alias text, so the
+* condition's refs to the joined scope bind to the inner row (SQL name
+* shadowing) while refs to the entry and earlier joins stay correlated to
+* the outer query. The ordering ends with the primary key, so the pick is
+* deterministic; NULL sorts first in `asc` (`nullsSortLargest` dialects
+* render `NULLS FIRST` / `NULLS LAST`). No window functions — SQLite, MySQL 8
+* and PostgreSQL render it alike.
+* @since 0.1.147
+*/
+function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
+	const first = join.first;
+	const key = resolveFieldRef({
+		type: join.targetType,
+		field: first.key
+	});
+	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => {
+		const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
+		return `${resolveFieldRef(ref)} ${desc ? "DESC" : "ASC"}${nulls}`;
+	}).join(", ")} LIMIT 1)`;
+}
+/**
 * Builds a CREATE VIEW statement from a view plan and column mappings.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
@@ -543,35 +712,41 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 * join target may be views.
 */
 function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
-	const selectCols = columns.map((c) => {
-		return `${c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-	}).join(", ");
+	const columnByPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const hasAggregates = columns.some((c) => c.aggFn);
+	const computedSql = /* @__PURE__ */ new Map();
+	/** A column's SELECT expression: computed, aggregate or plain source. */
+	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
+	const selectCols = columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ");
 	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
-		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		const condition = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
 		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
+		const onClause = join.first ? firstRowOn(dialect, join, target, condition, resolveFieldRef) : condition;
 		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
 		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
 		sql += ` WHERE ${whereClause}`;
 	}
-	if (columns.some((c) => c.aggFn)) {
-		const dimensionCols = columns.filter((c) => !c.aggFn);
+	if (hasAggregates) {
+		const dimensionCols = columns.filter((c) => !c.aggFn && c.expr === void 0);
 		if (dimensionCols.length > 0) {
 			const groupByCols = dimensionCols.map((c) => viewSourceExpr(dialect, c)).join(", ");
 			sql += ` GROUP BY ${groupByCols}`;
 		}
 		if (plan.having) {
-			const columnByPath = /* @__PURE__ */ new Map();
-			for (const c of columns) columnByPath.set(c.viewPath, c);
+			let grouped;
+			const groupedColumns = () => grouped ??= new Set(dimensionCols.filter((c) => !c.json).map((c) => c.sourceColumn.toLowerCase()));
 			const havingResolver = (ref) => {
 				const col = ref.type ? void 0 : columnByPath.get(ref.field);
 				if (!col) return resolveFieldRef(ref);
+				if (col.expr !== void 0) return columnExpr(col);
 				if (col.aggFn) return viewAggExpr(dialect, col, resolveFieldRef);
 				const expr = viewSourceExpr(dialect, col);
-				return col.json ? havingGroupRef(dialect, expr, col.viewColumn) : expr;
+				if (!col.json) return expr;
+				return dialect.bucketAliasInHaving && groupedColumns().has(col.viewColumn.toLowerCase()) ? `MIN(${expr})` : havingGroupRef(dialect, expr, col.viewColumn);
 			};
 			const havingClause = queryNodeToSql(plan.having, havingResolver);
 			sql += ` HAVING ${havingClause}`;
@@ -632,11 +807,8 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 function buildSelect(dialect, table, where, controls) {
 	let sql = `SELECT ${buildProjection(dialect, controls?.$select)} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
 	const params = [...where.params];
-	if (controls?.$sort) {
-		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
-		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
-	}
+	const orderBy = orderByList(dialect, controls?.$sort);
+	if (orderBy) sql += ` ORDER BY ${orderBy}`;
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
 		params.push(controls.$limit);
@@ -651,6 +823,53 @@ function buildSelect(dialect, table, where, controls) {
 		params
 	});
 }
+/** `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders nothing. */
+function orderByList(dialect, sort) {
+	if (!sort) return "";
+	const parts = [];
+	for (const [col, dir] of Object.entries(sort)) parts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+	return parts.join(", ");
+}
+/**
+* The row-number column {@link buildPartitionedSelect} adds to every row;
+* {@link stripPartitionRowNumber} removes it from the result rows.
+* @since 0.1.147
+*/
+const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
+/**
+* Builds a SELECT whose `$skip` / `$limit` apply to each partition — the rows
+* sharing the values of the `partitionBy` columns (physical names) — instead
+* of to the whole result: a `ROW_NUMBER() OVER (PARTITION BY … ORDER BY
+* <$sort>)` window in a derived table, filtered on the row number. The rows
+* of each partition come out in `$sort` order (partitions interleave); every
+* row carries {@link PARTITION_ROW_NUMBER_ALIAS}. Window functions need
+* SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
+* @since 0.1.147
+*/
+function buildPartitionedSelect(dialect, table, where, controls, partitionBy) {
+	const rn = dialect.quoteIdentifier(PARTITION_ROW_NUMBER_ALIAS);
+	const orderBy = orderByList(dialect, controls.$sort);
+	const window = `PARTITION BY ${partitionBy.map((col) => dialect.quoteIdentifier(col)).join(", ")}` + (orderBy ? ` ORDER BY ${orderBy}` : "");
+	const inner = `SELECT ${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const skip = controls.$skip ?? 0;
+	const limit = controls.$limit;
+	const params = [...where.params, skip];
+	let sql = `SELECT * FROM (${inner}) AS ${dialect.quoteIdentifier("__atscript_p")} WHERE ${rn} > ?`;
+	if (limit !== void 0 && limit !== null) {
+		sql += ` AND ${rn} <= ?`;
+		params.push(skip + limit);
+	}
+	sql += ` ORDER BY ${rn}`;
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+function stripPartitionRowNumber(rows) {
+	for (const row of rows) delete row[PARTITION_ROW_NUMBER_ALIAS];
+	return rows;
+}
 /**
 * Marker value for {@link buildUpdate}: the column is assigned its DDL
 * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -810,6 +1029,13 @@ function buildProjection(dialect, select, qualifier) {
 */
 const GEO_DISTANCE_ALIAS = "__atscript_distance";
 /**
+* Alias of the searched table inside the geo and vector search statements —
+* a filter rendered into them correlates its relational predicates to it
+* (`buildWhere(filter, { qualifier: dialect.quoteTable(SEARCH_SOURCE_ALIAS) })`).
+* @since 0.1.147
+*/
+const SEARCH_SOURCE_ALIAS = "t";
+/**
 * Builds a distance-ranked geo search SELECT:
 *
 * ```sql
@@ -1032,6 +1258,8 @@ exports.AGG_FN_SQL = AGG_FN_SQL;
 exports.EMPTY_AND = EMPTY_AND;
 exports.EMPTY_OR = EMPTY_OR;
 exports.GEO_DISTANCE_ALIAS = GEO_DISTANCE_ALIAS;
+exports.PARTITION_ROW_NUMBER_ALIAS = PARTITION_ROW_NUMBER_ALIAS;
+exports.SEARCH_SOURCE_ALIAS = SEARCH_SOURCE_ALIAS;
 exports.SQL_DEFAULT = SQL_DEFAULT;
 exports.VECTOR_DISTANCE_ALIAS = VECTOR_DISTANCE_ALIAS;
 exports.buildAggregateCount = buildAggregateCount;
@@ -1042,6 +1270,7 @@ exports.buildGeoSearchCount = buildGeoSearchCount;
 exports.buildGeoSearchSelect = buildGeoSearchSelect;
 exports.buildInsert = buildInsert;
 exports.buildInsertMany = buildInsertMany;
+exports.buildPartitionedSelect = buildPartitionedSelect;
 exports.buildProjection = buildProjection;
 exports.buildSelect = buildSelect;
 exports.buildUpdate = buildUpdate;
@@ -1054,6 +1283,7 @@ exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
 exports.derivedColumnExpr = derivedColumnExpr;
 exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
+exports.foreignKeySql = foreignKeySql;
 exports.geoWindowFromControls = geoWindowFromControls;
 exports.groupKeySql = groupKeySql;
 exports.insertManyColumns = insertManyColumns;
@@ -1068,5 +1298,6 @@ exports.renameGeoDistance = renameGeoDistance;
 exports.replaceColumnsFor = replaceColumnsFor;
 exports.sqlStringLiteral = sqlStringLiteral;
 exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;
+exports.stripPartitionRowNumber = stripPartitionRowNumber;
 exports.toSqlValue = toSqlValue;
 exports.vectorDistanceSource = vectorDistanceSource;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
@@ -34,8 +34,10 @@ interface SqlDialect {
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
   /**
    * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
-   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
-   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * (the local calendar date of the bucket's first day in `b.tz`; for unit
+   * `hour`, `'YYYY-MM-DDTHH:00'`, the local wall-clock hour — truncate the
+   * zone's wall time, never the UTC instant), or NULL for a NULL source or
+   * one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
    * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
    *
    * The expression must be PARAMETER-FREE — inline the zone with
@@ -83,6 +85,24 @@ interface SqlDialect {
    * @since 0.1.136
    */
   jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
+  /**
+   * `expr` cast to an IEEE double — how a computed view column
+   * (`@db.compute`) evaluates every field / literal leaf, so `7 / 2 = 3.5`
+   * everywhere (no integer division, no DECIMAL rounding): SQLite
+   * `CAST(x AS REAL)`, MySQL `CAST(x AS DOUBLE)`, PostgreSQL
+   * `CAST(x AS DOUBLE PRECISION)`. Parameter-free. Dialects without it fail
+   * view sync with `computed view columns are not supported by this adapter`.
+   * @since 0.1.147
+   */
+  castDouble?(expr: string): string;
+  /**
+   * `true` when the database sorts NULL as the LARGEST value (PostgreSQL):
+   * first-row join order keys then render `ASC NULLS FIRST` /
+   * `DESC NULLS LAST`, keeping the uniform "NULL is the smallest value"
+   * ordering SQLite, MySQL and MongoDB have natively.
+   * @since 0.1.147
+   */
+  nullsSortLargest?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -117,6 +137,35 @@ interface TFilterVisitorOptions {
    * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
    */
   columnRef?: (field: string) => string;
+  /**
+   * The quoted outer table or alias that relational predicates
+   * (`{ nav: { $some | $none: … } }`) correlate to: their `EXISTS` subqueries
+   * compare the related rows with `<qualifier>."<column>"`. Defaults to the
+   * predicate's source table (`dialect.quoteTable(node.source.table)`), which
+   * is right for every statement whose FROM is the bare table; a statement
+   * that aliases its FROM (`FROM "items" AS "t"`) must pass that alias here.
+   *
+   * @since 0.1.147
+   */
+  qualifier?: string;
+  /**
+   * Alias sequence of the relational-predicate subqueries (`_rf1`, `_rf2`, …),
+   * shared by the visitors of one statement so nested predicates get distinct
+   * aliases. A visitor created without one starts its own.
+   *
+   * @internal
+   * @since 0.1.147
+   */
+  aliasSeq?: TRelationAliasSeq;
+}
+/**
+ * Alias counter of the relational-predicate subqueries of one statement.
+ *
+ * @internal
+ * @since 0.1.147
+ */
+interface TRelationAliasSeq {
+  n: number;
 }
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -124,8 +173,18 @@ interface TFilterVisitorOptions {
 declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * Translates a filter expression into a parameterized SQL WHERE clause.
+ *
+ * Relational predicates (`{ nav: { $some | $none: … } }`, resolved by the
+ * core into `ResolvedRelationFilter` operands) render as correlated
+ * `[NOT] EXISTS (…)` subqueries; `opts.qualifier` names the outer table or
+ * alias they correlate to (default: the source table — see
+ * {@link TFilterVisitorOptions.qualifier}). `opts.columnRef` overrides how
+ * the filter's own columns render (e.g. `t."col"` for an aliased FROM).
+ * Placeholders stay positional `?` in textual order.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragment;
+declare function buildWhere(dialect: SqlDialect, filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/geo.d.ts
 /**
@@ -135,6 +194,13 @@ declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragme
  * across dialects, so the public name can't be used directly.
  */
 declare const GEO_DISTANCE_ALIAS = "__atscript_distance";
+/**
+ * Alias of the searched table inside the geo and vector search statements —
+ * a filter rendered into them correlates its relational predicates to it
+ * (`buildWhere(filter, { qualifier: dialect.quoteTable(SEARCH_SOURCE_ALIAS) })`).
+ * @since 0.1.147
+ */
+declare const SEARCH_SOURCE_ALIAS = "t";
 /** The query controls a geo search page reads — an adapter passes its `query.controls` as-is. */
 interface TGeoSearchControls {
   $limit?: number;
@@ -272,6 +338,25 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * The row-number column {@link buildPartitionedSelect} adds to every row;
+ * {@link stripPartitionRowNumber} removes it from the result rows.
+ * @since 0.1.147
+ */
+declare const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
+/**
+ * Builds a SELECT whose `$skip` / `$limit` apply to each partition — the rows
+ * sharing the values of the `partitionBy` columns (physical names) — instead
+ * of to the whole result: a `ROW_NUMBER() OVER (PARTITION BY … ORDER BY
+ * <$sort>)` window in a derived table, filtered on the row number. The rows
+ * of each partition come out in `$sort` order (partitions interleave); every
+ * row carries {@link PARTITION_ROW_NUMBER_ALIAS}. Window functions need
+ * SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
+ * @since 0.1.147
+ */
+declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
  * Marker value for {@link buildUpdate}: the column is assigned its DDL
  * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -376,6 +461,13 @@ declare function jsonDollarPath(path: readonly string[]): string;
 declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
+/**
+ * `FOREIGN KEY (…) REFERENCES <target> (…)[ ON DELETE …][ ON UPDATE …]` of a
+ * foreign key over its physical columns ({@link fkColumns}); the target is
+ * schema-qualified when it declares `@db.schema`. `quote` quotes one
+ * identifier.
+ */
+declare function foreignKeySql(quote: (name: string) => string, fk: TDbForeignKey): string;
 declare function refActionToSql(action: TDbReferentialAction): string;
 /** Returns a safe SQL DEFAULT literal for a given design type. */
 declare function defaultValueForType(designType: string): string;
@@ -446,4 +538,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -34,8 +34,10 @@ interface SqlDialect {
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
   /**
    * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
-   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
-   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * (the local calendar date of the bucket's first day in `b.tz`; for unit
+   * `hour`, `'YYYY-MM-DDTHH:00'`, the local wall-clock hour — truncate the
+   * zone's wall time, never the UTC instant), or NULL for a NULL source or
+   * one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
    * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
    *
    * The expression must be PARAMETER-FREE — inline the zone with
@@ -83,6 +85,24 @@ interface SqlDialect {
    * @since 0.1.136
    */
   jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
+  /**
+   * `expr` cast to an IEEE double — how a computed view column
+   * (`@db.compute`) evaluates every field / literal leaf, so `7 / 2 = 3.5`
+   * everywhere (no integer division, no DECIMAL rounding): SQLite
+   * `CAST(x AS REAL)`, MySQL `CAST(x AS DOUBLE)`, PostgreSQL
+   * `CAST(x AS DOUBLE PRECISION)`. Parameter-free. Dialects without it fail
+   * view sync with `computed view columns are not supported by this adapter`.
+   * @since 0.1.147
+   */
+  castDouble?(expr: string): string;
+  /**
+   * `true` when the database sorts NULL as the LARGEST value (PostgreSQL):
+   * first-row join order keys then render `ASC NULLS FIRST` /
+   * `DESC NULLS LAST`, keeping the uniform "NULL is the smallest value"
+   * ordering SQLite, MySQL and MongoDB have natively.
+   * @since 0.1.147
+   */
+  nullsSortLargest?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -117,6 +137,35 @@ interface TFilterVisitorOptions {
    * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
    */
   columnRef?: (field: string) => string;
+  /**
+   * The quoted outer table or alias that relational predicates
+   * (`{ nav: { $some | $none: … } }`) correlate to: their `EXISTS` subqueries
+   * compare the related rows with `<qualifier>."<column>"`. Defaults to the
+   * predicate's source table (`dialect.quoteTable(node.source.table)`), which
+   * is right for every statement whose FROM is the bare table; a statement
+   * that aliases its FROM (`FROM "items" AS "t"`) must pass that alias here.
+   *
+   * @since 0.1.147
+   */
+  qualifier?: string;
+  /**
+   * Alias sequence of the relational-predicate subqueries (`_rf1`, `_rf2`, …),
+   * shared by the visitors of one statement so nested predicates get distinct
+   * aliases. A visitor created without one starts its own.
+   *
+   * @internal
+   * @since 0.1.147
+   */
+  aliasSeq?: TRelationAliasSeq;
+}
+/**
+ * Alias counter of the relational-predicate subqueries of one statement.
+ *
+ * @internal
+ * @since 0.1.147
+ */
+interface TRelationAliasSeq {
+  n: number;
 }
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -124,8 +173,18 @@ interface TFilterVisitorOptions {
 declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * Translates a filter expression into a parameterized SQL WHERE clause.
+ *
+ * Relational predicates (`{ nav: { $some | $none: … } }`, resolved by the
+ * core into `ResolvedRelationFilter` operands) render as correlated
+ * `[NOT] EXISTS (…)` subqueries; `opts.qualifier` names the outer table or
+ * alias they correlate to (default: the source table — see
+ * {@link TFilterVisitorOptions.qualifier}). `opts.columnRef` overrides how
+ * the filter's own columns render (e.g. `t."col"` for an aliased FROM).
+ * Placeholders stay positional `?` in textual order.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragment;
+declare function buildWhere(dialect: SqlDialect, filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/geo.d.ts
 /**
@@ -135,6 +194,13 @@ declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragme
  * across dialects, so the public name can't be used directly.
  */
 declare const GEO_DISTANCE_ALIAS = "__atscript_distance";
+/**
+ * Alias of the searched table inside the geo and vector search statements —
+ * a filter rendered into them correlates its relational predicates to it
+ * (`buildWhere(filter, { qualifier: dialect.quoteTable(SEARCH_SOURCE_ALIAS) })`).
+ * @since 0.1.147
+ */
+declare const SEARCH_SOURCE_ALIAS = "t";
 /** The query controls a geo search page reads — an adapter passes its `query.controls` as-is. */
 interface TGeoSearchControls {
   $limit?: number;
@@ -272,6 +338,25 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * The row-number column {@link buildPartitionedSelect} adds to every row;
+ * {@link stripPartitionRowNumber} removes it from the result rows.
+ * @since 0.1.147
+ */
+declare const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
+/**
+ * Builds a SELECT whose `$skip` / `$limit` apply to each partition — the rows
+ * sharing the values of the `partitionBy` columns (physical names) — instead
+ * of to the whole result: a `ROW_NUMBER() OVER (PARTITION BY … ORDER BY
+ * <$sort>)` window in a derived table, filtered on the row number. The rows
+ * of each partition come out in `$sort` order (partitions interleave); every
+ * row carries {@link PARTITION_ROW_NUMBER_ALIAS}. Window functions need
+ * SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
+ * @since 0.1.147
+ */
+declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
  * Marker value for {@link buildUpdate}: the column is assigned its DDL
  * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -376,6 +461,13 @@ declare function jsonDollarPath(path: readonly string[]): string;
 declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
+/**
+ * `FOREIGN KEY (…) REFERENCES <target> (…)[ ON DELETE …][ ON UPDATE …]` of a
+ * foreign key over its physical columns ({@link fkColumns}); the target is
+ * schema-qualified when it declares `@db.schema`. `quote` quotes one
+ * identifier.
+ */
+declare function foreignKeySql(quote: (name: string) => string, fk: TDbForeignKey): string;
 declare function refActionToSql(action: TDbReferentialAction): string;
 /** Returns a safe SQL DEFAULT literal for a given design type. */
 declare function defaultValueForType(designType: string): string;
@@ -446,4 +538,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
-import { DbError, isFieldRef } from "@atscript/db";
+import { DbError, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
 /**
@@ -60,6 +60,8 @@ const EMPTY_OR = {
 */
 function createFilterVisitor(dialect, options) {
 	const columnRef = options?.columnRef ?? ((field) => dialect.quoteIdentifier(field));
+	const qualifier = options?.qualifier;
+	const aliasSeq = options?.aliasSeq ?? { n: 0 };
 	return {
 		comparison(field, op, value) {
 			if (op === "$geoWithin") {
@@ -152,9 +154,75 @@ function createFilterVisitor(dialect, options) {
 				sql: `NOT (${child.sql})`,
 				params: child.params
 			};
+		},
+		relation(field, op, operand) {
+			if (!isResolvedRelationFilter(operand)) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+				path: field,
+				message: `Relational predicate "${op}" on "${field}" reached the SQL renderer unresolved`
+			}]);
+			return renderRelation(dialect, op, operand, qualifier ?? dialect.quoteTable(operand.source.table), aliasSeq);
 		}
 	};
 }
+/**
+* Renders one resolved relational predicate as a correlated `EXISTS`:
+*
+* ```sql
+* -- to / from
+* EXISTS (SELECT 1 FROM <target> AS "_rf1"
+*         WHERE "_rf1"."<pair.target>" = <outer>."<pair.source>" [AND …] [AND <inner>])
+* -- via
+* EXISTS (SELECT 1 FROM <junction> AS "_rf1" JOIN <target> AS "_rf2"
+*           ON "_rf2"."<toTarget.target>" = "_rf1"."<toTarget.junction>" [AND …]
+*         WHERE "_rf1"."<toSource.junction>" = <outer>."<toSource.source>" [AND …]
+*           [AND <junction filter on _rf1>] [AND <inner on _rf2>])
+* ```
+*
+* `$none` is `NOT EXISTS (…)`. Outer columns are always qualified (a bare
+* column would bind to the subquery's table on a self relation or a
+* same-named column). A NULL foreign-key component never satisfies `=`, so
+* such a row has no related row (`$some` false, `$none` true).
+*/
+function renderRelation(dialect, op, node, outer, aliasSeq) {
+	const q = (name) => dialect.quoteIdentifier(name);
+	const nextAlias = () => q(`_rf${++aliasSeq.n}`);
+	const conditions = [];
+	const params = [];
+	const addFilter = (filter, alias) => {
+		if (!filter || Object.keys(filter).length === 0) return;
+		const fragment = walkFilter(filter, createFilterVisitor(dialect, {
+			columnRef: (field) => `${alias}.${q(field)}`,
+			qualifier: alias,
+			aliasSeq
+		}));
+		if (fragment) {
+			conditions.push(fragment.sql);
+			params.push(...fragment.params);
+		}
+	};
+	let from;
+	if (node.kind === "via") {
+		const junction = node.junction;
+		if (!junction) throw new Error(`Relational predicate on "${node.nav}": a "via" relation needs a junction`);
+		const j = nextAlias();
+		const t = nextAlias();
+		const on = junction.toTarget.map((p) => `${t}.${q(p.target)} = ${j}.${q(p.junction)}`);
+		from = `${dialect.quoteTable(junction.table)} AS ${j} JOIN ${dialect.quoteTable(node.target.table)} AS ${t} ON ${on.join(" AND ")}`;
+		for (const p of junction.toSource) conditions.push(`${j}.${q(p.junction)} = ${outer}.${q(p.source)}`);
+		addFilter(junction.filter, j);
+		addFilter(node.filter, t);
+	} else {
+		const t = nextAlias();
+		from = `${dialect.quoteTable(node.target.table)} AS ${t}`;
+		for (const p of node.pairs) conditions.push(`${t}.${q(p.target)} = ${outer}.${q(p.source)}`);
+		addFilter(node.filter, t);
+	}
+	const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+	return {
+		sql: `${op === "$none" ? "NOT " : ""}EXISTS (SELECT 1 FROM ${from}${where})`,
+		params
+	};
+}
 const visitorCache = /* @__PURE__ */ new WeakMap();
 function getVisitor(dialect) {
 	let visitor = visitorCache.get(dialect);
@@ -166,10 +234,23 @@ function getVisitor(dialect) {
 }
 /**
 * Translates a filter expression into a parameterized SQL WHERE clause.
+*
+* Relational predicates (`{ nav: { $some | $none: … } }`, resolved by the
+* core into `ResolvedRelationFilter` operands) render as correlated
+* `[NOT] EXISTS (…)` subqueries; `opts.qualifier` names the outer table or
+* alias they correlate to (default: the source table — see
+* {@link TFilterVisitorOptions.qualifier}). `opts.columnRef` overrides how
+* the filter's own columns render (e.g. `t."col"` for an aliased FROM).
+* Placeholders stay positional `?` in textual order.
+*
+* @param opts - since 0.1.147
 */
-function buildWhere(dialect, filter) {
+function buildWhere(dialect, filter, opts) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
-	return walkFilter(filter, getVisitor(dialect)) ?? EMPTY_AND;
+	return walkFilter(filter, opts || containsRelationFilter(filter) ? createFilterVisitor(dialect, {
+		...opts,
+		aliasSeq: opts?.aliasSeq ?? { n: 0 }
+	}) : getVisitor(dialect)) ?? EMPTY_AND;
 }
 //#endregion
 //#region src/common.ts
@@ -214,6 +295,20 @@ function toSqlValue(value) {
 	if (typeof value === "boolean") return value ? 1 : 0;
 	return value;
 }
+/**
+* `FOREIGN KEY (…) REFERENCES <target> (…)[ ON DELETE …][ ON UPDATE …]` of a
+* foreign key over its physical columns ({@link fkColumns}); the target is
+* schema-qualified when it declares `@db.schema`. `quote` quotes one
+* identifier.
+*/
+function foreignKeySql(quote, fk) {
+	const { fields, targetFields } = fkColumns(fk);
+	const target = fk.targetSchema ? `${quote(fk.targetSchema)}.${quote(fk.targetTable)}` : quote(fk.targetTable);
+	let sql = `FOREIGN KEY (${fields.map(quote).join(", ")}) REFERENCES ${target} (${targetFields.map(quote).join(", ")})`;
+	if (fk.onDelete) sql += ` ON DELETE ${refActionToSql(fk.onDelete)}`;
+	if (fk.onUpdate) sql += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+	return sql;
+}
 function refActionToSql(action) {
 	switch (action) {
 		case "cascade": return "CASCADE";
@@ -531,6 +626,80 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
 }
 /**
+* The SQL expression of a computed view column (`@db.compute`), evaluated in
+* IEEE double on every dialect: each field and literal leaf is cast with
+* {@link SqlDialect.castDouble} (a computed leaf is already a double and is
+* inlined); `+ - *` render as `(l op r)`, `/` as `(l / NULLIF(r, 0))` —
+* division by zero is NULL — unary minus as `(-x)`, `coalesce` as
+* `COALESCE(…)`. A leaf reads its column like the SELECT list does: an
+* aggregate's call ({@link viewAggExpr}) or a dimension's source
+* ({@link viewSourceExpr}). `byPath` holds the view's mappings by `viewPath`.
+*
+* In a `grouped` view a JSON-extracted dimension leaf reads `MIN(<extract>)`:
+* the extraction is a GROUP BY key, so every row of a group holds the same
+* value, but MySQL's ONLY_FULL_GROUP_BY rejects an expression over the raw
+* JSON column (which is not itself grouped) — the aggregate form is accepted
+* everywhere and yields that same value.
+*
+* @throws when the dialect has no `castDouble`, or a leaf names no column.
+* @since 0.1.147
+*/
+function viewComputeExpr(dialect, c, byPath, resolveFieldRef, grouped = false, cache = /* @__PURE__ */ new Map()) {
+	const cached = cache.get(c.viewPath);
+	if (cached !== void 0) return cached;
+	const cast = dialect.castDouble?.bind(dialect);
+	if (!cast) throw new Error(`View column "${c.viewColumn}": computed view columns are not supported by this adapter`);
+	const render = (e) => {
+		if (typeof e === "number") {
+			if (!Number.isFinite(e)) throw new Error(`View column "${c.viewColumn}": non-finite literal in @db.compute`);
+			return cast(String(e));
+		}
+		if ("field" in e) {
+			const leaf = byPath.get(e.field);
+			if (!leaf) throw new Error(`View column "${c.viewColumn}": "${e.field}" is not a column of the view`);
+			if (leaf.expr !== void 0) return viewComputeExpr(dialect, leaf, byPath, resolveFieldRef, grouped, cache);
+			if (leaf.aggFn) return cast(viewAggExpr(dialect, leaf, resolveFieldRef));
+			const source = viewSourceExpr(dialect, leaf);
+			return cast(grouped && leaf.json ? `MIN(${source})` : source);
+		}
+		const args = e.args.map(render);
+		switch (e.op) {
+			case "neg": return `(-${args[0]})`;
+			case "coalesce": return `COALESCE(${args.join(", ")})`;
+			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
+			default: return `(${args[0]} ${e.op} ${args[1]})`;
+		}
+	};
+	const sql = render(c.expr);
+	cache.set(c.viewPath, sql);
+	return sql;
+}
+/**
+* The `ON` clause of a first-row join (`join.first`): the joined row is the
+* one whose primary key equals the key of the FIRST matching target row —
+* a correlated scalar subquery
+* `"T"."id" = (SELECT "T"."id" FROM "table" AS "T" WHERE <condition> ORDER BY … LIMIT 1)`.
+* The inner `FROM` repeats the join's own target / alias text, so the
+* condition's refs to the joined scope bind to the inner row (SQL name
+* shadowing) while refs to the entry and earlier joins stay correlated to
+* the outer query. The ordering ends with the primary key, so the pick is
+* deterministic; NULL sorts first in `asc` (`nullsSortLargest` dialects
+* render `NULLS FIRST` / `NULLS LAST`). No window functions — SQLite, MySQL 8
+* and PostgreSQL render it alike.
+* @since 0.1.147
+*/
+function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
+	const first = join.first;
+	const key = resolveFieldRef({
+		type: join.targetType,
+		field: first.key
+	});
+	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => {
+		const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
+		return `${resolveFieldRef(ref)} ${desc ? "DESC" : "ASC"}${nulls}`;
+	}).join(", ")} LIMIT 1)`;
+}
+/**
 * Builds a CREATE VIEW statement from a view plan and column mappings.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
@@ -542,35 +711,41 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 * join target may be views.
 */
 function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
-	const selectCols = columns.map((c) => {
-		return `${c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-	}).join(", ");
+	const columnByPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const hasAggregates = columns.some((c) => c.aggFn);
+	const computedSql = /* @__PURE__ */ new Map();
+	/** A column's SELECT expression: computed, aggregate or plain source. */
+	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
+	const selectCols = columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ");
 	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
-		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		const condition = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
 		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
+		const onClause = join.first ? firstRowOn(dialect, join, target, condition, resolveFieldRef) : condition;
 		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
 		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
 		sql += ` WHERE ${whereClause}`;
 	}
-	if (columns.some((c) => c.aggFn)) {
-		const dimensionCols = columns.filter((c) => !c.aggFn);
+	if (hasAggregates) {
+		const dimensionCols = columns.filter((c) => !c.aggFn && c.expr === void 0);
 		if (dimensionCols.length > 0) {
 			const groupByCols = dimensionCols.map((c) => viewSourceExpr(dialect, c)).join(", ");
 			sql += ` GROUP BY ${groupByCols}`;
 		}
 		if (plan.having) {
-			const columnByPath = /* @__PURE__ */ new Map();
-			for (const c of columns) columnByPath.set(c.viewPath, c);
+			let grouped;
+			const groupedColumns = () => grouped ??= new Set(dimensionCols.filter((c) => !c.json).map((c) => c.sourceColumn.toLowerCase()));
 			const havingResolver = (ref) => {
 				const col = ref.type ? void 0 : columnByPath.get(ref.field);
 				if (!col) return resolveFieldRef(ref);
+				if (col.expr !== void 0) return columnExpr(col);
 				if (col.aggFn) return viewAggExpr(dialect, col, resolveFieldRef);
 				const expr = viewSourceExpr(dialect, col);
-				return col.json ? havingGroupRef(dialect, expr, col.viewColumn) : expr;
+				if (!col.json) return expr;
+				return dialect.bucketAliasInHaving && groupedColumns().has(col.viewColumn.toLowerCase()) ? `MIN(${expr})` : havingGroupRef(dialect, expr, col.viewColumn);
 			};
 			const havingClause = queryNodeToSql(plan.having, havingResolver);
 			sql += ` HAVING ${havingClause}`;
@@ -631,11 +806,8 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 function buildSelect(dialect, table, where, controls) {
 	let sql = `SELECT ${buildProjection(dialect, controls?.$select)} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
 	const params = [...where.params];
-	if (controls?.$sort) {
-		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
-		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
-	}
+	const orderBy = orderByList(dialect, controls?.$sort);
+	if (orderBy) sql += ` ORDER BY ${orderBy}`;
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
 		params.push(controls.$limit);
@@ -650,6 +822,53 @@ function buildSelect(dialect, table, where, controls) {
 		params
 	});
 }
+/** `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders nothing. */
+function orderByList(dialect, sort) {
+	if (!sort) return "";
+	const parts = [];
+	for (const [col, dir] of Object.entries(sort)) parts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+	return parts.join(", ");
+}
+/**
+* The row-number column {@link buildPartitionedSelect} adds to every row;
+* {@link stripPartitionRowNumber} removes it from the result rows.
+* @since 0.1.147
+*/
+const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
+/**
+* Builds a SELECT whose `$skip` / `$limit` apply to each partition — the rows
+* sharing the values of the `partitionBy` columns (physical names) — instead
+* of to the whole result: a `ROW_NUMBER() OVER (PARTITION BY … ORDER BY
+* <$sort>)` window in a derived table, filtered on the row number. The rows
+* of each partition come out in `$sort` order (partitions interleave); every
+* row carries {@link PARTITION_ROW_NUMBER_ALIAS}. Window functions need
+* SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
+* @since 0.1.147
+*/
+function buildPartitionedSelect(dialect, table, where, controls, partitionBy) {
+	const rn = dialect.quoteIdentifier(PARTITION_ROW_NUMBER_ALIAS);
+	const orderBy = orderByList(dialect, controls.$sort);
+	const window = `PARTITION BY ${partitionBy.map((col) => dialect.quoteIdentifier(col)).join(", ")}` + (orderBy ? ` ORDER BY ${orderBy}` : "");
+	const inner = `SELECT ${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const skip = controls.$skip ?? 0;
+	const limit = controls.$limit;
+	const params = [...where.params, skip];
+	let sql = `SELECT * FROM (${inner}) AS ${dialect.quoteIdentifier("__atscript_p")} WHERE ${rn} > ?`;
+	if (limit !== void 0 && limit !== null) {
+		sql += ` AND ${rn} <= ?`;
+		params.push(skip + limit);
+	}
+	sql += ` ORDER BY ${rn}`;
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+function stripPartitionRowNumber(rows) {
+	for (const row of rows) delete row[PARTITION_ROW_NUMBER_ALIAS];
+	return rows;
+}
 /**
 * Marker value for {@link buildUpdate}: the column is assigned its DDL
 * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -809,6 +1028,13 @@ function buildProjection(dialect, select, qualifier) {
 */
 const GEO_DISTANCE_ALIAS = "__atscript_distance";
 /**
+* Alias of the searched table inside the geo and vector search statements —
+* a filter rendered into them correlates its relational predicates to it
+* (`buildWhere(filter, { qualifier: dialect.quoteTable(SEARCH_SOURCE_ALIAS) })`).
+* @since 0.1.147
+*/
+const SEARCH_SOURCE_ALIAS = "t";
+/**
 * Builds a distance-ranked geo search SELECT:
 *
 * ```sql
@@ -1027,4 +1253,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.145",
+  "version": "0.1.147",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@uniqu/core": "^0.1.11",
-    "unplugin-atscript": "^0.1.97"
+    "@uniqu/core": "^0.1.12",
+    "unplugin-atscript": "^0.1.99"
   },
   "peerDependencies": {
-    "@uniqu/core": "^0.1.11",
-    "@atscript/db": "^0.1.145"
+    "@uniqu/core": "^0.1.12",
+    "@atscript/db": "^0.1.147"
   },
   "scripts": {
     "build": "vp pack",