uql-orm 0.20.2 → 0.22.0

package/dist/mongo/mongoDialect.js

@@ -1,7 +1,8 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { getMeta } from '../entity/index.js';
-import { applyFilters, asSelectMap, buildQueryWhereAsMap, buildSortMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, } from '../util/index.js';
+import { QueryRaw } from '../type/queryRaw.js';
+import { asSelectMap, buildQueryWhereAsMap, buildSortMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -13,7 +14,7 @@ export const mongoDialectFeatures = {
     renameColumn: false,
     foreignKeyAlter: false,
     columnComment: false,
-    vectorIndexStyle: 'create',
+    inlineVectorIndex: false,
     vectorSupportsLength: false,
     supportsTimestamptz: false,
     defaultStringAsText: false,
@@ -24,7 +25,13 @@ export class MongoDialect extends AbstractDialect {
     // The MongoDB driver reports the exact `_id` of every inserted document (`insertedIds`).
     insertIdSource = 'returning';
     static ID_KEY = '_id';
+    /** Temporary lookup fields for relation conditions, dropped with `$unset` after the `$match`. */
+    static REL_TEMP_PREFIX = '__uql_rel_';
+    static REL_COUNT_KEY = 'n';
+    static REL_NESTED_KEY = '__uql_target';
     static VECTOR_INDEX_TYPES = new Set(['vectorSearch', 'hnsw', 'ivfflat', 'vector']);
+    /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
+    static MAX_NUM_CANDIDATES = 10_000;
     // Direct field aggregates → MongoDB accumulator. `$count` is handled separately (COUNT(*) vs
     // COUNT(field) differ), so it is not listed here.
     static AGGREGATE_OP_MAP = new Map([
@@ -33,14 +40,52 @@ export class MongoDialect extends AbstractDialect {
         ['$min', '$min'],
         ['$max', '$max'],
     ]);
+    /**
+     * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,
+     * `$group` refs and `$where` keys all map through here, so no read path can address a property name
+     * the document does not use.
+     */
+    columnOf(meta, key) {
+        if (key === MongoDialect.ID_KEY || key === meta.id) {
+            return MongoDialect.ID_KEY;
+        }
+        return super.columnOf(meta, key);
+    }
     where(entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
-        // Apply this entity's filters once, at the scope entry point; recursion uses `renderFilter`.
-        const whereMap = applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
-        return this.renderFilter(entity, whereMap);
+        // Filters are applied once, here at the scope entry point; recursion uses `renderFilter`.
+        return this.renderFilter(entity, this.scopedWhereMap(meta, where, opts));
+    }
+    /**
+     * A `$where` that may constrain relations, split into the `$lookup` stages it needs and the `$match`
+     * filter that consumes them. Each relation condition becomes one correlated lookup into a temporary
+     * field plus an ordinary condition on that field, so the caller's boolean structure survives intact
+     * (a relation inside `$or` still means what it says) and nothing depends on materializing ids.
+     * `unset` names the temporary fields, which the caller drops once the match is done.
+     */
+    whereWithRelations(entity, where = {}, opts = {}) {
+        const meta = getMeta(entity);
+        const lookups = { stages: [], temps: [] };
+        const filter = this.renderFilter(entity, this.scopedWhereMap(meta, where, opts), opts, lookups);
+        return { stages: lookups.stages, filter, unset: lookups.temps };
+    }
+    /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
+    constrainsRelations(entity, where) {
+        if (!where) {
+            return false;
+        }
+        const meta = getMeta(entity);
+        const whereMap = buildQueryWhereAsMap(meta, where);
+        return Object.entries(whereMap).some(([key, val]) => key === '$and' || key === '$or'
+            ? val.some((it) => this.constrainsRelations(entity, it))
+            : Boolean(meta.relations[key]));
     }
-    /** Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or` recursion). */
-    renderFilter(entity, where = {}) {
+    /**
+     * Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or`
+     * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
+     * given - a plain `find`/`updateMany` filter has nowhere to put them.
+     */
+    renderFilter(entity, where = {}, opts, lookups) {
         const meta = getMeta(entity);
         const whereMap = buildQueryWhereAsMap(meta, where);
         const filter = {};
@@ -48,17 +93,32 @@ export class MongoDialect extends AbstractDialect {
             let key = rawKey;
             let val = rawVal;
             if (key === '$and' || key === '$or') {
-                filter[key] = val.map((filterIt) => this.renderFilter(entity, filterIt));
+                filter[key] = val.map((filterIt) => {
+                    // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
+                    // `{ $and: [raw] }`, which lands back on this branch.
+                    this.assertNoRaw(filterIt);
+                    return this.renderFilter(entity, filterIt, opts, lookups);
+                });
+            }
+            else if (key === '$text') {
+                // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
+                // the way it does elsewhere - the same shape as `$distance` being index-defined here.
+                filter['$text'] = { $search: val.$value };
+            }
+            else if (meta.relations[key]) {
+                this.assertNoRaw(val);
+                if (!lookups) {
+                    throw new TypeError(`filtering by relation '${key}' is not supported here on MongoDB`);
+                }
+                Object.assign(filter, this.appendRelationLookup(meta, key, val, opts, lookups));
             }
             else {
-                const field = meta.fields[key];
-                if (key === MongoDialect.ID_KEY || key === meta.id) {
-                    key = MongoDialect.ID_KEY;
+                this.assertNoRaw(val);
+                this.assertKnownPathRoot(meta, key);
+                key = this.pathOf(meta, key);
+                if (key === MongoDialect.ID_KEY) {
                     val = this.getIdValue(val);
                 }
-                else if (field) {
-                    key = this.resolveColumnName(key, field);
-                }
                 if (isOperatorObject(val)) {
                     val = this.transformOperators(val);
                 }
@@ -70,6 +130,115 @@ export class MongoDialect extends AbstractDialect {
         }
         return filter;
     }
+    /**
+     * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
+     * result: presence of a row for a plain relation filter, a comparison against the row count for
+     * `$size`. The target's (and, for ManyToMany, the junction's) own filters scope the lookup, so a
+     * relation subquery can no more read out-of-scope rows than a direct query on the target can.
+     */
+    appendRelationLookup(meta, relKey, val, opts, lookups) {
+        const relOpts = meta.relations[relKey];
+        const relEntity = relOpts.entity();
+        const relMeta = getMeta(relEntity);
+        const temp = `${MongoDialect.REL_TEMP_PREFIX}${lookups.temps.length}`;
+        const sizeVal = parseRelationSize(val);
+        // `$count` for a size test, `$limit: 1` for existence: neither returns the matched documents.
+        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: MongoDialect.REL_COUNT_KEY }];
+        // Scope first, render once - merging the target's filters into an already-rendered filter would
+        // leave their own keys unmapped. The caller's filter bypass is deliberately *not* passed down:
+        // `withDeleted()` or `hardDelete` on the parent must not un-hide trashed rows of the target, the
+        // same rule the SQL dialects' relation subqueries follow.
+        const targetCondition = (sizeVal === undefined ? val : {});
+        const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, targetCondition), opts);
+        lookups.temps.push(temp);
+        lookups.stages.push(relOpts.cardinality === 'mm' && relOpts.through
+            ? this.junctionLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts)
+            : {
+                $lookup: {
+                    from: this.resolveTableName(relEntity, relMeta),
+                    ...this.joinKeys(meta, relMeta, relOpts),
+                    pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), ...tail],
+                    as: temp,
+                },
+            });
+        return sizeVal === undefined
+            ? { [`${temp}.0`]: { $exists: true } }
+            : { $expr: this.compareRelationCount(temp, sizeVal) };
+    }
+    /**
+     * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
+     * lookup - the junction's filters apply too, since a soft-deleted link is not a link.
+     */
+    junctionLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
+        const throughEntity = relOpts.through();
+        const throughMeta = getMeta(throughEntity);
+        const junctionScope = this.renderFilter(throughEntity, this.scopedWhereMap(throughMeta, {}), opts);
+        const nested = MongoDialect.REL_NESTED_KEY;
+        return {
+            $lookup: {
+                from: this.resolveTableName(throughEntity, throughMeta),
+                localField: MongoDialect.ID_KEY,
+                foreignField: this.columnOf(throughMeta, relOpts.references[0].local),
+                pipeline: [
+                    ...(hasKeys(junctionScope) ? [{ $match: junctionScope }] : []),
+                    {
+                        $lookup: {
+                            from: this.resolveTableName(relEntity, relMeta),
+                            localField: this.columnOf(throughMeta, relOpts.references[1].local),
+                            foreignField: MongoDialect.ID_KEY,
+                            pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), { $limit: 1 }],
+                            as: nested,
+                        },
+                    },
+                    { $match: { [`${nested}.0`]: { $exists: true } } },
+                    ...tail,
+                ],
+                as: temp,
+            },
+        };
+    }
+    /**
+     * Compares the looked-up row count, which is `[{ n: <count> }]` or `[]` when nothing matched - hence
+     * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
+     */
+    compareRelationCount(temp, sizeVal) {
+        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${MongoDialect.REL_COUNT_KEY}`, 0] }, 0] };
+        if (typeof sizeVal === 'number') {
+            return { $eq: [count, sizeVal] };
+        }
+        const comparisons = Object.entries(sizeVal)
+            .filter(([, bound]) => bound !== undefined)
+            .flatMap(([op, bound]) => op === '$between'
+            ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
+            : [{ [op]: [count, bound] }]);
+        if (!comparisons.length) {
+            throw new TypeError('$size on a relation needs at least one comparison');
+        }
+        return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
+    }
+    /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
+    subtractsKey(key, select, exclude) {
+        const at = (map) => map?.[key];
+        return at(exclude) === true || at(select) === false;
+    }
+    /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
+    assertNoRaw(value) {
+        if (value instanceof QueryRaw) {
+            throw new TypeError('raw() in $where is not supported on MongoDB');
+        }
+    }
+    /**
+     * A dotted key addresses an embedded path, whose root must still be a declared field - otherwise it
+     * is a typo (or an injected key) that would silently match nothing, the same guard the SQL dialects
+     * apply to JSON paths.
+     */
+    assertKnownPathRoot(meta, key) {
+        const root = key.includes('.') ? key.slice(0, key.indexOf('.')) : key;
+        if (root === MongoDialect.ID_KEY || root === meta.id || meta.fields[root]) {
+            return;
+        }
+        throw new TypeError(`path ${key} does not exist in ${meta.name ?? ''}`);
+    }
     mapTableNameRow(row) {
         return row.table_name;
     }
@@ -168,87 +337,145 @@ export class MongoDialect extends AbstractDialect {
         if (Array.isArray(select)) {
             throw new TypeError('raw $select is not supported on MongoDB');
         }
-        const selectedFields = normalizeScalarFieldSelection(meta, asSelectMap(select), exclude);
-        return selectedFields.reduce((acc, key) => {
-            acc[key] = 1;
+        const selectMap = asSelectMap(select);
+        // Projected by column, not by field key; `normalizeId` maps them back on the way out.
+        const projection = normalizeScalarFieldSelection(meta, selectMap, exclude).reduce((acc, key) => {
+            acc[this.columnOf(meta, key)] = 1;
             return acc;
         }, {});
+        // MongoDB returns `_id` unless it is explicitly excluded, so subtracting the primary key needs
+        // `_id: 0` - the one inclusion/exclusion mix MongoDB allows - or `$exclude: { id: true }` would
+        // have no effect at all.
+        if (this.subtractsKey(meta.id, selectMap, exclude)) {
+            projection[MongoDialect.ID_KEY] = 0;
+        }
+        return projection;
     }
     sort(entity, sort) {
-        const raw = buildSortMap(sort);
+        const meta = getMeta(entity);
+        return this.sortBy(sort, (key) => {
+            if (meta.relations[key]) {
+                throw new TypeError(`sorting by relation '${key}' is not supported on MongoDB`);
+            }
+            return this.pathOf(meta, key);
+        });
+    }
+    /**
+     * Aggregate results are keyed by `$group`/`$agg` alias rather than by column, so an aggregate
+     * `$sort` addresses those aliases as-is - the same reason the SQL dialects sort by alias there.
+     */
+    aliasSort(sort) {
+        return this.sortBy(sort, (alias) => alias);
+    }
+    /** Shared direction normalization; `mapKey` decides whether keys are columns or aggregate aliases. */
+    sortBy(sort, mapKey) {
         const normalized = {};
-        for (const [key, dir] of Object.entries(raw)) {
-            normalized[key] = dir === 'desc' || dir === -1 ? -1 : 1;
+        for (const [key, dir] of Object.entries(buildSortMap(sort))) {
+            normalized[mapKey(key)] = dir === 'desc' || dir === -1 ? -1 : 1;
         }
         return normalized;
     }
+    /**
+     * {@link columnOf} for a possibly dotted key: only the root is a field key, the rest addresses an
+     * embedded path (`kind.city` -> `<kind's column>.city`).
+     */
+    pathOf(meta, key) {
+        const dot = key.indexOf('.');
+        if (dot < 0) {
+            return this.columnOf(meta, key);
+        }
+        return this.columnOf(meta, key.slice(0, dot)) + key.slice(dot);
+    }
     aggregationPipeline(entity, q, relationSummary, opts) {
-        const meta = getMeta(entity);
-        const where = this.where(entity, q.$where, opts);
+        const { stages, filter, unset } = this.whereWithRelations(entity, q.$where, opts);
         const sort = this.sort(entity, q.$sort);
-        const firstPipelineEntry = {};
-        if (hasKeys(where)) {
-            firstPipelineEntry.$match = where;
+        const match = {};
+        if (hasKeys(filter)) {
+            match.$match = filter;
         }
         if (hasKeys(sort)) {
-            firstPipelineEntry.$sort = sort;
-        }
+            match.$sort = sort;
+        }
+        // Lookups that a relation condition needs come first, then the match that reads them, then the
+        // temporary fields are dropped so they never reach the caller.
+        const pipeline = [...stages];
+        if (hasKeys(match)) {
+            pipeline.push(match);
+        }
+        if (unset.length) {
+            pipeline.push({ $unset: unset });
+        }
+        const relStages = this.relationStages(entity, q, relationSummary, opts);
+        const pager = [
+            ...(q.$skip === undefined ? [] : [{ $skip: q.$skip }]),
+            ...(q.$limit === undefined ? [] : [{ $limit: q.$limit }]),
+        ];
+        // A `$required` relation drops parents when it unwinds, so paging has to come after it - as it
+        // does after an INNER JOIN. Otherwise paging first is equivalent and spares the lookups.
+        const dropsParents = relStages.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
+        pipeline.push(...(dropsParents ? [...relStages, ...pager] : [...pager, ...relStages]));
+        return pipeline;
+    }
+    /**
+     * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
+     * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.
+     */
+    relationStages(entity, q, relationSummary, opts) {
+        const meta = getMeta(entity);
         const pipeline = [];
-        if (hasKeys(firstPipelineEntry)) {
-            pipeline.push(firstPipelineEntry);
-        }
         const relKeys = (relationSummary ?? getRelationRequestSummary(meta, q.$populate)).joinableKeys;
         for (const relKey of relKeys) {
             const relOpts = meta.relations[relKey];
             if (!relOpts)
                 continue;
             if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
-                // '1m' and 'mm' should be resolved in a higher layer because they will need multiple queries
+                // '1m' and 'mm' are resolved in a higher layer: they need a second query each.
                 continue;
             }
             const relEntity = relOpts.entity();
             const relMeta = getMeta(relEntity);
+            const { query: relQuery, required } = parseRelationAtKey(relKey, q.$populate);
             // Unconditional, not gated by an explicit relation-level `$where`: the related entity's own
             // filters (in particular `security: true` ones) must apply even to a bare
             // `$populate: { rel: true }`, exactly like the SQL dialects' JOIN ON-clause filters.
-            const relationFilter = this.where(relEntity, {}, opts);
-            if (relOpts.cardinality === 'm1') {
-                const localField = meta.fields[relOpts.references[0].local];
-                pipeline.push({
-                    $lookup: {
-                        from: this.resolveTableName(relEntity, relMeta),
-                        localField: this.resolveColumnName(relOpts.references[0].local, localField),
-                        foreignField: '_id',
-                        // MongoDB runs `pipeline` after its own localField/foreignField match, so the related
-                        // entity's filters layer on top of the join condition without a `let`/`$expr` rewrite.
-                        ...(hasKeys(relationFilter) ? { pipeline: [{ $match: relationFilter }] } : {}),
-                        as: relKey,
-                    },
-                });
-            }
-            else {
-                const foreignField = relMeta.fields[relOpts.references[0].foreign];
-                const foreignFieldName = this.resolveColumnName(relOpts.references[0].foreign, foreignField);
-                const referenceSort = this.sort(relEntity, q.$sort);
-                const _id = MongoDialect.ID_KEY;
-                const referencePipelineEntry = {
-                    $match: { [foreignFieldName]: where[_id], ...relationFilter },
-                };
-                if (hasKeys(referenceSort)) {
-                    referencePipelineEntry.$sort = referenceSort;
-                }
-                pipeline.push({
-                    $lookup: {
-                        from: this.resolveTableName(relEntity, relMeta),
-                        pipeline: [referencePipelineEntry],
-                        as: relKey,
-                    },
-                });
-            }
-            pipeline.push({ $unwind: { path: `$${relKey}`, preserveNullAndEmptyArrays: true } });
+            const relationFilter = this.where(relEntity, relQuery.$where ?? {}, opts);
+            pipeline.push({
+                $lookup: {
+                    from: this.resolveTableName(relEntity, relMeta),
+                    ...this.joinKeys(meta, relMeta, relOpts),
+                    ...(hasKeys(relationFilter) ? { pipeline: [{ $match: relationFilter }] } : {}),
+                    as: relKey,
+                },
+            });
+            // `$required` drops parents with no match, the aggregation equivalent of an INNER JOIN.
+            pipeline.push({ $unwind: { path: `$${relKey}`, preserveNullAndEmptyArrays: !required } });
         }
         return pipeline;
     }
