@atscript/db-mysql 0.1.141 → 0.1.143

package/dist/index.cjs

@@ -1353,13 +1353,21 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		for (const index of this._table.indexes.values()) if (index.type === "fulltext") indexes.push({
 			name: index.key,
 			description: `FULLTEXT index on ${index.fields.map((f) => f.name).join(", ")}`,
-			type: "text"
-		});
-		for (const [field, vec] of this._vectorFields) indexes.push({
-			name: vec.indexName,
-			description: `VECTOR(${vec.dimensions}) on ${field}, ${vec.similarity}`,
-			type: "vector"
+			type: "text",
+			fields: this._indexLogicalPaths(index),
+			isDefault: indexes.length === 0
 		});
+		let firstVector = true;
+		for (const [field, vec] of this._vectorFields) {
+			indexes.push({
+				name: vec.indexName,
+				description: `VECTOR(${vec.dimensions}) on ${field}, ${vec.similarity}`,
+				type: "vector",
+				fields: [field],
+				isDefault: firstVector
+			});
+			firstVector = false;
+		}
 		return indexes;
 	}
 	async search(text, query, indexName) {
@@ -1456,7 +1464,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				found = true;
 				break;
 			}
-			if (!found) throw new Error(`Vector index "${indexName}" not found`);
+			if (!found) throw new Error((0, _atscript_db.vectorIndexNotFoundMessage)(indexName));
 		} else {
 			const first = this._vectorFields.entries().next();
 			if (first.done) throw new Error("No vector fields defined");
@@ -1478,36 +1486,36 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			vectorStr: vectorToString(vector)
 		};
 	}
-	_buildVectorSearchQuery(vector, query, indexName) {
-		const ctx = this._prepareVectorSearch(vector, query, indexName);
-		const inner = `SELECT *, ${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?)) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${ctx.where.sql}`;
-		const params = [ctx.vectorStr, ...ctx.where.params];
-		let sql = `SELECT * FROM (${inner}) _v`;
-		if (ctx.threshold !== void 0) {
-			sql += ` WHERE _distance <= ?`;
-			params.push(2 * (1 - ctx.threshold));
-		}
-		sql += ` ORDER BY _distance ASC`;
-		if (ctx.controls.$skip) sql += ` LIMIT ${Number(ctx.controls.$limit) || 1e3} OFFSET ${Number(ctx.controls.$skip)}`;
-		else sql += ` LIMIT ${Number(ctx.controls.$limit) || 20}`;
+	/**
+	* The row source + distance cap of a vector search. The threshold is a
+	* normalized score matching MongoDB Atlas semantics: cosine score =
+	* (1 + cos_sim) / 2, VEC_DISTANCE_COSINE = 1 - cos_sim, so the distance cap
+	* is 2 * (1 - score).
+	*/
+	_vectorSearchSource(ctx, withRows) {
+		const distExpr = {
+			sql: `${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?))`,
+			params: [ctx.vectorStr]
+		};
 		return {
-			sql,
-			params
+			source: (0, _atscript_db_sql_tools.vectorDistanceSource)(mysqlDialect, ctx.tableName, ctx.where, distExpr, withRows),
+			maxDistance: ctx.threshold === void 0 ? void 0 : 2 * (1 - ctx.threshold)
 		};
 	}
-	_buildVectorSearchCountQuery(vector, query, indexName) {
+	_buildVectorSearchQuery(vector, query, indexName) {
 		const ctx = this._prepareVectorSearch(vector, query, indexName);
-		const inner = `SELECT ${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?)) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${ctx.where.sql}`;
-		const params = [ctx.vectorStr, ...ctx.where.params];
-		let sql = `SELECT COUNT(*) AS cnt FROM (${inner}) _v`;
-		if (ctx.threshold !== void 0) {
-			sql += ` WHERE _distance <= ?`;
-			params.push(2 * (1 - ctx.threshold));
-		}
-		return {
-			sql,
-			params
-		};
+		const { source, maxDistance } = this._vectorSearchSource(ctx, true);
+		const skip = Number(ctx.controls.$skip) || 0;
+		return (0, _atscript_db_sql_tools.buildVectorSearchSelect)(mysqlDialect, source, {
+			select: ctx.controls.$select,
+			limit: Number(ctx.controls.$limit) || (skip ? 1e3 : 20),
+			skip,
+			maxDistance
+		});
+	}
+	_buildVectorSearchCountQuery(vector, query, indexName) {
+		const { source, maxDistance } = this._vectorSearchSource(this._prepareVectorSearch(vector, query, indexName), false);
+		return (0, _atscript_db_sql_tools.buildVectorSearchCount)(mysqlDialect, source, { maxDistance });
 	}
 	/** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */
 	_resolveVectorThreshold(controls, indexName) {
@@ -1549,10 +1557,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		};
 	}
 	_buildGeoSearchSelect(ctx) {
-		return (0, _atscript_db_sql_tools.buildGeoSearchSelect)(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, {
-			$limit: ctx.controls.$limit,
-			$skip: ctx.controls.$skip
-		});
+		return (0, _atscript_db_sql_tools.buildGeoSearchSelect)(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, ctx.controls);
 	}
 	/**
 	* Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a

package/dist/index.d.cts

@@ -255,6 +255,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   }>;
   /** Resolves vector field and computes shared context for vector search SQL builders. */
   private _prepareVectorSearch;
+  /**
+   * The row source + distance cap of a vector search. The threshold is a
+   * normalized score matching MongoDB Atlas semantics: cosine score =
+   * (1 + cos_sim) / 2, VEC_DISTANCE_COSINE = 1 - cos_sim, so the distance cap
+   * is 2 * (1 - score).
+   */
+  private _vectorSearchSource;
   private _buildVectorSearchQuery;
   private _buildVectorSearchCountQuery;
   /** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */

package/dist/index.d.mts

@@ -255,6 +255,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   }>;
   /** Resolves vector field and computes shared context for vector search SQL builders. */
   private _prepareVectorSearch;
