uql-orm 0.56.0 → 0.58.0

package/dist/mongo/mongoDialect.js

@@ -3,8 +3,9 @@ import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
+import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -72,7 +73,7 @@ export class MongoDialect extends AbstractDialect {
     whereWithRelations(entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
         const lookups = { stages: [], temps: [] };
-        const filter = this.renderFilter(entity, this.scopedWhere(meta, where, opts), opts, lookups);
+        const filter = this.renderFilter(entity, this.scopedWhere(meta, where, 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. */
@@ -91,14 +92,14 @@ export class MongoDialect extends AbstractDialect {
      * 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) {
+    renderFilter(entity, where = {}, lookups) {
         const meta = getMeta(entity);
         const filter = {};
         for (const [rawKey, rawVal] of Object.entries(where)) {
             let key = rawKey;
             let val = rawVal;
             if (MongoDialect.isGroupOp(key)) {
-                this.appendLogicalOperator(filter, entity, key, val, opts, lookups);
+                this.appendLogicalOperator(filter, entity, key, val, lookups);
             }
             else if (key === '$text') {
                 // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
@@ -110,7 +111,7 @@ export class MongoDialect extends AbstractDialect {
                 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));
+                Object.assign(filter, this.appendRelationLookup(meta, key, val, lookups));
             }
             else {
                 this.assertNoRaw(val);
@@ -140,12 +141,12 @@ export class MongoDialect extends AbstractDialect {
      * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
      * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
      */
-    appendLogicalOperator(filter, entity, key, val, opts, lookups) {
+    appendLogicalOperator(filter, entity, key, val, lookups) {
         const { join, negate } = MongoDialect.GROUP_OPS[key];
         const parts = MongoDialect.groupClauses(key, val)
             .map((filterIt) => {
             this.assertNoRaw(filterIt);
-            return this.renderFilter(entity, filterIt, opts, lookups);
+            return this.renderFilter(entity, filterIt, lookups);
         })
             .filter((part) => Object.keys(part).length > 0);
         if (!parts.length) {
@@ -164,80 +165,72 @@ export class MongoDialect extends AbstractDialect {
      * `$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);
+    appendRelationLookup(meta, relKey, val, lookups) {
         const temp = `${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: COUNT_ALIAS }];
-        // 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.scopedWhere(relMeta, targetCondition), opts);
+        const where = (sizeVal === undefined ? val : {});
         lookups.temps.push(temp);
-        lookups.stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts));
+        lookups.stages.push(this.relationLookup(meta, meta.relations[relKey], where, temp, tail));
         return sizeVal === undefined
             ? { [`${temp}.0`]: { $exists: true } }
             : { $expr: this.compareRelationCount(temp, sizeVal) };
     }
     /**
-     * The correlated `$lookup` for one relation, as `temp`: through its junction for a ManyToMany, or
-     * straight at the target otherwise. `tail` decides what the lookup leaves behind - a row to test
-     * for existence, or a `$count` - so a filter and an ordering build the same stage.
+     * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
+     * the target, or for a many-to-many from inside its junction's rows. The caller's filter bypass is not
+     * passed down, as on the SQL dialects. `tail` decides what the lookup leaves behind - a row to test for
+     * existence, or a `$count` - so a filter and an ordering build the same stage.
      */
-    relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
-        return relOpts.cardinality === 'mm' && relOpts.through
-            ? this.junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts)
-            : {
-                $lookup: {
-                    from: this.resolveTableName(relMeta),
-                    ...this.joinKeys(meta, relMeta, relOpts),
-                    pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), ...tail],
-                    as: temp,
-                },
+    relationLookup(meta, relOpts, where, temp, tail) {
+        const relEntity = relOpts.entity();
+        const relMeta = getMeta(relEntity);
+        const targetScope = this.renderFilter(relEntity, this.scopedWhere(relMeta, where));
+        const targetMatch = hasKeys(targetScope) ? [{ $match: targetScope }] : [];
+        const from = this.resolveTableName(relMeta);
+        if (!relOpts.through) {
+            return {
+                $lookup: { from, ...this.joinKeys(meta, relMeta, relOpts), pipeline: [...targetMatch, ...tail], as: temp },
             };
+        }
+        const junction = this.junctionOf(meta, relOpts, relMeta, relOpts.through());
+        const target = {
+            $lookup: {
+                from,
+                localField: junction.target,
+                foreignField: MongoDialect.ID_KEY,
+                pipeline: [...targetMatch, { $limit: 1 }],
+                as: REL_NESTED_KEY,
+            },
+        };
+        return {
+            $lookup: {
+                ...junction.lookup,
+                pipeline: [...junction.scope, target, { $match: { [`${REL_NESTED_KEY}.0`]: { $exists: true } } }, ...tail],
+                as: temp,
+            },
+        };
     }
     /**
-     * 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.
+     * The junction a many-to-many reaches its targets through: the lookup keys matching a parent's rows of
+     * it, its own filters, since a soft-deleted link is not a link, and the field holding each target's id.
+     * Each end is one field matched against one `_id`, so both sides must be sole-keyed.
      */
-    junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts) {
-        const throughEntity = relOpts.through();
-        const throughMeta = getMeta(throughEntity);
-        const junctionScope = this.renderFilter(throughEntity, this.scopedWhere(throughMeta, {}), opts);
-        const nested = REL_NESTED_KEY;
-        // Both ends are one column here - each `$lookup` matches one field against `_id` - so both sides
-        // must be sole-keyed. Sliced rather than indexed positionally: `references[1]` is the parent's
-        // *second* column on a composite, a real column of the wrong side.
+    junctionOf(meta, relOpts, relMeta, through) {
+        const throughMeta = getMeta(through);
         assertSoleId(meta, 'MongoDB');
         assertSoleId(relMeta, 'MongoDB');
         const [parentJoin] = parentJoins(relOpts, meta.ids.length);
         const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
+        const scope = this.renderFilter(through, this.scopedWhere(throughMeta, {}));
         return {
-            $lookup: {
+            lookup: {
                 from: this.resolveTableName(throughMeta),
                 localField: MongoDialect.ID_KEY,
                 foreignField: this.columnOf(throughMeta, parentJoin.joined),
-                pipeline: [
-                    ...(hasKeys(junctionScope) ? [{ $match: junctionScope }] : []),
-                    {
-                        $lookup: {
-                            from: this.resolveTableName(relMeta),
-                            localField: this.columnOf(throughMeta, targetColumn),
-                            foreignField: MongoDialect.ID_KEY,
-                            pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), { $limit: 1 }],
-                            as: nested,
-                        },
-                    },
-                    { $match: { [`${nested}.0`]: { $exists: true } } },
-                    ...tail,
-                ],
-                as: temp,
             },
+            scope: hasKeys(scope) ? [{ $match: scope }] : [],
+            target: this.columnOf(throughMeta, targetColumn),
         };
     }
     /**
@@ -245,7 +238,7 @@ export class MongoDialect extends AbstractDialect {
      * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
      */
     compareRelationCount(temp, sizeVal) {
-        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] };
+        const count = this.tally(temp);
         if (typeof sizeVal === 'number') {
             return { $eq: [count, sizeVal] };
         }
@@ -295,7 +288,7 @@ export class MongoDialect extends AbstractDialect {
     mapTableNameRow(row) {
         return row.table_name;
     }
-    /** String operators → { pattern: (v) => regex, caseInsensitive } */
+    /** String operators -> { pattern: (v) => regex, caseInsensitive } */
     static REGEX_OP_MAP = new Map([
         ['$startsWith', { wrap: (v) => `^${v}`, ci: false }],
         ['$istartsWith', { wrap: (v) => `^${v}`, ci: true }],
@@ -340,7 +333,7 @@ export class MongoDialect extends AbstractDialect {
                 result[op] = val;
                 continue;
             }
-            // String/pattern → regex operators (8 variants including $like/$ilike)
+            // String/pattern -> regex operators (8 variants including $like/$ilike)
             const regexEntry = MongoDialect.REGEX_OP_MAP.get(op);
             if (regexEntry) {
                 result['$regex'] = regexEntry.wrap(val);
@@ -468,7 +461,7 @@ export class MongoDialect extends AbstractDialect {
      * per parent, and the `$set` that lifts the tally onto the document as the field the `$sort` then
      * orders by. A parent with no related row gets no lookup result at all, which is a zero.
      */
-    sortCountStages(entity, sort, opts) {
+    sortCountStages(entity, sort) {
         const meta = getMeta(entity);
         const stages = [];
         const fields = [];
@@ -477,18 +470,78 @@ export class MongoDialect extends AbstractDialect {
             if (!relOpts || parseSortByCount(value) === undefined) {
                 continue;
             }
-            const relEntity = relOpts.entity();
-            const relMeta = getMeta(relEntity);
             const temp = sortCountField(key);
-            const targetScope = this.renderFilter(relEntity, this.scopedWhere(relMeta, {}), opts);
-            const tail = [{ $count: COUNT_ALIAS }];
-            stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts), {
-                $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] } },
-            });
+            stages.push(this.tallyLookup(meta, relOpts, {}, temp), { $addFields: { [temp]: this.tally(temp) } });
             fields.push(temp);
         }
         return { stages, fields };
     }
+    /** The correlated lookup counting a relation's rows, which `where` narrows, into `temp`. */
+    tallyLookup(meta, relOpts, where, temp) {
+        return this.relationLookup(meta, relOpts, where, temp, [{ $count: COUNT_ALIAS }]);
+    }
+    /** The tally a lookup left in `temp`, which holds no row at all where nothing matched: a zero. */
+    tally(temp) {
+        return { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] };
+    }
+    /**
+     * The lookups reading each to-many a query populates, and the tally of each `$count`, onto the fields
+     * its rows answer under, and the fields they parked a junction's pairings or a tally on taken back out.
+     * [The design](../../../../architecture/relations-in-one-statement.md).
+     */
+    relationReadStages(entity, q) {
+        const meta = getMeta(entity);
+        const stages = [];
+        const temps = [];
+        for (const relKey of getRelationRequestSummary(meta, q.$populate).toManyKeys) {
+            stages.push(...this.toManyLookup(meta, relKey, parseRelationAtKey(relKey, q.$populate).query, temps));
+        }
+        for (const { relKey, relation, where } of countedRelations(meta, q.$count)) {
+            const temp = `${REL_TEMP_PREFIX}count_${relKey}`;
+            temps.push(temp);
+            stages.push(this.tallyLookup(meta, relation, where, temp), {
+                $addFields: { [`${COUNT_RESULT_KEY}.${relKey}`]: this.tally(temp) },
+            });
+        }
+        return temps.length ? [...stages, { $unset: temps }] : stages;
+    }
+    /**
+     * A to-many's rows as a lookup running their own read, whose filters, ordering and page apply per
+     * parent inside it. A many-to-many reads its targets, each once, by the ids its junction pairs the
+     * parent with, parked in a temporary field of the parent's.
+     */
+    toManyLookup(meta, relKey, query, temps) {
+        const relOpts = relationOf(meta, relKey);
+        const relEntity = relOpts.entity();
+        const relMeta = getMeta(relEntity);
+        const read = this.aggregationPipeline(relEntity, query);
+        const pipeline = read.length ? { pipeline: read } : {};
+        const from = this.resolveTableName(relMeta);
+        if (!relOpts.through) {
+            return [{ $lookup: { from, ...this.joinKeys(meta, relMeta, relOpts), ...pipeline, as: relKey } }];
+        }
+        const junction = this.junctionOf(meta, relOpts, relMeta, relOpts.through());
+        const temp = `${REL_TEMP_PREFIX}${relKey}`;
+        temps.push(temp);
+        return [
+            {
+                $lookup: {
+                    ...junction.lookup,
+                    pipeline: [...junction.scope, { $project: { [junction.target]: 1 } }],
+                    as: temp,
+                },
+            },
+            {
+                $lookup: {
+                    from,
+                    localField: `${temp}.${junction.target}`,
+                    foreignField: MongoDialect.ID_KEY,
+                    ...pipeline,
+                    as: relKey,
+                },
+            },
+        ];
+    }
     /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
     sortsRelations(entity, sort) {
         if (!sort) {
@@ -498,7 +551,7 @@ export class MongoDialect extends AbstractDialect {
         return someKey(sort, (key) => Boolean(meta.relations[key]));
     }
     /**
-     * Aggregate results are keyed by `$group`/`$agg` alias rather than by column, so an aggregate
+     * Aggregate results are keyed by `$group`/`$select` 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) {
@@ -527,7 +580,7 @@ export class MongoDialect extends AbstractDialect {
             ...stages,
             ...(hasKeys(filter) ? [{ $match: filter }] : []),
             ...(unset.length ? [{ $unset: unset }] : []),
-            ...this.readStages(entity, q, opts, {
+            ...this.readStages(entity, q, {
                 sort: this.sort(entity, q.$sort, q.$populate),
                 pager: [
                     ...(q.$skip === undefined ? [] : [{ $skip: assertNonNegativeInteger(q.$skip, '$skip') }]),
@@ -544,13 +597,15 @@ export class MongoDialect extends AbstractDialect {
      * Shared by the plain pipeline and the `$vectorSearch` one, which each used to spell the order out
      * for themselves and each got a different part of it wrong.
      */
-    readStages(entity, q, opts, extra = {}) {
+    readStages(entity, q, extra = {}) {
         const meta = getMeta(entity);
         const joins = resolveQueryJoins(meta, q);
         // The tally an ordering by a relation's size reads, and the field it parks it on: both belong
         // with the lookups, since the `$sort` right after them is what they exist for.
-        const counted = this.sortCountStages(entity, q.$sort, opts);
-        const lookups = [...this.lookupStages(meta, joins, undefined, opts), ...counted.stages];
+        const counted = this.sortCountStages(entity, q.$sort);
+        const lookups = [...this.lookupStages(meta, joins), ...counted.stages];
+        // Each to-many and each `$count`, which neither drop nor reorder a row, so they read the page alone.
+        const related = this.relationReadStages(entity, q);
         const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
         const pager = extra.pager ?? [];
         // Merged into the query's own projection rather than standing in for one: a query that asked
@@ -578,7 +633,7 @@ export class MongoDialect extends AbstractDialect {
         // ordering and the page have to run after it to address the set the caller actually receives.
         const dedup = q.$distinct ? this.distinctStages(projected) : [];
         if (dedup.length) {
-            return [...lookups, ...project, ...dedup, ...sort, ...pager];
+            return [...lookups, ...related, ...project, ...dedup, ...sort, ...pager];
         }
         // A `$required` relation drops parents when it unwinds, and an ordering may read a field only a
         // lookup produces: either one puts the lookups first, as an INNER JOIN does. Otherwise paging
@@ -587,6 +642,7 @@ export class MongoDialect extends AbstractDialect {
             lookups.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
         return [
             ...(lookupsFirst ? [...lookups, ...sort, ...pager] : [...sort, ...pager, ...lookups]),
+            ...related,
             ...unset,
             ...project,
         ];
@@ -610,42 +666,28 @@ export class MongoDialect extends AbstractDialect {
     }
     /**
      * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
-     * the joined documents, and the `_id` a to-many fill groups children by. It goes last, after the
-     * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
-     * empty, and is why the pipeline emitted no projection at all and returned every column.
+     * each populated relation and the tallies. It goes last, after the lookups have read the join keys -
+     * projecting any earlier is what used to leave `$populate` empty, and is why the pipeline emitted no
+     * projection at all and returned every column.
      */
     pipelineProjection(entity, q) {
         if (!q.$select && !q.$exclude) {
             return undefined;
         }
         const projection = this.select(entity, q.$select, q.$exclude);
-        const summary = getRelationRequestSummary(getMeta(entity), q.$populate);
-        for (const relKey of summary.joinableKeys) {
+        for (const relKey of getRelationRequestSummary(getMeta(entity), q.$populate).requestedKeys) {
             projection[relKey] = 1;
         }
-        // Only ever undoes an exclusion: a relation cannot be filled onto a parent with no key.
-        if (summary.requestedKeys.length && projection[MongoDialect.ID_KEY] === 0) {
-            delete projection[MongoDialect.ID_KEY];
+        if (q.$count) {
+            projection[COUNT_RESULT_KEY] = 1;
         }
         return projection;
     }
-    /**
-     * `$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, opts) {
-        // The whole query, not `$populate` alone: an ordering by a related field needs that relation
-        // looked up just as much as selecting it does. A `$lookup` does put a field on the document
-        // where a SQL join is invisible, so the ones only the ordering asked for are unset again by
-        // {@link readStages} before the caller sees the row.
-        const meta = getMeta(entity);
-        return this.lookupStages(meta, resolveQueryJoins(meta, q), undefined, opts);
-    }
     /**
      * The `$lookup`/`$unwind` pair for each relation joined below `parent`, its own relations nested
      * inside its pipeline and resolved before the projection that reads them.
      */
-    lookupStages(parentMeta, joins, parent, opts) {
+    lookupStages(parentMeta, joins, parent) {
         const pipeline = [];
         // Every join at this level hangs off `parent`, so its metadata is `parentMeta` - no branch, and
         // no union of two unrelated entity types to resolve the join column through.
@@ -654,19 +696,19 @@ export class MongoDialect extends AbstractDialect {
                 continue;
             }
             // 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(join.entity, join.query.$where ?? {}, opts);
+            // filters (in particular `security: true` ones) apply even to a bare `$populate: { rel: true }`,
+            // and the caller's bypass never reaches them, exactly like the SQL dialects' JOIN ON-clause filters.
+            const relationFilter = this.where(join.entity, join.query.$where ?? {});
             // The relation's own projection runs inside the lookup, where its keys resolve against the
             // related entity. Left out, `$populate: { rel: { $select } }` returned all of `rel`'s columns.
             const relationProjection = this.pipelineProjection(join.entity, join.query);
             // MongoDB returns `_id` unless a projection subtracts it, so dropping the key from the map is
-            // how a joined document keeps its own id - as it does on the SQL dialects, and as a nested
-            // to-many fill needs.
+            // how a joined document keeps its own id, as it does on the SQL dialects.
             delete relationProjection?.[MongoDialect.ID_KEY];
             const lookupPipeline = [
                 ...(hasKeys(relationFilter) ? [{ $match: relationFilter }] : []),
-                ...this.lookupStages(join.meta, joins, join, opts),
+                ...this.lookupStages(join.meta, joins, join),
+                ...this.relationReadStages(join.entity, join.query),
                 ...(relationProjection ? [{ $project: relationProjection }] : []),
             ];
             pipeline.push({
@@ -916,7 +958,7 @@ export class MongoDialect extends AbstractDialect {
             }
         }
         // $group stage
-        const { groupId, groupAccumulators, distinctReducers } = this.buildGroupSpec(getMeta(entity), parseGroupMap(q.$group, q.$agg));
+        const { groupId, groupAccumulators, distinctReducers } = this.buildGroupSpec(getMeta(entity), parseGroupMap(q.$group, q.$select));
         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.
@@ -966,7 +1008,7 @@ export class MongoDialect extends AbstractDialect {
      */
     buildGroupSpec(meta, groupEntries) {
         if (!groupEntries.length) {
-            throw new TypeError('aggregate requires at least one $group column or $agg function');
+            throw new TypeError('aggregate requires at least one $group column or $select function');
         }
         const groupId = {};
         const groupAccumulators = {};

package/dist/mongo/mongodbQuerier.d.ts

@@ -1,7 +1,6 @@
 import type { Document, MongoClient } from 'mongodb';
 import { AbstractQuerier } from '../querier/index.js';
 import type { EntityData, ExtraOptions, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
-import { type ParentPartition } from '../util/index.js';
 import type { MongoDialect } from './mongoDialect.js';
 export declare class MongodbQuerier extends AbstractQuerier {
     readonly dialect: MongoDialect;
@@ -11,27 +10,21 @@ export declare class MongodbQuerier extends AbstractQuerier {
     constructor(dialect: MongoDialect, conn: MongoClient, extra?: ExtraOptions | undefined);
     private execute;
     protected internalFindMany<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    protected internalFindManyStream<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<E, void, unknown>;
     /**
-     * Every parent's own bounded page. One `$unionWith` per parent after the first, so the whole page is
-     * one round trip - measured ~6x faster than a query each (11.0 ms -> 1.9 ms at 50 parents, 87.5 ms
-     * -> 14.1 ms at 500), because `execute` serializes on the session and a query each is N round trips
-     * rather than N concurrent ones.
-     *
-     * Both arms return documents with their own relations already filled, so this only chooses between
-     * them: leaving that to the caller once meant the arm that fills its own did it twice.
-     * [The design](../../../../architecture/populate-limits.md).
+     * The cursor a read runs on: the aggregation pipeline for a clause only a stage can express - a
+     * lookup, a grouping, a vector search - and the plain `find` cursor for everything else. One routing
+     * for a read and a stream alike, so both load the same relations.
      */
-    protected internalFindManyPerParent<E extends Document>(entity: Type<E>, q: Query<E>, { joins, parents }: ParentPartition): Promise<E[]>;
-    /** Every parent's page as one `$unionWith` pipeline. */
-    private readInOnePipeline;
-    /** A query each, for what one pipeline cannot carry. `internalFindMany` fills its own relations. */
-    private readEachInTurn;
-    protected internalFindManyStream<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<E, void, unknown>;
+    private readCursor;
+    /**
+     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter
+     * or order by a relation, and the grouping `$distinct` is.
+     */
+    private readsThroughPipeline;
     private buildScalarProjection;
     /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */
     private buildFindCursor;
-    /** Execute an aggregation pipeline and normalize `_id` → `id`. */
-    private runPipeline;
     /**
      * Build an aggregation pipeline for vector similarity search.
      * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.