turbine-orm 0.32.2 → 0.34.0

package/dist/query/builder.d.ts

@@ -829,6 +829,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
     private buildRelationPickOrderBy;
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    private compilePickPieces;
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
      * validation (a warmed cache can never skip it), then pushes in the same

package/dist/query/builder.js

@@ -959,14 +959,22 @@ export class QueryInterface {
             else {
                 selectClause = `${qt}.*`;
             }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
+            // Piece-then-assemble. The join-sink between FROM and WHERE carries any
+            // `plan: 'lateral'` pick joins; it is populated during the ORDER BY build
+            // below and spliced in at final assembly. Empty for every other query
+            // shape → the assembled SQL is byte-identical to the incremental-append
+            // form for the default plan (asserted by the byte-equality snapshot test).
+            const lateralJoins = [];
+            // WHERE + cursor conditions accumulate into `tail`, pushing params in
+            // where → cursor order (the collect path mirrors this exactly).
+            let tail = freshWhereSql;
             if (args?.cursor) {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
-                        // orderBy values can be the { sort, nulls } spec form — normalize
+                        // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
                         const dir = args.orderBy?.[k];
                         const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
@@ -974,33 +982,38 @@ export class QueryInterface {
                         freshParams.push(v);
                         return `${qt}.${col} ${op} ${this.p(freshParams.length)}`;
                     });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
+                    tail += freshWhereSql ? ` AND ${cursorConditions.join(' AND ')}` : ` WHERE ${cursorConditions.join(' AND ')}`;
                 }
             }
-            if (args?.orderBy) {
-                if (distinctPrefix) {
-                    // Postgres requires DISTINCT ON expressions to lead the ORDER BY.
-                    // Prisma semantics ("first row per combination, result in the user's
-                    // order") need two levels: inner DISTINCT ON ordered by the distinct
-                    // columns then the user's order (picks the right representative row),
-                    // outer re-ordered by the user's order alone.
-                    if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
-                        throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
-                    }
-                    const userOrder = this.buildOrderBy(args.orderBy, freshParams);
-                    sql += ` ORDER BY ${distinctCols.map((c) => `${c} ASC`).join(', ')}, ${userOrder}`;
-                    sql = `SELECT * FROM (${sql}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
-                }
-                else {
-                    // Pass freshParams so vector KNN ordering binds its `$n::vector` query
-                    // vector at the correct position (after cursor params, before LIMIT).
-                    sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
+            // ORDER BY is built AFTER the cursor pushes (param order
+            // where → with → cursor → orderBy → limit → offset) and BEFORE final
+            // assembly (so the lateral sink is filled before the FROM clause is
+            // written). distinct + relation orderBy is refused up front, so a lateral
+            // pick can never reach the distinct branch (lateralJoins stays empty).
+            let sql;
+            if (args?.orderBy && distinctPrefix) {
+                // Postgres requires DISTINCT ON expressions to lead the ORDER BY. Prisma
+                // semantics ("first row per combination, result in the user's order")
+                // need two levels: inner DISTINCT ON ordered by the distinct columns then
+                // the user's order (picks the right representative row), outer re-ordered
+                // by the user's order alone.
+                if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
+                    throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
+                const userOrder = this.buildOrderBy(args.orderBy, freshParams);
+                const inner = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${tail} ORDER BY ${distinctCols
+                    .map((c) => `${c} ASC`)
+                    .join(', ')}, ${userOrder}`;
+                sql = `SELECT * FROM (${inner}) AS ${this.q(`${this.table}_distinct`)} ORDER BY ${userOrder}`;
+            }
+            else {
+                // Pass freshParams so vector KNN ordering binds its `$n::vector` query
+                // vector at the correct position (after cursor params, before LIMIT), and
+                // lateralJoins so a lateral pick splices its join into the FROM clause.
+                const orderBySql = args?.orderBy
+                    ? ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams, lateralJoins)}`
+                    : '';
+                sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
             // Pagination — push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
@@ -4318,7 +4331,13 @@ export class QueryInterface {
             const pickWhere = d.pick?.where
                 ? `;pw=${this.fingerprintAliasWhere(d.pick.where, targetTable)}`
                 : '';
-            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere})`;
+            // Plan discriminator: the lateral plan emits DIFFERENT SQL (a FROM-clause
+            // join + a qualified order term) so a warm cache must never serve one
+            // plan's SQL for the other. Emitted ONLY for `'lateral'`: absent means
+            // the default subquery plan, keeping every pre-existing cache key
+            // byte-identical (no cold-cache churn on upgrade).
+            const planTag = d.plan === 'lateral' ? ';plan=lat' : '';
+            return `pick(${by},${d.direction ?? 'asc'},${d.nulls ?? ''};po=${pickOrder}${pickWhere}${planTag})`;
         }
         if (isOrderBySpec(d))
             return `spec(${d.sort},${d.nulls ?? ''})`;
