uql-orm 0.69.0 → 0.71.0

package/dist/migrate/ddl/sqliteIndexDdl.js

@@ -0,0 +1,38 @@
+import { indexDistance, isVectorIndexType, unsupportedVectorMetric } from '../../type/vector.js';
+import { IndexDdl } from './indexDdl.js';
+/**
+ * SQLite's `CREATE INDEX`, which names no index type. A vector index is libSQL's DiskANN where the dialect
+ * can index its metric, and a plain index on an engine with none, so an entity written for Postgres migrates.
+ */
+export class SqliteIndexDdl extends IndexDdl {
+    indexColumn(entry, index) {
+        const metric = this.vectorIndexMetric(index);
+        if (metric === undefined) {
+            return super.indexColumn(entry, index);
+        }
+        const options = [
+            `metric=${metric}`,
+            ...(index.m === undefined ? [] : [`max_neighbors=${index.m}`]),
+            ...(index.efConstruction === undefined ? [] : [`insert_l=${index.efConstruction}`]),
+        ];
+        const args = [this.dialect.escapeId(entry.column), ...options.map((option) => this.dialect.escape(option))];
+        return `libsql_vector_idx(${args.join(', ')})`;
+    }
+    /** The metric libSQL's index names, or `undefined` where the index is no vector index or the engine has none. */
+    vectorIndexMetric(index) {
+        const { vectorMetrics, dialectName } = this.dialect;
+        if (!isVectorIndexType(index.type) || !this.dialect.hasVectorIndex()) {
+            return undefined;
+        }
+        const distance = indexDistance(index);
+        const metric = vectorMetrics.get(distance)?.index;
+        if (!metric) {
+            throw unsupportedVectorMetric(dialectName, distance, index.name);
+        }
+        // Its tables are named after the index, unquoted: any other name fails with "unable to initialize diskann".
+        if (!/^\w+$/.test(index.name) || index.entries.length !== 1) {
+            throw new TypeError(`libSQL names a vector index only by letters, digits and underscores, over one column (index "${index.name}")`);
+        }
+        return metric;
+    }
+}

package/dist/migrate/generator/mongoCommand.d.ts

@@ -6,6 +6,24 @@ export type MongoIndexOptions = {
     readonly name: string;
     readonly partialFilterExpression?: Readonly<Record<string, unknown>>;
 };