+    /**
+     * The correlated join for a single-valued or one-to-many relation. MongoDB runs a lookup's `pipeline`
+     * after its own localField/foreignField match, so the target's filters layer on top of the join
+     * condition with no `let`/`$expr` rewrite: m1 joins the parent's FK to the target's `_id`, every other
+     * direction joins the parent's `_id` to the target's FK.
+     */
+    joinKeys(meta, relMeta, relOpts) {
+        return relOpts.cardinality === 'm1'
+            ? { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY }
+            : { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
+    }
+    /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
+    renamedColumns(meta) {
+        let renamed = this.#renamedColumns.get(meta);
+        if (!renamed) {
+            renamed = getKeys(meta.fields)
+                .map((key) => [this.columnOf(meta, key), key])
+                .filter(([column, key]) => column !== key);
+            this.#renamedColumns.set(meta, renamed);
+        }
+        return renamed;
+    }
+    // Keyed by the meta object itself; entity metadata is immutable once defined.
+    #renamedColumns = new WeakMap();
     normalizeIds(meta, docs) {
         return docs?.map((doc) => this.normalizeId(meta, doc));
     }
@@ -264,12 +491,12 @@ export class MongoDialect extends AbstractDialect {
                 delete res[_id];
             }
         }
-        for (const key of getKeys(meta.fields)) {
-            const field = meta.fields[key];
-            const dbName = this.resolveColumnName(key, field);
-            if (dbName !== key && res[dbName] !== undefined) {
-                res[key] = res[dbName];
-                delete res[dbName];
+        // Only the renamed fields need touching, and which those are is a property of the entity, not of
+        // the document - so it is derived once instead of for every row of a result set.
+        for (const [column, key] of this.renamedColumns(meta)) {
+            if (res[column] !== undefined) {
+                res[key] = res[column];
+                delete res[column];
             }
         }
         const relKeys = getKeys(meta.relations).filter((key) => res[key]);
@@ -398,7 +625,7 @@ export class MongoDialect extends AbstractDialect {
             }
         }
         // $group stage
-        const { groupId, groupAccumulators, distinctReducers } = this.buildGroupSpec(parseGroupMap(q.$group, q.$agg));
+        const { groupId, groupAccumulators, distinctReducers } = this.buildGroupSpec(getMeta(entity), parseGroupMap(q.$group, q.$agg));
         pipeline.push({ $group: { _id: hasKeys(groupId) ? groupId : null, ...groupAccumulators } });
         // Project stage - rename _id fields back to their original names, and reduce collected distinct
         // sets. Needed whenever there are group keys OR any distinct alias.
@@ -420,9 +647,9 @@ export class MongoDialect extends AbstractDialect {
                 pipeline.push({ $match: havingFilter });
             }
         }