@@ -4335,7 +4354,7 @@ export class QueryInterface {
         }
         return String(d);
     }
-    buildOrderBy(orderBy, params) {
+    buildOrderBy(orderBy, params, lateralSink) {
         // Dev-only: validate that orderBy fields exist in the table schema. Relation
         // orderBy keys (object values that are neither a vector nor an OrderBySpec)
         // are validated in the relation branch below, so skip them here.
@@ -4378,7 +4397,7 @@ export class QueryInterface {
             // keyed by a relation name (`{ posts: { _count: 'desc' } }` / `{ author:
             // { name: 'asc' } }`).
             if (this.isRelationOrderByValue(value)) {
-                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params);
+                return this.buildRelationOrderBy(key, value, `ord${relOrdCounter++}`, params, undefined, lateralSink);
             }
             // Scalar column ordering — a plain direction or an OrderBySpec (nulls).
             if (meta && !(key in meta.columnMap)) {
@@ -4472,7 +4491,18 @@ export class QueryInterface {
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+        // Rows whose document lacks the path extract to NULL. Without a nulls
+        // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
+        // pick-row ordering (NULLS LAST both directions since 0.33) and from
+        // engines whose path ordering is nulls-last in both directions. Default to
+        // NULLS LAST in BOTH directions unless the caller set `nulls` explicitly;
+        // the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `${lhs} ${dir}${nullsSql}`;
     }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
@@ -4487,7 +4517,7 @@ export class QueryInterface {
      * subquery's orderBy the relations live on the TARGET table's metadata and
      * the correlation parent is the relation's alias, not `this.table`.
      */
-    buildRelationOrderBy(relName, value, alias, params, ctx) {
+    buildRelationOrderBy(relName, value, alias, params, ctx, lateralSink) {
         const ownerMeta = ctx?.meta ?? this.tableMeta;
         const ownerTable = ctx?.table ?? this.table;
         const parentRef = ctx?.parentRef ?? this.table;
@@ -4503,7 +4533,7 @@ export class QueryInterface {
         // scope errors, shared with the cache-hit collect mirror.
         if (isRelationPickOrderBy(value)) {
             this.validatePickOrderBy(relName, relDef, value, ctx !== undefined);
-            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params);
+            return this.buildRelationPickOrderBy(relName, relDef, value, alias, parentRef, params, lateralSink);
         }
         // To-many: only `_count` is meaningful → correlated COUNT(*) subquery.
         if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
@@ -4595,6 +4625,25 @@ export class QueryInterface {
             throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" requires \`by\`: a target column name ` +
                 "or a JSON-path spec ({ field: 'data', path: ['title'] }).");
         }
+        // Physical plan gate. A typo like `plan: 'latreal'` must never silently run
+        // the subquery plan (a silent plan change wearing a validation gap). Shared
+        // by build and cache-hit collect so a warmed cache throws identically.
+        if (spec.plan !== undefined && spec.plan !== 'subquery' && spec.plan !== 'lateral') {
+            throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" has an invalid \`plan\`: ` +
+                `${JSON.stringify(spec.plan)}. Use 'subquery' (default) or 'lateral'.`);
+        }
+        if (spec.plan === 'lateral') {
+            if (!this.dialect.supportsLateralJoin) {
+                throw new UnsupportedFeatureError("pick-row ordering with plan: 'lateral'", this.dialect.name, "LATERAL joins are only available on PostgreSQL. Omit `plan` (or use 'subquery').");
+            }
+            // The lateral exposes one reserved output column, `__turbine_pick`. A
+            // parent column with that exact name would make the unqualified WHERE
+            // reference ambiguous once the join is in scope; refuse it explicitly.
+            if (this.tableMeta.allColumns.includes('__turbine_pick')) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' cannot be used: table "${this.tableMeta.name}" ` +
+                    'has a column named "__turbine_pick", which the lateral join output reserves.');
+            }
+        }
     }
     /**
      * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
@@ -4613,36 +4662,83 @@ export class QueryInterface {
      * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
      * target global filter → `pick.where` → `pick.orderBy` JSON paths.
      */
-    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params) {
+    buildRelationPickOrderBy(relName, relDef, spec, alias, parentRef, params, lateralSink) {
         if (!params) {
             throw new ValidationError(`[turbine] Pick-row ordering on relation "${relName}" is only supported in a top-level findMany orderBy.`);
         }
         const targetMeta = this.schema.tables[relDef.to];
         if (!targetMeta)
             throw new RelationError(`[turbine] Unknown relation target "${relDef.to}"`);
+        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        const limitOne = this.buildPagination('1', undefined, true);
+        // Parents with ZERO surviving related rows have no row to pick: the
+        // correlated subquery yields NULL, and the LEFT JOIN LATERAL null-extends
+        // its single row identically. Without a nulls clause, Postgres DESC
+        // defaults to NULLS FIRST (every childless parent tops a "highest first"
+        // sort). Default to NULLS LAST in BOTH directions (deterministic across
+        // engines: SQLite's NULL-is-smallest default diverges from Postgres) unless
+        // the caller set `nulls` explicitly; the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        // Lateral plan: splice a `LEFT JOIN LATERAL (... LIMIT 1) ON true` into the
+        // FROM clause (via the sink) and order by its single reserved output column.
+        // Param push order is IDENTICAL to the subquery plan (compilePickPieces is
+        // shared), so the cache-hit collect mirror needs no changes. Scope +
+        // capability were already enforced by validatePickOrderBy (shared with the
+        // collect path); the missing-sink guard catches a non-findMany build
+        // context and hard-fails rather than silently emitting a subquery.
+        if (spec.plan === 'lateral') {
+            if (!lateralSink) {
+                throw new ValidationError(`[turbine] Pick-row ordering with plan: 'lateral' on relation "${relName}" is only supported ` +
+                    'in a top-level findMany orderBy.');
+            }
+            const childAlias = `${alias}i`;
+            const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params);
+            lateralSink.push(` LEFT JOIN LATERAL (SELECT ${byExpr} AS ${this.q('__turbine_pick')} FROM ${this.q(relDef.to)} ${childAlias}` +
+                ` WHERE ${where}${orderClause}${limitOne}) ${alias} ON true`);
+            return `${alias}.${this.q('__turbine_pick')} ${dir}${nullsSql}`;
+        }
+        // Subquery plan (default): a correlated scalar subquery in ORDER BY.
+        const { byExpr, where, orderClause } = this.compilePickPieces(relDef, targetMeta, spec, alias, parentRef, params);
+        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+    }
+    /**
+     * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+     * (the table alias the related row is read from): the `by` value expression,
+     * the correlation + target global filter + `pick.where` predicate, and the
+     * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+     * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+     * push order (`by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths), which is why the collect mirror
+     * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+     */
+    compilePickPieces(relDef, targetMeta, spec, childAlias, parentRef, params) {
         // The value surfaced from the picked row (SELECT list: its param binds first).
         let byExpr;
         if (typeof spec.by === 'string') {
             const col = this.resolveOrderByColumn(relDef.to, targetMeta, spec.by);
-            byExpr = `${alias}.${this.q(col)}`;
+            byExpr = `${childAlias}.${this.q(col)}`;
         }
         else {
             const col = this.validateJsonPathOrderBy(relDef.to, targetMeta, spec.by.field, {
                 path: spec.by.path,
             });
             params.push(this.jsonPathParam(spec.by.path));
-            const extract = this.dialect.buildJsonPathExtract(`${alias}.${this.q(col)}`, this.p(params.length));
+            const extract = this.dialect.buildJsonPathExtract(`${childAlias}.${this.q(col)}`, this.p(params.length));
             byExpr = spec.by.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         }
         // Correlation to the parent row, then the target's global filter (a
         // soft-deleted / other-tenant row must never be picked: matches the
         // `with` subquery and to-one relation-orderBy semantics), then pick.where.
-        let where = this.dialect.buildCorrelation(alias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
-        const gf = this.targetGlobalFilterAlias(relDef.to, alias, params);
+        let where = this.dialect.buildCorrelation(childAlias, relDef.foreignKey, this.q(parentRef), relDef.referenceKey);
+        const gf = this.targetGlobalFilterAlias(relDef.to, childAlias, params);
         if (gf)
             where += ` AND ${gf}`;
         if (spec.pick.where) {
-            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, alias, spec.pick.where, params);
+            const pickWhere = this.buildAliasWhere(relDef.to, targetMeta, childAlias, spec.pick.where, params);
             if (pickWhere)
                 where += ` AND ${pickWhere}`;
         }
@@ -4650,21 +4746,8 @@ export class QueryInterface {
         // (plain columns, OrderBySpec nulls, JSON-path specs); a nested pick in
         // here routes back through buildRelationOrderBy with ctx set and throws
         // the top-level-only E003.
-        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, alias, Object.entries(spec.pick.orderBy), params);
-        const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        const limitOne = this.buildPagination('1', undefined, true);
-        // Parents with ZERO surviving related rows make the correlated subquery
-        // yield NULL. Without a nulls clause, Postgres DESC defaults to NULLS
-        // FIRST — every childless parent would top a "highest first" sort. Default
-        // to NULLS LAST in BOTH directions (deterministic across engines: SQLite's
-        // NULL-is-smallest default diverges from Postgres) unless the caller set
-        // `nulls` explicitly; the grammar gate matches nullsSuffix (PG + SQLite).
-        const nullsSql = spec.nulls
-            ? this.nullsSuffix(spec.nulls)
-            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
-                ? ' NULLS LAST'
-                : '';
-        return `(SELECT ${byExpr} FROM ${this.q(relDef.to)} ${alias} WHERE ${where}${orderClause}${limitOne}) ${dir}${nullsSql}`;
+        const orderClause = this.buildRelationOrderClause(relDef.to, targetMeta, childAlias, Object.entries(spec.pick.orderBy), params);
+        return { byExpr, where, orderClause };
     }
     /**
      * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same

package/dist/query/filters.d.ts

@@ -156,9 +156,9 @@ export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
 export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`

package/dist/query/filters.js

@@ -296,9 +296,9 @@ export function isJsonPathOrderBy(value) {
 }
 /**
  * Check if an orderBy value is a pick-row relation ordering:
- * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
- * required — `pick` must be an object carrying `orderBy`, `by` must be
- * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
  * relation whose target has real columns literally named `pick` and `by`
  * (whose values are direction strings or `{ sort, nulls }` specs, never an
  * object with `orderBy`) still falls through to column ordering. `distance`
@@ -316,7 +316,7 @@ export function isRelationPickOrderBy(value) {
     if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
         return false;
     for (const key of Object.keys(v)) {
-        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls' && key !== 'plan')
             return false;
     }
     return true;

package/dist/query/types.d.ts

@@ -618,6 +618,11 @@ export interface JsonPathGroupKey {
  * json/jsonb column, e.g. `SUM((col #>> $n::text[])::numeric)`. The arg key
  * is the result alias. `_sum`/`_avg` always cast numeric (a text sum is
  * meaningless); `_min`/`_max` compare as text unless `type: 'numeric'`.
+ *
+ * Engine note: when a group has NO value at the path, SQL engines return
+ * `null` for `_sum` (SUM over zero rows), while PowDB returns `0` (engine
+ * sum semantics). Treat `null` and `0` totals as equivalent when a group can
+ * be empty at the path.
  */
 export interface JsonPathAggregateTarget {
     /** json/jsonb column (camelCase field name, columnMap-resolved). */
@@ -758,15 +763,37 @@ export interface RelationFilter {
     is?: Record<string, unknown>;
     isNot?: Record<string, unknown>;
 }
-/** JSONB query operators for where clauses */
+/**
+ * JSONB query operators for where clauses.
+ *
+ * PowDB (`turbine-orm/powdb`) semantic deltas. The PowDB engine evaluates
+ * `->` path filters with full type knowledge, so a few behaviours differ from
+ * the Postgres `#>>`-text driver (documented, never silently wrong):
+ *   - `{ path, equals: null }` matches JSON null OR a MISSING key on PowDB
+ *     (compiles to `is null`), whereas the PG driver compares extracted text
+ *     against the string `'null'` and matches only a JSON string `"null"`.
+ *   - equality is TYPE-STRICT on PowDB: `{ path, equals: 7 }` matches a stored
+ *     JSON int `7` but not `7.0` or the JSON string `"7"` (PG text-extraction
+ *     matches `equals: 7` against the string `"7"`). Range ops (`gt`/`lt`/…)
+ *     still coerce int/float numerically.
+ *   - a digit-only path segment (`path: ['tags', '0']`) is an ARRAY INDEX on
+ *     both PowDB and the SQL engines (a json object key that is literally `"0"`
+ *     is likewise addressed by index).
+ *   - `contains`, and `equals` WITHOUT a `path` (whole-document containment),
+ *     throw `UnsupportedFeatureError` (E017) on PowDB: PowQL has no containment
+ *     operator.
+ */
 export interface JsonFilter {
-    /** Access nested path via #>> operator */
+    /**
+     * Access nested path via `#>>` operator (Postgres) / `->` path (PowDB). A
+     * digit-only segment (`'0'`) is treated as an array index on every engine.
+     */
     path?: string[];
-    /** Exact match: column @> value::jsonb (containment) */
+    /** Exact match: `column @> value::jsonb` (containment). On PowDB, requires `path` and compares the typed value (throws E017 without `path`). */
     equals?: unknown;
-    /** Containment check: column @> value::jsonb */
+    /** Containment check: `column @> value::jsonb`. Unsupported on PowDB (E017: PowQL has no containment operator). */
     contains?: unknown;
-    /** Key existence check: column ? key */
+    /** Key existence check: `column ? key`. */
     hasKey?: string;
     /**
      * Greater-than comparison of the value at `path` (required). Numbers cast
@@ -897,7 +924,13 @@ export interface JsonPathOrderBy {
     direction?: OrderDirection;
     /** Comparison kind for the extracted value. Defaults to `'text'`; `'numeric'` adds a numeric cast. */
     type?: 'numeric' | 'text';
-    /** NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}). */
+    /**
+     * NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}).
+     * Rows whose document lacks the path extract to NULL and sort LAST in BOTH
+     * directions by default (matching pick-row ordering and the PowDB engine
+     * contract, so ordering is predictable across drivers); set `nulls` to
+     * override on PostgreSQL / SQLite.
+     */
     nulls?: 'first' | 'last';
 }
 /**
@@ -979,6 +1012,17 @@ export interface RelationPickOrderBy {
      * "highest first" sort). Set `nulls` explicitly to override.
      */
     nulls?: 'first' | 'last';
+    /**
+     * Physical plan for the pick. `'subquery'` (default) compiles a correlated
+     * scalar subquery in ORDER BY. `'lateral'` (PostgreSQL only, E017 elsewhere)
+     * compiles a `LEFT JOIN LATERAL (... LIMIT 1) ON true` and orders by the
+     * joined value. Identical results; the lateral form can be significantly
+     * faster on large parent sets where the ordering subquery dominates the plan.
+     * Never falls back silently: contexts that cannot take a lateral (non-Postgres
+     * engines, `distinct`, nested `with` orderBy, a parent column literally named
+     * `__turbine_pick`) throw.
+     */
+    plan?: 'subquery' | 'lateral';
 }
 /**
  * An orderBy clause maps each key to one of:

package/dist/schema-builder.d.ts

@@ -126,6 +126,42 @@ export interface CheckDef {
     /** Raw SQL boolean expression, e.g. `price > cost`. */
     expression: string;
 }
