uql-orm 0.104.1 → 0.105.1

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 (161) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/querier/httpQuerier.d.ts +3 -3
  3. package/dist/browser/type/clientQuerier.d.ts +1 -1
  4. package/dist/browser/uql-browser.min.js +2 -2
  5. package/dist/browser/uql-browser.min.js.map +9 -9
  6. package/dist/cockroachdb/cockroachDialect.d.ts +2 -2
  7. package/dist/dialect/abstractDialect.d.ts +3 -3
  8. package/dist/dialect/abstractSqlDialect.d.ts +39 -37
  9. package/dist/dialect/abstractSqlDialect.js +35 -32
  10. package/dist/dialect/aliases.d.ts +2 -0
  11. package/dist/dialect/aliases.js +2 -0
  12. package/dist/dialect/jsonSql.js +2 -2
  13. package/dist/dialect/mergeSqlDialect.d.ts +2 -2
  14. package/dist/dialect/mysqlLikeSqlDialect.d.ts +7 -7
  15. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  16. package/dist/dialect/operators.js +2 -4
  17. package/dist/dialect/queryJoins.d.ts +4 -2
  18. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  19. package/dist/dialect/vectorSqlDialect.js +1 -1
  20. package/dist/entity/column.d.ts +3 -0
  21. package/dist/entity/column.js +3 -0
  22. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  23. package/dist/entity/columnOptionsBuilder.js +108 -0
  24. package/dist/entity/decorator/bag.d.ts +5 -5
  25. package/dist/entity/decorator/entity.d.ts +3 -20
  26. package/dist/entity/decorator/entity.js +3 -37
  27. package/dist/entity/decorator/members.d.ts +46 -76
  28. package/dist/entity/decorator/members.js +18 -7
  29. package/dist/entity/index.d.ts +2 -1
  30. package/dist/entity/index.js +2 -1
  31. package/dist/entity/metadata/definition.d.ts +15 -26
  32. package/dist/entity/metadata/definition.js +344 -148
  33. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  34. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  35. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  36. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  37. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  38. package/dist/entity/metadata/schemaFixture/book.js +23 -0
  39. package/dist/http/contract.d.ts +2 -2
  40. package/dist/http/handler.d.ts +2 -2
  41. package/dist/http/query.js +12 -13
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -1
  44. package/dist/mariadb/mariaDialect.d.ts +2 -2
  45. package/dist/mariadb/mariaDialect.js +1 -1
  46. package/dist/mariadb/mariadbQuerier.js +1 -3
  47. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  48. package/dist/migrate/builder/columnBuilder.js +104 -110
  49. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  50. package/dist/migrate/builder/migrationBuilder.js +7 -6
  51. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  52. package/dist/migrate/builder/tableBuilder.js +88 -204
  53. package/dist/migrate/builder/types.d.ts +52 -151
  54. package/dist/migrate/builder/types.js +0 -6
  55. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  56. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  57. package/dist/migrate/codegen/entityTypes.d.ts +2 -2
  58. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  59. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  60. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  61. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  62. package/dist/migrate/ddl/defaultSql.js +7 -6
  63. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  64. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  65. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  66. package/dist/migrate/ddl/indexDdl.js +33 -30
  67. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  68. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  69. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  70. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  71. package/dist/migrate/drift/driftDetector.js +2 -2
  72. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  73. package/dist/migrate/generator/definitionToNode.js +4 -5
  74. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  75. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  76. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  77. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  78. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  79. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  80. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  81. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  82. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  83. package/dist/migrate/migrator.d.ts +2 -2
  84. package/dist/migrate/schemaChange.d.ts +3 -3
  85. package/dist/migrate/schemaChange.js +3 -2
  86. package/dist/migrate/schemaGenerator.d.ts +5 -5
  87. package/dist/migrate/schemaGenerator.js +1 -1
  88. package/dist/migrate/storage/databaseStorage.js +4 -4
  89. package/dist/mongodb/mongoDialect.d.ts +41 -44
  90. package/dist/mongodb/mongoDialect.js +118 -32
  91. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  92. package/dist/mongodb/mongoIntrospector.js +11 -5
  93. package/dist/mongodb/mongoSchemaGenerator.d.ts +4 -4
  94. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  95. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  96. package/dist/mongodb/mongodbQuerier.js +9 -43
  97. package/dist/mssql/mssqlDialect.d.ts +4 -4
  98. package/dist/postgres/postgresDialect.d.ts +2 -2
  99. package/dist/querier/abstractQuerier.d.ts +0 -1
  100. package/dist/querier/abstractQuerier.js +1 -20
  101. package/dist/querier/abstractSqlQuerier.d.ts +1 -1
  102. package/dist/querier/keyset.js +3 -3
  103. package/dist/schema/declaredColumn.d.ts +11 -0
  104. package/dist/schema/declaredColumn.js +21 -0
  105. package/dist/schema/indexColumns.d.ts +0 -3
  106. package/dist/schema/indexColumns.js +11 -7
  107. package/dist/schema/indexDifferences.d.ts +10 -5
  108. package/dist/schema/indexDifferences.js +42 -28
  109. package/dist/schema/schemaASTBuilder.d.ts +4 -4
  110. package/dist/schema/schemaASTBuilder.js +28 -36
  111. package/dist/schema/schemaASTDiffer.js +8 -4
  112. package/dist/schema/sqlExpression.d.ts +21 -17
  113. package/dist/schema/sqlExpression.js +11 -23
  114. package/dist/type/column.d.ts +328 -0
  115. package/dist/type/column.js +2 -0
  116. package/dist/type/config.d.ts +3 -3
  117. package/dist/type/dialect.d.ts +15 -14
  118. package/dist/type/dialect.js +1 -0
  119. package/dist/type/entity.d.ts +292 -281
  120. package/dist/type/entity.js +6 -1
  121. package/dist/type/index.d.ts +2 -0
  122. package/dist/type/index.js +2 -0
  123. package/dist/type/migration.d.ts +11 -11
  124. package/dist/type/querier.d.ts +2 -2
  125. package/dist/type/query.d.ts +44 -40
  126. package/dist/type/query.js +2 -3
  127. package/dist/type/queryAggregate.d.ts +22 -12
  128. package/dist/type/querySql.d.ts +22 -6
  129. package/dist/type/querySql.js +27 -9
  130. package/dist/type/schemaEntity.d.ts +194 -0
  131. package/dist/type/schemaEntity.js +1 -0
  132. package/dist/type/utility.d.ts +4 -7
  133. package/dist/type/vector.d.ts +1 -1
  134. package/dist/util/ddlExpression.util.d.ts +12 -13
  135. package/dist/util/ddlExpression.util.js +12 -21
  136. package/dist/util/dialect.util.d.ts +11 -5
  137. package/dist/util/dialect.util.js +31 -37
  138. package/dist/util/field.util.d.ts +10 -9
  139. package/dist/util/field.util.js +14 -10
  140. package/dist/util/fieldOption.util.d.ts +11 -95
  141. package/dist/util/fieldOption.util.js +49 -16
  142. package/dist/util/hook.util.d.ts +3 -15
  143. package/dist/util/hook.util.js +3 -16
  144. package/dist/util/index.d.ts +1 -0
  145. package/dist/util/index.js +1 -0
  146. package/dist/util/indexEntry.util.d.ts +45 -0
  147. package/dist/util/indexEntry.util.js +138 -0
  148. package/dist/util/relationQuery.util.d.ts +0 -1
  149. package/dist/util/relationQuery.util.js +0 -5
  150. package/dist/util/sql.d.ts +13 -10
  151. package/dist/util/sql.js +34 -16
  152. package/dist/util/sql.util.d.ts +4 -5
  153. package/dist/util/sql.util.js +7 -16
  154. package/dist/util/string.util.d.ts +2 -0
  155. package/dist/util/string.util.js +4 -0
  156. package/dist/util/triggerWrite.d.ts +5 -5
  157. package/dist/util/uqlError.d.ts +1 -1
  158. package/dist/util/uqlError.js +1 -1
  159. package/package.json +1 -1
  160. package/skills/uql-orm/SKILL.md +76 -25
  161. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -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,6 +1,6 @@