+/** A field of an Atlas vector search index: the vector itself, or one its `filter` pre-filters on. */
+export type MongoVectorSearchField = {
+    readonly type: 'vector';
+    readonly path: string;
+    readonly numDimensions: number;
+    readonly similarity: string;
+} | {
+    readonly type: 'filter';
+    readonly path: string;
+};
+/** An Atlas search index as `createSearchIndex` takes one. */
+export type MongoSearchIndex = {
+    readonly name: string;
+    readonly type: 'vectorSearch';
+    readonly definition: {
+        readonly fields: readonly MongoVectorSearchField[];
+    };
+};
 /** The commands {@link MongoSchemaGenerator} emits as JSON, one per statement. */
 export type MongoCommand = {
     readonly action: 'createCollection';
@@ -27,6 +45,14 @@ export type MongoCommand = {
     readonly action: 'dropIndex';
     readonly collection: string;
     readonly name: string;
+} | {
+    readonly action: 'createSearchIndex';
+    readonly collection: string;
+    readonly index: MongoSearchIndex;
+} | {
+    readonly action: 'dropSearchIndex';
+    readonly collection: string;
+    readonly name: string;
 };
 export declare function serializeMongoCommand(command: MongoCommand): string;
 /**
@@ -41,6 +67,8 @@ export type MongoCommandTarget = {
         drop(): Promise<unknown>;
         createIndex(key: MongoIndexKey, options: MongoIndexOptions): Promise<unknown>;
         dropIndex(name: string): Promise<unknown>;
+        createSearchIndex(index: MongoSearchIndex): Promise<unknown>;
+        dropSearchIndex(name: string): Promise<unknown>;
     };
 };
 /** Execute one emitted command. */

package/dist/migrate/generator/mongoCommand.js

@@ -25,6 +25,10 @@ export function runMongoCommand(db, statement) {
             return db.collection(command.collection).createIndex(command.key, command.options);
         case 'dropIndex':
             return db.collection(command.collection).dropIndex(command.name);
+        case 'createSearchIndex':
+            return db.collection(command.collection).createSearchIndex(command.index);
+        case 'dropSearchIndex':
+            return db.collection(command.collection).dropSearchIndex(command.name);
         default:
             // Unreachable for a command this module produced; a hand-written statement lands here rather
             // than being silently skipped.
@@ -46,6 +50,10 @@ export function mongoCommandSource(statement, db) {
             return `${db}.collection(${literal(command.collection)}).createIndex(${literal(command.key)}, ${literal(command.options)})`;
         case 'dropIndex':
             return `${db}.collection(${literal(command.collection)}).dropIndex(${literal(command.name)})`;
+        case 'createSearchIndex':
+            return `${db}.collection(${literal(command.collection)}).createSearchIndex(${literal(command.index)})`;
+        case 'dropSearchIndex':
+            return `${db}.collection(${literal(command.collection)}).dropSearchIndex(${literal(command.name)})`;
         default:
             throw unsupportedMongoCommand(statement);
     }

package/dist/migrate/generator/mongoSchemaGenerator.d.ts

@@ -35,6 +35,8 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
     generateAlterTableDown(diff: SchemaDiff): string[];
     /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
     generateCreateIndex(tableName: string, index: IndexSchema): string;
+    /** An Atlas vector search index: its vector field first, then each field a `$vectorSearch` pre-filters on. */
+    private generateCreateSearchIndex;
     generateDropIndex(tableName: string, indexName: string): string;
     /** A collection and its indexes, which is all a document store has: a column, a constraint or SQL throws. */
     generateOperation(operation: AnyMigrationOperation): string[];

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -1,16 +1,22 @@
 import { getMeta } from '../../entity/index.js';
 import { MongoDialect } from '../../mongo/mongoDialect.js';
 import { QueryRaw, } from '../../type/index.js';
-import { declaredIndexes, indexNameParts, renderIndexColumn } from '../../util/ddlExpression.util.js';
-import { derivedIndexName } from '../../util/sql.util.js';
+import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
+import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../../util/ddlExpression.util.js';
 import { assertIndexFeatures, assertIndexType } from '../ddl/indexDdl.js';
 import { assertIndexPredicate, refusedIndexPredicate } from '../indexPredicate.js';
 import { renderIndexDefinition } from './definitionToNode.js';
 import { serializeMongoCommand } from './mongoCommand.js';
-/** The index types a key spec can say: a plain key, or `'text'`. */
-const MONGO_INDEX_TYPES = new Set(['btree', 'fulltext']);
+/** The index types a key spec can say, a plain key or `'text'`, and Atlas's vector search index. */
+const MONGO_INDEX_TYPES = new Set(['btree', 'fulltext', 'vectorSearch']);
 /** A key spec's one feature beyond its keys: a partial filter. */
 const MONGO_INDEX_FEATURES = new Set(['partial']);
+/** Atlas's name for each metric a vector search index scores by. */
+const ATLAS_SIMILARITY = {
+    cosine: 'cosine',
+    l2: 'euclidean',
+    inner: 'dotProduct',
+};
 export class MongoSchemaGenerator extends MongoDialect {
     defaultForeignKeyAction;
     constructor(namingStrategy, defaultForeignKeyAction) {
@@ -51,7 +57,11 @@ export class MongoSchemaGenerator extends MongoDialect {
         const entries = index.columns
             .map((entry) => renderIndexColumn(entry, () => this.compileDdl()))
             .map((entry) => ({ ...entry, column: this.columnOf(meta, entry.column) }));
-        const name = index.name ?? derivedIndexName(collectionName, indexNameParts(entries));
+        const [first] = index.columns;
+        const vector = index.type === 'vectorSearch' && typeof first?.column === 'string' ? meta.fields[first.column] : undefined;
+        const name = vector
+            ? this.vectorSearchIndexName(index.name, entries[0].column)
+            : declaredIndexName(index.name, collectionName, entries);
         return {
             name,
             entries,
@@ -59,6 +69,8 @@ export class MongoSchemaGenerator extends MongoDialect {
             type: index.type,
             include: index.include,
             where: index.where && this.compileIndexPredicate(index.where, meta.entity, name),
+            distance: index.distance ?? vector?.distance,
+            dimensions: vector?.dimensions,
         };
     }
     /**
@@ -94,11 +106,16 @@ export class MongoSchemaGenerator extends MongoDialect {
         return (diff.indexesToAdd ?? []).map((index) => this.generateCreateIndex(diff.tableName, index));
     }
     generateAlterTableDown(diff) {
-        return (diff.indexesToAdd ?? []).map((index) => this.generateDropIndex(diff.tableName, index.name));
+        return (diff.indexesToAdd ?? []).map((index) => index.type === 'vectorSearch'
+            ? serializeMongoCommand({ action: 'dropSearchIndex', collection: diff.tableName, name: index.name })
+            : this.generateDropIndex(diff.tableName, index.name));
     }
     /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
     generateCreateIndex(tableName, index) {
         assertIndexType(index, MONGO_INDEX_TYPES, this.dialectName);
+        if (index.type === 'vectorSearch') {
+            return this.generateCreateSearchIndex(tableName, index);
+        }
         assertIndexFeatures(index, MONGO_INDEX_FEATURES, this.dialectName);
         const key = {};
         for (const entry of index.entries) {
@@ -116,6 +133,33 @@ export class MongoSchemaGenerator extends MongoDialect {
             },
         });
     }
+    /** An Atlas vector search index: its vector field first, then each field a `$vectorSearch` pre-filters on. */
+    generateCreateSearchIndex(tableName, index) {
+        assertIndexFeatures(index, new Set(), this.dialectName);
+        const [vector, ...filters] = index.entries;
+        if (!vector || index.dimensions === undefined) {
+            throw new TypeError(`an Atlas vector search index states its field's dimensions (index "${index.name}")`);
+        }
+        const distance = indexDistance(index);
+        const similarity = ATLAS_SIMILARITY[distance];
+        if (!similarity) {
+            throw unsupportedVectorMetric(this.dialectName, distance, index.name);
+        }
+        return serializeMongoCommand({
+            action: 'createSearchIndex',
+            collection: tableName,
+            index: {
+                name: index.name,
+                type: 'vectorSearch',
+                definition: {
+                    fields: [
+                        { type: 'vector', path: vector.column, numDimensions: index.dimensions, similarity },
+                        ...filters.map((entry) => ({ type: 'filter', path: entry.column })),
+                    ],
+                },
+            },
+        });
+    }
     generateDropIndex(tableName, indexName) {
         return serializeMongoCommand({ action: 'dropIndex', collection: tableName, name: indexName });
     }

package/dist/migrate/introspection/mongoIntrospector.js

@@ -1,5 +1,7 @@
 import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
 import { isMongoQuerier, } from '../../type/index.js';
+/** What a server without Atlas Search answers a search index command with. */
+const SEARCH_NOT_ENABLED = 31082;
 /**
  * MongoDB schema introspector.
  * MongoDB doesn't have a fixed schema, so this primarily focuses on collections and indexes.
@@ -29,15 +31,27 @@ export class MongoSchemaIntrospector {
             }
             // Annotated rather than inferred: the driver's `indexes()` is overloaded and resolves to `any` on
             // some versions, which silently made every field below unchecked.
-            const indexes = await db.collection(tableName).indexes();
+            const collection = db.collection(tableName);
+            const indexes = await collection.indexes();
+            const searchIndexes = await listSearchIndexes(collection);
             return {
                 name: tableName,
                 columns: [],
-                indexes: indexes.map((idx) => ({
-                    name: idx.name ?? Object.keys(idx.key).join('_'),
-                    entries: Object.keys(idx.key).map((column) => ({ column })),
-                    unique: !!idx.unique,
-                })),
+                indexes: [
+                    ...indexes.map((idx) => ({
+                        name: idx.name ?? Object.keys(idx.key).join('_'),
+                        entries: Object.keys(idx.key).map((column) => ({ column })),
+                        unique: !!idx.unique,
+                    })),
+                    ...searchIndexes
+                        .filter((idx) => idx.type === 'vectorSearch')
+                        .map((idx) => ({
+                        name: idx.name,
+                        entries: idx.latestDefinition.fields.map(({ path }) => ({ column: path })),
+                        unique: false,
+                        type: 'vectorSearch',
+                    })),
+                ],
             };
         });
     }
@@ -61,6 +75,18 @@ export class MongoSchemaIntrospector {
         });
     }
 }
+/** A collection's Atlas search indexes, none where the server has no Atlas Search. */
+async function listSearchIndexes(collection) {
+    try {
+        return await collection.aggregate([{ $listSearchIndexes: {} }]).toArray();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === SEARCH_NOT_ENABLED) {
+            return [];
+        }
+        throw error;
+    }
+}
 async function hasCollection(db, name) {
     const collections = await db.listCollections({ name, type: 'collection' }, { nameOnly: true }).toArray();
     return collections.length > 0;
@@ -83,7 +109,7 @@ function buildTable({ name, indexes = [] }) {
                 });
             }
         }
-        table.indexes.push({ name: index.name, table, entries: index.entries, unique: index.unique });
+        table.indexes.push({ name: index.name, table, entries: index.entries, unique: index.unique, type: index.type });
     }
     return table;
 }