+  /**
+   * The row source + distance cap of a vector search. The threshold is a
+   * normalized score matching MongoDB Atlas semantics: cosine score =
+   * (1 + cos_sim) / 2, VEC_DISTANCE_COSINE = 1 - cos_sim, so the distance cap
+   * is 2 * (1 - score).
+   */
+  private _vectorSearchSource;
   private _buildVectorSearchQuery;
   private _buildVectorSearchCountQuery;
   /** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, geoWindowFromControls, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, toSqlValue } from "@atscript/db-sql-tools";
+import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, geoWindowFromControls, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, toSqlValue, vectorDistanceSource } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/sql-builder.ts
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
@@ -1352,13 +1352,21 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		for (const index of this._table.indexes.values()) if (index.type === "fulltext") indexes.push({
 			name: index.key,
 			description: `FULLTEXT index on ${index.fields.map((f) => f.name).join(", ")}`,
-			type: "text"
-		});
-		for (const [field, vec] of this._vectorFields) indexes.push({
-			name: vec.indexName,
-			description: `VECTOR(${vec.dimensions}) on ${field}, ${vec.similarity}`,
-			type: "vector"
+			type: "text",
+			fields: this._indexLogicalPaths(index),
+			isDefault: indexes.length === 0
 		});
+		let firstVector = true;
+		for (const [field, vec] of this._vectorFields) {
+			indexes.push({
+				name: vec.indexName,
+				description: `VECTOR(${vec.dimensions}) on ${field}, ${vec.similarity}`,
+				type: "vector",
+				fields: [field],
+				isDefault: firstVector
+			});
+			firstVector = false;
+		}
 		return indexes;
 	}
 	async search(text, query, indexName) {
@@ -1455,7 +1463,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				found = true;
 				break;
 			}
-			if (!found) throw new Error(`Vector index "${indexName}" not found`);
+			if (!found) throw new Error(vectorIndexNotFoundMessage(indexName));
 		} else {
 			const first = this._vectorFields.entries().next();
 			if (first.done) throw new Error("No vector fields defined");
@@ -1477,36 +1485,36 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			vectorStr: vectorToString(vector)
 		};
 	}
-	_buildVectorSearchQuery(vector, query, indexName) {
-		const ctx = this._prepareVectorSearch(vector, query, indexName);
-		const inner = `SELECT *, ${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?)) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${ctx.where.sql}`;
-		const params = [ctx.vectorStr, ...ctx.where.params];
-		let sql = `SELECT * FROM (${inner}) _v`;
-		if (ctx.threshold !== void 0) {
-			sql += ` WHERE _distance <= ?`;
-			params.push(2 * (1 - ctx.threshold));
-		}
-		sql += ` ORDER BY _distance ASC`;
-		if (ctx.controls.$skip) sql += ` LIMIT ${Number(ctx.controls.$limit) || 1e3} OFFSET ${Number(ctx.controls.$skip)}`;
-		else sql += ` LIMIT ${Number(ctx.controls.$limit) || 20}`;
+	/**
+	* The row source + distance cap of a vector search. The threshold is a
+	* normalized score matching MongoDB Atlas semantics: cosine score =
+	* (1 + cos_sim) / 2, VEC_DISTANCE_COSINE = 1 - cos_sim, so the distance cap
+	* is 2 * (1 - score).
+	*/
+	_vectorSearchSource(ctx, withRows) {
+		const distExpr = {
+			sql: `${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?))`,
+			params: [ctx.vectorStr]
+		};
 		return {
-			sql,
-			params
+			source: vectorDistanceSource(mysqlDialect, ctx.tableName, ctx.where, distExpr, withRows),
+			maxDistance: ctx.threshold === void 0 ? void 0 : 2 * (1 - ctx.threshold)
 		};
 	}