1
1
  import type { AnyMigrationOperation } from '../migrate/builder/types.js';
2
2
  import type { TableNode } from '../schema/types.js';
3
- import { type CreateSchemaOptions, type IndexSchema, type NamingStrategy, type SchemaDiff, type SchemaGenerator, type Type } from '../type/index.js';
3
+ import { type CreateSchemaOptions, type IndexSchema, type NamingStrategy, type SchemaDiff, type SchemaGenerator, type AbstractType } from '../type/index.js';
4
4
  import { MongoDialect } from './mongoDialect.js';
5
5
  export declare class MongoSchemaGenerator extends MongoDialect implements SchemaGenerator {
6
6
  /** Takes no default foreign key action, since a document store has no foreign keys. */
@@ -9,8 +9,8 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
9
9
  * A document store has no cross-collection constraint, so unlike the SQL generator there is nothing to
10
10
  * defer and no order to respect: this is each collection and nothing more.
11
11
  */
12
- generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
13
- generateDropSchema(entities: readonly Type<object>[]): string[];
12
+ generateCreateSchema(entities: readonly AbstractType<object>[], options?: CreateSchemaOptions): string[];
13
+ generateDropSchema(entities: readonly AbstractType<object>[]): string[];
14
14
  /** A collection, and one `createIndex` command for each of its indexes, as SQL's `[CREATE TABLE, ...CREATE INDEX]`. */
15
15
  private createCollection;
16
16
  /**
@@ -41,5 +41,5 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
41
41
  private generateCreateSearchIndex;
42
42
  /** A collection and its indexes, which is all a document store has: a column, a constraint or SQL throws. */
43
43
  generateOperation(operation: AnyMigrationOperation): string[];
44
- diffSchema(entity: Type<object>, currentTable: TableNode | undefined): SchemaDiff | undefined;
44
+ diffSchema(entity: AbstractType<object>, currentTable: TableNode | undefined): SchemaDiff | undefined;
45
45
  }
