uql-orm 0.69.0 → 0.71.0

package/dist/dialect/abstractSqlDialect.js

@@ -3,10 +3,10 @@ import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEY
 import { isInlinedExpression } from '../util/field.util.js';
 import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
-import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, COUNT_ALIAS, COUNTED_ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
+import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
 import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
+import { groupPathField, NO_JOINS, resolveGroupJoins, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** The key a term answers under in a populated relation's row, which a raw expression has only once aliased. */
@@ -150,7 +150,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (opts.prefix !== prefix) {
             opts = { ...opts, prefix };
         }
-        this.where(ctx, entity, q.$where, opts);
+        this.where(ctx, entity, this.rankedWhere(meta, q, prefix), opts);
         const sorted = order
             ? this.orderCarried(ctx, q, order)
             : this.sort(ctx, entity, q.$sort, { prefix, joins, distinct: q.$distinct });
@@ -916,7 +916,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     count(ctx, entity, q, opts) {
         const { $where, $skip, $limit } = q;
         if ($skip === undefined && $limit === undefined) {
-            this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(COUNT_ALIAS)] });
+            this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(AGGREGATE_VALUE_ALIAS)] });
             this.search(ctx, entity, { $where }, opts);
             return;
         }
@@ -936,9 +936,9 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** `SELECT COUNT(*)` over the rows `rows` appends, as a derived table. */
     countRows(ctx, rows) {
-        ctx.append(`SELECT COUNT(*) ${this.escapeId(COUNT_ALIAS, true)} FROM (`);
+        ctx.append(`SELECT COUNT(*) ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM (`);
         rows();
-        ctx.append(`) ${this.escapeId(COUNTED_ROWS_ALIAS, true)}`);
+        ctx.append(`) ${this.escapeId(ROWS_ALIAS, true)}`);
     }
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
@@ -958,35 +958,40 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     };
     aggregate(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
-        const tableName = this.escapedTableName(meta);
+        const entries = parseGroupMap(q.$group, q.$select);
+        if (!entries.length) {
+            throw new TypeError('aggregate requires at least one $group column or $select function');
+        }
+        const table = this.tableRef(meta, this.readOptions(ctx, meta).alias);
+        const { joins, where } = resolveGroupJoins(meta, q, (path) => ctx.claimAlias(path));
+        const prefix = joins.size ? table.alias : undefined;
+        const reads = entries.map((entry) => ({ entry, value: this.aggregateValue(ctx, entity, entry, joins, prefix) }));
+        // Only bare columns are read inline: SQL Server refuses a subquery inside an aggregate or a
+        // `GROUP BY`, and a filter's bound values would repeat in `HAVING`. A derived table answers by alias.
+        const derived = reads.some(({ value }) => !value.bare);
+        const named = (sql, alias) => sql === this.escapeId(alias) ? sql : `${sql} ${this.escapeId(alias)}`;
         const groupKeys = [];
         const selectParts = [];
         // Every column the statement emits, mapped to the SQL that references it. `$having` and `$sort`
         // may name these and nothing else, so one map answers both "is this legal?" and "what do I
         // emit for it?".
         const emittedColumns = {};
-        for (const entry of parseGroupMap(q.$group, q.$select)) {
+        for (const { entry, value } of reads) {
+            const column = derived ? this.escapeId(entry.alias) : value.sql;
+            const expr = entry.kind === 'key' ? column : this.aggregateFn(entry.op, value.sql === '*' ? '*' : column, entry.distinct);
             if (entry.kind === 'key') {
-                const field = meta.fields[entry.alias];
-                const columnName = this.resolveColumnName(entry.alias, field);
-                const escaped = this.escapeId(columnName);
-                groupKeys.push(escaped);
-                emittedColumns[entry.alias] = escaped;
-                selectParts.push(columnName !== entry.alias ? `${escaped} ${this.escapeId(entry.alias)}` : escaped);
-            }
-            else {
-                const sqlFn = AbstractSqlDialect.AGGREGATE_FN[entry.op];
-                const sqlArg = entry.fieldRef === '*' ? '*' : this.escapeId(this.columnOf(meta, entry.fieldRef));
-                const expr = `${sqlFn}(${entry.distinct ? 'DISTINCT ' : ''}${sqlArg})`;
-                emittedColumns[entry.alias] = expr;
-                selectParts.push(`${expr} ${this.escapeId(entry.alias)}`);
+                groupKeys.push(expr);
             }
+            emittedColumns[entry.alias] = expr;
+            selectParts.push(named(expr, entry.alias));
         }
-        if (!selectParts.length) {
-            throw new TypeError('aggregate requires at least one $group column or $select function');
+        const columns = reads.flatMap(({ entry, value }) => (value.sql === '*' ? [] : [named(value.sql, entry.alias)]));
+        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${derived ? `(SELECT ${columns.join(', ')} FROM ` : ''}${table.ref}`);
+        this.selectRelationJoins(ctx, meta, table.alias, joins);
+        this.where(ctx, entity, where, { ...opts, prefix });
+        if (derived) {
+            ctx.append(`) ${this.escapeId(ROWS_ALIAS, true)}`);
         }
-        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${tableName}`);
-        this.where(ctx, entity, q.$where, opts);
         if (groupKeys.length) {
             ctx.append(` GROUP BY ${groupKeys.join(', ')}`);
         }
@@ -996,6 +1001,34 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const sorted = this.aggregateSort(ctx, q.$sort, emittedColumns);
         this.pager(ctx, q, sorted);
     }
