uql-orm 0.70.0 → 0.71.0

package/README.md

@@ -65,6 +65,8 @@ The compiler catches each of those, with no codegen: the entity classes are the
 - [Entities](https://uql-orm.dev/entities/basic) - decorators, relations, hooks, or the decorator-free [imperative API](https://uql-orm.dev/entities/imperative)
 - [Switching to UQL](https://uql-orm.dev/switching-to-uql) - coming from Prisma, Drizzle, TypeORM, or MikroORM
 
+Using a coding agent? The package ships a [skill](skills/uql-orm/SKILL.md) for it (`npx @tanstack/intent install`, or `npx skills add rogerpadilla/uql`), and every docs page is Markdown, indexed at [uql-orm.dev/llms.txt](https://uql-orm.dev/llms.txt).
+
 Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/main/CHANGELOG.md).
 
 ---

package/dist/cockroachdb/cockroachDialect.d.ts

@@ -1,4 +1,5 @@
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
+import type { IndexType } from '../schema/types.js';
 import type { QueryContext, SqlDialectFeatures, Type } from '../type/index.js';
 /** CockroachDB: the Postgres wire and SQL, without `xmax` (so no upsert `created`) and with native vectors. */
 export declare class CockroachDialect extends PgLikeSqlDialect {
@@ -9,6 +10,11 @@ export declare class CockroachDialect extends PgLikeSqlDialect {
      * Re-check that issue before adding it.
      */
     readonly vectorMetrics: Map<import("../type/vector.js").VectorDistance, import("../type/vector.js").VectorMetric>;
+    /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.3): the config goes as text, the search as plain words. */
+    protected readonly textConfigCast = "";
+    protected readonly textQueryFn = "PLAINTO_TSQUERY";
+    /** Its own beam for either type that builds its vector index; it refuses pgvector's `hnsw.ef_search`. */
+    protected readonly annSettings: ReadonlyMap<IndexType, string>;
     /** An upsert batch mixing an update and an insert returns the update first (verified on v26.2). */
     readonly features: SqlDialectFeatures;
     /**

package/dist/cockroachdb/cockroachDialect.js

@@ -10,6 +10,14 @@ export class CockroachDialect extends PgLikeSqlDialect {
      * Re-check that issue before adding it.
      */
     vectorMetrics = new Map([...PG_VECTOR_METRICS].filter(([metric]) => metric !== 'l1'));
+    /** Neither `regconfig` nor `WEBSEARCH_TO_TSQUERY` exist here (v26.3): the config goes as text, the search as plain words. */
+    textConfigCast = '';
+    textQueryFn = 'PLAINTO_TSQUERY';
+    /** Its own beam for either type that builds its vector index; it refuses pgvector's `hnsw.ef_search`. */
+    annSettings = new Map([
+        ['hnsw', 'vector_search_beam_size'],
+        ['vector', 'vector_search_beam_size'],
+    ]);
     /** An upsert batch mixing an update and an insert returns the update first (verified on v26.2). */
     features = { ...PG_FEATURES, orderedUpsertReturning: false };
     /**

package/dist/d1/d1SqliteDialect.d.ts

@@ -1,10 +1,13 @@
 import { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import type { SqlDialectFeatures } from '../type/index.js';
 /**
  * SQLite Dialect specialization for Cloudflare D1.
  *
  * @remarks Distinct type for `D1QuerierPool` and a hook for D1-specific SQL differences.
  */
 export declare class D1SqliteDialect extends SqliteDialect {
+    /** A vector stays text: D1 answers a BLOB as an array of its byte values, which reads like a vector. */
+    readonly features: SqlDialectFeatures;
     readonly maxBindValues: number;
     readonly maxFunctionArgs: number;
     /**

package/dist/d1/d1SqliteDialect.js

@@ -1,10 +1,12 @@
-import { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import { SQLITE_FEATURES, SqliteDialect } from '../sqlite/sqliteDialect.js';
 /**
  * SQLite Dialect specialization for Cloudflare D1.
  *
  * @remarks Distinct type for `D1QuerierPool` and a hook for D1-specific SQL differences.
  */
 export class D1SqliteDialect extends SqliteDialect {
+    /** A vector stays text: D1 answers a BLOB as an array of its byte values, which reads like a vector. */
+    features = { ...SQLITE_FEATURES, vectorBytes: false };
     // Cloudflare D1 caps bound parameters at 100 per query.
     maxBindValues = 100;
     // And a function call at 32 arguments.

package/dist/dialect/abstractSqlDialect.d.ts

@@ -446,6 +446,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private readOptions;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * 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: readonly string[], _config?: string): string;
     /** Where an insert's id clause goes: `RETURNING` at the end, or SQL Server's `OUTPUT` before `VALUES`. */
     readonly returningPosition: 'suffix' | 'after-target';
     /**

package/dist/dialect/abstractSqlDialect.js

@@ -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 });
@@ -963,7 +963,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             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 = resolveGroupJoins(meta, q.$group, (path) => ctx.claimAlias(path));
+        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
@@ -988,7 +988,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         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, q.$where, { ...opts, prefix });
+        this.where(ctx, entity, where, { ...opts, prefix });
         if (derived) {
             ctx.append(`) ${this.escapeId(ROWS_ALIAS, true)}`);
         }
@@ -1127,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';
     /**
@@ -1340,7 +1347,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /** The same for an aggregate's row, per query: each alias decodes by {@link aggregateKind}. */
     hydratableAggregates(entity, q) {
         const meta = getMeta(entity);
-        const joins = resolveGroupJoins(meta, q.$group);
+        const { joins } = resolveGroupJoins(meta, q);
         const decoded = [];
         for (const entry of parseGroupMap(q.$group, q.$select)) {
             const kind = entry.kind === 'fn'
@@ -1387,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':

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

@@ -23,6 +23,7 @@ export const MYSQL_FEATURES = {
     commentSyntax: 'inline',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
+    vectorBytes: false,
     supportsTimestamptz: false,
     stringSizing: 'varchar',
     supportsUnsigned: true,
@@ -178,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,6 +27,7 @@ export const PG_FEATURES = {
     commentSyntax: 'statement',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,
+    vectorBytes: false,
     supportsTimestamptz: true,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
@@ -87,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'],
     ]);
     /**
@@ -101,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;
@@ -121,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, QueryGroupMap, 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,8 +39,19 @@ 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: each to-one relation a `$group` path passes through. */
-export declare function resolveGroupJoins<E>(meta: EntityMeta<E>, group: QueryGroupMap<E> | undefined, 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;

package/dist/dialect/queryJoins.js

@@ -1,5 +1,5 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -11,18 +11,35 @@ export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     }
     const joins = new Map();
     addPopulateJoins(joins, claimAlias, meta, q.$populate);
-    addPathJoins(joins, claimAlias, meta, q.$sort);
+    addPathJoins(joins, claimAlias, meta, q.$sort, false);
     return joins;
 }
-/** What an aggregate joins: each to-one relation a `$group` path passes through. */
-export function resolveGroupJoins(meta, group, claimAlias = (path) => path) {
+/**
+ * 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 function resolveGroupJoins(meta, q, claimAlias = (path) => path) {
     const joins = new Map();
-    for (const ref of Object.values(group ?? {})) {
+    for (const ref of Object.values(q.$group ?? {})) {
         if (isRecord(ref)) {
-            addPathJoins(joins, claimAlias, meta, ref);
+            addPathJoins(joins, claimAlias, meta, ref, true);
         }
     }
-    return joins;
+    if (!q.$where) {
+        return { joins, where: q.$where };
+    }
+    const where = { ...q.$where };
+    for (const key of getKeys(q.$where)) {
+        const join = joins.get(key);
+        const filter = q.$where[key];
+        if (join && isRecord(filter) && parseRelationSize(filter) === undefined) {
+            joins.set(key, { ...join, query: { $where: filter } });
+            delete where[key];
+        }
+    }
+    return { joins, where };
 }
 /** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
 export function groupPathField(joins, path) {
@@ -93,8 +110,11 @@ function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
         addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-/** The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding no columns. */
-function addPathJoins(joins, claimAlias, meta, map, parent) {
+/**
+ * The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding
+ * no columns: `required` where the path names a related row, as a group's does, and a sort's does not.
+ */
+function addPathJoins(joins, claimAlias, meta, map, required, parent) {
     if (!map) {
         return;
     }
@@ -106,9 +126,9 @@ function addPathJoins(joins, claimAlias, meta, map, parent) {
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, required, false);
         // `E` stated: inferred from the nested map, it lands on the nested relation's target.
-        addPathJoins(joins, claimAlias, join.meta, value, join);
+        addPathJoins(joins, claimAlias, join.meta, value, required, join);
     }
 }
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */

package/dist/dialect/vectorCast.d.ts

@@ -20,5 +20,7 @@ export declare function toSparsevecLiteral(values: readonly unknown[]): string;
  * as it was written, `{1:1,3:2}/3` or `[1,2,3]`; `undefined` where the text matches neither.
  */
 export declare function parseVectorLiteral(raw: string, cast: VectorCast): number[] | undefined;
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export declare function encodeFloat32s(values: readonly unknown[]): Uint8Array;
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export declare function decodeFloat32s(bytes: Uint8Array): number[];

package/dist/dialect/vectorCast.js

@@ -62,6 +62,13 @@ function parseDense(text) {
         return undefined;
     }
 }
+/** The packed little-endian float32s a blob vector column holds, and {@link decodeFloat32s} reads back. */
+export function encodeFloat32s(values) {
+    const bytes = new Uint8Array(values.length * 4);
+    const view = new DataView(bytes.buffer);
+    values.forEach((value, at) => view.setFloat32(at * 4, Number(value), true));
+    return bytes;
+}
 /** Packed little-endian float32s, each read as {@link shortestFloat32}. */
 export function decodeFloat32s(bytes) {
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);

package/dist/dialect/vectorSqlDialect.d.ts

@@ -1,6 +1,6 @@
-import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, QueryWhere, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
 import { AbstractDialect } from './abstractDialect.js';
-import type { VectorCast } from './vectorCast.js';
+import { type VectorCast } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -20,12 +20,16 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     protected tunedVectorIndex<E>(meta: EntityMeta<E>, q: Query<E>): EntityIndexMeta | undefined;
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    protected rankedWhere<E>(_meta: EntityMeta<E>, q: Query<E>, _prefix: string | undefined): QueryWhere<E> | undefined;
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex(): boolean;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
@@ -39,7 +43,7 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     };
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -1,7 +1,8 @@
-import { unsupportedVectorMetric } from '../type/vector.js';
-import { findVectorIndex, findVectorSort } from '../util/dialect.util.js';
+import { DEFAULT_VECTOR_DISTANCE, unsupportedVectorMetric } from '../type/vector.js';
+import { findVectorIndex, findVectorSort, vectorCandidates } from '../util/dialect.util.js';
 import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
+import { encodeFloat32s } from './vectorCast.js';
 /**
  * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
  * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
@@ -24,22 +25,26 @@ export class VectorSqlDialect extends AbstractDialect {
      * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     tunedVectorIndex(meta, q) {
-        const candidates = q.$candidates;
-        if (candidates === undefined) {
+        if (vectorCandidates(q) === undefined) {
             return undefined;
         }
-        if (!Number.isInteger(candidates) || candidates < 1) {
-            throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
-        }
         const key = this.vectorSortKey(q);
         return key ? findVectorIndex(meta, key) : undefined;
     }
+    /** The `$where` a read runs: the query's own, which an engine reading its vector index as a table narrows. */
+    rankedWhere(_meta, q, _prefix) {
+        return q.$where;
+    }
     /**
      * Every distance metric this dialect has, and how a search and an index spell each. Empty means no
      * vector search at all, which is what MySQL and D1 are. The key set is the single answer to "is this
      * metric supported here", for a query and an index alike.
      */
     vectorMetrics = new Map();
+    /** Whether this engine has a vector index: the one a metric's `index` names. */
+    hasVectorIndex() {
+        return [...this.vectorMetrics.values()].some((metric) => metric.index);
+    }
     /**
      * What a distance expression reads, for a `$sort` and a `$near` alike. The metric falls back to the
      * field's, then its index's, which serves no other, then cosine.
@@ -47,15 +52,15 @@ export class VectorSqlDialect extends AbstractDialect {
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? 'cosine';
+        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE;
         return { colName, distance, field };
     }
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
-     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     * dialect needing a conversion around it (`$1::vector`, `CAST(? AS VECTOR(n))`) declares it once.
      */
     appendVectorValue(ctx, value, _field) {
-        ctx.addValue(`[${value.join(',')}]`);
+        ctx.addValue(this.features.vectorBytes ? encodeFloat32s(value) : `[${value.join(',')}]`);
     }
     /**
      * The vector type this dialect actually has for a declared one, so the cast follows the column

package/dist/libsql/libsqlDialect.d.ts

@@ -7,6 +7,6 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
  * functions, which `TursoDialect` inherits.
  */
 export declare class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/libsql/libsqlDialect.js

@@ -6,9 +6,9 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  * functions, which `TursoDialect` inherits.
  */
 export class LibsqlDialect extends SqliteDialect {
-    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
+    /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
     vectorMetrics = new Map([
-        ['cosine', { fn: 'vector_distance_cos' }],
-        ['l2', { fn: 'vector_distance_l2' }],
+        ['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
+        ['l2', { fn: 'vector_distance_l2', index: 'l2' }],
     ]);
 }

package/dist/maria/mariaDialect.d.ts

@@ -6,8 +6,9 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
     /**
-     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
+     * Unlike MySQL: `VECTOR(n)` takes its dimension and binds as packed float32 bytes, every column of a
+     * vector index has to be NOT NULL, `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed
+     * to one table of a join.
      */
     readonly features: SqlDialectFeatures;
     /**
@@ -34,13 +35,6 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected jsonDiffers(elem: string, operand: string): string;
     /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+, which the index's `DISTANCE=` names alike. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
-    /**
-     * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
-     * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
-     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
-     * conversion, needed on both paths.
-     */
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
      * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
      * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,