ydb-qdrant 4.7.2 → 4.8.0

package/dist/repositories/pointsRepo.one-table.js

@@ -231,195 +231,113 @@ async function searchPointsOneTableApproximate(tableName, queryVector, top, with
     const rawCandidateLimit = safeTop * overfetchMultiplier;
     const candidateLimit = Math.max(safeTop, rawCandidateLimit);
     const results = await withSession(async (s) => {
+        let yql;
+        let params;
         if (CLIENT_SIDE_SERIALIZATION_ENABLED) {
             const binaries = buildVectorBinaryParams(queryVector);
-            // Phase 1: approximate candidate selection using embedding_quantized
-            const phase1Query = `
+            yql = `
         DECLARE $qbin_bit AS String;
-        DECLARE $k AS Uint32;
+        DECLARE $qbinf AS String;
+        DECLARE $candidateLimit AS Uint32;
+        DECLARE $safeTop AS Uint32;
         DECLARE $uid AS Utf8;
-        SELECT point_id
+
+        $candidates = (
+          SELECT point_id
+          FROM ${tableName}
+          WHERE uid = $uid AND embedding_quantized IS NOT NULL
+          ORDER BY ${bitFn}(embedding_quantized, $qbin_bit) ${bitOrder}
+          LIMIT $candidateLimit
+        );
+
+        SELECT point_id, ${withPayload ? "payload, " : ""}${fn}(embedding, $qbinf) AS score
         FROM ${tableName}
-        WHERE uid = $uid AND embedding_quantized IS NOT NULL
-        ORDER BY ${bitFn}(embedding_quantized, $qbin_bit) ${bitOrder}
-        LIMIT $k;
+        WHERE uid = $uid
+          AND point_id IN $candidates
+        ORDER BY score ${order}
+        LIMIT $safeTop;
       `;
+            params = {
+                $qbin_bit: typeof TypedValues.bytes === "function"
+                    ? TypedValues.bytes(binaries.bit)
+                    : binaries.bit,
+                $qbinf: typeof TypedValues.bytes === "function"
+                    ? TypedValues.bytes(binaries.float)
+                    : binaries.float,
+                $candidateLimit: TypedValues.uint32(candidateLimit),
+                $safeTop: TypedValues.uint32(safeTop),
+                $uid: TypedValues.utf8(uid),
+            };
             logger.debug({
                 tableName,
                 distance,
                 top,
                 safeTop,
                 candidateLimit,
-                mode: "one_table_approximate_phase1_client_side_serialization",
-                yql: phase1Query,
+                mode: "one_table_approximate_client_side_serialization",
+                yql,
                 params: {
                     uid,
-                    top: candidateLimit,
+                    safeTop,
+                    candidateLimit,
                     vectorLength: queryVector.length,
                     vectorPreview: queryVector.slice(0, 3),
                 },
-            }, "one_table search (approximate, phase 1): executing YQL");
-            const phase1Params = {
-                $qbin_bit: typeof TypedValues.bytes === "function"
-                    ? TypedValues.bytes(binaries.bit)
-                    : binaries.bit,
-                $k: TypedValues.uint32(candidateLimit),
-                $uid: TypedValues.utf8(uid),
-            };
-            const rs1 = await s.executeQuery(phase1Query, phase1Params);
-            const rowset1 = rs1.resultSets?.[0];
-            const rows1 = (rowset1?.rows ?? []);
-            const candidateIds = rows1
-                .map((row) => row.items?.[0]?.textValue)
-                .filter((id) => typeof id === "string");
-            if (candidateIds.length === 0) {
-                return [];
-            }
-            // Phase 2: exact re-ranking on full-precision embedding for candidates only
-            const phase2Query = `
-        DECLARE $qbinf AS String;
-        DECLARE $k AS Uint32;
+            }, "one_table search (approximate): executing YQL with client-side serialization");
+        }
+        else {
+            const qf = buildVectorParam(queryVector);
+            yql = `
+        DECLARE $qf AS List<Float>;
+        DECLARE $candidateLimit AS Uint32;
+        DECLARE $safeTop AS Uint32;
         DECLARE $uid AS Utf8;
-        DECLARE $ids AS List<Utf8>;
+
+        $qbin_bit = Knn::ToBinaryStringBit($qf);
+        $qbinf = Knn::ToBinaryStringFloat($qf);
+
+        $candidates = (
+          SELECT point_id
+          FROM ${tableName}
+          WHERE uid = $uid AND embedding_quantized IS NOT NULL
+          ORDER BY ${bitFn}(embedding_quantized, $qbin_bit) ${bitOrder}
+          LIMIT $candidateLimit
+        );
+
         SELECT point_id, ${withPayload ? "payload, " : ""}${fn}(embedding, $qbinf) AS score
         FROM ${tableName}
-        WHERE uid = $uid AND point_id IN $ids
+        WHERE uid = $uid
+          AND point_id IN $candidates
         ORDER BY score ${order}
-        LIMIT $k;
+        LIMIT $safeTop;
       `;
+            params = {
+                $qf: qf,
+                $candidateLimit: TypedValues.uint32(candidateLimit),
+                $safeTop: TypedValues.uint32(safeTop),
+                $uid: TypedValues.utf8(uid),
+            };
             logger.debug({
                 tableName,
                 distance,
                 top,
                 safeTop,
-                candidateCount: candidateIds.length,
-                mode: "one_table_approximate_phase2_client_side_serialization",
-                yql: phase2Query,
+                candidateLimit,
+                mode: "one_table_approximate",
+                yql,
                 params: {
                     uid,
-                    top: safeTop,
+                    safeTop,
+                    candidateLimit,
                     vectorLength: queryVector.length,
                     vectorPreview: queryVector.slice(0, 3),
-                    ids: candidateIds,
                 },
-            }, "one_table search (approximate, phase 2): executing YQL");
-            const idsParam = TypedValues.list(Types.UTF8, candidateIds);
-            const phase2Params = {
-                $qbinf: typeof TypedValues.bytes === "function"
-                    ? TypedValues.bytes(binaries.float)
-                    : binaries.float,
-                $k: TypedValues.uint32(safeTop),
-                $uid: TypedValues.utf8(uid),
-                $ids: idsParam,
-            };
-            const rs2 = await s.executeQuery(phase2Query, phase2Params);
-            const rowset2 = rs2.resultSets?.[0];
-            const rows2 = (rowset2?.rows ?? []);
-            return rows2.map((row) => {
-                const id = row.items?.[0]?.textValue;
-                if (typeof id !== "string") {
-                    throw new Error("point_id is missing in YDB search result");
-                }
-                let payload;
-                let scoreIdx = 1;
-                if (withPayload) {
-                    const payloadText = row.items?.[1]?.textValue;
-                    if (payloadText) {
-                        try {
-                            payload = JSON.parse(payloadText);
-                        }
-                        catch {
-                            payload = undefined;
-                        }
-                    }
-                    scoreIdx = 2;
-                }
-                const score = Number(row.items?.[scoreIdx]?.floatValue ?? row.items?.[scoreIdx]?.textValue);
-                return { id, score, ...(payload ? { payload } : {}) };
-            });
-        }
-        const qf = buildVectorParam(queryVector);
-        // Phase 1: approximate candidate selection using embedding_quantized
-        const phase1Query = `
-      DECLARE $qf AS List<Float>;
-      DECLARE $k AS Uint32;
-      DECLARE $uid AS Utf8;
-      $qbin_bit = Knn::ToBinaryStringBit($qf);
-      SELECT point_id
-      FROM ${tableName}
-      WHERE uid = $uid AND embedding_quantized IS NOT NULL
-      ORDER BY ${bitFn}(embedding_quantized, $qbin_bit) ${bitOrder}
-      LIMIT $k;
-    `;
-        logger.debug({
-            tableName,
-            distance,
-            top,
-            safeTop,
-            candidateLimit,
-            mode: "one_table_approximate_phase1",
-            yql: phase1Query,
-            params: {
-                uid,
-                top: candidateLimit,
-                vectorLength: queryVector.length,
-                vectorPreview: queryVector.slice(0, 3),
-            },
-        }, "one_table search (approximate, phase 1): executing YQL");
-        const phase1Params = {
-            $qf: qf,
-            $k: TypedValues.uint32(candidateLimit),
-            $uid: TypedValues.utf8(uid),
-        };
-        const rs1 = await s.executeQuery(phase1Query, phase1Params);
-        const rowset1 = rs1.resultSets?.[0];
-        const rows1 = (rowset1?.rows ?? []);
-        const candidateIds = rows1
-            .map((row) => row.items?.[0]?.textValue)
-            .filter((id) => typeof id === "string");
-        if (candidateIds.length === 0) {
-            return [];
+            }, "one_table search (approximate): executing YQL");
         }