-        // $sort stage
+        // $sort stage - by alias, since $group/$project already renamed everything
         if (q.$sort) {
-            const sort = this.sort(entity, q.$sort);
+            const sort = this.aliasSort(q.$sort);
             if (hasKeys(sort)) {
                 pipeline.push({ $sort: sort });
             }
@@ -441,7 +668,7 @@ export class MongoDialect extends AbstractDialect {
      * `distinctReducers` maps each DISTINCT alias (collected via `$addToSet`) to the `$project`
      * operator that reduces its set: `$size` for `$count`, `$sum`/`$avg` for the numeric ops.
      */
-    buildGroupSpec(groupEntries) {
+    buildGroupSpec(meta, groupEntries) {
         if (!groupEntries.length) {
             throw new TypeError('aggregate requires at least one $group column or $agg function');
         }
@@ -449,25 +676,27 @@ export class MongoDialect extends AbstractDialect {
         const groupAccumulators = {};
         const distinctReducers = new Map();
         for (const entry of groupEntries) {
+            // Aliases stay as the caller wrote them ($project maps them back); the *refs* address columns.
+            const ref = entry.kind === 'key' ? `$${this.columnOf(meta, entry.alias)}` : `$${this.columnOf(meta, entry.fieldRef)}`;
             if (entry.kind === 'key') {
-                groupId[entry.alias] = `$${entry.alias}`;
+                groupId[entry.alias] = ref;
             }
             else if (entry.distinct) {
                 // Collect the set now; reduce it in $project: `$size` counts it, `$sum`/`$avg` reduce the array.
-                groupAccumulators[entry.alias] = { $addToSet: `$${entry.fieldRef}` };
+                groupAccumulators[entry.alias] = { $addToSet: ref };
                 distinctReducers.set(entry.alias, entry.op === '$count' ? '$size' : entry.op);
             }
             else if (entry.op === '$count') {
                 // COUNT(*) counts every row; COUNT(field) counts non-null values, matching SQL.
                 groupAccumulators[entry.alias] =
-                    entry.fieldRef === '*' ? { $sum: 1 } : { $sum: { $cond: [{ $ne: [`$${entry.fieldRef}`, null] }, 1, 0] } };
+                    entry.fieldRef === '*' ? { $sum: 1 } : { $sum: { $cond: [{ $ne: [ref, null] }, 1, 0] } };
             }
             else {
                 const mongoOp = MongoDialect.AGGREGATE_OP_MAP.get(entry.op);
                 if (!mongoOp) {
                     throw TypeError(`unsupported aggregate operator: ${entry.op}`);
                 }
-                groupAccumulators[entry.alias] = { [mongoOp]: `$${entry.fieldRef}` };
+                groupAccumulators[entry.alias] = { [mongoOp]: ref };
             }
         }
         return { groupId, groupAccumulators, distinctReducers };
@@ -522,13 +751,17 @@ export class MongoDialect extends AbstractDialect {
         }
         const colName = this.resolveColumnName(key, field);
         // Resolve index name from @Index metadata, or fall back to convention
-        const indexMeta = meta.indexes?.find((idx) => idx.columns.includes(key) && MongoDialect.VECTOR_INDEX_TYPES.has(idx.type));
+        const indexMeta = meta.indexes?.find((idx) => idx.columns.some((entry) => entry.column === key) && MongoDialect.VECTOR_INDEX_TYPES.has(idx.type));
         const indexName = indexMeta?.name ?? `${colName}_index`;
+        if (!limit) {
+            throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
+        }
         const stage = {
             index: indexName,
             path: colName,
             queryVector: [...search.$vector],
-            numCandidates: limit * 10,
+            // Atlas caps `numCandidates` at 10000 and wants roughly 10x the limit below that.
+            numCandidates: Math.min(limit * 10, MongoDialect.MAX_NUM_CANDIDATES),
             limit,
         };
         // Pre-filter: merge $where into $vectorSearch.filter
@@ -541,4 +774,3 @@ export class MongoDialect extends AbstractDialect {
         return { $vectorSearch: stage };
     }
 }
-//# sourceMappingURL=mongoDialect.js.map

package/dist/mongo/mongodbNativeDialect.d.ts

@@ -7,4 +7,3 @@ import { MongoDialect } from './mongoDialect.js';
  */
 export declare class MongodbNativeDialect extends MongoDialect {
 }
-//# sourceMappingURL=mongodbNativeDialect.d.ts.map

package/dist/mongo/mongodbNativeDialect.js

@@ -7,4 +7,3 @@ import { MongoDialect } from './mongoDialect.js';
  */
 export class MongodbNativeDialect extends MongoDialect {
 }
-//# sourceMappingURL=mongodbNativeDialect.js.map

package/dist/mongo/mongodbQuerier.d.ts

@@ -23,6 +23,11 @@ export declare class MongodbQuerier extends AbstractQuerier {
     private buildVectorPipeline;
     protected internalAggregate<E extends Document, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     protected internalCount<E extends Document>(entity: Type<E>, qm?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * The `_id`s a search matches. Writes need this whenever the `$where` constrains a relation, since a
+     * MongoDB `updateMany`/`deleteMany` filter cannot host a `$lookup` - reads never pay this cost.
+     */
+    private matchedIds;
     internalInsertMany<E extends Document>(entity: Type<E>, payloads: E[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     private buildConflictFilter;
@@ -49,4 +54,3 @@ export declare class MongodbQuerier extends AbstractQuerier {
     rollbackTransaction(): Promise<void>;
     internalRelease(): Promise<void>;
 }
-//# sourceMappingURL=mongodbQuerier.d.ts.map