+/** A plain (column-list) index declaration. */
+export interface ColumnIndexDef {
+    /** camelCase field name(s) the index covers. */
+    columns: string[];
+    /** Whether the index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A doc-field expression index on a JSON document column (PowDB ≥ 0.13).
+ * Indexes the value at `docField-><path>` inside the json document, so a
+ * `JsonFilter`/`orderBy` on that path can use an index instead of a scan.
+ */
+export interface DocFieldIndexDef {
+    /** camelCase field name of the json document column. */
+    docField: string;
+    /** JSON path into the document: string keys and integer array indexes. */
+    path: (string | number)[];
+    /** Whether the expression index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A single index declaration on a table: either a plain column-list index
+ * ({@link ColumnIndexDef}) or a doc-field expression index into a json column
+ * ({@link DocFieldIndexDef}).
+ *
+ * Consumed today by the PowDB DDL generator (`powqlSchemaDDL`) and carried onto
+ * {@link import('./schema.js').IndexMetadata} by `schemaDefToMetadata`. The SQL
+ * DDL generators (`schema-sql.ts` / `schemaDiff`) do NOT consume these yet.
+ */
+export type SchemaIndexDef = ColumnIndexDef | DocFieldIndexDef;
+/** Type guard: is this index declaration a doc-field expression index? */
+export declare function isDocFieldIndexDef(idx: SchemaIndexDef): idx is DocFieldIndexDef;
 export interface TableDef {
     /**
      * DDL-facing table name (snake_case). This is the name used when generating
@@ -159,6 +195,13 @@ export interface TableDef {
     manyToMany?: readonly ManyToManyDef[];
     /** Table-level `CHECK` constraints. */
     checks?: readonly CheckDef[];
+    /**
+     * Index declarations for this table (plain column indexes and/or PowDB
+     * doc-field expression indexes). Consumed by the PowDB DDL generator
+     * (`powqlSchemaDDL`) and carried onto `IndexMetadata` by
+     * `schemaDefToMetadata`; the SQL DDL generators do not consume them yet.
+     */
+    indexes?: readonly SchemaIndexDef[];
 }
 /**
  * User-facing input shape for a single table when using the object format.
@@ -171,8 +214,10 @@ export interface TableInput {
     manyToMany?: readonly ManyToManyDef[];
     /** Optional table-level CHECK constraints */
     checks?: readonly CheckDef[];
+    /** Optional index declarations (plain column and/or doc-field expression) */
+    indexes?: readonly SchemaIndexDef[];
     /** Column definitions keyed by camelCase field name */
-    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | undefined;
+    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | readonly SchemaIndexDef[] | undefined;
 }
 export interface SchemaDef {
     /**

package/dist/schema-builder.js

@@ -96,6 +96,10 @@ function resolveColumn(def) {
         check: def.check ?? null,
     };
 }
+/** Type guard: is this index declaration a doc-field expression index? */
+export function isDocFieldIndexDef(idx) {
+    return 'docField' in idx && typeof idx.docField === 'string';
+}
 /** Check if a value is a TableDef (from legacy table() builder) */
 function isTableDef(v) {
     return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
@@ -139,7 +143,17 @@ export function defineSchema(input, options) {
             let pk;
             let m2m;
             let checks;
+            let indexes;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'indexes') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                        }
+                        indexes = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
@@ -199,6 +213,7 @@ export function defineSchema(input, options) {
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
                 ...(checks && checks.length > 0 ? { checks } : {}),
+                ...(indexes && indexes.length > 0 ? { indexes } : {}),
             };
         }
     }

package/dist/schema-metadata.d.ts

@@ -24,10 +24,12 @@
  *     the same conservative auto-`manyToMany` treatment as introspection.
  *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
  *     {@link applyManyToManyRelations} (additive, never clobbering).
- *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
- *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
- *     and the dev-mode missing-index warning stay silent instead of
- *     producing blanket false positives.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -67,10 +69,14 @@ import { type SchemaDef } from './schema-builder.js';
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * What SchemaDef cannot express (and how it degrades):
- *   - Indexes → every table gets `indexes: []`, which keeps
- *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
- *     false positives on code-first metadata.
  *   - Views → never marked (`isView` is introspection-only).
  *   - Composite foreign keys → `references:` is single-column by design.
  */