uql-orm 0.69.0 → 0.70.0

package/dist/mongo/mongoDialect.d.ts

@@ -33,20 +33,15 @@ export declare class MongoDialect extends AbstractDialect {
     columnOf<E>(meta: EntityMeta<E>, key: string): string;
     where<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): Filter<E>;
     /**
-     * A `$where` that may constrain relations, as the `$lookup` stages it needs and the `$match` reading
-     * them: each condition a lookup into a temporary field (`unset` names them), so `$or` keeps its meaning.
+     * The stages every pipeline starts with: the `$lookup` each relation condition needs, into a temporary
+     * field so `$or` keeps its meaning, the `$match` reading them, and the temporaries taken back out. Each
+     * relation aggregate the `$where` or `named` reads is left on the document, once, under its column.
      */
-    whereWithRelations<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): {
-        readonly stages: MongoAggregationPipelineEntry<Document>[];
-        readonly filter: Filter<E>;
-        readonly unset: string[];
-    };
-    /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
-    constrainsRelations<E extends Document>(entity: Type<E>, where: QueryWhere<E> | undefined): boolean;
+    matchStages<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions, named?: readonly string[]): MongoAggregationPipelineEntry<Document>[];
     /**
      * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
-     * 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.
+     * recursion). A relation, or a relation aggregate, needs `$lookup` stages, so it is only accepted
+     * when `lookups` is given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
     protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookups?: RelationLookups): Filter<E>;
     /**
@@ -141,20 +136,14 @@ export declare class MongoDialect extends AbstractDialect {
     };
     /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
     readsAggregates<E extends Document>(entity: Type<E>, q: Query<E>): boolean;
-    /**
-     * The relation aggregates one query reads: the ones its projection carries, plus any its `$where` or
-     * `$sort` names, which a read materializes whether or not it answers with them.
-     */
+    /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
     private aggregateKeys;
     /**
-     * The stages a relation aggregate a query names needs: the correlated lookup that reads the related
-     * rows - narrowed, ordered and capped as the field declared - ending in the tally or total it wants,
-     * and the `$addFields` that puts the value on the document under the field's own name.
-     *
-     * The same spec the SQL dialects render as a correlated subquery: a relation aggregate is data, so a
-     * document engine builds it out of stages rather than being refused a language it does not speak.
+     * The relation aggregate `key` computes, put on the document under its column by the stages
+     * {@link aggregateStages} builds from the same spec SQL renders as a subquery. Once however many
+     * clauses read it; a key computing none adds nothing.
      */
-    private aggregateFieldStages;
+    private appendAggregateField;
     /**
      * One relation aggregate on the document under `field`: the correlated lookup that reads the related
      * rows - narrowed, ordered and capped as the spec says - ending in the tally or total it wants, and
@@ -258,13 +247,28 @@ export declare class MongoDialect extends AbstractDialect {
     /**
      * Build MongoDB aggregation pipeline stages from a QueryAggregate.
      */
-    buildAggregateStages<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Record<string, unknown>[];
+    buildAggregateStages<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
     /**
-     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage.
-     * `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.
+     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage, and the
+     * `columns` its `$project` reads each result from: a group key out of `_id`, a DISTINCT set by its
+     * size, and a `$sum` as null where it read no value, as SQL answers it. `named` is every field it reads,
+     * filters included, so each relation aggregate among them is put on the document first.
      */
     private buildGroupSpec;
+    /** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
+    private static countOf;
+    /** Whether `ref` is null or missing: an expression compares a missing field as neither. */
+    private static isNullExpr;
+    /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
+    private groupedPath;
+    /**
+     * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
+     * comparisons and the logical operators translate, anything else is refused by name. `named` gathers
+     * the fields it reads, so a relation aggregate among them is on the document first.
+     */
+    private whereExpression;
+    /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
+    private fieldExpression;
     private buildHavingFilter;
     /**
      * Separate vector sort entries from regular sort entries.
@@ -275,7 +279,7 @@ export declare class MongoDialect extends AbstractDialect {
      * Build a `$vectorSearch` aggregation pipeline stage.
      * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
      */
-    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): Record<string, unknown>;
+    buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): MongoAggregationPipelineEntry<Document>;
 }
 export type MongoAggregationPipelineEntry<E extends Document> = {
     $lookup?: MongoAggregationLookup;

package/dist/mongo/mongoDialect.js

@@ -1,11 +1,11 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
-import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, } from '../dialect/aliases.js';
+import { groupPathField, resolveGroupJoins, 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, RelationAggregate } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { QueryRaw } from '../type/queryRaw.js';
+import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
     ifNotExists: false,
@@ -22,6 +22,7 @@ export const mongoDialectFeatures = {
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
     serverSideCursors: false,
+    correlatedWrites: false,
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
 const HEX_24 = /^[0-9a-f]{24}$/i;
@@ -61,30 +62,27 @@ export class MongoDialect extends AbstractDialect {
         return this.renderFilter(entity, this.scopedWhere(meta, where, opts));
     }
     /**
-     * A `$where` that may constrain relations, as the `$lookup` stages it needs and the `$match` reading
-     * them: each condition a lookup into a temporary field (`unset` names them), so `$or` keeps its meaning.
+     * The stages every pipeline starts with: the `$lookup` each relation condition needs, into a temporary
+     * field so `$or` keeps its meaning, the `$match` reading them, and the temporaries taken back out. Each
+     * relation aggregate the `$where` or `named` reads is left on the document, once, under its column.
      */
-    whereWithRelations(entity, where = {}, opts = {}) {
+    matchStages(entity, where = {}, opts = {}, named = []) {
         const meta = getMeta(entity);
         const lookups = { stages: [], temps: [] };
-        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. */
-    constrainsRelations(entity, where) {
-        if (!where) {
-            return false;
+        for (const key of named) {
+            this.appendAggregateField(meta, key, lookups);
         }
-        const meta = getMeta(entity);
-        const whereMap = where;
-        return someKey(whereMap, (key) => MongoDialect.isGroupOp(key)
-            ? (whereMap[key] ?? []).some((it) => !(it instanceof QueryRaw) && this.constrainsRelations(entity, it))
-            : Boolean(meta.relations[key]));
+        const filter = this.renderFilter(entity, this.scopedWhere(meta, where, opts), lookups);
+        return [
+            ...lookups.stages,
+            ...(hasKeys(filter) ? [{ $match: filter }] : []),
+            ...(lookups.temps.length ? [{ $unset: lookups.temps }] : []),
+        ];
     }
     /**
      * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
-     * 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.
+     * recursion). A relation, or a relation aggregate, needs `$lookup` stages, so it is only accepted
+     * when `lookups` is given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
     renderFilter(entity, where = {}, lookups) {
         const meta = getMeta(entity);
@@ -110,6 +108,12 @@ export class MongoDialect extends AbstractDialect {
             else {
                 this.assertNoRaw(val);
                 this.assertKnownPathRoot(meta, key);
+                if (aggregateOf(meta.fields[key])) {
+                    if (!lookups) {
+                        throw new TypeError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
+                    }
+                    this.appendAggregateField(meta, key, lookups);
+                }
                 const isReference = !!meta.fields[key]?.references;
                 key = this.pathOf(meta, key);
                 if ((key === MongoDialect.ID_KEY || isReference) && !isOperatorObject(val)) {
@@ -423,16 +427,11 @@ export class MongoDialect extends AbstractDialect {
         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) => {
-            // Swept in with the rest of the entity's fields, a computed one is skipped; asked for by name
-            // it is refused, since the document holds nothing to project under it.
+            // A computed field writing SQL leaves the document nothing to project: refused asked for by
+            // name, skipped swept in with the rest. A relation aggregate is on it by now, like any column.
             const field = meta.fields[key];
-            if (field?.computed) {
-                // An aggregate is on the document by the time this projects, under the field's own name; SQL
-                // is refused where it was asked for by name, and skipped where it was swept in with the rest.
-                if (aggregateOf(field)) {
-                    acc[key] = 1;
-                }
-                else if (selectMap && key in selectMap) {
+            if (field?.computed && !aggregateOf(field)) {
+                if (selectMap && key in selectMap) {
                     assertReadable(meta, key);
                 }
                 return acc;
@@ -521,36 +520,25 @@ export class MongoDialect extends AbstractDialect {
     readsAggregates(entity, q) {
         return this.aggregateKeys(entity, q).length > 0;
     }
-    /**
-     * The relation aggregates one query reads: the ones its projection carries, plus any its `$where` or
-     * `$sort` names, which a read materializes whether or not it answers with them.
-     */
+    /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
     aggregateKeys(entity, q) {
         const meta = getMeta(entity);
         const projected = normalizeScalarFieldSelection(meta, asSelectMap(q.$select), q.$exclude);
-        const named = [...Object.keys(q.$where ?? {}), ...Object.keys(q.$sort ?? {})];
-        return [...new Set([...projected, ...named])].flatMap((key) => {
-            const spec = aggregateOf(meta.fields[key]);
-            return spec ? [[key, spec]] : [];
-        });
+        return [...projected, ...Object.keys(q.$sort ?? {})].filter((key) => aggregateOf(meta.fields[key]));
     }
     /**
-     * The stages a relation aggregate a query names needs: the correlated lookup that reads the related
-     * rows - narrowed, ordered and capped as the field declared - ending in the tally or total it wants,
-     * and the `$addFields` that puts the value on the document under the field's own name.
-     *
-     * The same spec the SQL dialects render as a correlated subquery: a relation aggregate is data, so a
-     * document engine builds it out of stages rather than being refused a language it does not speak.
+     * The relation aggregate `key` computes, put on the document under its column by the stages
+     * {@link aggregateStages} builds from the same spec SQL renders as a subquery. Once however many
+     * clauses read it; a key computing none adds nothing.
      */
-    aggregateFieldStages(meta, aggregates) {
-        const stages = [];
-        const temps = [];
-        for (const [key, spec] of aggregates) {
-            const temp = `${REL_TEMP_PREFIX}${key}`;
-            stages.push(...this.aggregateStages(meta, spec, temp, key));
-            temps.push(temp);
+    appendAggregateField(meta, key, lookups) {
+        const spec = aggregateOf(meta.fields[key]);
+        const temp = `${REL_TEMP_PREFIX}${key}`;
+        if (!spec || lookups.temps.includes(temp)) {
+            return;
         }
-        return { stages, temps };
+        lookups.temps.push(temp);
+        lookups.stages.push(...this.aggregateStages(meta, spec, temp, this.columnOf(meta, key)));
     }
     /**
      * One relation aggregate on the document under `field`: the correlated lookup that reads the related
@@ -651,7 +639,7 @@ export class MongoDialect extends AbstractDialect {
             return false;
         }
         const meta = getMeta(entity);
-        return someKey(sort, (key) => Boolean(meta.relations[key]));
+        return someKey(sort, (key) => !!meta.relations[key]);
     }
     /**
      * Aggregate results are keyed by `$group`/`$select` alias rather than by column, so an aggregate
@@ -677,22 +665,12 @@ export class MongoDialect extends AbstractDialect {
         return this.columnOf(meta, key.slice(0, dot)) + key.slice(dot);
     }
     aggregationPipeline(entity, q, opts) {
-        // 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.
-        // Every relation aggregate the query reads comes first: a `$match`, a `$sort` and the projection all
-        // name it as a field of the document, which is what these stages make true.
-        const aggregates = this.aggregateFieldStages(getMeta(entity), this.aggregateKeys(entity, q));
-        const { stages, filter, unset } = this.whereWithRelations(entity, q.$where, opts);
         return [
-            ...aggregates.stages,
-            ...stages,
-            ...(hasKeys(filter) ? [{ $match: filter }] : []),
-            ...(unset.length ? [{ $unset: unset }] : []),
+            ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
             ...this.readStages(entity, q, {
                 sort: this.sort(entity, q.$sort, q.$populate),
                 pager: this.pagerStages(q),
             }),
-            ...(aggregates.temps.length ? [{ $unset: aggregates.temps }] : []),
         ];
     }
     /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
@@ -1037,33 +1015,19 @@ export class MongoDialect extends AbstractDialect {
      * Build MongoDB aggregation pipeline stages from a QueryAggregate.
      */
     buildAggregateStages(entity, q, opts) {
-        const pipeline = [];
-        // $match stage (WHERE equivalent - before grouping)
-        if (q.$where) {
-            const filter = this.where(entity, q.$where, opts);
-            if (hasKeys(filter)) {
-                pipeline.push({ $match: filter });
-            }
-        }
-        // $group stage
-        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.
-        if (hasKeys(groupId) || distinctReducers.size) {
-            const project = { _id: 0 };
-            for (const alias of Object.keys(groupId)) {
-                project[alias] = `$_id.${alias}`;
-            }
-            for (const alias of Object.keys(groupAccumulators)) {
-                const reduceOp = distinctReducers.get(alias);
-                project[alias] = reduceOp ? { [reduceOp]: `$${alias}` } : 1;
-            }
-            pipeline.push({ $project: project });
-        }
+        const meta = getMeta(entity);
+        const joins = resolveGroupJoins(meta, q.$group);
+        const { groupId, accumulators, columns, named } = this.buildGroupSpec(meta, parseGroupMap(q.$group, q.$select), joins);
+        const pipeline = [
+            ...this.matchStages(entity, q.$where, opts, named),
+            ...this.lookupStages(meta, joins),
+            { $group: { _id: hasKeys(groupId) ? groupId : null, ...accumulators } },
+            // `$group` answers with `_id` even when grouping by nothing, and with what `columns` read to the end.
+            { $project: { _id: 0, ...columns } },
+        ];
         // Everything the pipeline emits, which is all `$having` and `$sort` may name. The `$project`
         // above has already dropped the rest, so an unchecked key matched nothing or ordered by nothing.
-        const emitted = new Set([...Object.keys(groupId), ...Object.keys(groupAccumulators)]);
+        const emitted = new Set(Object.keys(columns));
         // $match stage for HAVING (post-group filtering)
         if (q.$having) {
             assertAggregateColumns(q.$having, emitted, '$having');
@@ -1084,39 +1048,139 @@ export class MongoDialect extends AbstractDialect {
         return pipeline;
     }
     /**
-     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage.
-     * `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.
+     * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage, and the
+     * `columns` its `$project` reads each result from: a group key out of `_id`, a DISTINCT set by its
+     * size, and a `$sum` as null where it read no value, as SQL answers it. `named` is every field it reads,
+     * filters included, so each relation aggregate among them is put on the document first.
      */
-    buildGroupSpec(meta, groupEntries) {
+    buildGroupSpec(meta, groupEntries, joins) {
         if (!groupEntries.length) {
             throw new TypeError('aggregate requires at least one $group column or $select function');
         }
         const groupId = {};
-        const groupAccumulators = {};
-        const distinctReducers = new Map();
+        const accumulators = {};
+        const columns = {};
+        const named = [];
         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] = ref;
+                groupId[entry.alias] = `$${this.groupedPath(meta, joins, entry.path, named)}`;
+                columns[entry.alias] = `$_id.${entry.alias}`;
+                continue;
             }
-            else if (entry.distinct) {
-                // Collect the set now; reduce it in $project: `$size` counts it, `$sum`/`$avg` reduce the array.
-                groupAccumulators[entry.alias] = { $addToSet: ref };
-                distinctReducers.set(entry.alias, entry.op === '$count' ? '$size' : entry.op);
+            named.push(entry.fieldRef);
+            const ref = `$${this.columnOf(meta, entry.fieldRef)}`;
+            const test = entry.where && this.whereExpression(meta, entry.where, named);
+            // What the accumulator reads from a row its own `$where` passes, and from one it does not.
+            const read = (passed, failed) => (test ? { $cond: [test, passed, failed] } : passed);
+            columns[entry.alias] = 1;
+            if (entry.distinct) {
+                accumulators[entry.alias] = { $addToSet: read(ref, '$$REMOVE') };
+                columns[entry.alias] = { $size: `$${entry.alias}` };
             }
             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: [ref, null] }, 1, 0] } };
+                accumulators[entry.alias] = { $sum: entry.fieldRef === '*' ? read(1, 0) : read(MongoDialect.countOf(ref), 0) };
             }
             else {
-                // `$sum`, `$avg`, `$min` and `$max` are MongoDB accumulators of the same name.
-                groupAccumulators[entry.alias] = { [entry.op]: ref };
+                // `$sum`, `$avg`, `$min` and `$max` are MongoDB accumulators of the same name, and skip a null.
+                accumulators[entry.alias] = { [entry.op]: read(ref, null) };
+            }
+            if (entry.op === '$sum' && !entry.distinct) {
+                const counted = `${SUM_COUNT_ALIAS}_${entry.alias}`;
+                accumulators[counted] = { $sum: read(MongoDialect.countOf(ref), 0) };
+                columns[entry.alias] = { $cond: [{ $eq: [`$${counted}`, 0] }, null, `$${entry.alias}`] };
+            }
+        }
+        return { groupId, accumulators, columns, named };
+    }
+    /** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
+    static countOf(ref) {
+        return { $cond: [MongoDialect.isNullExpr(ref), 0, 1] };
+    }
+    /** Whether `ref` is null or missing: an expression compares a missing field as neither. */
+    static isNullExpr(ref) {
+        return { $eq: [{ $ifNull: [ref, null] }, null] };
+    }
+    /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
+    groupedPath(meta, joins, path, named) {
+        const { key, join } = groupPathField(joins, path);
+        if (!join) {
+            named.push(key);
+            return this.columnOf(meta, key);
+        }
+        if (aggregateOf(join.meta.fields[key])) {
+            throw new TypeError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
+        }
+        return `${join.path}.${this.columnOf(join.meta, key)}`;
+    }
+    /**
+     * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
+     * comparisons and the logical operators translate, anything else is refused by name. `named` gathers
+     * the fields it reads, so a relation aggregate among them is on the document first.
+     */
+    whereExpression(meta, where, named) {
+        const terms = getKeys(where)
+            .filter((key) => where[key] !== undefined)
+            .map((key) => {
+            if (MongoDialect.isGroupOp(key)) {
+                const { join, negate } = MongoDialect.GROUP_OPS[key];
+                const clauses = MongoDialect.groupClauses(key, where[key]).map((clause) => {
+                    if (clause instanceof QueryRaw) {
+                        throw new TypeError('raw SQL is not supported in an aggregate $where on MongoDB');
+                    }
+                    return this.whereExpression(meta, clause, named);
+                });
+                return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
             }
+            if (key.startsWith('$')) {
+                throw new TypeError(`aggregate $where operator '${key}' is not supported on MongoDB`);
+            }
+            const val = where[key];
+            named.push(key);
+            const path = this.pathOf(meta, key);
+            const wire = (value) => path === MongoDialect.ID_KEY || meta.fields[key]?.references ? this.toWireId(value) : value;
+            return this.fieldExpression(`$${path}`, val, wire);
+        });
+        return terms.length === 1 ? terms[0] : { $and: terms };
+    }
+    /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
+    fieldExpression(ref, val, wire) {
+        const equals = (value) => (value === null ? MongoDialect.isNullExpr(ref) : { $eq: [ref, wire(value)] });
+        if (!isOperatorMap(val)) {
+            return Array.isArray(val) ? { $in: [ref, wire(val)] } : equals(val);
         }
-        return { groupId, groupAccumulators, distinctReducers };
+        // A null or missing field compares below every value in an expression, where SQL leaves it unmatched.
+        const present = { $not: [MongoDialect.isNullExpr(ref)] };
+        const terms = Object.entries(val).map(([op, operand]) => {
+            switch (op) {
+                case '$eq':
+                    return equals(operand);
+                case '$ne':
+                    return { $not: [equals(operand)] };
+                case '$gt':
+                case '$gte':
+                    return { [op]: [ref, wire(operand)] };
+                case '$lt':
+                case '$lte':
+                    return { $and: [present, { [op]: [ref, wire(operand)] }] };
+                case '$in':
+                    return { $in: [ref, wire(operand)] };
+                case '$nin':
+                    return { $not: [{ $in: [ref, wire(operand)] }] };
+                case '$between': {
+                    const [min, max] = operand;
+                    return { $and: [{ $gte: [ref, wire(min)] }, { $lte: [ref, wire(max)] }] };
+                }
+                case '$isNull':
+                    return operand ? MongoDialect.isNullExpr(ref) : present;
+                case '$isNotNull':
+                    return operand ? present : MongoDialect.isNullExpr(ref);
+                default:
+                    throw new TypeError(`aggregate $where operator '${op}' is not supported on MongoDB`);
+            }
+        });
+        return terms.length === 1 ? terms[0] : { $and: terms };
     }
     buildHavingFilter(having) {
         const filter = {};
@@ -1195,14 +1259,10 @@ export class MongoDialect extends AbstractDialect {
 function sortDirection(value) {
     return value === 'desc' || value === -1 ? -1 : 1;
 }
-/** The relation aggregate a field computes, where it computes one rather than writing SQL. */
-function aggregateOf(field) {
-    return field?.computed instanceof RelationAggregate ? field.computed.spec : undefined;
-}
 /**
  * A `computed` field writing SQL is refused wherever a query names it, since no document engine
  * evaluates SQL and answering with the property name would hand back `undefined` for every row. One
- * computing a relation aggregate is read: `aggregateFieldStages` builds it.
+ * computing a relation aggregate is read: `appendAggregateField` builds it.
  */
 function assertReadable(meta, key) {
     const field = meta.fields[key];

package/dist/mongo/mongodbQuerier.d.ts

@@ -44,8 +44,6 @@ export declare class MongodbQuerier extends AbstractQuerier {
      * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
      */
     estimatedCount<E extends Document>(entity: Type<E>): Promise<number>;
-    /** A `find` filter cannot host the `$lookup` a relation condition needs, so such a write names its rows by id. */
-    protected settlesWrite<E extends Document>(entity: Type<E>, q: QuerySearch<E>): boolean;
     internalInsertMany<E extends Document>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /**

package/dist/mongo/mongodbQuerier.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
@@ -143,10 +143,10 @@ export class MongodbQuerier extends AbstractQuerier {
         const [founds, counted] = await Promise.all([
             this.internalFindMany(entity, q, opts),
             this.execute((session) => this.collection(entity)
-                .aggregate([...this.dialect.aggregationPipeline(entity, unpaged, opts), { $count: COUNT_ALIAS }], { session })
+                .aggregate([...this.dialect.aggregationPipeline(entity, unpaged, opts), { $count: AGGREGATE_VALUE_ALIAS }], { session })
                 .toArray()),
         ]);
-        return [founds, counted[0]?.[COUNT_ALIAS] ?? 0];
+        return [founds, counted[0]?.[AGGREGATE_VALUE_ALIAS] ?? 0];
     }
     /** The pipeline `countDocuments` runs, spelled out so a relation condition gets its lookups and a page its stages. */
     async internalCount(entity, q, opts) {
@@ -154,10 +154,15 @@ export class MongodbQuerier extends AbstractQuerier {
             return 0;
         }
         return this.timed('internalCount', undefined, async () => {
-            const { stages, filter } = this.dialect.whereWithRelations(entity, q.$where, opts);
-            const pipeline = [...stages, { $match: filter }, ...this.dialect.pagerStages(q), { $count: COUNT_ALIAS }];
-            const [counted] = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
-            return counted?.[COUNT_ALIAS] ?? 0;
+            const pipeline = [
+                ...this.dialect.matchStages(entity, q.$where, opts),
+                ...this.dialect.pagerStages(q),
+                { $count: AGGREGATE_VALUE_ALIAS },
+            ];
+            const [counted] = await this.execute((session) => this.collection(entity)
+                .aggregate(pipeline, { session })
+                .toArray());
+            return counted?.[AGGREGATE_VALUE_ALIAS] ?? 0;
         });
     }
     /**
@@ -167,10 +172,6 @@ export class MongodbQuerier extends AbstractQuerier {
     async estimatedCount(entity) {
         return this.timed('estimatedCount', undefined, async () => this.execute((session) => this.collection(entity).estimatedDocumentCount({ session })));
     }
-    /** A `find` filter cannot host the `$lookup` a relation condition needs, so such a write names its rows by id. */
-    settlesWrite(entity, q) {
-        return super.settlesWrite(entity, q) || this.dialect.constrainsRelations(entity, q.$where);
-    }
     async internalInsertMany(entity, rows) {
         return this.timed('internalInsertMany', undefined, async () => {
             const meta = getMeta(entity);

package/dist/mssql/mssqlDialect.js

@@ -1,5 +1,5 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
-import { COUNT_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
@@ -29,6 +29,7 @@ const MSSQL_FEATURES = {
     stringSizing: 'varchar',
     supportsUnsigned: false,
     serverSideCursors: false,
+    correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
@@ -227,7 +228,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     /** The estimate the engine already keeps per partition, live without a stats refresh. */
     estimatedCount(ctx, entity) {
         const meta = getMeta(entity);
-        ctx.append(`SELECT SUM(p.rows) ${this.escapeId(COUNT_ALIAS, true)} FROM sys.partitions p` +
+        ctx.append(`SELECT SUM(p.rows) ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM sys.partitions p` +
             ` JOIN sys.objects o ON o.object_id = p.object_id` +
             ` JOIN sys.schemas s ON s.schema_id = o.schema_id` +
             ` WHERE p.index_id IN (0, 1) AND o.name = `);

package/dist/postgres/postgresDialect.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { PG_FEATURES, PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 /** PostgreSQL, under every driver: `pg`, Neon, PGlite, `bun:sql`. Adds pgvector and the `xmax` upsert `created`. */
@@ -18,7 +18,7 @@ export class PostgresDialect extends PgLikeSqlDialect {
      * back raw it would read as a negative row count.
      */
     estimatedCount(ctx, entity) {
-        ctx.append(`SELECT GREATEST(reltuples, 0)::bigint ${this.escapeId(COUNT_ALIAS, true)} FROM pg_class WHERE oid = to_regclass(`);
+        ctx.append(`SELECT GREATEST(reltuples, 0)::bigint ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM pg_class WHERE oid = to_regclass(`);
         ctx.addValue(this.escapedTableName(getMeta(entity)));
         ctx.append(')');
     }