uql-orm 0.37.1 → 0.39.0

package/dist/type/dialect.js

@@ -1,3 +1,18 @@
+/**
+ * An index capability that some engines have and others reject outright. Verified live: expression
+ * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
+ * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
+ * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only; the
+ * MySQL family is alone in having no partial indexes. The two JSON ones split the other way: the
+ * engines that index a path inside a document are the ones whose planner matches the query's own
+ * extraction back to it (Postgres, CockroachDB, SQLite - MySQL matches neither
+ * `CAST(col->>'$.x' AS CHAR(n))` nor `JSON_VALUE(... RETURNING ...)`, verified on 26.7, and needs a
+ * generated column instead), while MySQL alone has the multi-valued index a JSON array needs.
+ *
+ * Introspectors reuse the vocabulary for what they can read *back*, which is what diffing may
+ * compare. The two sets are deliberately not the same object and must not be unified: Postgres can
+ * emit an expression index and read one back, but MySQL emits one it cannot describe afterwards.
+ */
 export const INDEX_FEATURE_LABELS = {
     expression: 'expression indexes',
     partial: 'partial indexes',
@@ -5,4 +20,6 @@ export const INDEX_FEATURE_LABELS = {
     nullsOrder: 'NULLS FIRST/LAST in an index',
     opsClass: 'index operator classes',
     include: 'covering indexes (INCLUDE)',
+    jsonPath: 'indexes over a path inside a JSON column',
+    jsonArray: 'multi-valued indexes over a JSON array',
 };

package/dist/type/entity.d.ts

@@ -7,6 +7,13 @@ import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vect
  * Allow to customize the name of the property that identifies an entity
  */
 export declare const idKey: unique symbol;
+/**
+ * The one filter name uql registers itself, from `@Field({ softDelete })`. Four ends have to agree on
+ * it and none would fail if they drifted: the field that registers it, the decorator that reserves
+ * the name against a user's own filter, the hard delete that switches it off, and the bypass check
+ * that lets it through on an entity which never declared one.
+ */
+export declare const SOFT_DELETE_FILTER = "softDelete";
 /**
  * Infers the key names of an entity
  */
@@ -521,10 +528,59 @@ export type IndexTypeOptions = {
  * ```
  *
  * `C` is the entity's `FieldKey` on the `@Index`/`defineEntity` paths, where the decorated class says
- * which columns exist. It defaults to `string` for the migration builder's `table.index(...)`, which
- * names raw table columns with no entity in scope.
+ * which columns exist, and `E` the entity itself, which is what checks a JSON entry's path. Both
+ * default to the unchecked form for the migration builder's `table.index(...)`, which names raw
+ * table columns with no entity in scope.
  */
-export type IndexColumnInput<C extends string = string> = C | QueryRaw | IndexColumnOptions<C>;
+export type IndexColumnInput<C extends string = string, E = unknown> = C | QueryRaw | IndexColumnOptions<C> | IndexJsonColumnOptions<C, E>;
+/**
+ * The JSON entries, whose `path` is checked against the payload of the column the same entry names -
+ * a mapped union, one arm per JSON field, so `{ column: 'kind', jsonPath: { path: 'thema.color' } }`
+ * cannot compile. It matters more here than anywhere else in the index API: a path that is merely
+ * *misspelled* still builds a perfectly valid index, one no query will ever match, and nothing at
+ * runtime can tell that from the index you meant.
+ *
+ * `jsonArray`'s path is the array's own, so on a column that *is* the array (`Json<string[]>`) it
+ * resolves to `never` and the property can only be omitted, which is exactly the truth.
+ *
+ * Falls back to the unchecked shape only where there is no entity to check against - the migration
+ * builder. An entity with no JSON field at all offers no arm, which is also the truth.
+ */
+type IndexJsonColumnOptions<C extends string, E> = unknown extends E ? IndexColumnModifiers & {
+    readonly column: C | QueryRaw;
+} : {
+    [K in JsonColumnKey<E>]: IndexColumnPlainModifiers & {
+        readonly column: K;
+    } & ({
+        readonly jsonPath: WithCheckedPath<IndexJsonPath, E, K>;
+        readonly jsonArray?: never;
+    } | {
+        readonly jsonArray: WithCheckedPath<IndexJsonArray, E, K>;
+        readonly jsonPath?: never;
+    });
+}[JsonColumnKey<E>];
+/**
+ * The JSON columns an index can address, which is a wider set than {@link JsonFieldKey}: that one
+ * unwraps arrays to find the brand, so a column that *is* an array (`Json<string[]>`) reads as a
+ * plain one - right for `$where`, which has no path into it, and wrong for `jsonArray`, whose whole
+ * subject is that column.
+ */
+type JsonColumnKey<E> = {
+    readonly [K in keyof E]-?: IsJson<NonNullable<E[K]>> extends true ? K : IsJson<JsonElement<E[K]>> extends true ? K : never;
+}[Key<E>];
+/** The payload a path is checked against: the column's own brand, or that of the documents it holds. */
+type JsonColumnPayload<V> = IsJson<NonNullable<V>> extends true ? UnwrapJson<NonNullable<V>> : JsonPayload<V>;
+/**
+ * A JSON modifier with its `path` narrowed to the ones that column's payload actually has. Everything
+ * else - and `path`'s own optionality, which `jsonArray` needs and `jsonPath` does not - is taken
+ * from the declared type rather than restated, so a property added to either cannot miss the checked
+ * form.
+ */
+type WithCheckedPath<T extends {
+    path?: string;
+}, E, K extends Key<E>> = Except<T, 'path' & keyof T> & {
+    [P in keyof Pick<T, Extract<keyof T, 'path'>>]: DeepJsonKeys<JsonColumnPayload<E[K]>>;
+};
 /**
  * What an index entry can carry besides the thing being indexed. Shared with the normalized
  * `IndexColumnSchema`, so the authored and internal shapes cannot drift apart.
@@ -541,8 +597,56 @@ export type IndexColumnModifiers = {
     readonly nulls?: 'first' | 'last';
     /** Operator class, e.g. `jsonb_path_ops` for a smaller GIN index. Postgres only. */
     readonly opsClass?: string;
+    /** Index a path inside a JSON column. See {@link IndexJsonPath}. */
+    readonly jsonPath?: IndexJsonPath;
+    /** Index every element of a JSON array. See {@link IndexJsonArray}. */
+    readonly jsonArray?: IndexJsonArray;
 };
-export type IndexColumnOptions<C extends string = string> = IndexColumnModifiers & {
+/**
+ * An index over one path inside a JSON column, compiled by the same code a `$where` on that path is:
+ * an expression index is matched by its own text, so an index spelled even slightly differently is
+ * one the planner never reaches for.
+ *
+ * `type` picks the reading the way an operand's own type does (`jsonCompareMode`): compared as a
+ * number, indexed as a number. Which engines have it is `IndexFeature`'s `jsonPath`.
+ *
+ * @example
+ * ```ts
+ * @Index([{ column: 'kind', jsonPath: { path: 'theme.color', type: String } }]) // 'kind.theme.color': 'red'
+ * @Index([{ column: 'kind', jsonPath: { path: 'rating', type: Number } }])      // 'kind.rating': { $gte: 4 }
+ * ```
+ */
+export type IndexJsonPath = {
+    /** The path inside the column, spelled as a `$where` key spells it: `'theme.color'`. */
+    readonly path: string;
+    /** How the value is read, matching what the queries over it compare against. */
+    readonly type: FieldType;
+};
+/**
+ * MySQL's multi-valued index: one key per *element* of the JSON array at `path` (the column itself
+ * when there is none), which is the only index `$all`/`$elemMatch` containment can use. `type` is
+ * the element's, and a string or binary one needs a `length`, since the cast is what sizes the key.
+ *
+ * MySQL is alone in having it - `IndexFeature`'s `jsonArray` - and an index asking for it elsewhere
+ * is refused rather than silently built.
+ *
+ * @example
+ * ```ts
+ * @Index([{ column: 'tags', jsonArray: { type: String, length: 64 } }]) // tags: { $all: [...] }
+ * @Index([{ column: 'kind', jsonArray: { path: 'ids', type: Number } }]) // 'kind.ids': { $all: [...] }
+ * ```
+ */
+export type IndexJsonArray = {
+    /** The array's path inside the column, spelled as a `$where` key spells it; omit for the column. */
+    readonly path?: string;
+    /** The element type, matching what the queries over the array compare against. */
+    readonly type: FieldType;
+    /** Length of a string or binary element, which MySQL's `CHAR(n) ARRAY` cast requires. */
+    readonly length?: number;
+};
+/** The modifiers that do not name a JSON path, and so need no entity to be checked against. */
+type IndexColumnPlainModifiers = Except<IndexColumnModifiers, 'jsonPath' | 'jsonArray'>;
+export type IndexColumnOptions<C extends string = string> = IndexColumnPlainModifiers & {
     /** The column to index, or `raw(...)` for an expression. */
     readonly column: C | QueryRaw;
 };
@@ -621,7 +725,7 @@ export type EntityOptions<E = unknown> = {
     readonly relations?: {
         readonly [K in RelationKey<E>]?: RelationOptionsFor<E[K]>;
     };
-    readonly indexes?: readonly EntityIndexInput<FieldKey<E>>[];
+    readonly indexes?: readonly EntityIndexInput<FieldKey<E>, E>[];
     /** Map hook events to method names on the entity class. */
     readonly hooks?: Partial<Record<HookEvent, readonly MethodKey<E>[]>>;
 };
@@ -630,11 +734,16 @@ export type EntityOptions<E = unknown> = {
  * migration builder's `table.index(...)`. `Except` (not plain `Omit`) keeps `type`/`distance` a
  * discriminated pair: omitting `distance` on a vector index type is a compile error.
  */
-export type IndexOptions = Except<EntityIndexMeta, 'columns'>;
+export type IndexOptions<E = unknown> = Except<EntityIndexMeta, 'columns' | 'include'> & {
+    /** Non-key columns stored in the index; a typo builds nothing, the server refusing the statement. */
+    readonly include?: readonly IndexFieldKey<E>[];
+};
+/** A field of `E`, or any name where there is no entity to check it against - the migration builder. */
+type IndexFieldKey<E> = unknown extends E ? string : FieldKey<E>;
 /**
  * An index as authored, before `defineIndex` normalizes its columns.
  */
-export type EntityIndexInput<C extends string = string> = IndexOptions & {
-    readonly columns: readonly IndexColumnInput<C>[];
+export type EntityIndexInput<C extends string = string, E = unknown> = IndexOptions<E> & {
+    readonly columns: readonly IndexColumnInput<C, E>[];
 };
 export {};

package/dist/type/entity.js

@@ -2,3 +2,10 @@
  * Allow to customize the name of the property that identifies an entity
  */
 export const idKey = Symbol('idKey');
+/**
+ * The one filter name uql registers itself, from `@Field({ softDelete })`. Four ends have to agree on
+ * it and none would fail if they drifted: the field that registers it, the decorator that reserves
+ * the name against a user's own filter, the hard delete that switches it off, and the bypass check
+ * that lets it through on an entity which never declared one.
+ */
+export const SOFT_DELETE_FILTER = 'softDelete';

package/dist/type/query.d.ts

@@ -245,6 +245,18 @@ export type Query<E> = {
      * is what keeps the clause off those statements at the type level.
      */
     $lock?: QueryLock;
+    /**
+     * how many candidates an approximate-nearest-neighbour index explores before ranking, for a vector
+     * search. Higher trades speed for recall; the default is whatever the engine's own is, which is
+     * tuned for speed. Ignored where the search is exact (SQLite, libSQL and Turso scan every row) and
+     * where the field carries no ANN index, since there is nothing to widen.
+     *
+     * The units are the index's, not UQL's, so the number is not comparable across index types: it
+     * becomes `hnsw.ef_search` or `ivfflat.probes` on Postgres, `mhnsw_ef_search` on MariaDB, and
+     * `numCandidates` on MongoDB Atlas. On Postgres it needs an open transaction, since a `SET LOCAL`
+     * outside one applies to nothing.
+     */
+    $candidates?: number;
     /**
      * filtering options.
      */
@@ -275,6 +287,12 @@ export declare const QUERY_OBJECT_CLAUSES: readonly ["$select", "$populate", "$e
  */
 export declare const QUERY_ROOT_OBJECT_CLAUSES: readonly ["$count"];
 export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
+/**
+ * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.
+ * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows
+ * the statement returns, so a relation's own query has nothing to tune.
+ */
+export declare const QUERY_ROOT_NUMBER_CLAUSES: readonly ["$candidates"];
 export declare const QUERY_BOOLEAN_CLAUSES: readonly ["$distinct"];
 /**
  * options to get a single record.

package/dist/type/query.js

@@ -32,4 +32,10 @@ export const QUERY_OBJECT_CLAUSES = [
  */
 export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
+/**
+ * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.
+ * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows
+ * the statement returns, so a relation's own query has nothing to tune.
+ */
+export const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];

package/dist/type/queryWhere.d.ts

@@ -1,6 +1,7 @@
 import type { FieldKey, IdValue, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
+import type { QueryVectorQuery } from './vector.js';
 /**
  * options for full-text-search operator.
  */
@@ -91,6 +92,34 @@ export type QueryNegateOp = keyof Pick<QueryWhereRootOperator<unknown>, '$not' |
 export type QuerySizeComparisonOps = {
     [K in QueryHavingOp | '$between']?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
 };
+/**
+ * Filter by distance to a query vector: `$where`'s counterpart to `$sort`'s ranking, so "the closest
+ * ten" and "everything closer than 0.35" stay separate asks.
+ *
+ * Bounded by {@link QueryOrderedOp} - what {@link QuerySizeComparisonOps} ranges over, minus
+ * `$eq`/`$ne`. A distance is a float, so exact equality against one is a bug every time, where
+ * `$size` compares an integer `COUNT`. No `$project` either: naming the distance is `$sort`'s job,
+ * since the `SELECT` list is built from `$sort` alone and a `$near` nested inside an `$or` has no
+ * business projecting a column.
+ *
+ * `$distance` is here for the same reason `$sort` has it: each clause states its own search
+ * completely, so neither depends on the other. Omitted, it falls back to the field's declared metric,
+ * which is where the metric belongs - beside the index it has to match. Naming a different one per
+ * query mostly buys a full scan, since an ANN index is built for exactly one operator class.
+ *
+ * `$vector` is required, and repeating it beside a `$sort` that ranks by the same field is the point:
+ * every other `$where` operator means the same thing wherever it appears, and inheriting one from a
+ * sibling clause would make this the first whose validity depends on what else the query contains -
+ * unfixable in the type, and carried into merged entity filters and `/http` payloads alike. Naming
+ * the vector in a `const` is what removes the repetition, at the call site where it belongs.
+ *
+ * A `$near` carrying no bound is a `WHERE` that is always true. The dialect rejects that rather than
+ * the type: `/http` casts client JSON straight to `Query`, so the check has to exist there anyway,
+ * and an "at least one of these five" union would cost every caller worse errors for a second copy.
+ */
+export type QueryVectorNear = QueryVectorQuery & {
+    [K in QueryOrderedOp]?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
+};
 export type QueryWhereFieldOperatorMap<T> = {
     /**
      * whether a value is equal to the given value.
@@ -200,6 +229,12 @@ export type QueryWhereFieldOperatorMap<T> = {
      * @example { addresses: { $elemMatch: { city: { $like: 'New%' } } } }
      */
     $elemMatch?: unknown extends T ? QueryWhereElemMatch<unknown> : NonNullable<T> extends readonly (infer U)[] ? QueryWhereElemMatch<U> : never;
+    /**
+     * whether a vector is within a given distance of the query vector. `$sort` ranks by distance;
+     * this filters by it, so "the closest ten" and "everything closer than 0.35" are separate asks.
+     * @example { embedding: { $near: { $vector: queryVec, $lt: 0.35 } } }
+     */
+    $near?: QueryVectorNear;
 };
 /**
  * Element-level conditions for `$elemMatch`. Scalar elements take an operator map for the element
@@ -241,15 +276,24 @@ type QueryArrayOp = keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$all' | '$s
  * Ordering operators: {@link QueryCompareOp} plus `$between`.
  */
 type QueryOrderedOp = QueryCompareOp | keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$between'>;
+/**
+ * Vector-only operators. `Pick`'s constraint ties this back to {@link QueryWhereFieldOperatorMap}
+ * so a rename there breaks this union at compile time.
+ */
+type QueryVectorOp = keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$near'>;
 /**
  * Operators applicable to every field type: equality, membership, negation, and null checks.
+ *
+ * @remarks This is a subtraction, not a list, so an operator added to
+ * {@link QueryWhereFieldOperatorMap} without also being classified above lands here and is offered
+ * on every field - `$near` on a `boolean`, say. Classify first, then add.
  */
-type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStringOp | QueryArrayOp | QueryOrderedOp>;
+type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStringOp | QueryArrayOp | QueryOrderedOp | QueryVectorOp>;
 /**
  * Operator keys applicable to a field of type `T`. Brackets prevent union distribution so an
  * optional field (`string | undefined`) or a literal union (`'a' | 'b'`) gates as one type.
  */
-type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
+type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | ([NonNullable<T>] extends [readonly number[] | Uint8Array] ? QueryVectorOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
 /**
  * Operators applicable to a field of type `T`: string operators require string fields, ordering
  * operators comparable fields, array operators array fields. `unknown` stays fully permissive

package/dist/type/vector.d.ts

@@ -11,6 +11,19 @@ import type { IndexType } from '../schema/types.js';
  * vector, which no field type maps to. It would be a value that compiles and always throws.
  */
 export type VectorDistance = 'cosine' | 'l2' | 'inner' | 'l1';
+/**
+ * The vector and the metric: the half of a similarity search that names *what* distance to compute,
+ * shared by `$sort`'s ranking ({@link QueryVectorSearch}) and `$where`'s threshold
+ * ({@link QueryVectorNear}) so the two cannot describe the same distance differently.
+ */
+export interface QueryVectorQuery {
+    /** The query vector to compare against. */
+    readonly $vector: readonly number[];
+    /** Distance metric. Overrides entity-level default. Falls back to `'cosine'`. */
+    readonly $distance?: VectorDistance;
+}
+/** The keys that describe the search rather than bound it, so `$near`'s bounds are what is left. */
+export declare const VECTOR_QUERY_KEYS: readonly ["$vector", "$distance"];
 /**
  * Vector similarity search options - used inside `$sort` on vector fields.
  *
@@ -22,11 +35,7 @@ export type VectorDistance = 'cosine' | 'l2' | 'inner' | 'l1';
  * });
  * ```
  */
-export interface QueryVectorSearch {
-    /** The query vector to compare against. */
-    readonly $vector: readonly number[];
-    /** Distance metric. Overrides entity-level default. Falls back to `'cosine'`. */
-    readonly $distance?: VectorDistance;
+export interface QueryVectorSearch extends QueryVectorQuery {
     /** Project the computed distance as a named field in the result. */
     readonly $project?: string;
 }
@@ -40,6 +49,29 @@ export interface QueryVectorSearch {
  * ```
  */
 export type WithDistance<E, K extends string = '_distance'> = E & Record<K, number>;
+/**
+ * How one dialect spells one distance metric. Two shapes exist across engines - an infix operator
+ * (`"col" <=> $1`, pgvector) or a function call (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB and the
+ * SQLite family) - so they are one discriminated map rather than two parallel ones. That is what
+ * lets a single `appendVectorSort` serve every engine, and makes the map's key set the one answer
+ * to "does this dialect have this metric".
+ *
+ * `opsSuffix` rides along on the operator form because pgvector's index operator class is named from
+ * the same metric (`vector_cosine_ops`): keeping them together is what stops a dialect from having
+ * the operator but not the class it indexes with.
+ */
+export type VectorMetric = {
+    readonly op: string;
+    readonly opsSuffix: string;
+} | {
+    readonly fn: string;
+};
+/** The operator form, for the pgvector-family dialects whose index DDL also needs `opsSuffix`. */
+export type VectorOperatorMetric = Extract<VectorMetric, {
+    op: string;
+}>;
+/** Every dialect words this the same, and one of them used to throw a bare `Error` for it. */
+export declare function unsupportedVectorMetric(dialectName: string, distance: VectorDistance, indexName?: string): TypeError;
 /**
  * Vector-specific tuning options shared by `@Index` decorator, entity metadata, and migration schema.
  */
@@ -53,5 +85,11 @@ export type VectorIndexOptions = {
     /** IVFFlat: number of inverted lists. */
     lists?: number;
 };
-/** Index types whose emitted DDL depends on the distance metric. */
-export type VectorIndexType = Extract<IndexType, 'hnsw' | 'ivfflat' | 'vector'>;
+/**
+ * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
+ * the type and every dialect's "do I have this one?" answer cannot drift from each other.
+ */
+export declare const VECTOR_INDEX_TYPES: readonly ["hnsw", "ivfflat", "vector"];
+export type VectorIndexType = (typeof VECTOR_INDEX_TYPES)[number];
+/** Whether an index type is one of {@link VECTOR_INDEX_TYPES}; narrows an optional `IndexSchema.type`. */
+export declare function isVectorIndexType(type: IndexType | undefined): type is VectorIndexType;

package/dist/type/vector.js

@@ -1 +1,16 @@
-export {};
+/** The keys that describe the search rather than bound it, so `$near`'s bounds are what is left. */
+export const VECTOR_QUERY_KEYS = ['$vector', '$distance'];
+/** Every dialect words this the same, and one of them used to throw a bare `Error` for it. */
+export function unsupportedVectorMetric(dialectName, distance, indexName) {
+    const where = indexName === undefined ? '' : ` (index "${indexName}")`;
+    return new TypeError(`${dialectName} does not support vector distance metric: ${distance}${where}`);
+}
+/**
+ * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
+ * the type and every dialect's "do I have this one?" answer cannot drift from each other.
+ */
+export const VECTOR_INDEX_TYPES = ['hnsw', 'ivfflat', 'vector'];
+/** Whether an index type is one of {@link VECTOR_INDEX_TYPES}; narrows an optional `IndexSchema.type`. */
+export function isVectorIndexType(type) {
+    return type !== undefined && VECTOR_INDEX_TYPES.includes(type);
+}

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /**
@@ -62,6 +62,25 @@ export declare function asSelectMap<E>(select: QuerySelectValue<E> | undefined):
 export declare function normalizeScalarFieldSelection<E>(meta: EntityMeta<E>, select?: QuerySelect<E>, exclude?: QueryExclude<E>): FieldKey<E>[];
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export declare function isVectorSearch(value: unknown): value is QueryVectorSearch;
+/**
+ * The vector search a `$sort` carries, if it ranks by one. First entry wins when two fields are
+ * ranked at once - one scan for every dialect, so the SQL side and MongoDB cannot disagree about
+ * which, as they did when one took the first and the other the last.
+ */
+export declare function findVectorSort<E>(sort: QuerySortMap<E> | undefined): {
+    key: string;
+    search: QueryVectorSearch;
+} | undefined;
+/**
+ * The vector index declared on `key`, if any. Answers both "is there an ANN index to tune here" and
+ * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
+ */
+export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta | undefined;
+/**
+ * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
+ * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.
+ */
+export declare function hasVectorNear(where: unknown): boolean;
 /** Type guard: checks whether an update payload value is a JSON operator object. */
 export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
 export declare function augmentWhere<E>(meta: EntityMeta<E>, target?: QueryWhere<E>, source?: QueryWhere<E>): QueryWhere<E>;

package/dist/util/dialect.util.js

@@ -1,6 +1,7 @@
 import { getContext, UqlSecurityError } from '../context/context.js';
-import { QueryRaw, resolveAggregateOp, } from '../type/index.js';
-import { getFieldKeys, getKeys, hasKeys, someKey } from './object.util.js';
+import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
+import { VECTOR_INDEX_TYPES } from '../type/vector.js';
+import { entityName, getFieldKeys, getKeys, hasKeys, someKey } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -162,6 +163,50 @@ export function normalizeScalarFieldSelection(meta, select, exclude) {
 export function isVectorSearch(value) {
     return value !== null && typeof value === 'object' && '$vector' in value;
 }
+/**
+ * The vector search a `$sort` carries, if it ranks by one. First entry wins when two fields are
+ * ranked at once - one scan for every dialect, so the SQL side and MongoDB cannot disagree about
+ * which, as they did when one took the first and the other the last.
+ */
+export function findVectorSort(sort) {
+    for (const key of getKeys(sort ?? {})) {
+        const search = sort?.[key];
+        // The guard narrows here, where a `.find()` over entries would hand back an untyped tuple.
+        if (isVectorSearch(search)) {
+            return { key, search };
+        }
+    }
+    return undefined;
+}
+/**
+ * Every index type that means "vector" to some engine: pgvector's two, the generic one MariaDB and
+ * CockroachDB share, and Atlas's. Wider than {@link VECTOR_INDEX_TYPES}, which is the set whose DDL
+ * depends on a distance metric - Atlas takes its metric from the index definition instead.
+ */
+const VECTOR_INDEX_MATCH = new Set([...VECTOR_INDEX_TYPES, 'vectorSearch']);
+/**
+ * The vector index declared on `key`, if any. Answers both "is there an ANN index to tune here" and
+ * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
+ */
+export function findVectorIndex(meta, key) {
+    return meta.indexes?.find((index) => index.type !== undefined && VECTOR_INDEX_MATCH.has(index.type) && indexCoversColumn(index, key));
+}
+/**
+ * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
+ * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.
+ */
+export function hasVectorNear(where) {
+    if (where === null || typeof where !== 'object') {
+        return false;
+    }
+    if (Array.isArray(where)) {
+        return where.some(hasVectorNear);
+    }
+    return Object.entries(where).some(([key, value]) => key === '$near' || hasVectorNear(value));
+}
+function indexCoversColumn(index, key) {
+    return index.columns.some((entry) => !(entry instanceof QueryRaw) && entry.column === key);
+}
 /** `satisfies` ties this to {@link JsonUpdateOp}, so renaming an operator breaks it at compile time. */
 const JSON_UPDATE_OPS = [
     '$set',
@@ -199,7 +244,7 @@ export function buildQueryWhereAsMap(meta, filter = {}) {
 }
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
 export function withoutSoftDeleteFilter(filters) {
-    return filters === false ? false : { ...filters, softDelete: false };
+    return filters === false ? false : { ...filters, [SOFT_DELETE_FILTER]: false };
 }
 /**
  * Returns a new `$where` map with every active entity filter's condition merged in, resolving
@@ -241,7 +286,7 @@ export function applyFilters(meta, whereMap, opts) {
         if (condition === undefined) {
             const onMissing = filter.onMissing ?? (filter.security ? 'throw' : 'skip');
             if (onMissing === 'throw') {
-                throw new UqlSecurityError(`filter '${name}' on '${meta.name ?? ''}' could not resolve (missing context)`);
+                throw new UqlSecurityError(`filter '${name}' on '${entityName(meta)}' could not resolve (missing context)`);
             }
             continue;
         }

package/dist/util/object.util.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, FieldOptions } from '../type/index.js';
+import type { EntityMeta, FieldKey, FieldOptions } from '../type/index.js';
 export declare function throwPendingTransaction(): never;
 export declare function throwNoPendingTransaction(): never;
 export declare function clone<T>(value: T): T;
@@ -20,6 +20,12 @@ export declare function isOperatorObject(value: unknown): value is Record<string
 /** Whether every key of the non-empty object `value` is an operator (no plain field names mixed in). */
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
 export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
+/**
+ * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
+ * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
+ * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ */
+export declare function entityName<E>(meta: EntityMeta<E>): string;
 export declare function getFieldKeys<E>(fields: {
     [K in FieldKey<E>]?: FieldOptions;
 }): FieldKey<E>[];

package/dist/util/object.util.js

@@ -52,6 +52,14 @@ export function isOperatorOnlyObject(value) {
 export function getKeys(obj) {
     return obj ? Object.keys(obj) : [];
 }
+/**
+ * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
+ * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
+ * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ */
+export function entityName(meta) {
+    return meta.name ?? meta.entity.name;
+}
 export function getFieldKeys(fields) {
     return getKeys(fields).filter((field) => fields[field].eager ?? true);
 }

package/dist/util/relationQuery.util.d.ts

@@ -30,9 +30,11 @@ export type JoinedRelationRejectedKey = (typeof JOINED_RELATION_REJECTIONS)[numb
 export declare function getRelationRequestSummary<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): RelationRequestSummary<E>;
 /** True when `$populate` includes at least one relation key. */
 export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
-export type RelationQuery<E extends object = object> = Except<Query<E>, '$lock'> & {
+export type RelationQuery<E extends object = object> = Except<Query<E>, StatementOnlyClause> & {
     $required?: boolean;
 };
+/** The clauses that describe the statement rather than what a query selects. */
+type StatementOnlyClause = '$lock' | '$candidates';
 export type ParsedRelationQuery<E extends object = object> = {
     query: RelationQuery<E>;
     required: boolean;

package/dist/util/relationQuery.util.js

@@ -1,4 +1,4 @@
-import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES } from '../type/query.js';
+import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, } from '../type/query.js';
 import { getKeys, someKey } from './object.util.js';
 /**
  * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
@@ -74,6 +74,8 @@ export function populatesRelations(meta, populate) {
         return false;
     return someKey(populate, (key) => !!populate[key] && key in meta.relations);
 }
+/** Their runtime half, so the check below cannot drift from the type above. */
+const STATEMENT_ONLY_CLAUSES = ['$lock', ...QUERY_ROOT_NUMBER_CLAUSES];
 // Taken from the clause groups declared beside `Query` itself, so a renamed clause fails to compile
 // here instead of quietly narrowing what a relation query accepts. `$required` is the one key that
 // is not a `Query` clause at all - it says how the relation joins, not what it selects.
@@ -91,8 +93,11 @@ function isRelationQueryObject(value) {
 export function parseRelationQueryValue(value) {
     // Caught before the shape check so the message names the key, rather than reporting the whole
     // object as an unrecognized relation query value.
-    if (isRecord(value) && '$lock' in value) {
-        throw new TypeError("'$lock' applies to the whole statement, not to a populated relation. Move it to the top level of the query.");
+    if (isRecord(value)) {
+        const statementOnly = STATEMENT_ONLY_CLAUSES.find((clause) => clause in value);
+        if (statementOnly) {
+            throw new TypeError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
+        }
     }
     if (isRelationQueryObject(value)) {
         return { query: value, required: value.$required === true, nested: true };

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.37.1",
+  "version": "0.39.0",
   "type": "module",
   "engines": {
     "node": ">=24"