@@ -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
@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
3
  import { getMeta, soleIdOf } from '../entity/index.js';
4
4
  import { AbstractQuerier } from '../querier/index.js';
5
- import { clone, getKeys, deletionOf, hasKeys, hasTriggers, populatesRelations, textSortOf, vectorCandidates, whereEach, upsertKeepsOwnKey, } from '../util/index.js';
5
+ import { clone, getKeys, deletionOf, hasKeys, hasTriggers, whereEach, upsertKeepsOwnKey } from '../util/index.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  /**
8
8
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
@@ -65,34 +65,16 @@ export class MongodbQuerier extends AbstractQuerier {
65
65
  * for a read and a stream alike, so both load the same relations.
66
66
  */
67
67
  readCursor(entity, q, opts, session) {
68
- const vectorSort = this.dialect.extractVectorSort(q.$sort);
69
- const pipeline = vectorSort
70
- ? this.buildVectorPipeline(entity, q, vectorSort, opts)
71
- : this.readsThroughPipeline(entity, q) && this.dialect.aggregationPipeline(entity, q, opts);
72
- return pipeline
73
- ? this.collection(entity).aggregate(pipeline, { session })
74
- : this.buildFindCursor(entity, q, opts, session);
75
- }
76
- /**
77
- * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
78
- * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
79
- */
80
- readsThroughPipeline(entity, q) {
81
- return (!!q.$distinct ||
82
- hasKeys(q.$count) ||
83
- populatesRelations(getMeta(entity), q.$populate) ||
84
- this.dialect.constrainsRelations(entity, q.$where) ||
85
- this.dialect.sortsRelations(entity, q.$sort) ||
86
- this.dialect.readsAggregates(entity, q) ||
87
- // A placement is a field the pipeline adds and orders by; a `find` cursor can add none.
88
- hasKeys(this.dialect.sortPlan(entity, q).fields) ||
89
- textSortOf(q.$sort) !== undefined);
68
+ const read = this.dialect.readPlan(entity, q, opts);
69
+ return 'pipeline' in read
70
+ ? this.collection(entity).aggregate(read.pipeline, { session })
71
+ : this.buildFindCursor(entity, q, read.sort, opts, session);
90
72
  }
91
73
  buildScalarProjection(entity, q) {
92
- return this.dialect.select(entity, q.$select, q.$exclude);
74
+ return this.dialect.select(entity, q.$select);
93
75
  }
94
- /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */
95
- buildFindCursor(entity, q, opts, session) {
76
+ /** Build a MongoDB FindCursor with filter, projection, skip, and limit from the query, ordered by `sort`. */
77
+ buildFindCursor(entity, q, sort, opts, session) {
96
78
  const cursor = this.collection(entity).find({}, { session });
97
79
  const filter = this.dialect.where(entity, q.$where, opts);
98
80
  if (hasKeys(filter)) {
@@ -102,7 +84,6 @@ export class MongodbQuerier extends AbstractQuerier {
102
84
  if (hasKeys(select)) {
103
85
  cursor.project(select);
104
86
  }
105
- const sort = this.dialect.sort(entity, q);
106
87
  if (hasKeys(sort)) {
107
88
  cursor.sort(sort);
108
89
  }
@@ -115,21 +96,6 @@ export class MongodbQuerier extends AbstractQuerier {
115
96
  }
116
97
  return cursor;
117
98
  }
118
- /**
119
- * Build an aggregation pipeline for vector similarity search.
120
- * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
121
- */
122
- buildVectorPipeline(entity, q, vectorSort, opts) {
123
- const scoreAlias = vectorSort.vectorSearch.$project;
124
- return [
125
- this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
126
- // `$vectorSearch` has already applied `$limit`, so the pager is its own.
127
- ...this.dialect.readStages(entity, q, {
128
- sort: this.dialect.sortPlan(entity, { ...q, $sort: vectorSort.regularSort }),
129
- score: scoreAlias ? { field: scoreAlias, meta: 'vectorSearchScore' } : undefined,
130
- }),
131
- ];
132
- }
133
99
  async internalAggregate(entity, q, opts) {
134
100
  const pipeline = this.dialect.buildAggregateStages(entity, q, opts);
135
101
  const rows = await this.execute('internalAggregate', (session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
@@ -266,7 +232,7 @@ export class MongodbQuerier extends AbstractQuerier {
266
232
  const { deletedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).deleteMany(filter, { session }));
267
233
  return deletedCount;
268
234
  }
269
- // The mapped column, which reads filter on: a `@Field({ name })` mismatch would leave the row visible.
235
+ // The mapped column, which reads filter on: a `.name()` mismatch would leave the row visible.
270
236
  const column = this.dialect.resolveColumnName(stamp.key, stamp.field);
271
237
  const update = { $set: { [column]: stamp.value() } };
272
238
  const { matchedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).updateMany(filter, update, { session }));
@@ -1,7 +1,7 @@
1
1
  import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode, type JsonContainer, type JsonKeyWrite, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
4
- import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
4
+ import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, AbstractType, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
5
5
  /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
6
6
  export declare class MsSqlDialect extends MergeSqlDialect {
7
7
  #private;
@@ -48,7 +48,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
48
48
  pager(ctx: QueryContext, opts: QueryPager & {
49
49
  $distinct?: boolean;
50
50
  }, sorted?: boolean): void;
51
- insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
51
+ insert<E>(ctx: QueryContext, entity: AbstractType<E>, payload: E | E[], opts?: QueryOptions): void;
52
52
  /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
53
53
  private identityInsertTarget;
54
54
  /** An exact decimal, converted before it crosses the wire, where `tedious` would round it. */
@@ -76,7 +76,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
76
76
  * carrying a trigger, and through a table it works whether one is there or not.
77
77
  */
78
78
  returningId<E>(meta: EntityMeta<E>): string;
79
- upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
79
+ upsert<E>(ctx: QueryContext, entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
80
80
  /**
81
81
  * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
82
82
  * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
@@ -113,7 +113,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
113
113
  /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
114
114
  createSchemaSql(schema: string): string;
115
115
  /** The estimate the engine already keeps per partition, live without a stats refresh. */
116
- estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
116
+ estimatedCount<E>(ctx: QueryContext, entity: AbstractType<E>): void;
117
117
  /** Null-safe on every version, `EXCEPT` comparing NULLs as equal: `IS DISTINCT FROM` needs 2022. */
118
118
  neExpr(field: string, ph: string): string;
119
119
  protected numericCast(expr: string): string;