package/dist/migrate/introspection/postgresIntrospector.js

@@ -199,6 +199,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
                 type: INDEX_TYPES.find((type) => type === rows[0].method),
                 where: rows[0].predicate ?? undefined,
                 include: include.length > 0 ? include : undefined,
+                ...fulltextIndex(rows),
             };
         });
     }
@@ -267,6 +268,24 @@ const FOREIGN_KEY_ACTION_CODES = {
 };
 const NUMBER_DEFAULT = /^\(?(-?\d+(?:\.\d+)?)\)?$/;
 const QUOTED_NUMBER_DEFAULT = /^'(-?\d+(?:\.\d+)?)'::(?:smallint|integer|bigint|numeric|real|double precision)$/;
+/**
+ * A `fulltext` index read back as declared, from the document its `GIN` index (`inverted` on CockroachDB)
+ * is over as UQL builds it, `to_tsvector('english'::regconfig, COALESCE(title, ''::text) || ...)`: its
+ * columns and config, so it compares with the entity. Any other expression stays the expression it is.
+ */
+function fulltextIndex(rows) {
+    const [row] = rows;
+    const document = rows.length === 1 && TEXT_INDEX_METHODS.has(row.method) && row.is_expression;
+    const config = document ? /^\(?to_tsvector\('((?:[^']|'')*)'::/i.exec(row.entry) : null;
+    const columns = config
+        ? [...row.entry.matchAll(/COALESCE\(("(?:[^"]|"")+"|[^,()\s]+),/gi)].map(([, column]) => column.startsWith('"') ? column.slice(1, -1).replaceAll('""', '"') : column)
+        : [];
+    if (!config || !columns.length) {
+        return undefined;
+    }
+    return { type: 'fulltext', entries: columns.map((column) => ({ column })), config: config[1].replaceAll("''", "'") };
+}
+const TEXT_INDEX_METHODS = new Set(['gin', 'inverted']);
 /**
  * Postgres states every entry in full: a plain column still reports `order: 'asc'`, and only a
  * non-default operator class is named. The diff defaults the entity side to match, so an option

package/dist/migrate/introspection/sqliteIntrospector.d.ts

@@ -1,9 +1,13 @@
+import type { IndexFacet } from '../../schema/indexDifferences.js';
 import type { ColumnSchema, ForeignKeySchema, IndexSchema } from '../../type/index.js';
 import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQLite schema introspector
  */
 export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
+    /** Whether an index is libSQL's vector index, where the engine has one; elsewhere a declared one is built plain. */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
+    /** Not SQLite's own tables, nor the ones libSQL keeps a vector index in: its metadata and `<index>_shadow`. */
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
     protected parseTableExistsResult([row]: SqliteCountRow[]): boolean;
@@ -29,6 +33,8 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected mapForeignKeysResult(_read: TableRowReader, tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
     protected mapPrimaryKeyResult(results: SqliteColumnRow[]): string[] | undefined;
     private getUniqueColumns;
+    /** libSQL's `libsql_vector_idx(col, 'metric=...')`, read back from the statement that created it. */
+    private getVectorIndex;
     private getIndexColumns;
     protected normalizeType(type: string): string;
     protected extractLength(type: string): number | undefined;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -4,12 +4,17 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * SQLite schema introspector
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
+    /** Whether an index is libSQL's vector index, where the engine has one; elsewhere a declared one is built plain. */
+    indexFacets = new Set(this.dialect.hasVectorIndex() ? ['vector'] : []);
+    /** Not SQLite's own tables, nor the ones libSQL keeps a vector index in: its metadata and `<index>_shadow`. */
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT name
       FROM sqlite_master
       WHERE type = 'table'
         AND name NOT LIKE 'sqlite_%'
+        AND name <> 'libsql_vector_meta_shadow'
+        AND name NOT IN (SELECT name || '_shadow' FROM sqlite_master WHERE type = 'index')
       ORDER BY name
     `;
     }
@@ -85,15 +90,24 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             const isCompositeUnique = index.origin === 'u' && columns.length > 1;
             // `PRAGMA index_info` names an expression entry `null` (its `cid` is -2), and the expression text
             // lives only in `sqlite_master.sql`. Reporting `{ column: null }` put a column literally named
-            // `null` into the diff, so an index UQL cannot describe is left out entirely instead.
+            // `null` into the diff, so an index UQL cannot describe is left out, libSQL's vector index aside.
             const named = columns.filter((column) => column.name !== null);
-            if (named.length === columns.length && (isUserCreated || isCompositeUnique)) {
+            if (!isUserCreated && !isCompositeUnique) {
+                continue;
+            }
+            if (named.length === columns.length) {
                 indexSchemas.push({
                     name: index.name,
                     entries: named.map((column) => ({ column: column.name })),
                     unique: Boolean(index.unique),
                 });
             }
+            else {
+                const vectorIndex = await this.getVectorIndex(read, index.name);
+                if (vectorIndex) {
+                    indexSchemas.push(vectorIndex);
+                }
+            }
         }
         return indexSchemas;
     }
@@ -143,12 +157,24 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return uniqueColumns;
     }
+    /** libSQL's `libsql_vector_idx(col, 'metric=...')`, read back from the statement that created it. */
+    async getVectorIndex(read, indexName) {
+        const [row] = await read(
+        /*sql*/ `SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?`, [indexName]);
+        const column = row?.sql?.match(/libsql_vector_idx\s*\(\s*[`"[]?([^`"\],\s)]+)/i)?.[1];
+        if (!column) {
+            return undefined;
+        }
+        const metric = row.sql?.match(/'metric=(\w+)'/i)?.[1]?.toLowerCase();
+        const distances = new Map([...this.dialect.vectorMetrics].map(([distance, { index }]) => [index, distance]));
+        return { name: indexName, entries: [{ column }], unique: false, type: 'vector', distance: distances.get(metric) };
+    }
     getIndexColumns(read, indexName) {
         return read(/*sql*/ `PRAGMA index_info(${this.escapeId(indexName)})`);
     }
     normalizeType(type) {
         // Extract base type without length/precision
-        const match = type.match(/^([A-Za-z]+)/);
+        const match = type.match(/^([A-Za-z][A-Za-z0-9_]*)/);
         return match ? match[1].toUpperCase() : type.toUpperCase();
     }
     extractLength(type) {

package/dist/migrate/migrator.d.ts

@@ -49,7 +49,8 @@ export declare class Migrator {
     /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
     private runInOrder;
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
     /**

package/dist/migrate/migrator.js

@@ -112,14 +112,15 @@ export class Migrator {
         return results;
     }
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
         return this.target.withSession(async ({ querier, transaction }) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-                await transaction(async () => {
+                const work = async () => {
                     if (direction === 'up') {
                         await migration.up(querier);
                         await this.storage.logWithQuerier(querier, migration.name);
@@ -128,7 +129,8 @@ export class Migrator {
                         await migration.down(querier);
                         await this.storage.unlogWithQuerier(querier, migration.name);
                     }
-                });
+                };
+                await (migration.transaction === false ? work() : transaction(work));
                 const duration = Date.now() - startTime;
                 this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
                 return {

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,24 +247,41 @@ 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.
      * Returns `undefined` if no vector sort is present.
      */
     extractVectorSort<E extends Document>(sort: QuerySortMap<E> | undefined): ExtractedVectorSort<E> | undefined;
+    /** The Atlas index a `$vectorSearch` over `column` reads, and migrations create: its declared name, else `<column>_index`. */
+    protected vectorSearchIndexName(name: string | undefined, column: string): string;
     /**
      * 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;