@atscript/db-mongo 0.1.146 → 0.1.148

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { a as queryNodeToExpr, i as orNull, n as distinctCountExpr, r as buildMongoFilter, t as buildAccumulator } from "./mongo-accumulator-Dc0w4t0l.mjs";
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, UniquSelect, bucketTimeZoneUnavailable, computeInsights, createFailureCollector, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, isAtscriptDbView, isFieldRef, resolveDesignType, searchIndexNotFoundMessage, tableNameOf, translateQueryTree, vectorIndexNotFoundMessage } from "@atscript/db";
-import { MongoClient, MongoServerError, ObjectId } from "mongodb";
+import { a as buildMongoQuery, c as planStages, d as orNull, f as queryNodeToExpr, i as buildMongoFilter, l as exprToMongo, n as distinctCountExpr, o as collationOfAdapter, p as correlate, r as REL_FILTER_TEMP_PREFIX, s as mongoFilterStages, t as buildAccumulator } from "./mongo-accumulator-BvJNCVoc.mjs";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, andFilters, bucketTimeZoneUnavailable, computeInsights, containsRelationFilter, createFailureCollector, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, isAtscriptDbView, isFieldRef, relationStaticFilter, resolveDesignType, searchIndexNotFoundMessage, tableNameOf, translateQueryTree, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
+import { MongoBulkWriteError, MongoClient, MongoServerError, ObjectId } from "mongodb";
 import { resolveAggregateSearch } from "@atscript/db/agg";
 //#region src/lib/path-utils.ts
 function joinPath(prefix, segment) {
@@ -373,47 +373,67 @@ function mongoIndexKey(type, name) {
 }
 //#endregion
 //#region src/lib/mongo-relations.ts
-function buildPKKey(primaryKeys, doc) {
-	if (primaryKeys.length === 1) {
-		const val = doc[primaryKeys[0]];
-		return val == null ? "" : `${val}`;
-	}
+/** Join key of a row's primary key values (`fields` = the row's own names for them). */
+function buildPKKey(fields, doc) {
 	let key = "";
-	for (let i = 0; i < primaryKeys.length; i++) {
+	for (let i = 0; i < fields.length; i++) {
 		if (i > 0) key += "\0";
-		const val = doc[primaryKeys[i]];
+		const val = doc[fields[i]];
 		key += val == null ? "" : `${val}`;
 	}
 	return key;
 }
+function resolveReadable(tableResolver, type) {
+	if (!type || !tableResolver) return;
+	return tableResolver(type);
+}
+/** The collection a readable reads (a view's name for a `@db.view`). */
+function collectionOf(readable) {
+	return readable.getAdapter().resolveTableName(false);
+}
+/**
+* Native `$with` loading: one aggregation over the source collection
+* (re-selected by primary key) with a `$lookup` per relation.
+*
+* Every name is physical (since 0.1.147): join fields go through each
+* side's `physicalPath`, and the `$with` sub-query (filter — relational
+* predicates included —, `$sort`, `$select`) through the related table's
+* own translation. The relation's `@db.rel.filter` is part of the lookup
+* (target conditions ANDed into the sub-filter, junction conditions on the
+* junction rows). Loaded documents come back as logical rows (renames,
+* value formatters, decryption) before nested `$with` loads on them.
+*/
 async function loadRelationsImpl(host, rows, withRelations, relations, foreignKeys, tableResolver) {
 	if (rows.length === 0 || withRelations.length === 0) return;
-	const primaryKeys = host._table.primaryKeys;
+	const source = host._table;
+	const primaryKeys = source.primaryKeys;
 	const relMeta = [];
 	for (const withRel of withRelations) {
 		if (withRel.name.includes(".")) continue;
 		const relation = relations.get(withRel.name);
 		if (!relation) throw new Error(`Unknown relation "${withRel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
-		const lookupResult = buildRelationLookup(host, withRel, relation, foreignKeys, tableResolver);
-		if (!lookupResult) continue;
-		relMeta.push({
-			name: withRel.name,
-			isArray: lookupResult.isArray,
-			relation,
-			nestedWith: extractNestedWith(withRel),
-			stages: lookupResult.stages
-		});
+		const lookup = buildRelationLookup(source, withRel, relation, foreignKeys, tableResolver);
+		if (lookup) relMeta.push(lookup);
 	}
 	if (relMeta.length === 0) return;
 	const pkMatchFilter = buildPKMatchFilter(rows, primaryKeys);
 	if (pkMatchFilter) {
-		const pipeline = [{ $match: pkMatchFilter }];
+		const { filter } = source._translateForAdapter({ filter: pkMatchFilter });
+		const sourceMeta = source.getMetadata();
+		const physicalKeys = primaryKeys.map((pk) => sourceMeta.physicalPath(pk));
+		const project = {};
+		for (const key of physicalKeys) project[key] = 1;
+		for (const meta of relMeta) project[meta.name] = 1;
+		const pipeline = [{ $match: buildMongoFilter(filter) }];
 		for (const meta of relMeta) pipeline.push(...meta.stages);
-		mergeRelationResults(rows, await host.collection.aggregate(pipeline, host._getSessionOpts()).toArray(), primaryKeys, relMeta);
+		pipeline.push({ $project: project });
+		const results = await host.collection.aggregate(pipeline, host._getSessionOpts()).toArray();
+		await Promise.all(relMeta.map((meta) => toLogicalRows(results, meta)));
+		mergeRelationResults(rows, results, primaryKeys, physicalKeys, relMeta);
 	} else for (const row of rows) for (const meta of relMeta) row[meta.name] = meta.isArray ? [] : null;
-	await loadNestedRelations(rows, relMeta, tableResolver);
+	await loadNestedRelations(rows, relMeta);
 }
-/** Builds a $match filter to re-select source rows by PK. */
+/** Builds a $match filter to re-select source rows by PK (logical names and values). */
 function buildPKMatchFilter(rows, primaryKeys) {
 	if (primaryKeys.length === 1) {
 		const pk = primaryKeys[0];
@@ -447,137 +467,164 @@ function buildPKMatchFilter(rows, primaryKeys) {
 	return orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
 }
 /** Dispatches to the correct $lookup builder based on relation direction. */
-function buildRelationLookup(host, withRel, relation, foreignKeys, tableResolver) {
+function buildRelationLookup(source, withRel, relation, foreignKeys, tableResolver) {
+	const target = resolveReadable(tableResolver, relation.targetType());
+	if (!target) return;
+	let built;
 	switch (relation.direction) {
-		case "to": return buildToLookup(withRel, relation, foreignKeys);
-		case "from": return buildFromLookup(host, withRel, relation, tableResolver);
-		case "via": return buildViaLookup(host, withRel, relation, tableResolver);
+		case "to":
+			built = buildToLookup(source, target, withRel, relation, foreignKeys);
+			break;
+		case "from":
+			built = buildFromLookup(source, target, withRel, relation);
+			break;
+		case "via":
+			built = buildViaLookup(source, target, withRel, relation, tableResolver);
+			break;
 		default: return;
 	}
-}
-/** Builds `let` variable bindings and the corresponding `$expr` match for `$lookup`. */
-function buildLookupJoin(localFields, remoteFields, varPrefix) {
-	const letVars = {};
-	for (let i = 0; i < localFields.length; i++) letVars[`${varPrefix}${i}`] = `$${localFields[i]}`;
-	if (remoteFields.length === 1) return {
-		letVars,
-		exprMatch: { $eq: [`$${remoteFields[0]}`, `$$${varPrefix}0`] }
-	};
-	const andClauses = [];
-	for (let i = 0; i < remoteFields.length; i++) andClauses.push({ $eq: [`$${remoteFields[i]}`, `$$${varPrefix}${i}`] });
-	return {
-		letVars,
-		exprMatch: { $and: andClauses }
+	return built && {
+		name: withRel.name,
+		isArray: built.isArray,
+		target,
+		readControls: built.readControls,
+		nestedWith: extractNestedWith(withRel),
+		stages: built.stages
 	};
 }
+/** Pairs of physical join fields: `outer` on the looking-up side, `inner` on the looked-up one. */
+function joinPairs(outerMeta, outerFields, innerMeta, innerFields) {
+	return outerFields.map((field, i) => ({
+		outer: outerMeta.physicalPath(field),
+		inner: innerMeta.physicalPath(innerFields[i])
+	}));
+}
 /** $lookup for TO relations (FK is on this table → target). Always single-valued. */
-function buildToLookup(withRel, relation, foreignKeys) {
+function buildToLookup(source, target, withRel, relation, foreignKeys) {
 	const fk = findFKForRelation(relation, foreignKeys);
-	if (!fk) return;
-	const innerPipeline = buildLookupInnerPipeline(withRel, fk.targetFields);
-	const { letVars, exprMatch } = buildLookupJoin(fk.localFields, fk.targetFields, "fk_");
-	return {
-		stages: [{ $lookup: {
-			from: fk.targetTable,
-			let: letVars,
-			pipeline: [{ $match: { $expr: exprMatch } }, ...innerPipeline],
-			as: withRel.name
-		} }, { $unwind: {
-			path: `$${withRel.name}`,
-			preserveNullAndEmptyArrays: true
-		} }],
-		isArray: false
-	};
+	return fk ? directLookup(source, target, withRel, relation, fk.localFields, fk.targetFields, "fk_", false) : void 0;
 }
 /** $lookup for FROM relations (FK is on target → this table). */
-function buildFromLookup(host, withRel, relation, tableResolver) {
-	const targetType = relation.targetType();
-	if (!targetType || !tableResolver) return;
-	const targetMeta = tableResolver(targetType);
-	if (!targetMeta) return;
-	const remoteFK = findRemoteFK(targetMeta, host._table.tableName, relation.alias);
-	if (!remoteFK) return;
-	const targetTableName = tableNameOf(relation.targetType());
-	const innerPipeline = buildLookupInnerPipeline(withRel, remoteFK.fields);
-	const { letVars, exprMatch } = buildLookupJoin(remoteFK.targetFields, remoteFK.fields, "pk_");
+function buildFromLookup(source, target, withRel, relation) {
+	const remoteFK = findRemoteFK(target, source.tableName, relation.alias);
+	return remoteFK ? directLookup(source, target, withRel, relation, remoteFK.targetFields, remoteFK.fields, "pk_", relation.isArray) : void 0;
+}
+/**
+* The correlated `$lookup` of a TO / FROM relation: `sourceFields` of this
+* table paired with `targetFields` of the target, unwound when single-valued.
+*/
+function directLookup(source, target, withRel, relation, sourceFields, targetFields, prefix, isArray) {
+	const pairs = joinPairs(source.getMetadata(), sourceFields, target.getMetadata(), targetFields);
+	const inner = buildLookupInnerPipeline(target, withRel, relation, pairs.map((p) => p.inner));
+	const join = correlate(prefix, pairs);
 	const stages = [{ $lookup: {
-		from: targetTableName,
-		let: letVars,
-		pipeline: [{ $match: { $expr: exprMatch } }, ...innerPipeline],
+		from: collectionOf(target),
+		let: join.let,
+		pipeline: [
+			...join.stages,
+			...inner.filter,
+			...inner.page
+		],
 		as: withRel.name
 	} }];
-	if (!relation.isArray) stages.push({ $unwind: {
+	if (!isArray) stages.push({ $unwind: {
 		path: `$${withRel.name}`,
 		preserveNullAndEmptyArrays: true
 	} });
 	return {
 		stages,
-		isArray: relation.isArray
+		isArray,
+		readControls: inner.readControls
 	};
 }
 /** $lookup for VIA relations (M:N through junction table). Always array. */
-function buildViaLookup(host, withRel, relation, tableResolver) {
-	if (!relation.viaType || !tableResolver) return;
-	const junctionType = relation.viaType();
-	if (!junctionType) return;
-	const junctionMeta = tableResolver(junctionType);
-	if (!junctionMeta) return;
-	const junctionTableName = tableNameOf(junctionType);
-	const targetTableName = tableNameOf(relation.targetType());
-	const fkToThis = findRemoteFK(junctionMeta, host._table.tableName);
+function buildViaLookup(source, target, withRel, relation, tableResolver) {
+	const junction = resolveReadable(tableResolver, relation.viaType?.());
+	if (!junction) return;
+	const fkToThis = findRemoteFK(junction, source.tableName);
 	if (!fkToThis) return;
-	const fkToTarget = findRemoteFK(junctionMeta, targetTableName);
+	const fkToTarget = findRemoteFK(junction, tableNameOf(relation.targetType()));
 	if (!fkToTarget) return;
-	const innerPipeline = buildLookupInnerPipeline(withRel, fkToTarget.targetFields);
-	const { letVars, exprMatch } = buildLookupJoin(fkToThis.targetFields, fkToThis.fields, "pk_");
+	const sourceMeta = source.getMetadata();
+	const junctionMeta = junction.getMetadata();
+	const targetMeta = target.getMetadata();
+	const toSource = correlate("pk_", joinPairs(sourceMeta, fkToThis.targetFields, junctionMeta, fkToThis.fields));
+	const toTargetPairs = joinPairs(junctionMeta, fkToTarget.fields, targetMeta, fkToTarget.targetFields);
+	const toTarget = correlate("fk_", toTargetPairs);
+	const inner = buildLookupInnerPipeline(target, withRel, relation, toTargetPairs.map((p) => p.inner));
+	const junctionFilter = relationStaticFilter(relation, withRel.name).junction;
+	const junctionStages = junctionFilter ? filterStages(junction, junction._translateForAdapter({ filter: junctionFilter }).filter) : [];
 	return {
 		stages: [{ $lookup: {
-			from: junctionTableName,
-			let: letVars,
+			from: collectionOf(junction),
+			let: toSource.let,
 			pipeline: [
-				{ $match: { $expr: exprMatch } },
+				...toSource.stages,
+				...junctionStages,
 				{ $lookup: {
-					from: targetTableName,
-					localField: fkToTarget.fields[0],
-					foreignField: fkToTarget.targetFields[0],
-					pipeline: innerPipeline,
+					from: collectionOf(target),
+					let: toTarget.let,
+					pipeline: [...toTarget.stages, ...inner.filter],
 					as: "__target"
 				} },
 				{ $unwind: {
 					path: "$__target",
 					preserveNullAndEmptyArrays: false
 				} },
-				{ $replaceRoot: { newRoot: "$__target" } }
+				{ $replaceRoot: { newRoot: "$__target" } },
+				...inner.page
 			],
 			as: withRel.name
 		} }],
-		isArray: true
+		isArray: true,
+		readControls: inner.readControls
 	};
 }
-/** Builds inner pipeline stages for relation controls ($sort, $limit, $skip, $select, filter). */
-function buildLookupInnerPipeline(withRel, requiredFields) {
-	const pipeline = [];
+/** Stages applying a translated filter on `readable`'s collection (none when empty). */
+function filterStages(readable, filter) {
+	if (!filter || Object.keys(filter).length === 0) return [];
+	return mongoFilterStages(filter, { collation: collationOfAdapter(readable.getAdapter()) });
+}
+/**
+* The `$with` sub-query on the related table: its filter AND the target part
+* of the relation's `@db.rel.filter`, plus `$sort` / `$skip` / `$limit` /
+* `$select` — translated by the TARGET readable (physical names, value
+* formatters, relational predicates resolved). `requiredFields` (physical
+* join keys) are always projected.
+*/
+function buildLookupInnerPipeline(target, withRel, relation, requiredFields) {
 	const flatRel = withRel;
 	const nested = withRel.controls || {};
-	const filter = withRel.filter;
 	const sort = nested.$sort || flatRel.$sort;
 	const limit = nested.$limit ?? flatRel.$limit;
 	const skip = nested.$skip ?? flatRel.$skip;
 	const select = nested.$select || flatRel.$select;
-	if (filter && Object.keys(filter).length > 0) pipeline.push({ $match: buildMongoFilter(filter) });
-	if (sort) pipeline.push({ $sort: sort });
-	if (skip) pipeline.push({ $skip: skip });
-	if (limit !== null && limit !== void 0) pipeline.push({ $limit: limit });
-	const projection = select ? new UniquSelect(select).asProjection : void 0;
+	const statics = relationStaticFilter(relation, withRel.name);
+	const controls = {};
+	if (sort) controls.$sort = sort;
+	if (select) controls.$select = select;
+	const translated = target._translateForAdapter({
+		filter: andFilters(statics.target, withRel.filter),
+		controls
+	});
+	const page = [];
+	if (translated.controls?.$sort) page.push({ $sort: translated.controls.$sort });
+	if (skip) page.push({ $skip: skip });
+	if (limit !== null && limit !== void 0) page.push({ $limit: limit });
+	const projection = translated.controls?.$select?.asProjection;
 	if (projection) {
 		const project = { ...projection };
 		if (Object.values(project).some((flag) => flag === 1 || flag === true)) {
 			for (const f of requiredFields) project[f] = 1;
 			if (!("_id" in projection) && !requiredFields.includes("_id")) project._id = 0;
 		} else for (const f of requiredFields) delete project[f];
-		if (Object.keys(project).length > 0) pipeline.push({ $project: dedupeProjection(project) });
+		if (Object.keys(project).length > 0) page.push({ $project: dedupeProjection(project) });
 	}
-	return pipeline;
+	return {
+		filter: filterStages(target, translated.filter),
+		page,
+		readControls: select ? { $select: select } : {}
+	};
 }
 /** Extracts nested $with from a WithRelation's controls. */
 function extractNestedWith(withRel) {
@@ -586,15 +633,10 @@ function extractNestedWith(withRel) {
 	return nestedWith && nestedWith.length > 0 ? nestedWith : void 0;
 }
 /** Post-processes nested $with by delegating to the target table's own relation loading. */
-async function loadNestedRelations(rows, relMeta, tableResolver) {
-	if (!tableResolver) return;
+async function loadNestedRelations(rows, relMeta) {
 	const tasks = [];
 	for (const meta of relMeta) {
 		if (!meta.nestedWith || meta.nestedWith.length === 0) continue;
-		const targetType = meta.relation.targetType();
-		if (!targetType) continue;
-		const targetTable = tableResolver(targetType);
-		if (!targetTable) continue;
 		const subRows = [];
 		for (const row of rows) {
 			const val = row[meta.name];
@@ -602,21 +644,44 @@ async function loadNestedRelations(rows, relMeta, tableResolver) {
 			else if (val && typeof val === "object") subRows.push(val);
 		}
 		if (subRows.length === 0) continue;
-		tasks.push(targetTable.loadRelations(subRows, meta.nestedWith));
+		tasks.push(meta.target.loadRelations(subRows, meta.nestedWith));
 	}
 	await Promise.all(tasks);
 }
-/** Merges aggregation results back onto the original rows by PK. */
-function mergeRelationResults(rows, results, primaryKeys, relMeta) {
+/**
+* Replaces one relation's loaded documents on every aggregation result with
+* the related table's LOGICAL rows (one conversion call for all of them).
+*/
+async function toLogicalRows(results, meta) {
+	const physical = [];
+	const spans = [];
+	for (const doc of results) {
+		const value = doc[meta.name];
+		const list = Array.isArray(value) ? value : value && typeof value === "object" ? [value] : [];
+		spans.push([
+			doc,
+			physical.length,
+			list.length
+		]);
+		physical.push(...list);
+	}
+	const logical = physical.length > 0 ? await meta.target._rowsFromAdapter(physical, meta.readControls) : [];
+	for (const [doc, start, length] of spans) doc[meta.name] = meta.isArray ? logical.slice(start, start + length) : length > 0 ? logical[start] : null;
+}
+/**
+* Merges aggregation results back onto the original rows by PK — the
+* results carry the PHYSICAL key fields (`physicalKeys`), the rows the
+* logical ones (`primaryKeys`).
+*/
+function mergeRelationResults(rows, results, primaryKeys, physicalKeys, relMeta) {
 	const resultIndex = /* @__PURE__ */ new Map();
-	for (const doc of results) resultIndex.set(buildPKKey(primaryKeys, doc), doc);
+	for (const doc of results) resultIndex.set(buildPKKey(physicalKeys, doc), doc);
 	for (const row of rows) {
 		const enriched = resultIndex.get(buildPKKey(primaryKeys, row));
-		for (const meta of relMeta) if (enriched) {
-			const value = enriched[meta.name];
-			if (!meta.isArray && Array.isArray(value)) row[meta.name] = value[0] ?? null;
-			else row[meta.name] = value ?? (meta.isArray ? [] : null);
-		} else row[meta.name] = meta.isArray ? [] : null;
+		for (const meta of relMeta) {
+			const value = enriched?.[meta.name];
+			row[meta.name] = value ?? (meta.isArray ? [] : null);
+		}
 	}
 }
 /** Finds FK entry for a TO relation from this table's foreignKeys map. */
@@ -643,6 +708,10 @@ function findRemoteFK(target, thisTableName, alias) {
 }
 //#endregion
 //#region src/lib/mongo-search.ts
+/** Renders a host's filter with relational predicates — its 'nocase' fields per field. */
+function filterOptionsOf(host) {
+	return { collation: collationOfAdapter(host) };
+}
 /**
 * Returns available search indexes as generic metadata for UI. The text
 * default is the `DEFAULT` entry (an alias of the index `search()` answers
@@ -735,7 +804,7 @@ const DISTANCE_FIELD = "__atscript_distance";
 /** Distance-ranked geo search via a leading `$geoNear` aggregation stage. */
 async function geoSearchImpl(host, point, query, indexName) {
 	const controls = query.controls || {};
-	const pipeline = [buildGeoNearStage(host, point, query, indexName)];
+	const pipeline = buildGeoNearStages(host, point, query, indexName);
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
 	pipeline.push({ $limit: controls.$limit || 1e3 });
 	pushGeoProjection(pipeline, query.controls);
@@ -749,7 +818,7 @@ async function geoSearchWithCountImpl(host, point, query, indexName) {
 	if (controls.$skip) dataStages.push({ $skip: controls.$skip });
 	if (controls.$limit) dataStages.push({ $limit: controls.$limit });
 	pushGeoProjection(dataStages, query.controls);
-	const pipeline = [buildGeoNearStage(host, point, query, indexName), { $facet: {
+	const pipeline = [...buildGeoNearStages(host, point, query, indexName), { $facet: {
 		data: dataStages,
 		meta: [{ $count: "count" }]
 	} }];
@@ -760,9 +829,15 @@ async function geoSearchWithCountImpl(host, point, query, indexName) {
 		count: result[0]?.meta?.[0]?.count || 0
 	};
 }
-/** Builds the leading `$geoNear` stage; the filter rides in its `query` option. */
-function buildGeoNearStage(host, point, query, indexName) {
+/**
+* Builds the leading `$geoNear` stage; the filter rides in its `query`
+* option. A filter with relational predicates keeps its predicate-free
+* conjuncts there and applies the rest (predicate `$lookup`s + `$match`)
+* right after — exact, since `$geoNear` has no result cut-off of its own.
+*/
+function buildGeoNearStages(host, point, query, indexName) {
 	const controls = query.controls || {};
+	const plan = containsRelationFilter(query.filter) ? buildMongoQuery(query.filter, filterOptionsOf(host)) : void 0;
 	const geoNear = {
 		near: {
 			type: "Point",
@@ -771,11 +846,14 @@ function buildGeoNearStage(host, point, query, indexName) {
 		distanceField: DISTANCE_FIELD,
 		spherical: true,
 		key: resolveGeoKeyPath(host, indexName),
-		query: buildMongoFilter(query.filter)
+		query: plan ? plan.pre ?? {} : buildMongoFilter(query.filter)
 	};
 	if (typeof controls.$maxDistance === "number") geoNear.maxDistance = controls.$maxDistance;
 	if (typeof controls.$minDistance === "number") geoNear.minDistance = controls.$minDistance;
-	return { $geoNear: geoNear };
+	return plan ? [{ $geoNear: geoNear }, ...planStages({
+		...plan,
+		pre: void 0
+	})] : [{ $geoNear: geoNear }];
 }
 /** Resolves the physical field path of the targeted geo index. */
 function resolveGeoKeyPath(host, indexName) {
@@ -984,14 +1062,13 @@ function buildVectorSearchStage(host, vector, indexName, limit) {
 }
 /** Runs a search/vector pipeline and returns results. Shared by search + vectorSearch. */
 async function runSearchPipeline(host, stage, query, label, threshold, classicText = false) {
-	const filter = buildMongoFilter(query.filter);
 	const controls = query.controls || {};
 	const pipeline = [stage];
 	if (threshold !== void 0) {
 		pipeline.push({ $addFields: { _score: { $meta: "vectorSearchScore" } } });
 		pipeline.push({ $match: { _score: { $gte: threshold } } });
 	} else if (classicText) pipeline.push({ $addFields: { _score: { $meta: "textScore" } } });
-	pipeline.push({ $match: filter });
+	pipeline.push(...mongoFilterStages(query.filter, filterOptionsOf(host)));
 	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
 	else if (classicText) pipeline.push({ $sort: { _score: -1 } });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
@@ -1006,7 +1083,6 @@ async function runSearchPipeline(host, stage, query, label, threshold, classicTe
 }
 /** Runs a search/vector pipeline with $facet for count. Shared by searchWithCount + vectorSearchWithCount. */
 async function runSearchWithCountPipeline(host, stage, query, label, threshold, classicText = false) {
-	const filter = buildMongoFilter(query.filter);
 	const controls = query.controls || {};
 	const preStages = [];
 	if (threshold !== void 0) {
@@ -1025,7 +1101,7 @@ async function runSearchWithCountPipeline(host, stage, query, label, threshold,
 	const pipeline = [
 		stage,
 		...preStages,
-		{ $match: filter },
+		...mongoFilterStages(query.filter, filterOptionsOf(host)),
 		{ $facet: {
 			data: dataStages,
 			meta: [{ $count: "count" }]
@@ -1088,11 +1164,28 @@ function buildViewPipeline(view) {
 	/** A column's source field as an aggregation operand. */
 	const colSourceField = (col) => `$${prefixes.get(col.sourceTable) ?? ""}${col.sourceColumn}`;
 	const colValue = (col) => col.nullable ? orNull(colSourceField(col)) : colSourceField(col);
+	const byPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const rendered = /* @__PURE__ */ new Map();
+	const computedExpr = (col, leaf) => {
+		let out = rendered.get(col.viewPath);
+		if (out === void 0) {
+			out = exprToMongo(col.expr, (path) => {
+				const c = byPath.get(path);
+				return c.expr === void 0 ? { $toDouble: leaf(c) } : computedExpr(c, leaf);
+			});
+			rendered.set(col.viewPath, out);
+		}
+		return out;
+	};
 	if (columns.some((c) => c.aggFn)) {
 		const group = { _id: {} };
 		const project = { _id: 0 };
 		const distinctSizes = {};
-		for (const col of columns) if (col.aggFn) {
+		const computed = {};
+		for (const col of columns) if (col.expr !== void 0) {
+			computed[col.viewColumn] = computedExpr(col, (c) => c.aggFn ? `$${c.viewColumn}` : `$_id.${c.viewColumn}`);
+			project[col.viewColumn] = `$${col.viewColumn}`;
+		} else if (col.aggFn) {
 			const predicate = col.aggFilter ? queryNodeToExpr(col.aggFilter, (ref) => `$${pathOf(ref)}`) : void 0;
 			group[col.viewColumn] = buildAccumulator(col.aggFn, col.aggField === "*" ? "*" : colSourceField(col), predicate, col.viewColumn);
 			project[col.viewColumn] = `$${col.viewColumn}`;
@@ -1103,11 +1196,12 @@ function buildViewPipeline(view) {
 		}
 		pipeline.push({ $group: group });
 		if (Object.keys(distinctSizes).length > 0) pipeline.push({ $addFields: distinctSizes });
-		if (plan.having) pipeline.push({ $match: havingMatch(plan.having, columns) });
+		if (Object.keys(computed).length > 0) pipeline.push({ $addFields: computed });
+		if (plan.having) pipeline.push({ $match: havingMatch(plan.having, byPath) });
 		pipeline.push({ $project: project });
 	} else {
 		const project = { _id: 0 };
-		for (const col of columns) project[col.viewColumn] = colValue(col);
+		for (const col of columns) project[col.viewColumn] = col.expr === void 0 ? colValue(col) : computedExpr(col, colValue);
 		pipeline.push({ $project: project });
 	}
 	return pipeline;
@@ -1128,7 +1222,7 @@ function buildViewPipeline(view) {
 function buildLookup(view, join, outer) {
 	const scope = join.scope;
 	const as = joinedAs(scope);
-	const simple = simpleJoinFields(view, join, outer);
+	const simple = join.first ? void 0 : simpleJoinFields(view, join, outer);
 	if (simple) return { $lookup: {
 		from: join.targetTable,
 		...simple,
@@ -1150,11 +1244,16 @@ function buildLookup(view, join, outer) {
 		}
 		return `$$${varName}`;
 	};
-	const expr = queryNodeToExpr(join.condition, pathOf);
+	const pipeline = [{ $match: { $expr: queryNodeToExpr(join.condition, pathOf) } }];
+	if (join.first) {
+		const sort = {};
+		for (const { ref, desc } of join.first.order) sort[view.resolveRefSource(ref).source.column] = desc ? -1 : 1;
+		pipeline.push({ $sort: sort }, { $limit: 1 });
+	}
 	return { $lookup: {
 		from: join.targetTable,
 		...varByPath.size > 0 ? { let: letVars } : {},
-		pipeline: [{ $match: { $expr: expr } }],
+		pipeline,
 		as
 	} };
 }
@@ -1204,12 +1303,11 @@ function viewMatch(node, pathOf) {
 * `@db.view.having` as a `$match` after `$group`: refs name view fields —
 * aggregates are top-level, dimensions under `_id`.
 */
-function havingMatch(node, columns) {
-	const colMap = new Map(columns.map((c) => [c.viewPath, c]));
+function havingMatch(node, colMap) {
 	return viewMatch(node, (ref) => {
 		const col = ref.type ? void 0 : colMap.get(ref.field);
 		if (!col) return ref.field;
-		return col.aggFn ? col.viewColumn : `_id.${col.viewColumn}`;
+		return col.aggFn || col.expr !== void 0 ? col.viewColumn : `_id.${col.viewColumn}`;
 	});
 }
 //#endregion
@@ -1699,6 +1797,16 @@ function objectIdFromStorage(value) {
 	if (Array.isArray(value)) return value.map(objectIdFromStorage);
 	return value;
 }
+/**
+* Documents per `_id $in` write when a mutation filter holds relational
+* predicates (see {@link MongoAdapter.supportsRelationFilters}).
+*/
+const REL_WRITE_BATCH = 1e3;
+/** Whether a bulk-write error carries a write-concern failure besides (or instead of) write errors. */
+function hasWriteConcernError(error) {
+	const e = error;
+	return Boolean(e.writeConcernError || e.result?.getWriteConcernError?.() || e.result?.writeConcernErrors?.length);
+}
 var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	db;
 	client;
@@ -1742,6 +1850,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return this.client ?? this.db;
 	}
 	/**
+	* Same store = same client (or database handle) AND the same database: a
+	* `$lookup` only reads collections of the pipeline's own database, and one
+	* client may serve several (since 0.1.147).
+	*/
+	sharesStoreWith(other) {
+		return other instanceof MongoAdapter && other._transactionOwner() === this._transactionOwner() && other.db.databaseName === this.db.databaseName;
+	}
+	/**
 	* Per-client cache: whether transactions are unavailable (standalone MongoDB).
 	* Shared across all adapter instances for the same client so topology is probed once.
 	*/
@@ -1796,21 +1912,35 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		if (!this._collection) this._collection = this.db.collection(this.resolveTableName(false));
 		return this._collection;
 	}
-	aggregatePipeline(pipeline) {
-		return this.collection.aggregate(pipeline, this._getSessionOpts());
+	aggregatePipeline(pipeline, options) {
+		return this.collection.aggregate(pipeline, {
+			...options,
+			...this._getSessionOpts()
+		});
 	}
 	async aggregate(query) {
-		const { buildAggregatePipeline, buildCountPipeline } = await import("./agg.mjs");
+		const { aggregateOptions, buildAggregatePipeline, buildCountPipeline, buildMatchedProbe, emptyGroupRow, emptyGroupStages } = await import("./agg.mjs");
+		const emptyGroup = async (forCount) => {
+			const row = emptyGroupRow(query);
+			if (!row) return void 0;
+			const probe = buildMatchedProbe(query, searchStage, this._predicateFilterOpts);
+			if ((await wrapInvalidQuery(() => this.aggregatePipeline(probe).toArray())).length > 0) return;
+			const stages = emptyGroupStages(query, row, forCount);
+			if (!stages) return row;
+			return (await wrapInvalidQuery(() => this.aggregatePipeline(stages).toArray()))[0];
+		};
 		const searchStage = buildAggregateSearchStage(this, query.controls);
 		if (query.controls?.$count) {
-			const pipeline = buildCountPipeline(query, searchStage);
+			const pipeline = buildCountPipeline(query, searchStage, this._predicateFilterOpts);
 			this._log("aggregate (count)", pipeline);
-			const result = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
-			return result.length > 0 ? result : [{ count: 0 }];
+			const result = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline, aggregateOptions(pipeline)).toArray());
+			return result.length > 0 ? result : [{ count: await emptyGroup(true) ? 1 : 0 }];
 		}
-		const pipeline = buildAggregatePipeline(query, searchStage);
+		const pipeline = buildAggregatePipeline(query, searchStage, this._predicateFilterOpts);
 		this._log("aggregate", pipeline);
-		return wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
+		const rows = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline, aggregateOptions(pipeline)).toArray());
+		const empty = rows.length === 0 ? await emptyGroup(false) : void 0;
+		return empty ? [empty] : rows;
 	}
 	get idType() {
 		const idProp = this._table.type.type.props.get("_id");
@@ -1846,14 +1976,22 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	supportsNativePatch() {
 		return true;
 	}
-	/** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+	/** Every unit, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
 	calendarBucketUnits() {
 		return ALL_BUCKET_UNITS;
 	}
-	/** Every aggregate function, `countDistinct` included. */
+	/** Every aggregate function: `countDistinct`, `first` and `last` included. */
 	aggregateFns() {
 		return ALL_AGGREGATE_FNS;
 	}
+	/** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+	supportsAggregateExpressions() {
+		return true;
+	}
+	/** Computed view columns and first-row joins. */
+	viewCapabilities() {
+		return ALL_VIEW_CAPABILITIES;
+	}
 	/**
 	* See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
 	* BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
@@ -1911,6 +2049,58 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	supportsNativeRelations() {
 		return true;
 	}
+	/**
+	* Relational predicates (`{ nav: { $some | $none: … } }`) render as
+	* correlated `$lookup` stages, so a read whose filter holds one runs as an
+	* aggregation pipeline (find / count / findManyWithCount / grouped
+	* aggregate / search / geo); predicate-free reads keep their plain
+	* `find` / `countDocuments` path.
+	*
+	* Writes (`updateMany` / `replaceMany` / `deleteMany` and the single-row
+	* variants, whose scope may carry a predicate) first resolve the matching
+	* `_id`s through that pipeline, then write by `_id` in batches of
+	* {@link REL_WRITE_BATCH} — re-checking the predicate-free part of the
+	* filter. Inside an active transaction both steps share its session and
+	* are atomic; without one there is a window between resolving and writing
+	* in which a related document can change, so a written document may no
+	* longer satisfy the predicate (or a newly matching one is missed).
+	*
+	* Collation: such a pipeline runs without an operation-wide `collation`
+	* (it would govern the join keys and every related field too); each
+	* table's `'nocase'` fields are compared case-insensitively explicitly
+	* ({@link TMongoFilterOptions.collation}) — on reads and on these writes.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return true;
+	}
+	/**
+	* The `@db.column.collate` of a field (physical or logical path), or
+	* `undefined` for a byte-wise one — how predicate pipelines render this
+	* table's `'nocase'` comparisons ({@link TMongoFilterOptions.collation}).
+	*
+	* @since 0.1.147
+	*/
+	fieldCollation(field) {
+		this._table.flatMap;
+		return this._collateFields?.get(field);
+	}
+	/** Filter-rendering options of a pipeline with relational predicates on this table. */
+	get _predicateFilterOpts() {
+		return { collation: collationOfAdapter(this) };
+	}
+	/**
+	* Operation options of a read: the request collation for a predicate-free
+	* filter ({@link _getCollationOpts}); none with relational predicates —
+	* those pipelines render collation per field ({@link _predicateFilterOpts}).
+	*/
+	_readOpts(query) {
+		return containsRelationFilter(query.filter) ? this._getSessionOpts() : {
+			...this._getCollationOpts(query),
+			...this._getSessionOpts()
+		};
+	}
 	async loadRelations(rows, withRelations, relations, foreignKeys, tableResolver) {
 		return loadRelationsImpl(this, rows, withRelations, relations, foreignKeys, tableResolver);
 	}
@@ -1923,7 +2113,11 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		};
 	}
 	async nativePatch(filter, patch, ops, expectedVersion) {
-		const mongoFilter = this._buildCasFilter(filter, expectedVersion, "nativePatch");
+		const mongoFilter = await this._buildCasFilter(filter, expectedVersion, "nativePatch");
+		if (!mongoFilter) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
 		const versionColumn = this._table.versionColumnPhysical;
 		const effectiveOps = versionColumn !== void 0 ? {
 			...ops,
@@ -1961,10 +2155,7 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	}
 	onFieldScanned(field, _type, metadata) {
 		if (field === "_id") this._hasExplicitId = true;
-		if (field !== "_id" && metadata.has("meta.id")) {
-			this._addMongoIndexField("unique", "__pk", field);
-			this._pendingUniqueFields.push(field);
-		}
+		if (field !== "_id" && metadata.has("meta.id")) this._pendingUniqueFields.push(field);
 		for (const index of metadata.get("db.mongo.search.text") || []) this._pendingSearchFields.push({
 			indexName: index.indexName,
 			field,
@@ -2031,6 +2222,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		};
 	}
 	onAfterFlatten() {
+		const meta = this._table.getMetadata();
+		for (const field of this._pendingUniqueFields) this._addMongoIndexField("unique", "__pk", meta.documentPath(field));
 		for (const pending of this._pendingSearchFields) this._addFieldToSearchIndex("search_text", pending.indexName, pending.field, pending.mappings);
 		this._pendingSearchFields = [];
 		for (const [key, value] of this._vectorFilters.entries()) {
@@ -2120,25 +2313,12 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return geoSearchWithCountImpl(this, point, query, indexName);
 	}
 	async findManyWithCount(query) {
-		const filter = buildMongoFilter(query.filter);
-		const controls = query.controls || {};
-		const dataStages = [];
-		if (controls.$sort) dataStages.push({ $sort: controls.$sort });
-		if (controls.$skip) dataStages.push({ $skip: controls.$skip });
-		if (controls.$limit) dataStages.push({ $limit: controls.$limit });
-		if (controls.$select) {
-			const projection = controls.$select.asProjection;
-			if (projection) dataStages.push({ $project: dedupeProjection(projection) });
-		}
-		const pipeline = [{ $match: filter }, { $facet: {
-			data: dataStages,
+		const pipeline = [...mongoFilterStages(query.filter, this._predicateFilterOpts), { $facet: {
+			data: pageStages(query.controls),
 			meta: [{ $count: "count" }]
 		} }];
 		this._log("aggregate (findManyWithCount)", pipeline);
-		const result = await wrapInvalidQuery(() => this.collection.aggregate(pipeline, {
-			...this._getCollationOpts(query),
-			...this._getSessionOpts()
-		}).toArray());
+		const result = await wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray());
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -2168,14 +2348,94 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	* is supplied for a non-versioned table — fail loud at the adapter boundary
 	* rather than silently dropping the CAS predicate.
 	*/
-	_buildCasFilter(filter, expectedVersion, op) {
+	async _buildCasFilter(filter, expectedVersion, op) {
 		const versionColumn = this._table.versionColumnPhysical;
 		if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error(`${op}: expectedVersion requires versionColumn`);
-		const mongoFilter = buildMongoFilter(filter);
+		const mongoFilter = await this._writeFilterOne(filter);
+		if (!mongoFilter) return;
 		if (expectedVersion !== void 0 && versionColumn !== void 0) mongoFilter[versionColumn] = expectedVersion;
 		return mongoFilter;
 	}
 	/**
+	* The id-resolving pipeline of a write filter holding relational
+	* predicates: the matching `_id`s (in the active transaction's session,
+	* if any), each table's `'nocase'` fields compared like on reads
+	* ({@link _predicateFilterOpts}). `pre` is the predicate-free part, which
+	* every `_id`-based write re-checks — so a document that stopped matching
+	* it in between is not written.
+	*/
+	_predicateWritePlan(filter) {
+		const plan = buildMongoQuery(filter, this._predicateFilterOpts);
+		return {
+			pipeline: planStages(plan),
+			pre: plan.pre
+		};
+	}
+	/** A write filter's `_id` filter (re-checking `pre`). */
+	static _byIds(ids, pre) {
+		const byId = ids.length === 1 ? { _id: ids[0] } : { _id: { $in: ids } };
+		return pre ? { $and: [byId, pre] } : byId;
+	}
+	/** Single-document write over a predicate filter: the first match's `_id` filter (`undefined`: none). */
+	async _predicateWriteFilterOne(filter) {
+		const { pipeline, pre } = this._predicateWritePlan(filter);
+		pipeline.push({ $limit: 1 }, { $project: { _id: 1 } });
+		this._log("aggregate (write id)", pipeline);
+		const [doc] = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
+		return doc ? MongoAdapter._byIds([doc._id], pre) : void 0;
+	}
+	/**
+	* Multi-document write over `filter`: a predicate-free filter is written
+	* as is; one with predicates calls `write` with one `_id`-based filter per
+	* batch of {@link REL_WRITE_BATCH} matching ids, streamed from the cursor
+	* (never all ids in memory at once).
+	*
+	* The ids come sorted by `_id`, so writes made while the cursor is open
+	* can never feed back into it (otherwise a document an update moves within
+	* the index the cursor scans could be returned — and written — twice):
+	* after the `$lookup`s that `$sort` consumes every match before the first
+	* batch returns, and an `_id` order read from the `_id` index is stable
+	* (`_id` never changes).
+	*/
+	async _forEachMatching(filter, write) {
+		if (!containsRelationFilter(filter)) return write(buildMongoFilter(filter));
+		const { pipeline, pre } = this._predicateWritePlan(filter);
+		pipeline.push({ $project: { _id: 1 } }, { $sort: { _id: 1 } });
+		this._log("aggregate (write ids)", pipeline);
+		const cursor = this.aggregatePipeline(pipeline, { allowDiskUse: true }).batchSize(REL_WRITE_BATCH);
+		try {
+			const next = () => wrapInvalidQuery(() => cursor.next());
+			let ids = [];
+			for (let doc = await next(); doc; doc = await next()) {
+				ids.push(doc._id);
+				if (ids.length === REL_WRITE_BATCH) {
+					await write(MongoAdapter._byIds(ids, pre));
+					ids = [];
+				}
+			}
+			if (ids.length > 0) await write(MongoAdapter._byIds(ids, pre));
+		} finally {
+			await cursor.close();
+		}
+	}
+	/** Runs an update-shaped write over `filter` ({@link _forEachMatching}), counts summed. */
+	async _updateMatching(filter, write) {
+		const total = {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
+		await this._forEachMatching(filter, async (mongoFilter) => {
+			const result = await write(mongoFilter);
+			total.matchedCount += result.matchedCount;
+			total.modifiedCount += result.modifiedCount;
+		});
+		return total;
+	}
+	/** The filter of a single-document write — its predicates resolved to one `_id`. */
+	_writeFilterOne(filter) {
+		return containsRelationFilter(filter) ? this._predicateWriteFilterOne(filter) : buildMongoFilter(filter);
+	}
+	/**
 	* Wraps an async operation to catch MongoDB duplicate key errors
 	* (code 11000) and rethrow as structured `DbError` — every write path
 	* (insert, replace, update, patch, their `*Many` variants) goes through it,
@@ -2185,13 +2445,17 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		try {
 			return await fn();
 		} catch (error) {
-			if (error instanceof MongoServerError && error.code === 11e3) throw new DbError("CONFLICT", [{
-				path: error.keyPattern ? Object.keys(error.keyPattern)[0] ?? "" : "",
-				message: error.message
-			}]);
-			throw error;
+			return this._mapConstraintError(error);
 		}
 	}
+	/** Rethrows a duplicate-key (11000) server error as `CONFLICT`, anything else as is. */
+	_mapConstraintError(error) {
+		if (error instanceof MongoServerError && error.code === 11e3) throw new DbError("CONFLICT", [{
+			path: error.keyPattern ? Object.keys(error.keyPattern)[0] ?? "" : "",
+			message: error.message
+		}]);
+		throw error;
+	}
 	/** An update-shaped write under {@link _wrapDuplicateKeyError}, reduced to `TDbUpdateResult`. */
 	async _wrapUpdate(fn) {
 		const { matchedCount, modifiedCount } = await this._wrapDuplicateKeyError(fn);
@@ -2215,6 +2479,98 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return { insertedId: objectIdFromStorage(this._resolveInsertedId(data, result.insertedId)) };
 	}
 	async insertMany(data) {
+		await this._prepareInsertBatch(data);
+		this._log("insertMany", `${data.length} docs`);
+		const result = await this._wrapDuplicateKeyError(() => this.collection.insertMany(data, this._getSessionOpts()));
+		return {
+			insertedCount: result.insertedCount,
+			insertedIds: data.map((item, i) => objectIdFromStorage(this._resolveInsertedId(item, result.insertedIds[i])))
+		};
+	}
+	supportsInsertIgnore() {
+		return true;
+	}
+	/**
+	* Conflict-ignoring batch insert (the core already removed in-batch duplicates).
+	*
+	* Outside a transaction: `insertMany(…, { ordered: false })`; duplicate-key
+	* write errors (11000) mark the skipped rows, every other write error
+	* rethrows after the batch (rows already written stay — as for a plain
+	* non-transactional `insertMany`).
+	*
+	* Inside a transaction a duplicate key would abort the transaction even with
+	* `ordered: false`, so the stored keys are looked up first (inside the
+	* session), the matches are skipped and the rest is inserted ordered. A
+	* residual 11000 (e.g. a collation-equal value) throws `CONFLICT`.
+	*/
+	async insertManyIgnore(data) {
+		if (data.length === 0) return [];
+		await this._prepareInsertBatch(data);
+		this._log("insertManyIgnore", `${data.length} docs`);
+		const idOf = (item) => objectIdFromStorage(this._resolveInsertedId(item, item._id));
+		if (this._getTransactionState()) {
+			const skipped = await this._findStoredKeyConflicts(data);
+			const survivors = data.filter((_, i) => !skipped.has(i));
+			if (survivors.length > 0) await this._wrapDuplicateKeyError(() => this.collection.insertMany(survivors, {
+				ordered: true,
+				...this._getSessionOpts()
+			}));
+			return data.map((item, i) => skipped.has(i) ? null : { insertedId: idOf(item) });
+		}
+		const skipped = /* @__PURE__ */ new Set();
+		try {
+			await this.collection.insertMany(data, {
+				ordered: false,
+				...this._getSessionOpts()
+			});
+		} catch (error) {
+			if (!(error instanceof MongoBulkWriteError)) this._mapConstraintError(error);
+			const writeErrors = [error.writeErrors].flat().filter(Boolean);
+			if (writeErrors.length === 0 || hasWriteConcernError(error)) throw error;
+			for (const writeError of writeErrors) {
+				if (writeError.code !== 11e3) throw error;
+				skipped.add(writeError.index);
+			}
+		}
+		return data.map((item, i) => skipped.has(i) ? null : { insertedId: idOf(item) });
+	}
+	/**
+	* Indices of `data` rows whose primary (`_id`) or unique-index key tuple is
+	* already stored (rows with a null / missing key component never collide).
+	* One `$or` query per chunk covers every key set.
+	*/
+	async _findStoredKeyConflicts(data) {
+		const keySets = [["_id"], ...this._table.uniqueKeySets.filter((f) => !(f.length === 1 && f[0] === "_id"))];
+		const rowTuples = data.map((row) => keySets.map((fields) => uniqueKeyTuple(row, fields)));
+		const projection = Object.fromEntries(keySets.flat().map((f) => [f, 1]));
+		const stored = keySets.map(() => /* @__PURE__ */ new Set());
+		const CHUNK = 1e3;
+		for (let offset = 0; offset < data.length; offset += CHUNK) {
+			const clauses = [];
+			keySets.forEach((fields, k) => {
+				const rows = data.slice(offset, offset + CHUNK).filter((_, i) => rowTuples[offset + i][k]);
+				if (rows.length === 0) return;
+				if (fields.length === 1) clauses.push({ [fields[0]]: { $in: rows.map((row) => getPath(row, fields[0])) } });
+				else for (const row of rows) clauses.push(Object.fromEntries(fields.map((f) => [f, getPath(row, f)])));
+			});
+			if (clauses.length === 0) continue;
+			const found = await this.collection.find({ $or: clauses }, {
+				projection,
+				...this._getSessionOpts()
+			}).toArray();
+			for (const doc of found) keySets.forEach((fields, k) => {
+				const tuple = uniqueKeyTuple(doc, fields);
+				if (tuple !== void 0) stored[k].add(tuple);
+			});
+		}
+		const skipped = /* @__PURE__ */ new Set();
+		rowTuples.forEach((tuples, i) => {
+			if (tuples.some((t, k) => t !== void 0 && stored[k].has(t))) skipped.add(i);
+		});
+		return skipped;
+	}
+	/** Version default + `@db.default.increment` allocation shared by every batch insert. */
+	async _prepareInsertBatch(data) {
 		const versionColumn = this._table.versionColumnPhysical;
 		if (versionColumn !== void 0) {
 			for (const item of data) if (!(versionColumn in item)) item[versionColumn] = 0;
@@ -2224,14 +2580,12 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			for (const item of data) for (const f of this._fieldsNeedingIncrement(item)) allFields.add(f);
 			if (allFields.size > 0) await this._assignBatchIncrements(data, allFields);
 		}
-		this._log("insertMany", `${data.length} docs`);
-		const result = await this._wrapDuplicateKeyError(() => this.collection.insertMany(data, this._getSessionOpts()));
-		return {
-			insertedCount: result.insertedCount,
-			insertedIds: data.map((item, i) => objectIdFromStorage(this._resolveInsertedId(item, result.insertedIds[i])))
-		};
 	}
 	async findOne(query) {
+		if (containsRelationFilter(query.filter)) {
+			const [row] = await this._aggregateFind(query, "findOne", 1);
+			return row ?? null;
+		}
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
 		this._log("findOne", filter, opts);
@@ -2242,6 +2596,7 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}));
 	}
 	async findMany(query) {
+		if (containsRelationFilter(query.filter)) return this._aggregateFind(query, "findMany");
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
 		this._log("findMany", filter, opts);
@@ -2252,6 +2607,11 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}).toArray());
 	}
 	async count(query) {
+		if (containsRelationFilter(query.filter)) {
+			const pipeline = [...mongoFilterStages(query.filter, this._predicateFilterOpts), { $count: "count" }];
+			this._log("aggregate (count)", pipeline);
+			return (await wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray()))[0]?.count ?? 0;
+		}
 		const filter = buildMongoFilter(query.filter);
 		this._log("countDocuments", filter);
 		return this.collection.countDocuments(filter, {
@@ -2260,13 +2620,21 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		});
 	}
 	async updateOne(filter, data, ops, expectedVersion) {
-		const mongoFilter = this._buildCasFilter(filter, expectedVersion, "updateOne");
+		const mongoFilter = await this._buildCasFilter(filter, expectedVersion, "updateOne");
+		if (!mongoFilter) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
 		const updateDoc = buildMongoUpdateDoc(data, ops, this._table.versionColumnPhysical);
 		this._log("updateOne", mongoFilter, updateDoc);
 		return this._wrapUpdate(() => this.collection.updateOne(mongoFilter, updateDoc, this._getSessionOpts()));
 	}
 	async replaceOne(filter, data, expectedVersion) {
-		const mongoFilter = this._buildCasFilter(filter, expectedVersion, "replaceOne");
+		const mongoFilter = await this._buildCasFilter(filter, expectedVersion, "replaceOne");
+		if (!mongoFilter) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
 		const versionColumn = this._table.versionColumnPhysical;
 		this._log("replaceOne", mongoFilter, data);
 		if (versionColumn !== void 0) {
@@ -2279,27 +2647,34 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return this._wrapUpdate(() => this.collection.replaceOne(mongoFilter, data, this._getSessionOpts()));
 	}
 	async deleteOne(filter) {
-		const mongoFilter = buildMongoFilter(filter);
+		const mongoFilter = await this._writeFilterOne(filter);
+		if (!mongoFilter) return { deletedCount: 0 };
 		this._log("deleteOne", mongoFilter);
 		return { deletedCount: (await this.collection.deleteOne(mongoFilter, this._getSessionOpts())).deletedCount };
 	}
 	async updateMany(filter, data, ops) {
 		const versionColumn = this._table.versionColumnPhysical;
-		const mongoFilter = buildMongoFilter(filter);
 		const updateDoc = buildMongoUpdateDoc(data, ops, versionColumn);
-		this._log("updateMany", mongoFilter, updateDoc);
-		return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
+		return this._updateMatching(filter, (mongoFilter) => {
+			this._log("updateMany", mongoFilter, updateDoc);
+			return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
+		});
 	}
 	async replaceMany(filter, data) {
-		const mongoFilter = buildMongoFilter(filter);
 		const updateDoc = buildMongoUpdateDoc(data, void 0, this._table.versionColumnPhysical);
-		this._log("replaceMany", mongoFilter, updateDoc);
-		return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
+		return this._updateMatching(filter, (mongoFilter) => {
+			this._log("replaceMany", mongoFilter, updateDoc);
+			return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
+		});
 	}
 	async deleteMany(filter) {
-		const mongoFilter = buildMongoFilter(filter);
-		this._log("deleteMany", mongoFilter);
-		return { deletedCount: (await this.collection.deleteMany(mongoFilter, this._getSessionOpts())).deletedCount };
+		let deletedCount = 0;
+		await this._forEachMatching(filter, async (mongoFilter) => {
+			this._log("deleteMany", mongoFilter);
+			const result = await this.collection.deleteMany(mongoFilter, this._getSessionOpts());
+			deletedCount += result.deletedCount;
+		});
+		return { deletedCount };
 	}
 	clearCollectionCache() {
 		this._collection = void 0;
@@ -2426,6 +2801,15 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			fieldCounters.set(physical, next + 1);
 		}
 	}
+	/** A find whose filter holds relational predicates, as an aggregation pipeline. */
+	async _aggregateFind(query, label, limit) {
+		const pipeline = [...mongoFilterStages(query.filter, this._predicateFilterOpts), ...pageStages(limit ? {
+			...query.controls,
+			$limit: limit
+		} : query.controls)];
+		this._log(`aggregate (${label})`, pipeline);
+		return wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray());
+	}
 	_buildFindOptions(controls) {
 		const opts = {};
 		if (!controls) return opts;
@@ -2442,6 +2826,9 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	* Returns MongoDB collation options if any filter field has a non-binary collation.
 	* Uses pre-computed insights when available, falls back to computing them on demand.
 	* Maps: nocase → strength 2 (case-insensitive), unicode → strength 1 (case+accent-insensitive).
+	* Predicate-free filters only — a filter with relational predicates never gets an
+	* operation-wide collation ({@link _readOpts}), so insights are never computed over
+	* resolved predicate operands.
 	*/
 	_getCollationOpts(query) {
 		if (!this._collateFields) return;
@@ -2544,6 +2931,19 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return node.fields;
 	}
 };
+/** `$sort` → `$skip` → `$limit` → `$project` stages of a read's controls. */
+function pageStages(controls) {
+	const stages = [];
+	if (!controls) return stages;
+	if (controls.$sort) stages.push({ $sort: controls.$sort });
+	if (controls.$skip) stages.push({ $skip: controls.$skip });
+	if (controls.$limit) stages.push({ $limit: controls.$limit });
+	if (controls.$select) {
+		const projection = controls.$select.asProjection;
+		if (projection) stages.push({ $project: dedupeProjection(projection) });
+	}
+	return stages;
+}
 /**
 * Normalizes a declared `fuzzy` arg (`0-2`) into the query-time metadata Atlas
 * accepts. Atlas only honors an edit distance of `1` or `2`; `0`/undefined means
@@ -2603,7 +3003,7 @@ function buildMongoUpdateDoc(data, ops, versionColumn) {
 function createAdapter(connection, _options) {
 	const client = new MongoClient(connection);
 	const db = client.db();
-	return new DbSpace(() => new MongoAdapter(db, client));
+	return new DbSpace(() => new MongoAdapter(db, client), { onClose: () => client.close() });
 }
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, buildMongoFilter, createAdapter, mongoIndexKey, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };