uql-orm 0.104.1 → 0.105.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +7 -7
  4. package/dist/dialect/abstractSqlDialect.d.ts +6 -4
  5. package/dist/dialect/abstractSqlDialect.js +35 -32
  6. package/dist/dialect/aliases.d.ts +2 -0
  7. package/dist/dialect/aliases.js +2 -0
  8. package/dist/dialect/jsonSql.js +2 -2
  9. package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
  10. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  11. package/dist/dialect/operators.js +2 -4
  12. package/dist/dialect/queryJoins.d.ts +2 -0
  13. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  14. package/dist/dialect/vectorSqlDialect.js +1 -1
  15. package/dist/entity/column.d.ts +3 -0
  16. package/dist/entity/column.js +3 -0
  17. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  18. package/dist/entity/columnOptionsBuilder.js +108 -0
  19. package/dist/entity/decorator/bag.d.ts +4 -4
  20. package/dist/entity/decorator/entity.d.ts +2 -19
  21. package/dist/entity/decorator/entity.js +3 -37
  22. package/dist/entity/decorator/members.d.ts +46 -76
  23. package/dist/entity/decorator/members.js +18 -7
  24. package/dist/entity/index.d.ts +2 -1
  25. package/dist/entity/index.js +2 -1
  26. package/dist/entity/metadata/definition.d.ts +10 -24
  27. package/dist/entity/metadata/definition.js +329 -147
  28. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  29. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  30. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  31. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  32. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  33. package/dist/entity/metadata/schemaFixture/book.js +22 -0
  34. package/dist/http/query.js +12 -13
  35. package/dist/index.d.ts +2 -2
  36. package/dist/index.js +2 -1
  37. package/dist/mariadb/mariaDialect.js +1 -1
  38. package/dist/mariadb/mariadbQuerier.js +1 -3
  39. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  40. package/dist/migrate/builder/columnBuilder.js +104 -110
  41. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  42. package/dist/migrate/builder/migrationBuilder.js +7 -6
  43. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  44. package/dist/migrate/builder/tableBuilder.js +88 -204
  45. package/dist/migrate/builder/types.d.ts +52 -151
  46. package/dist/migrate/builder/types.js +0 -6
  47. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  48. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  49. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  50. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  51. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  52. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  53. package/dist/migrate/ddl/defaultSql.js +7 -6
  54. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  55. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  56. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  57. package/dist/migrate/ddl/indexDdl.js +33 -30
  58. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  59. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  60. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  61. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  62. package/dist/migrate/drift/driftDetector.js +2 -2
  63. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  64. package/dist/migrate/generator/definitionToNode.js +4 -5
  65. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  66. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  67. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  68. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  69. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  70. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  71. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  72. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  73. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  74. package/dist/migrate/schemaChange.d.ts +3 -3
  75. package/dist/migrate/schemaChange.js +3 -2
  76. package/dist/migrate/schemaGenerator.js +1 -1
  77. package/dist/migrate/storage/databaseStorage.js +4 -4
  78. package/dist/mongodb/mongoDialect.d.ts +33 -36
  79. package/dist/mongodb/mongoDialect.js +118 -32
  80. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  81. package/dist/mongodb/mongoIntrospector.js +11 -5
  82. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  83. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  84. package/dist/mongodb/mongodbQuerier.js +9 -43
  85. package/dist/querier/abstractQuerier.d.ts +0 -1
  86. package/dist/querier/abstractQuerier.js +1 -20
  87. package/dist/querier/keyset.js +3 -3
  88. package/dist/schema/declaredColumn.d.ts +11 -0
  89. package/dist/schema/declaredColumn.js +21 -0
  90. package/dist/schema/indexColumns.d.ts +0 -3
  91. package/dist/schema/indexColumns.js +11 -7
  92. package/dist/schema/indexDifferences.d.ts +10 -5
  93. package/dist/schema/indexDifferences.js +42 -28
  94. package/dist/schema/schemaASTBuilder.js +28 -36
  95. package/dist/schema/schemaASTDiffer.js +8 -4
  96. package/dist/schema/sqlExpression.d.ts +21 -17
  97. package/dist/schema/sqlExpression.js +11 -23
  98. package/dist/type/column.d.ts +328 -0
  99. package/dist/type/column.js +2 -0
  100. package/dist/type/config.d.ts +1 -1
  101. package/dist/type/dialect.d.ts +2 -1
  102. package/dist/type/dialect.js +1 -0
  103. package/dist/type/entity.d.ts +290 -279
  104. package/dist/type/entity.js +6 -1
  105. package/dist/type/index.d.ts +2 -0
  106. package/dist/type/index.js +2 -0
  107. package/dist/type/migration.d.ts +5 -5
  108. package/dist/type/query.d.ts +44 -40
  109. package/dist/type/query.js +2 -3
  110. package/dist/type/queryAggregate.d.ts +22 -12
  111. package/dist/type/querySql.d.ts +20 -4
  112. package/dist/type/querySql.js +27 -9
  113. package/dist/type/schemaEntity.d.ts +190 -0
  114. package/dist/type/schemaEntity.js +1 -0
  115. package/dist/type/utility.d.ts +0 -6
  116. package/dist/type/vector.d.ts +1 -1
  117. package/dist/util/ddlExpression.util.d.ts +12 -13
  118. package/dist/util/ddlExpression.util.js +12 -21
  119. package/dist/util/dialect.util.d.ts +11 -5
  120. package/dist/util/dialect.util.js +31 -37
  121. package/dist/util/field.util.d.ts +10 -9
  122. package/dist/util/field.util.js +14 -10
  123. package/dist/util/fieldOption.util.d.ts +11 -95
  124. package/dist/util/fieldOption.util.js +49 -16
  125. package/dist/util/hook.util.d.ts +2 -14
  126. package/dist/util/hook.util.js +3 -16
  127. package/dist/util/index.d.ts +1 -0
  128. package/dist/util/index.js +1 -0
  129. package/dist/util/indexEntry.util.d.ts +45 -0
  130. package/dist/util/indexEntry.util.js +138 -0
  131. package/dist/util/relationQuery.util.d.ts +0 -1
  132. package/dist/util/relationQuery.util.js +0 -5
  133. package/dist/util/sql.d.ts +10 -7
  134. package/dist/util/sql.js +34 -16
  135. package/dist/util/sql.util.d.ts +4 -5
  136. package/dist/util/sql.util.js +7 -16
  137. package/dist/util/string.util.d.ts +2 -0
  138. package/dist/util/string.util.js +4 -0
  139. package/dist/util/uqlError.d.ts +1 -1
  140. package/dist/util/uqlError.js +1 -1
  141. package/package.json +1 -1
  142. package/skills/uql-orm/SKILL.md +76 -25
  143. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -1,28 +1,12 @@
1
1
  import { type Document, type Filter, type Sort } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
- import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggregate, QueryExclude, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
3
+ import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggregate, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryWhere, Type } from '../type/index.js';
4
4
  import { type CallbackKey } from '../util/index.js';
5
- /**
6
- * An ordering as the pipeline runs it: the `$sort`, the fields it needs on the document first - a
7
- * placement's null flags - and the ones to take back off after it. One object, so a caller cannot
8
- * order by a field it forgot to add, or leave one behind in the rows it answers with.
9
- */
10
- export type MongoSortPlan = {
5
+ /** How a read runs: its pipeline, or the ordering of the `find` cursor where one expresses it. */
6
+ export type MongoRead = {
7
+ readonly pipeline: MongoAggregationPipelineEntry<Document>[];
8
+ } | {
11
9
  readonly sort: Sort;
12
- readonly stages: MongoAggregationPipelineEntry<Document>[];
13
- readonly fields: string[];
14
- };
15
- /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
16
- type MongoReadStages = {
17
- /** Ordering, which runs after the lookups when it reads one of their fields. */
18
- readonly sort: MongoSortPlan;
19
- readonly pager?: MongoAggregationPipelineEntry<Document>[];
20
- /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
21
- readonly score?: {
22
- readonly field: string;
23
- readonly meta: 'vectorSearchScore' | 'textScore';
24
- readonly temporary?: boolean;
25
- };
26
10
  };
27
11
  /** Lookup stages, and the temp fields they fill, which the pipeline takes back out once read. */
28
12
  type Lookup = {
@@ -100,20 +84,20 @@ export declare class MongoDialect extends AbstractDialect {
100
84
  private allHolding;
101
85
  /** An object's keys as {@link held} reads each, a nested object's by its dotted path rather than whole. */
102
86
  private containment;
103
- select<E extends Document>(entity: Type<E>, select?: QuerySelectValue<E>, exclude?: QueryExclude<E>): Record<string, 0 | 1>;
87
+ select<E extends Document>(entity: Type<E>, select?: QuerySelectValue<E>): Record<string, 0 | 1>;
104
88
  /**
105
89
  * The `$sort` stage. A relation key reads the document a `$lookup` unwound onto the parent, so - as
106
90
  * on the SQL dialects - it is only addressable when the statement joins that relation. Here that
107
91
  * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
108
92
  * added for the sort alone would change what the caller gets back.
109
93
  */
110
- sort<E extends Document>(entity: Type<E>, q: Query<E>): Sort;
94
+ private sort;
111
95
  /**
112
96
  * The ordering, and the paths whose nulls it places. MongoDB sorts null and missing lowest and takes
113
97
  * no placement, so one is emulated: {@link nullsSortStages} flags each path and the flag is ordered
114
- * by ahead of the value itself.
98
+ * by ahead of the value itself. `ranked` is a field holding a vector distance, ordered by first.
115
99
  */
116
- sortPlan<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): MongoSortPlan;
100
+ private sortPlan;
117
101
  /**
118
102
  * Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. `at` is where the
119
103
  * level is: the relations walked to it (`path`, ending in a dot), and the join its rows came from, if any.
@@ -127,8 +111,6 @@ export declare class MongoDialect extends AbstractDialect {
127
111
  sortAggregateStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): Lookup & {
128
112
  readonly fields: string[];
129
113
  };
130
- /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
131
- readsAggregates<E extends Document>(entity: Type<E>, q: Query<E>): boolean;
132
114
  /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
133
115
  private aggregateKeys;
134
116
  /**
@@ -175,14 +157,34 @@ export declare class MongoDialect extends AbstractDialect {
175
157
  * embedded path (`kind.city` -> `<kind's column>.city`).
176
158
  */
177
159
  private pathOf;
178
- aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
160
+ /**
161
+ * How a read runs, its ordering and aggregates read once for both the routing and the run: the one place
162
+ * deciding how a read is scored and ranked, a root vector search through Atlas.
163
+ */
164
+ readPlan<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoRead;
165
+ /**
166
+ * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
167
+ * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
168
+ */
169
+ private readsThroughPipeline;
170
+ /**
171
+ * Build an aggregation pipeline for vector similarity search.
172
+ * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
173
+ */
174
+ private vectorSearchPipeline;
175
+ /** A read as a pipeline, whether or not a `find` cursor would express it. */
176
+ aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
177
+ /** The pipeline of a read no `$vectorSearch` enters, given its ordering, aggregates and vector score. */
178
+ private scanPipeline;
179
+ /** A vector search's exact distance, by its metric, as a score to rank by: its `$project`, else a temporary field. */
180
+ private nearestScore;
179
181
  /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
180
182
  pagerStages(q: QueryPager): MongoAggregationPipelineEntry<Document>[];
181
183
  /**
182
184
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
183
185
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
184
186
  */
185
- readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
187
+ private readStages;
186
188
  /**
187
189
  * `$distinct` as a `$group` on the columns the query projects - the same set a SQL dialect puts
188
190
  * after `SELECT DISTINCT` - and the `$replaceRoot` that lifts the grouped key back to the top
@@ -278,14 +280,14 @@ export declare class MongoDialect extends AbstractDialect {
278
280
  * Separate vector sort entries from regular sort entries.
279
281
  * Returns `undefined` if no vector sort is present.
280
282
  */
281
- extractVectorSort<E extends Document>(sort: QuerySortMap<E> | undefined): ExtractedVectorSort<E> | undefined;
283
+ private extractVectorSort;
282
284
  /** The Atlas index a `$vectorSearch` over `column` reads, and migrations create: its declared name, else `<column>_index`. */
283
285
  protected vectorSearchIndexName(name: string | undefined, column: string): string;
284
286
  /**
285
287
  * Build a `$vectorSearch` aggregation pipeline stage.
286
288
  * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
287
289
  */
288
- buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): MongoAggregationPipelineEntry<Document>;
290
+ private buildVectorSearchStage;
289
291
  }
290
292
  export type MongoAggregationPipelineEntry<E extends Document> = {
291
293
  $lookup?: MongoAggregationLookup;
@@ -317,9 +319,4 @@ type MongoAggregationUnwind = {
317
319
  readonly path?: string;
318
320
  readonly preserveNullAndEmptyArrays?: boolean;
319
321
  };
320
- export type ExtractedVectorSort<E> = {
321
- readonly vectorKey: string;
322
- readonly vectorSearch: QueryVectorSearch;
323
- readonly regularSort: QuerySortMap<E>;
324
- };
325
322
  export {};
@@ -1,12 +1,12 @@
1
1
  import { ObjectId } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
- import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_FIELD_PREFIX, relTempField, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
3
+ import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_FIELD_PREFIX, relTempField, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, NEAREST_DISTANCE_ALIAS, } from '../dialect/aliases.js';
4
4
  import { betweenBounds, inOperands, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, sizeComparisons, } from '../dialect/operators.js';
5
5
  import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
6
6
  import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
7
7
  import { COUNT_RESULT_KEY } from '../type/query.js';
8
8
  import { QuerySql } from '../type/querySql.js';
9
- import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, foldJson, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, vectorDistanceOf, cachedIn, } from '../util/index.js';
9
+ import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, foldJson, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, indexedDistance, vectorDistanceOf, vectorCandidates, populatesRelations, cachedIn, } from '../util/index.js';
10
10
  import { UqlUsageError } from '../util/uqlError.js';
11
11
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
12
12
  import { textLanguage } from './textLanguage.js';
@@ -181,10 +181,16 @@ function regexMatch(ref, regex, insensitive = false) {
181
181
  const match = { $regexMatch: { input: ref, regex: literal(regex), ...(insensitive && { options: 'i' }) } };
182
182
  return { $cond: [{ $eq: [{ $type: ref }, 'string'] }, match, false] };
183
183
  }
184
- /** Atlas offers only a similarity threshold, on the index's own scale: converting a distance would mean guessing the metric. */
184
+ /** Atlas filters only before it ranks, by fields its index holds, never by a distance. */
185
185
  function nearRefusal() {
186
- return new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
187
- "Project the score with $sort's $project and filter on it instead.");
186
+ return new UqlUsageError('$near is not supported on MongoDB: Atlas cannot filter by distance. ' +
187
+ "Project the distance with $sort's $project and filter on it instead.");
188
+ }
189
+ /** `$text` runs only as a pipeline's first stage, which a relation's, inside its `$lookup`, never is. */
190
+ function assertNoRelationText(path, query) {
191
+ if (query.$where?.$text !== undefined || query.$sort?.$text !== undefined) {
192
+ throw new UqlUsageError(`cannot $text search relation '${path}' on MongoDB: $text runs only on the queried entity`);
193
+ }
188
194
  }
189
195
  /** MongoDB native operators - pass through as-is. */
190
196
  const NATIVE_OPS = new Set([
@@ -506,15 +512,15 @@ export class MongoDialect extends AbstractDialect {
506
512
  return isJsonObject(value) ? Object.entries(this.containment(value, path)) : [[path, this.held(value)]];
507
513
  }));
508
514
  }
509
- select(entity, select, exclude) {
515
+ select(entity, select) {
510
516
  const meta = getMeta(entity);
511
- if (!select && !exclude) {
517
+ if (!select) {
512
518
  return {};
513
519
  }
514
520
  if (isSelectList(select)) {
515
521
  throw rawRefusal('$select');
516
522
  }
517
- const fields = normalizeScalarFieldSelection(meta, select, exclude);
523
+ const fields = normalizeScalarFieldSelection(meta, select);
518
524
  // Projected by column, not by field key; `normalizeId` maps them back on the way out.
519
525
  const projection = fields.reduce((acc, key) => {
520
526
  // A computed field that writes SQL has nothing in the document to project: refused when `$select`
@@ -531,7 +537,7 @@ export class MongoDialect extends AbstractDialect {
531
537
  }, {});
532
538
  // MongoDB returns `_id` unless it is explicitly excluded, so a projection without the key sets `_id: 0`,
533
539
  // the one inclusion/exclusion mix MongoDB allows. This returns the same fields a SQL engine would, and is
534
- // what makes `$exclude: { id: true }` work at all.
540
+ // what makes `$select: { id: false }` work at all.
535
541
  if (!fields.includes(soleIdOf(meta, 'MongoDB'))) {
536
542
  projection[ID_KEY] = 0;
537
543
  }
@@ -549,11 +555,11 @@ export class MongoDialect extends AbstractDialect {
549
555
  /**
550
556
  * The ordering, and the paths whose nulls it places. MongoDB sorts null and missing lowest and takes
551
557
  * no placement, so one is emulated: {@link nullsSortStages} flags each path and the flag is ordered
552
- * by ahead of the value itself.
558
+ * by ahead of the value itself. `ranked` is a field holding a vector distance, ordered by first.
553
559
  */
554
- sortPlan(entity, { $sort: sort, $populate: populate, $where: where }) {
560
+ sortPlan(entity, { $sort: sort, $populate: populate, $where: where }, ranked) {
555
561
  const meta = getMeta(entity);
556
- const nearest = {};
562
+ const nearest = ranked ? { [ranked]: 1 } : {};
557
563
  const columns = {};
558
564
  const placed = [];
559
565
  // Refused as the SQL dialects refuse it, before MongoDB answers a missing score with its own error.
@@ -642,14 +648,10 @@ export class MongoDialect extends AbstractDialect {
642
648
  const lookups = specs.map((spec, index) => this.aggregateStages(meta, spec, relTempField('sort', fields[index]), fields[index]));
643
649
  return { ...mergeLookups(lookups), fields };
644
650
  }
645
- /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
646
- readsAggregates(entity, q) {
647
- return this.aggregateKeys(entity, q).length > 0;
648
- }
649
651
  /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
650
652
  aggregateKeys(entity, q) {
651
653
  const meta = getMeta(entity);
652
- const projected = normalizeScalarFieldSelection(meta, isSelectList(q.$select) ? undefined : q.$select, q.$exclude);
654
+ const projected = normalizeScalarFieldSelection(meta, isSelectList(q.$select) ? undefined : q.$select);
653
655
  return [...projected, ...Object.keys(q.$sort ?? {})].filter((key) => aggregateOf(meta.fields[key]));
654
656
  }
655
657
  /**
@@ -740,6 +742,7 @@ export class MongoDialect extends AbstractDialect {
740
742
  const relOpts = relationOf(meta, relKey);
741
743
  const relEntity = relOpts.entity();
742
744
  const relMeta = getMeta(relEntity);
745
+ assertNoRelationText(relKey, query);
743
746
  const read = this.aggregationPipeline(relEntity, query);
744
747
  const pipeline = read.length ? { pipeline: read } : {};
745
748
  const from = this.resolveTableName(relMeta);
@@ -806,18 +809,86 @@ export class MongoDialect extends AbstractDialect {
806
809
  }
807
810
  return `${this.columnOf(meta, key.slice(0, dot))}.${jsonPathKeys(key.slice(dot + 1)).join('.')}`;
808
811
  }
812
+ /**
813
+ * How a read runs, its ordering and aggregates read once for both the routing and the run: the one place
814
+ * deciding how a read is scored and ranked, a root vector search through Atlas.
815
+ */
816
+ readPlan(entity, q, opts) {
817
+ const vector = this.extractVectorSort(q.$sort);
818
+ if (vector) {
819
+ return { pipeline: this.vectorSearchPipeline(entity, q, vector, opts) };
820
+ }
821
+ const sort = this.sortPlan(entity, q);
822
+ const aggregates = this.aggregateKeys(entity, q);
823
+ return this.readsThroughPipeline(entity, q, sort, aggregates)
824
+ ? { pipeline: this.scanPipeline(entity, q, opts, sort, aggregates, []) }
825
+ : { sort: sort.sort };
826
+ }
827
+ /**
828
+ * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
829
+ * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
830
+ */
831
+ readsThroughPipeline(entity, q, sort, aggregates) {
832
+ return (!!q.$distinct ||
833
+ hasKeys(q.$count) ||
834
+ populatesRelations(getMeta(entity), q.$populate) ||
835
+ this.constrainsRelations(entity, q.$where) ||
836
+ this.sortsRelations(entity, q.$sort) ||
837
+ aggregates.length > 0 ||
838
+ // A placement is a field the pipeline adds and orders by; a `find` cursor can add none.
839
+ hasKeys(sort.fields) ||
840
+ textSortOf(q.$sort) !== undefined);
841
+ }
842
+ /**
843
+ * Build an aggregation pipeline for vector similarity search.
844
+ * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
845
+ */
846
+ vectorSearchPipeline(entity, q, vectorSort, opts) {
847
+ // Atlas ranks the rows already, so the exact distance is computed only where something reads it: its
848
+ // `$project`, or the other keys, which only break its ties.
849
+ const tied = hasKeys(vectorSort.regularSort);
850
+ const nearest = (vectorSort.vectorSearch.$project !== undefined || tied) && this.nearestScore(entity, vectorSort);
851
+ return [
852
+ this.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
853
+ // `$vectorSearch` has already applied `$limit`, so the pager is its own.
854
+ ...this.readStages(entity, q, {
855
+ sort: this.sortPlan(entity, { ...q, $sort: vectorSort.regularSort }, nearest && tied ? nearest.field : undefined),
856
+ scores: nearest ? [nearest] : [],
857
+ }),
858
+ ];
859
+ }
860
+ /** A read as a pipeline, whether or not a `find` cursor would express it. */
809
861
  aggregationPipeline(entity, q, opts) {
862
+ // A vector search here is one no `$vectorSearch` lifted, a relation's inside its lookup, which Atlas cannot reach.
863
+ const vector = this.extractVectorSort(q.$sort);
864
+ const nearest = vector && this.nearestScore(entity, vector);
865
+ const sort = this.sortPlan(entity, vector ? { ...q, $sort: vector.regularSort } : q, nearest?.field);
866
+ return this.scanPipeline(entity, q, opts, sort, this.aggregateKeys(entity, q), nearest ? [nearest] : []);
867
+ }
868
+ /** The pipeline of a read no `$vectorSearch` enters, given its ordering, aggregates and vector score. */
869
+ scanPipeline(entity, q, opts, sort, aggregates, nearest) {
810
870
  // Sorted as a field, which goes either way where a `$meta` sort only descends.
811
871
  const text = textSortOf(q.$sort);
872
+ const scores = [
873
+ ...nearest,
874
+ ...(text
875
+ ? [{ field: text.project ?? TEXT_SCORE_ALIAS, value: { $meta: 'textScore' }, temporary: !text.project }]
876
+ : []),
877
+ ];
812
878
  return [
813
- ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
814
- ...this.readStages(entity, q, {
815
- sort: this.sortPlan(entity, q),
816
- pager: this.pagerStages(q),
817
- score: text && { field: text.project ?? TEXT_SCORE_ALIAS, meta: 'textScore', temporary: !text.project },
818
- }),
879
+ ...this.matchStages(entity, q.$where, opts, aggregates),
880
+ ...this.readStages(entity, q, { sort, pager: this.pagerStages(q), scores }),
819
881
  ];
820
882
  }
883
+ /** A vector search's exact distance, by its metric, as a score to rank by: its `$project`, else a temporary field. */
884
+ nearestScore(entity, vector) {
885
+ const { vectorKey, vectorSearch } = vector;
886
+ const meta = getMeta(entity);
887
+ const metric = vectorDistanceOf(meta, vectorKey, vectorSearch);
888
+ const value = vectorDistanceExpr(this.columnOf(meta, vectorKey), vectorSearch.$vector, metric);
889
+ const field = vectorSearch.$project ?? NEAREST_DISTANCE_ALIAS;
890
+ return { field, value, temporary: vectorSearch.$project === undefined };
891
+ }
821
892
  /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
822
893
  pagerStages(q) {
823
894
  return [
@@ -845,14 +916,20 @@ export class MongoDialect extends AbstractDialect {
845
916
  // The score becomes a real field before anything reads it, so the lookups, the sort and the projection
846
917
  // that follow treat it like any other; merged into the query's own projection rather than standing in
847
918
  // for one, since a query that asked for no columns wants the whole document as well.
848
- const { score } = extra;
849
- if (score && !score.temporary) {
850
- this.assertProjectable(meta, score.field);
919
+ const { scores } = extra;
920
+ for (const score of scores) {
921
+ if (!score.temporary) {
922
+ this.assertProjectable(meta, score.field);
923
+ }
851
924
  }
852
- const scored = score ? [{ $addFields: { [score.field]: { $meta: score.meta } } }] : [];
853
- const unscored = score?.temporary ? [{ $unset: [score.field] }] : [];
925
+ const scored = scores.length
926
+ ? [{ $addFields: Object.fromEntries(scores.map((score) => [score.field, score.value])) }]
927
+ : [];
928
+ const unscored = unsetOf(scores.filter((score) => score.temporary).map((score) => score.field));
854
929
  const projection = this.pipelineProjection(entity, q);
855
- const projected = projection && score ? { ...projection, [score.field]: 1 } : projection;
930
+ const projected = projection && scores.length
931
+ ? { ...projection, ...Object.fromEntries(scores.map((score) => [score.field, 1])) }
932
+ : projection;
856
933
  const project = projected ? [{ $project: projected }] : [];
857
934
  // A `$lookup` the ordering asked for puts a field on the document the caller never requested,
858
935
  // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
@@ -871,6 +948,9 @@ export class MongoDialect extends AbstractDialect {
871
948
  if (q.$distinct && aggregated.fields.length) {
872
949
  throw new UqlUsageError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
873
950
  }
951
+ if (q.$distinct && scores.some((score) => score.temporary)) {
952
+ throw new UqlUsageError('cannot $sort by a vector distance or text score with $distinct unless it is projected: the grouping keeps only the columns it projects');
953
+ }
874
954
  if (q.$distinct && sortOnly.length) {
875
955
  throw new UqlUsageError(`cannot $sort by relation '${sortOnly[0].path}' with $distinct unless '${sortOnly[0].path}' is populated: the grouping keeps only the columns it projects`);
876
956
  }
@@ -917,10 +997,10 @@ export class MongoDialect extends AbstractDialect {
917
997
  * relation and the tallies); last, once the lookups have read the join keys.
918
998
  */
919
999
  pipelineProjection(entity, q) {
920
- if (!q.$select && !q.$exclude) {
1000
+ if (!q.$select) {
921
1001
  return undefined;
922
1002
  }
923
- const projection = this.select(entity, q.$select, q.$exclude);
1003
+ const projection = this.select(entity, q.$select);
924
1004
  const meta = getMeta(entity);
925
1005
  for (const relKey of getRelationRequestSummary(meta, q.$populate).requestedKeys) {
926
1006
  projection[relationField(relKey)] = 1;
@@ -945,6 +1025,7 @@ export class MongoDialect extends AbstractDialect {
945
1025
  // Unconditional, not gated by an explicit relation-level `$where`: the related entity's own
946
1026
  // filters (in particular `security: true` ones) apply even to a bare `$populate: { rel: true }`,
947
1027
  // and the caller's bypass never reaches them, exactly like the SQL dialects' JOIN ON-clause filters.
1028
+ assertNoRelationText(join.path, join.query);
948
1029
  const relationFilter = this.where(join.entity, join.query.$where ?? {});
949
1030
  // The relation's own projection runs inside the lookup, where its keys resolve against the
950
1031
  // related entity. Left out, `$populate: { rel: { $select } }` returned all of `rel`'s columns.
@@ -1438,7 +1519,12 @@ export class MongoDialect extends AbstractDialect {
1438
1519
  throw new UqlUsageError(`Field '${key}' not found in entity '${meta.name}'`);
1439
1520
  }
1440
1521
  const colName = this.resolveColumnName(key, field);
1441
- const indexName = this.vectorSearchIndexName(findVectorIndex(meta, key)?.name, colName);
1522
+ const index = findVectorIndex(meta, key);
1523
+ const ranked = indexedDistance(meta, key, index);
1524
+ if (search.$distance !== undefined && search.$distance !== ranked) {
1525
+ throw new UqlUsageError(`cannot rank '${meta.entity.name}.${key}' by '${search.$distance}' on MongoDB: its Atlas index ranks by '${ranked}'`);
1526
+ }
1527
+ const indexName = this.vectorSearchIndexName(index?.name, colName);
1442
1528
  if (!limit) {
1443
1529
  throw new UqlUsageError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
1444
1530
  }
@@ -1,5 +1,5 @@
1
1
  import { SchemaAST } from '../schema/schemaAST.js';
2
- import type { QuerierPool, SchemaIntrospector, TableSchema } from '../type/index.js';
2
+ import type { IndexEntry, QuerierPool, SchemaIntrospector, TableSchema } from '../type/index.js';
3
3
  /**
4
4
  * MongoDB schema introspector.
5
5
  * MongoDB doesn't have a fixed schema, so this primarily focuses on collections and indexes.
@@ -14,3 +14,5 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
14
14
  tableExists(tableName: string): Promise<boolean>;
15
15
  private withDb;
16
16
  }
17
+ /** A key as the entity declares it: the field, then the path inside it, so the two compare and name alike. */
18
+ export declare function documentEntry(key: string): IndexEntry<string>;
@@ -1,4 +1,5 @@
1
1
  import { createTableNode, SchemaAST } from '../schema/schemaAST.js';
2
+ import { entryColumns } from '../util/indexEntry.util.js';
2
3
  import { validatorCheck } from './mongoCommand.js';
3
4
  import { withMongoQuerierForMigrations } from './mongoQuerier.js';
4
5
  import { textConfigOf } from './textLanguage.js';
@@ -51,13 +52,13 @@ export class MongoSchemaIntrospector {
51
52
  type: 'fulltext',
52
53
  config: default_language && textConfigOf(default_language),
53
54
  }
54
- : { entries: Object.keys(key).map((column) => ({ column })) }),
55
+ : { entries: Object.keys(key).map(documentEntry) }),
55
56
  })),
56
57
  ...searchIndexes
57
58
  .filter((idx) => idx.type === 'vectorSearch')
58
59
  .map((idx) => ({
59
60
  name: idx.name,
60
- entries: idx.latestDefinition.fields.map(({ path }) => ({ column: path })),
61
+ entries: idx.latestDefinition.fields.map(({ path }) => documentEntry(path)),
61
62
  unique: false,
62
63
  type: 'vectorSearch',
63
64
  })),
@@ -81,8 +82,13 @@ export class MongoSchemaIntrospector {
81
82
  }
82
83
  }
83
84
  /** A text index field as an entity declares it: its weight stated only where it is not the default 1. */
84
- function textIndexEntry([column, weight]) {
85
- return weight === 1 ? { column } : { column, weight };
85
+ function textIndexEntry([key, weight]) {
86
+ return weight === 1 ? documentEntry(key) : { ...documentEntry(key), weight };
87
+ }
88
+ /** A key as the entity declares it: the field, then the path inside it, so the two compare and name alike. */
89
+ export function documentEntry(key) {
90
+ const dot = key.indexOf('.');
91
+ return dot < 0 ? { column: key } : { json: key.slice(0, dot), path: key.slice(dot + 1) };
86
92
  }
87
93
  /** A collection's Atlas search indexes, none where the server has no Atlas Search. */
88
94
  async function listSearchIndexes(collection) {
@@ -110,7 +116,7 @@ function buildTable({ name, indexes = [], checks = [] }) {
110
116
  const table = createTableNode(name, undefined, INDEX_FACETS);
111
117
  table.checks.push(...checks);
112
118
  for (const index of indexes) {
113
- for (const { column } of index.entries) {
119
+ for (const column of entryColumns(index.entries)) {
114
120
  if (!table.columns.has(column)) {
115
121
  table.columns.set(column, {
116
122
  name: column,
@@ -1,5 +1,6 @@
1
1
  import { getMeta } from '../entity/index.js';
2
- import { assertIndexFeatures, assertIndexType } from '../migrate/ddl/indexDdl.js';
2
+ import { INDEX_CAPABILITIES } from '../migrate/ddl/indexCapabilities.js';
3
+ import { assertExpressible } from '../migrate/ddl/indexDdl.js';
3
4
  import { renderIndexDefinition } from '../migrate/generator/definitionToNode.js';
4
5
  import { indexNodeToSchema } from '../migrate/generator/indexNodeToSchema.js';
5
6
  import { assertIndexPredicate, refusedIndexPredicate } from '../migrate/indexPredicate.js';
@@ -7,17 +8,15 @@ import { sides } from '../migrate/schemaChange.js';
7
8
  import { indexChanges } from '../schema/indexDifferences.js';
8
9
  import { QuerySql, } from '../type/index.js';
9
10
  import { indexDistance, unsupportedVectorMetric } from '../type/vector.js';
10
- import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
11
- import { fulltextConfig, fulltextWeights } from '../util/dialect.util.js';
11
+ import { declaredIndexes, namedIndex } from '../util/ddlExpression.util.js';
12
+ import { findVectorIndex, fulltextConfig, fulltextWeights, indexedDistance } from '../util/dialect.util.js';
13
+ import { entryKeys, entryModifiers, renamedEntry } from '../util/indexEntry.util.js';
12
14
  import { definedEntries, hasKeys } from '../util/object.util.js';
13
15
  import { UqlUsageError } from '../util/uqlError.js';
14
16
  import { serializeMongoCommand, validatorCheck } from './mongoCommand.js';
15
17
  import { MongoDialect } from './mongoDialect.js';
18
+ import { documentEntry } from './mongoIntrospector.js';
16
19
  import { textLanguage } from './textLanguage.js';
17
- /** The index types a key spec can say, a plain key or `'text'`, and Atlas's vector search index. */
18
- const MONGO_INDEX_TYPES = new Set(['btree', 'fulltext', 'vectorSearch']);
19
- /** A key spec's one feature beyond its keys: a partial filter. */
20
- const MONGO_INDEX_FEATURES = new Set(['partial']);
21
20
  /** Atlas's name for each metric a vector search index scores by. */
22
21
  const ATLAS_SIMILARITY = {
23
22
  cosine: 'cosine',
@@ -58,22 +57,26 @@ export class MongoSchemaGenerator extends MongoDialect {
58
57
  * `where` to a filter document, and every other option spread through, so a new one cannot be lost.
59
58
  */
60
59
  indexesOf(meta, collectionName) {
61
- return declaredIndexes(meta).map(({ columns, where, ...options }) => {
62
- const entries = columns
63
- .map((entry) => renderIndexColumn(entry, refuseSql))
64
- .map((entry) => ({ ...entry, column: this.columnOf(meta, entry.column) }));
65
- const [first] = columns;
66
- const vector = options.type === 'vectorSearch' && typeof first?.column === 'string' ? meta.fields[first.column] : undefined;
67
- const predicate = where && this.indexFilter(where, meta.entity, declaredIndexName(options.name, collectionName, entries));
60
+ return declaredIndexes(meta).map(({ entries: declared, where, ...options }) => {
61
+ // As the collection reports each back, its document path read the way the introspector reads one; a key
62
+ // spec takes no length.
63
+ const entries = declared.map((entry) => {
64
+ const renamed = renamedEntry(entry, (column) => this.columnOf(meta, column));
65
+ return { ...entryModifiers(renamed), ...documentEntry(documentPath(renamed)) };
66
+ });
67
+ const [first] = declared;
68
+ const vectorKey = options.type === 'vectorSearch' && typeof first?.column === 'string' ? first.column : undefined;
69
+ const vector = vectorKey === undefined ? undefined : meta.fields[vectorKey];
70
+ const named = namedIndex(options.name, collectionName, entries, (label) => where && this.indexFilter(where, meta.entity, label));
68
71
  return {
69
72
  ...options,
70
- name: vector
71
- ? this.vectorSearchIndexName(options.name, entries[0].column)
72
- : declaredIndexName(options.name, collectionName, entries, { where: predicate }),
73
+ ...named,
74
+ name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : named.name,
73
75
  entries,
74
76
  unique: options.unique ?? false,
75
- where: predicate,
76
- distance: options.distance ?? vector?.distance,
77
+ distance: vectorKey === undefined
78
+ ? options.distance
79
+ : indexedDistance(meta, vectorKey, findVectorIndex(meta, vectorKey)),
77
80
  dimensions: vector?.dimensions,
78
81
  };
79
82
  });
@@ -139,14 +142,13 @@ export class MongoSchemaGenerator extends MongoDialect {
139
142
  }
140
143
  /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
141
144
  generateCreateIndex(tableName, index) {
142
- assertIndexType(index, MONGO_INDEX_TYPES, this.engineName);
145
+ assertExpressible(index, INDEX_CAPABILITIES[this.dialectName], this.engineName);
143
146
  if (index.type === 'vectorSearch') {
144
147
  return this.generateCreateSearchIndex(tableName, index);
145
148
  }
146
- assertIndexFeatures(index, MONGO_INDEX_FEATURES, this.engineName);
147
149
  const key = {};
148
150
  for (const entry of index.entries) {
149
- key[entry.column] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;
151
+ key[documentPath(entry)] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;
150
152
  }
151
153
  const weights = fulltextWeights(index);
152
154
  return serializeMongoCommand({
@@ -158,14 +160,13 @@ export class MongoSchemaGenerator extends MongoDialect {
158
160
  unique: index.unique,
159
161
  name: index.name,
160
162
  partialFilterExpression: index.where && JSON.parse(index.where),
161
- weights: weights && Object.fromEntries(index.entries.map((entry, at) => [entry.column, weights[at]])),
163
+ weights: weights && Object.fromEntries(index.entries.map((entry, at) => [documentPath(entry), weights[at]])),
162
164
  default_language: index.type === 'fulltext' ? textLanguage(fulltextConfig(index)) : undefined,
163
165
  },
164
166
  });
165
167
  }
166
168
  /** An Atlas vector search index: its vector field first, then each field a `$vectorSearch` pre-filters on. */
167
169
  generateCreateSearchIndex(tableName, index) {
168
- assertIndexFeatures(index, new Set(), this.engineName);
169
170
  const [vector, ...filters] = index.entries;
170
171
  if (!vector || index.dimensions === undefined) {
171
172
  throw new UqlUsageError(`an Atlas vector search index states its field's dimensions (index "${index.name}")`);
@@ -183,8 +184,8 @@ export class MongoSchemaGenerator extends MongoDialect {
183
184
  type: 'vectorSearch',
184
185
  definition: {
185
186
  fields: [
186
- { type: 'vector', path: vector.column, numDimensions: index.dimensions, similarity },
187
- ...filters.map((entry) => ({ type: 'filter', path: entry.column })),
187
+ { type: 'vector', path: documentPath(vector), numDimensions: index.dimensions, similarity },
188
+ ...filters.map((entry) => ({ type: 'filter', path: documentPath(entry) })),
188
189
  ],
189
190
  },
190
191
  },
@@ -223,11 +224,18 @@ export class MongoSchemaGenerator extends MongoDialect {
223
224
  const desired = declared && validatorCheck(collectionName, declared);
224
225
  const [current] = currentTable.checks;
225
226
  const checks = desired?.name === current?.name ? [] : [{ from: current, to: desired }];
226
- const { changes } = indexChanges(collectionName, this.indexesOf(meta, collectionName), currentTable.indexes, currentTable.indexFacets);
227
+ const { changes } = indexChanges(this.indexesOf(meta, collectionName), currentTable);
227
228
  const indexes = changes.map(({ from, to }) => ({ from: from && indexNodeToSchema(from), to }));
228
229
  return indexes.length || checks.length ? { tableName: collectionName, type: 'alter', checks, indexes } : undefined;
229
230
  }
230
231
  }
232
+ /**
233
+ * The document path an index entry keys: its field, then the path inside it, which is how a `$where` on
234
+ * `'settings.theme'` reads it too. An expression entry is refused before any key is built.
235
+ */
236
+ function documentPath(entry) {
237
+ return entryKeys(entry)?.join('.') ?? refuseSql();
238
+ }
231
239
  /** A collection has no SQL to render a check, a computed column or an index expression into. */
232
240
  function refuseSql() {
233
241
  throw new UqlUsageError('MongoDB has no SQL to render a check, a computed column or an index expression into');
@@ -22,19 +22,9 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
22
22
  * for a read and a stream alike, so both load the same relations.
23
23
  */
24
24
  private readCursor;
25
- /**
26
- * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
27
- * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
28
- */
29
- private readsThroughPipeline;
30
25
  private buildScalarProjection;
31
- /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */
26
+ /** Build a MongoDB FindCursor with filter, projection, skip, and limit from the query, ordered by `sort`. */
32
27
  private buildFindCursor;
33
- /**
34
- * Build an aggregation pipeline for vector similarity search.
35
- * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
36
- */
37
- private buildVectorPipeline;
38
28
  protected internalAggregate<E extends Document>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
39
29
  /**
40
30
  * A `$required` relation drops parents that have no match, and `$distinct` collapses them, so both