-        // Phase 2: exact re-ranking on full-precision embedding for candidates only
-        const phase2Query = `
-      DECLARE $qf AS List<Float>;
-      DECLARE $k AS Uint32;
-      DECLARE $uid AS Utf8;
-      DECLARE $ids AS List<Utf8>;
-      $qbinf = Knn::ToBinaryStringFloat($qf);
-      SELECT point_id, ${withPayload ? "payload, " : ""}${fn}(embedding, $qbinf) AS score
-      FROM ${tableName}
-      WHERE uid = $uid AND point_id IN $ids
-      ORDER BY score ${order}
-      LIMIT $k;
-    `;
-        logger.debug({
-            tableName,
-            distance,
-            top,
-            safeTop,
-            candidateCount: candidateIds.length,
-            mode: "one_table_approximate_phase2",
-            yql: phase2Query,
-            params: {
-                uid,
-                top: safeTop,
-                vectorLength: queryVector.length,
-                vectorPreview: queryVector.slice(0, 3),
-                ids: candidateIds,
-            },
-        }, "one_table search (approximate, phase 2): executing YQL");
-        const idsParam = TypedValues.list(Types.UTF8, candidateIds);
-        const phase2Params = {
-            $qf: qf,
-            $k: TypedValues.uint32(safeTop),
-            $uid: TypedValues.utf8(uid),
-            $ids: idsParam,
-        };
-        const rs2 = await s.executeQuery(phase2Query, phase2Params);
-        const rowset2 = rs2.resultSets?.[0];
-        const rows2 = (rowset2?.rows ?? []);
-        return rows2.map((row) => {
+        const rs = await s.executeQuery(yql, params);
+        const rowset = rs.resultSets?.[0];
+        const rows = (rowset?.rows ?? []);
+        return rows.map((row) => {
             const id = row.items?.[0]?.textValue;
             if (typeof id !== "string") {
                 throw new Error("point_id is missing in YDB search result");

package/dist/services/PointsService.js

@@ -118,13 +118,23 @@ async function executeSearch(ctx, normalizedSearch, source) {
         throw err;
     }
     const threshold = normalizedSearch.scoreThreshold;
+    // For Cosine, repository hits use distance scores; convert to a
+    // similarity-like score so API consumers and IDE thresholds see
+    // "higher is better". This keeps ranking identical (monotonic 1 - d).
+    const normalizedHits = meta.distance === "Cosine"
+        ? hits.map((hit) => ({
+            ...hit,
+            score: 1 - hit.score,
+        }))
+        : hits;
     const filtered = threshold === undefined
-        ? hits
-        : hits.filter((hit) => {
-            const isSimilarity = meta.distance === "Cosine" || meta.distance === "Dot";
-            if (isSimilarity) {
+        ? normalizedHits
+        : normalizedHits.filter((hit) => {
+            if (meta.distance === "Dot" || meta.distance === "Cosine") {
+                // Similarity metrics: threshold is minimum similarity.
                 return hit.score >= threshold;
             }
+            // Euclid / Manhattan: pure distance metrics; threshold is max distance.
             return hit.score <= threshold;
         });
     logger.info({

package/dist/utils/distance.d.ts

@@ -5,13 +5,13 @@ export declare function mapDistanceToKnnFn(distance: DistanceKind): {
 };
 export declare function mapDistanceToIndexParam(distance: DistanceKind): string;
 /**
- * Maps a user-specified distance metric to a YDB Knn distance function
+ * Maps a user-specified distance metric to a YDB Knn function
  * suitable for bit-quantized vectors (Phase 1 approximate candidate selection).
- * Always returns a distance function (lower is better, ASC ordering).
+ * Cosine uses similarity (DESC); other metrics use distance (ASC).
  * For Dot, falls back to CosineDistance as a proxy since there is no
  * direct distance equivalent for inner product.
  */
 export declare function mapDistanceToBitKnnFn(distance: DistanceKind): {
     fn: string;
-    order: "ASC";
+    order: "ASC" | "DESC";
 };

package/dist/utils/distance.js

@@ -1,7 +1,7 @@
 export function mapDistanceToKnnFn(distance) {
     switch (distance) {
         case "Cosine":
-            return { fn: "Knn::CosineSimilarity", order: "DESC" };
+            return { fn: "Knn::CosineDistance", order: "ASC" };
         case "Dot":
             return { fn: "Knn::InnerProductSimilarity", order: "DESC" };
         case "Euclid":
@@ -9,7 +9,7 @@ export function mapDistanceToKnnFn(distance) {
         case "Manhattan":
             return { fn: "Knn::ManhattanDistance", order: "ASC" };
         default:
-            return { fn: "Knn::CosineSimilarity", order: "DESC" };
+            return { fn: "Knn::CosineDistance", order: "ASC" };
     }
 }
 export function mapDistanceToIndexParam(distance) {
@@ -27,18 +27,17 @@ export function mapDistanceToIndexParam(distance) {
     }
 }
 /**
- * Maps a user-specified distance metric to a YDB Knn distance function
+ * Maps a user-specified distance metric to a YDB Knn function
  * suitable for bit-quantized vectors (Phase 1 approximate candidate selection).
- * Always returns a distance function (lower is better, ASC ordering).
+ * Cosine uses similarity (DESC); other metrics use distance (ASC).
  * For Dot, falls back to CosineDistance as a proxy since there is no
  * direct distance equivalent for inner product.
  */
 export function mapDistanceToBitKnnFn(distance) {
     switch (distance) {
         case "Cosine":
-            return { fn: "Knn::CosineDistance", order: "ASC" };
+            return { fn: "Knn::CosineSimilarity", order: "DESC" };
         case "Dot":
-            // No direct distance equivalent; use Cosine as proxy
             return { fn: "Knn::CosineDistance", order: "ASC" };
         case "Euclid":
             return { fn: "Knn::EuclideanDistance", order: "ASC" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ydb-qdrant",
-  "version": "4.7.2",
+  "version": "4.8.0",
   "main": "dist/package/api.js",
   "types": "dist/package/api.d.ts",
   "exports": {