+    /**
+     * What one entry reads: a grouped field, through the join its path passes, or an aggregate's argument,
+     * narrowed by its own `$where` to `CASE WHEN … THEN … END`. Bare where it is a column or `'*'`.
+     */
+    aggregateValue(ctx, entity, entry, joins, prefix) {
+        if (entry.kind === 'key') {
+            const { key, join } = groupPathField(joins, entry.path);
+            return join
+                ? this.aggregateOperand(ctx, join.entity, key, join.alias)
+                : this.aggregateOperand(ctx, entity, key, prefix);
+        }
+        const arg = entry.fieldRef === '*' ? undefined : this.aggregateOperand(ctx, entity, entry.fieldRef, prefix);
+        const { where } = entry;
+        const condition = where &&
+            this.buildFragment(ctx, (fragment) => this.renderWhere(fragment, entity, where, { clause: false, prefix }));
+        if (!condition) {
+            return arg ?? { sql: '*', bare: true };
+        }
+        return { sql: `CASE WHEN ${condition} THEN ${arg?.sql ?? '1'} END`, bare: false };
+    }
+    /** A field as an aggregate reads it: its column, or the expression an inlined one stands for. */
+    aggregateOperand(ctx, entity, key, prefix) {
+        const field = getMeta(entity).fields[key];
+        return {
+            sql: this.resolveOperandField(ctx, entity, key, { prefix }),
+            bare: field === undefined || !isInlinedExpression(field),
+        };
+    }
     /**
      * ORDER BY for aggregate queries - handles both entity-field and alias references. A grouped
      * statement has no joins to address, so a relation key is rejected rather than emitted as an alias
@@ -1094,6 +1127,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             ctx.append(` ${returning}`);
         }
     }
+    /**
+     * What a text search matches and a fulltext index covers, which have to agree for the index to serve the
+     * search: the columns themselves, where the engine indexes them as they are (MySQL's `MATCH (a, b)`).
+     */
+    textSearchTarget(columns, _config) {
+        return columns.join(', ');
+    }
     /** Where an insert's id clause goes: `RETURNING` at the end, or SQL Server's `OUTPUT` before `VALUES`. */
     returningPosition = 'suffix';
     /**
@@ -1296,7 +1336,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         const decoded = [];
         for (const [key, field] of Object.entries(meta.fields)) {
-            const kind = this.aggregateHydrateKind(meta, field) ?? this.hydrateKind(field);
+            const kind = this.fieldKind(meta, field);
             if (kind) {
                 decoded.push([key, kind]);
             }
@@ -1306,13 +1346,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** The same for an aggregate's row, per query: each alias decodes by {@link aggregateKind}. */
     hydratableAggregates(entity, q) {
-        const { fields } = getMeta(entity);
+        const meta = getMeta(entity);
+        const { joins } = resolveGroupJoins(meta, q);
         const decoded = [];
         for (const entry of parseGroupMap(q.$group, q.$select)) {
-            // A grouped column is the field itself; an aggregate reads the one it aggregates, `'*'` for a tally.
-            const key = entry.kind === 'fn' ? entry.fieldRef : entry.alias;
-            const field = fields[key];
-            const kind = entry.kind === 'fn' ? this.aggregateKind(entry.op, field) : this.hydrateKind(field);
+            const kind = entry.kind === 'fn'
+                ? this.aggregateKind(entry.op, this.fieldKind(meta, meta.fields[entry.fieldRef]))
+                : this.groupedKind(meta, joins, entry.path);
             if (kind) {
                 decoded.push([entry.alias, kind]);
             }
@@ -1327,17 +1367,22 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      *
      * One rule for both readers: a relation aggregate a field declares, and an aggregate a query names.
      */
-    aggregateKind(op, field) {
-        return op === '$count' || op === '$avg' ? 'number' : this.hydrateKind(field);
+    aggregateKind(op, fieldKind) {
+        return op === '$count' || op === '$avg' ? 'number' : fieldKind;
+    }
+    /** What a grouped path decodes as: the kind of the field it reaches, through its join or on the entity. */
+    groupedKind(meta, joins, path) {
+        const { key, join } = groupPathField(joins, path);
+        return join ? this.fieldKind(join.meta, join.meta.fields[key]) : this.fieldKind(meta, meta.fields[key]);
     }
-    /** What a relation aggregate a field declares decodes as: {@link aggregateKind} over the target's column. */
-    aggregateHydrateKind(meta, field) {
+    /** What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind} over the target's column. */
+    fieldKind(meta, field) {
         const spec = aggregateOf(field);
         if (!spec) {
-            return undefined;
+            return this.hydrateKind(field);
         }
         const target = getMeta(relationOf(meta, spec.relation).entity());
-        return this.aggregateKind(spec.op, spec.field ? target.fields[spec.field] : undefined);
+        return this.aggregateKind(spec.op, spec.field ? this.fieldKind(target, target.fields[spec.field]) : undefined);
     }
     /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
     hydrateKind(field) {
@@ -1349,7 +1394,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             case 'json':
                 return 'json';
             case 'vector':
-                return this.supportedVectorType(resolveVectorCast(field));
+                return this.features.vectorBytes ? 'float32' : this.supportedVectorType(resolveVectorCast(field));
             case 'boolean':
                 return 'boolean';
             case 'numeric':
@@ -1395,8 +1440,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * `$pull` reads the column and every later one its expression once, so no value binds twice.
      */
     formatJsonUpdate(ctx, escapedCol, value, field) {
-        // Centralizes the one narrowing cast: the payload's keys are typed against the entity's JSON
-        // payload, which the dialects do not need - they only build SQL from keys and values.
         const { $pull, $set, $push, $unset } = value;
         let expr = escapedCol;
         if (hasKeys($pull)) {
@@ -1584,7 +1627,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const meta = getMeta(entity);
         const rel = relationOf(meta, aggregate.relation);
         const parent = prefix || this.resolveTableAlias(meta);
-        if (!aggregate.query?.$limit && aggregate.query?.$skip === undefined) {
+        const { $limit, $skip } = aggregate.query ?? {};
+        if ($limit === undefined && $skip === undefined) {
             this.appendRelationSubquery(ctx, meta, aggregate.relation, rel, { prefix: parent }, aggregate);
             return;
         }
@@ -1616,14 +1660,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const joins = resolveQueryJoins(getMeta(entity), query, (path) => ctx.claimAlias(path));
         this.read(ctx, entity, query, { alias }, joins);
     }
-    /** One aggregate over an operand, `COALESCE`d where the aggregate answers `0` on no rows rather than null. */
+    /** A relation aggregate over an operand, reading `0` on a parent with no rows where its type says so. */
     aggregateCall(op, operand) {
-        if (op === '$count') {
-            return 'COUNT(*)';
-        }
-        const call = `${AbstractSqlDialect.AGGREGATE_FN[op]}(${operand})`;
+        const call = this.aggregateFn(op, op === '$count' ? '*' : operand);
         return op === '$sum' ? `COALESCE(${call}, 0)` : call;
     }
+    /** One aggregate function call, the one spelling every statement that aggregates writes. */
+    aggregateFn(op, operand, distinct) {
+        return `${AbstractSqlDialect.AGGREGATE_FN[op]}(${distinct ? 'DISTINCT ' : ''}${operand})`;
+    }
     /**
      * One equality per key of the parent, anded: a composite correlates on every column, and matching on
      * part of one would find the rows of a different parent. `parentJoins` keeps the two ends the right

package/dist/dialect/aliases.d.ts

@@ -1,17 +1,20 @@
-/** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
-export declare const COUNT_ALIAS = "_uql_count";
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export declare const TOTAL_ALIAS = "_uql_total";
-/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
-export declare const COUNTED_ROWS_ALIAS = "_uql_rows";
+/**
+ * The derived table a statement wraps the rows it counts or aggregates in: a page, a `$distinct` set, or
+ * rows computing an inlined field an aggregate names. MySQL requires the alias.
+ */
+export declare const ROWS_ALIAS = "_uql_rows";
 /** The derived table a capped relation aggregate reads: the page is taken first, then aggregated over. */
 export declare const AGGREGATE_PAGE_ALIAS = "_uql_page";
 /**
- * What an aggregate answers under: the column a capped page carries out for the aggregate wrapping it,
- * and the field a MongoDB `$group` or `$count` leaves its value in. One name, since both ends of each
- * are written and read here.
+ * The one value a statement that aggregates answers under: a `COUNT(*)` or an estimate, the column a
+ * capped page carries out for the aggregate wrapping it, and the field a MongoDB `$group` or `$count`
+ * leaves its result in. One name, since both ends of each are written and read here.
  */
 export declare const AGGREGATE_VALUE_ALIAS = "_uql_value";
+/** Beside each MongoDB `$sum`, how many values it read: `$sum` answers 0 over none, where SQL answers null. */
+export declare const SUM_COUNT_ALIAS = "_uql_count";
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export declare const RELATION_ROW_ALIAS = "_uql_row";
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/aliases.js

@@ -1,19 +1,22 @@
 // Every identifier UQL invents, `_uql`-prefixed to stay off a user's own, collected in one place:
 // the ends writing and reading one sit in different modules, and a drift between them fails silently.
-/** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
-export const COUNT_ALIAS = '_uql_count';
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export const TOTAL_ALIAS = '_uql_total';
-/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
-export const COUNTED_ROWS_ALIAS = '_uql_rows';
+/**
+ * The derived table a statement wraps the rows it counts or aggregates in: a page, a `$distinct` set, or
+ * rows computing an inlined field an aggregate names. MySQL requires the alias.
+ */
+export const ROWS_ALIAS = '_uql_rows';
 /** The derived table a capped relation aggregate reads: the page is taken first, then aggregated over. */
 export const AGGREGATE_PAGE_ALIAS = '_uql_page';
 /**
- * What an aggregate answers under: the column a capped page carries out for the aggregate wrapping it,
- * and the field a MongoDB `$group` or `$count` leaves its value in. One name, since both ends of each
- * are written and read here.
+ * The one value a statement that aggregates answers under: a `COUNT(*)` or an estimate, the column a
+ * capped page carries out for the aggregate wrapping it, and the field a MongoDB `$group` or `$count`
+ * leaves its result in. One name, since both ends of each are written and read here.
  */
 export const AGGREGATE_VALUE_ALIAS = '_uql_value';
+/** Beside each MongoDB `$sum`, how many values it read: `$sum` answers 0 over none, where SQL answers null. */
+export const SUM_COUNT_ALIAS = '_uql_count';
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export const RELATION_ROW_ALIAS = '_uql_row';
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/hydrateColumn.d.ts

@@ -3,9 +3,10 @@ import { type VectorCast } from './vectorCast.js';
  * How a stored column is decoded on read: the inverse of `AbstractSqlDialect.persistKind`. `json`
  * parses; a {@link VectorCast} says which literal; `boolean` undoes an engine with no boolean type,
  * `number` and `bigint` a driver that hands a wide integer or a decimal back as text, and `date` and
- * `bytes` a row that crossed JSON inside its parent's statement, which spells both as text.
+ * `bytes` a row that crossed JSON inside its parent's statement, which spells both as text. `float32` is
+ * a vector bound as bytes (`DialectFeatures.vectorBytes`).
  */
-export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | 'date' | 'bytes' | VectorCast;
+export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | 'date' | 'bytes' | 'float32' | VectorCast;
 /**
  * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
  * and untouched where it does not match its column's format.

package/dist/dialect/hydrateColumn.js

@@ -20,6 +20,14 @@ function vectorDecoder(cast) {
         ? decodeFloat32s(hexBytes(text.slice(BYTES_PREFIX.length)))
         : (parseVectorLiteral(text, cast) ?? value));
 }
+const denseVector = vectorDecoder('vector');
+/** A vector bound as bytes: packed float32s as a driver returns them, else hex or text, as JSON or an older row carries it. */
+const float32Decoder = (value) => {
+    if (value instanceof ArrayBuffer) {
+        return decodeFloat32s(new Uint8Array(value));
+    }
+    return value instanceof Uint8Array ? decodeFloat32s(value) : denseVector(value);
+};
 const DECODERS = {
     // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
     boolean: (value) => (typeof value === 'boolean' ? value : Boolean(value)),
@@ -48,7 +56,8 @@ const DECODERS = {
             return value;
         }
     }),
-    vector: vectorDecoder('vector'),
+    float32: float32Decoder,
+    vector: denseVector,
     halfvec: vectorDecoder('halfvec'),
     sparsevec: vectorDecoder('sparsevec'),
 };

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -2,7 +2,7 @@ import { getMeta } from '../entity/index.js';
 import { textSearchFields } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect, } from './abstractSqlDialect.js';
-import { COUNT_ALIAS } from './aliases.js';
+import { AGGREGATE_VALUE_ALIAS } from './aliases.js';
 import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonSetCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
 import { aggregatesRelations } from './queryJoins.js';
@@ -23,10 +23,12 @@ export const MYSQL_FEATURES = {
     commentSyntax: 'inline',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
+    vectorBytes: false,
     supportsTimestamptz: false,
     stringSizing: 'varchar',
     supportsUnsigned: true,
     serverSideCursors: false,
+    correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
@@ -49,7 +51,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     estimatedCount(ctx, entity) {
         const meta = getMeta(entity);
         const schema = this.resolveSchema(meta);
-        ctx.append(`SELECT TABLE_ROWS ${this.escapeId(COUNT_ALIAS, true)} FROM information_schema.TABLES WHERE TABLE_SCHEMA = `);
+        ctx.append(`SELECT TABLE_ROWS ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM information_schema.TABLES WHERE TABLE_SCHEMA = `);
         if (schema) {
             ctx.addValue(schema);
         }
@@ -177,7 +179,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      */
     appendTextSearch(ctx, _entity, meta, search) {
         const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
-        ctx.append(`MATCH(${columns.join(', ')}) AGAINST(`);
+        ctx.append(`MATCH(${this.textSearchTarget(columns)}) AGAINST(`);
         ctx.addValue(search.$value);
         ctx.append(')');
     }

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,3 +1,4 @@
+import type { IndexType } from '../schema/types.js';
 import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
 import type { DialectOptions } from './abstractDialect.js';
 import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
@@ -45,11 +46,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly maxBindValues: number;
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /**
-     * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
+     * The setting each vector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
      * `$candidates` is documented in the index's own units rather than as a portable number.
      */
-    private static readonly ANN_SETTINGS;
+    protected readonly annSettings: ReadonlyMap<IndexType, string>;
     /**
      * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan = strict_order` where the query also filters
      * by distance, which would otherwise drop rows the candidate list missed.
@@ -58,11 +59,22 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     normalizeValue(value: unknown): unknown;
     placeholder(index: number): string;
     /**
-     * `TO_TSVECTOR(...) @@ WEBSEARCH_TO_TSQUERY(...)`. `WEBSEARCH_TO_TSQUERY` takes free-form user input
-     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`, which
-     * rejects anything unparseable - including a plain two-word search.
+     * `<document> @@ WEBSEARCH_TO_TSQUERY(...)`, under the `$config` asked for, else that of the fulltext
+     * index over these fields, which the planner serves it from. `WEBSEARCH_TO_TSQUERY` takes free-form
+     * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /**
+     * The document, `TO_TSVECTOR('english'::regconfig, COALESCE("a", '') || ' ' || COALESCE("b", ''))`, a
+     * `NULL` column read as empty rather than emptying it all. The config is a literal: an index is built
+     * over one, and a bound one reaches it only where the driver leaves the parameter untyped.
+     */
+    textSearchTarget(columns: readonly string[], config?: string): string;
+    /** A config as the text-search functions' first argument, or nothing, for the server's default. */
+    private textConfigArg;
+    /** How a config literal is typed, and the function reading a search's text: CockroachDB lacks both of these. */
+    protected readonly textConfigCast: string;
+    protected readonly textQueryFn: string;
     protected jsonContains(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
     protected jsonLength(slot: JsonSlot): string;
     /** Each element stays `jsonb`, so it is read as any path is: `->` for the value, `->>` for its text. */

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,5 +1,5 @@
 import { QueryRaw, } from '../type/index.js';
-import { hasVectorNear, textSearchFields } from '../util/dialect.util.js';
+import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
@@ -13,6 +13,8 @@ export const PG_VECTOR_METRICS = new Map([
     ['inner', { op: '<#>', index: 'ip' }],
     ['l1', { op: '<+>', index: 'l1' }],
 ]);
+/** pgvector's HNSW candidate list, the one setting an iterative scan goes with. */
+const HNSW_EF_SEARCH = 'hnsw.ef_search';
 /** What the Postgres-wire engines have. */
 export const PG_FEATURES = {
     ifNotExists: true,
@@ -25,10 +27,12 @@ export const PG_FEATURES = {
     commentSyntax: 'statement',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,
+    vectorBytes: false,
     supportsTimestamptz: true,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
     serverSideCursors: true,
+    correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: false,
     rowLockOf: true,
@@ -86,12 +90,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     maxBindValues = 65535;
     vectorMetrics = PG_VECTOR_METRICS;
     /**
-     * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
+     * The setting each vector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
      * `$candidates` is documented in the index's own units rather than as a portable number.
      */
-    static ANN_SETTINGS = new Map([
-        ['hnsw', 'hnsw.ef_search'],
+    annSettings = new Map([
+        ['hnsw', HNSW_EF_SEARCH],
         ['ivfflat', 'ivfflat.probes'],
     ]);
     /**
@@ -100,12 +104,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     vectorTuningStatements(meta, q) {
         const indexType = this.tunedVectorIndex(meta, q)?.type;
-        const setting = indexType ? PgLikeSqlDialect.ANN_SETTINGS.get(indexType) : undefined;
+        const setting = indexType ? this.annSettings.get(indexType) : undefined;
         if (!setting) {
             return [];
         }
         const statements = [`SET LOCAL ${setting} = ${q.$candidates}`];
-        if (indexType === 'hnsw' && hasVectorNear(q.$where)) {
+        if (setting === HNSW_EF_SEARCH && hasVectorNear(q.$where)) {
             statements.push('SET LOCAL hnsw.iterative_scan = strict_order');
         }
         return statements;
@@ -120,20 +124,35 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return `$${index}`;
     }
     /**
-     * `TO_TSVECTOR(...) @@ WEBSEARCH_TO_TSQUERY(...)`. `WEBSEARCH_TO_TSQUERY` takes free-form user input
-     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`, which
-     * rejects anything unparseable - including a plain two-word search.
+     * `<document> @@ WEBSEARCH_TO_TSQUERY(...)`, under the `$config` asked for, else that of the fulltext
+     * index over these fields, which the planner serves it from. `WEBSEARCH_TO_TSQUERY` takes free-form
+     * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
     appendTextSearch(ctx, _entity, meta, search) {
-        const fields = textSearchFields(meta, search)
-            .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
-            .join(` || ' ' || `);
-        // The config is bound once and its numbered placeholder reused by both calls.
-        const config = search.$config ? `${this.addValue(ctx, search.$config)}::regconfig, ` : '';
-        ctx.append(`TO_TSVECTOR(${config}${fields}) @@ WEBSEARCH_TO_TSQUERY(${config}`);
+        const keys = textSearchFields(meta, search);
+        const index = fulltextIndexOver(meta, keys);
+        const config = search.$config ?? (index && fulltextConfig(index));
+        const columns = keys.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        ctx.append(`${this.textSearchTarget(columns, config)} @@ ${this.textQueryFn}(${this.textConfigArg(config)}`);
         ctx.addValue(search.$value);
         ctx.append(')');
     }
+    /**
+     * The document, `TO_TSVECTOR('english'::regconfig, COALESCE("a", '') || ' ' || COALESCE("b", ''))`, a
+     * `NULL` column read as empty rather than emptying it all. The config is a literal: an index is built
+     * over one, and a bound one reaches it only where the driver leaves the parameter untyped.
+     */
+    textSearchTarget(columns, config) {
+        const document = columns.map((column) => `COALESCE(${column}, '')`).join(` || ' ' || `);
+        return `TO_TSVECTOR(${this.textConfigArg(config)}${document})`;
+    }
+    /** A config as the text-search functions' first argument, or nothing, for the server's default. */
+    textConfigArg(config) {
+        return config === undefined ? '' : `${this.escape(config)}${this.textConfigCast}, `;
+    }
+    /** How a config literal is typed, and the function reading a search's text: CockroachDB lacks both of these. */
+    textConfigCast = '::regconfig';
+    textQueryFn = 'WEBSEARCH_TO_TSQUERY';
     jsonContains(ctx, slot, values) {
         return `${this.jsonValue(slot)} @> ${this.jsonVal(ctx, values)}`;
     }

package/dist/dialect/queryJoins.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, Query, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
+import type { EntityMeta, Query, QueryGroupMap, QuerySortMap, QueryWhere, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -39,6 +39,24 @@ export type QuerySortOptions = {
  * columns, the `ORDER BY` and the lock agree. `claimAlias` names each join's table, parents first.
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
+/**
+ * What an aggregate joins, and the `$where` left to it. Each to-one relation a `$group` path passes through
+ * is an `INNER` join, since a group of a path names a related row; a filter on one of them, keyed at the top
+ * of the `$where` where an `AND` joins it, moves into that join rather than reading its table again. Under a
+ * `$not` it could not: the join would drop the rows the negation keeps.
+ */
+export declare function resolveGroupJoins<E>(meta: EntityMeta<E>, q: {
+    readonly $group?: QueryGroupMap<E>;
+    readonly $where?: QueryWhere<E>;
+}, claimAlias?: (path: string) => string): {
+    readonly joins: QueryJoins;
+    readonly where: QueryWhere<E> | undefined;
+};
+/** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
+export declare function groupPathField(joins: QueryJoins, path: readonly string[]): {
+    readonly key: string;
+    readonly join: QueryJoin | undefined;
+};
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or