-	_buildVectorSearchCountQuery(vector, query, indexName) {
+	_buildVectorSearchQuery(vector, query, indexName) {
 		const ctx = this._prepareVectorSearch(vector, query, indexName);
-		const inner = `SELECT ${ctx.distanceFn}(${qi(ctx.field)}, STRING_TO_VECTOR(?)) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${ctx.where.sql}`;
-		const params = [ctx.vectorStr, ...ctx.where.params];
-		let sql = `SELECT COUNT(*) AS cnt FROM (${inner}) _v`;
-		if (ctx.threshold !== void 0) {
-			sql += ` WHERE _distance <= ?`;
-			params.push(2 * (1 - ctx.threshold));
-		}
-		return {
-			sql,
-			params
-		};
+		const { source, maxDistance } = this._vectorSearchSource(ctx, true);
+		const skip = Number(ctx.controls.$skip) || 0;
+		return buildVectorSearchSelect(mysqlDialect, source, {
+			select: ctx.controls.$select,
+			limit: Number(ctx.controls.$limit) || (skip ? 1e3 : 20),
+			skip,
+			maxDistance
+		});
+	}
+	_buildVectorSearchCountQuery(vector, query, indexName) {
+		const { source, maxDistance } = this._vectorSearchSource(this._prepareVectorSearch(vector, query, indexName), false);
+		return buildVectorSearchCount(mysqlDialect, source, { maxDistance });
 	}
 	/** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */
 	_resolveVectorThreshold(controls, indexName) {
@@ -1548,10 +1556,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 	}
 	_buildGeoSearchSelect(ctx) {
-		return buildGeoSearchSelect(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, {
-			$limit: ctx.controls.$limit,
-			$skip: ctx.controls.$skip
-		});
+		return buildGeoSearchSelect(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, ctx.controls);
 	}
 	/**
 	* Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mysql",
-  "version": "0.1.141",
+  "version": "0.1.143",
   "description": "MySQL adapter for @atscript/db with mysql2 driver support.",
   "keywords": [
     "atscript",
@@ -52,8 +52,8 @@
     "@atscript/typescript": "^0.1.95",
     "@uniqu/core": "^0.1.11",
     "mysql2": ">=3.0.0",
-    "@atscript/db": "^0.1.141",
-    "@atscript/db-sql-tools": "^0.1.141"
+    "@atscript/db-sql-tools": "^0.1.143",
+    "@atscript/db": "^0.1.143"
   },
   "peerDependenciesMeta": {
     "mysql2": {