ydb-qdrant 4.7.1 → 4.8.0

package/dist/config/env.d.ts

@@ -19,3 +19,6 @@ export declare const SEARCH_MODE: SearchMode;
 export declare const OVERFETCH_MULTIPLIER: number;
 export declare const CLIENT_SIDE_SERIALIZATION_ENABLED: boolean;
 export declare const UPSERT_BATCH_SIZE: number;
+export declare const SESSION_POOL_MIN_SIZE: number;
+export declare const SESSION_POOL_MAX_SIZE: number;
+export declare const SESSION_KEEPALIVE_PERIOD_MS: number;

package/dist/config/env.js

@@ -78,3 +78,12 @@ export const SEARCH_MODE = resolveSearchModeEnv(COLLECTION_STORAGE_MODE);
 export const OVERFETCH_MULTIPLIER = parseIntegerEnv(process.env.YDB_QDRANT_OVERFETCH_MULTIPLIER, 10, { min: 1 });
 export const CLIENT_SIDE_SERIALIZATION_ENABLED = parseBooleanEnv(process.env.YDB_QDRANT_CLIENT_SIDE_SERIALIZATION_ENABLED, false);
 export const UPSERT_BATCH_SIZE = parseIntegerEnv(process.env.YDB_QDRANT_UPSERT_BATCH_SIZE, 100, { min: 1 });
+// Session pool configuration
+const RAW_SESSION_POOL_MIN_SIZE = parseIntegerEnv(process.env.YDB_SESSION_POOL_MIN_SIZE, 5, { min: 1, max: 500 });
+const RAW_SESSION_POOL_MAX_SIZE = parseIntegerEnv(process.env.YDB_SESSION_POOL_MAX_SIZE, 100, { min: 1, max: 500 });
+const NORMALIZED_SESSION_POOL_MIN_SIZE = RAW_SESSION_POOL_MIN_SIZE > RAW_SESSION_POOL_MAX_SIZE
+    ? RAW_SESSION_POOL_MAX_SIZE
+    : RAW_SESSION_POOL_MIN_SIZE;
+export const SESSION_POOL_MIN_SIZE = NORMALIZED_SESSION_POOL_MIN_SIZE;
+export const SESSION_POOL_MAX_SIZE = RAW_SESSION_POOL_MAX_SIZE;
+export const SESSION_KEEPALIVE_PERIOD_MS = parseIntegerEnv(process.env.YDB_SESSION_KEEPALIVE_PERIOD_MS, 5000, { min: 1000, max: 60000 });

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/dist/ydb/client.d.ts

@@ -8,7 +8,19 @@ type DriverConfig = {
     authService?: IAuthService;
 };
 export declare function __setDriverForTests(fake: unknown): void;
+export declare function __setDriverFactoryForTests(factory: ((config: unknown) => unknown) | undefined): void;
+export declare function __resetRefreshStateForTests(): void;
 export declare function configureDriver(config: DriverConfig): void;
 export declare function readyOrThrow(): Promise<void>;
 export declare function withSession<T>(fn: (s: Session) => Promise<T>): Promise<T>;
 export declare function isYdbAvailable(timeoutMs?: number): Promise<boolean>;
+/**
+ * Destroys the current driver and its session pool.
+ * Next call to withSession or readyOrThrow will create a new driver.
+ */
+export declare function destroyDriver(): Promise<void>;
+/**
+ * Destroys the current driver and immediately creates a fresh one.
+ * Use this to recover from session pool exhaustion or zombie sessions.
+ */
+export declare function refreshDriver(): Promise<void>;

package/dist/ydb/client.js

@@ -1,16 +1,72 @@
 import { createRequire } from "module";
-import { YDB_DATABASE, YDB_ENDPOINT } from "../config/env.js";
+import { YDB_DATABASE, YDB_ENDPOINT, SESSION_POOL_MIN_SIZE, SESSION_POOL_MAX_SIZE, SESSION_KEEPALIVE_PERIOD_MS, } from "../config/env.js";
+import { logger } from "../logging/logger.js";
 const require = createRequire(import.meta.url);
 const { Driver, getCredentialsFromEnv, Types, TypedValues, TableDescription, Column, } = require("ydb-sdk");
 export { Types, TypedValues, TableDescription, Column };
 const DRIVER_READY_TIMEOUT_MS = 15000;
 const TABLE_SESSION_TIMEOUT_MS = 20000;
 const YDB_HEALTHCHECK_READY_TIMEOUT_MS = 5000;
+const DRIVER_REFRESH_COOLDOWN_MS = 30000;
 let overrideConfig;
 let driver;
+let lastDriverRefreshAt = 0;
+let driverRefreshInFlight = null;
+// Test-only: allows injecting a mock Driver factory
+let driverFactoryOverride;
+function shouldTriggerDriverRefresh(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const msg = error.message ?? "";
+    if (/No session became available within timeout/i.test(msg)) {
+        return true;
+    }
+    if (/SESSION_POOL_EMPTY|session pool empty/i.test(msg)) {
+        return true;
+    }
+    if (/SessionExpired|SESSION_EXPIRED|session.*expired/i.test(msg)) {
+        return true;
+    }
+    return false;
+}
+async function maybeRefreshDriverOnSessionError(error) {
+    if (!shouldTriggerDriverRefresh(error)) {
+        return;
+    }
+    const now = Date.now();
+    if (now - lastDriverRefreshAt < DRIVER_REFRESH_COOLDOWN_MS) {
+        logger.warn({ lastDriverRefreshAt, cooldownMs: DRIVER_REFRESH_COOLDOWN_MS }, "YDB driver refresh skipped due to cooldown");
+        return;
+    }
+    if (driverRefreshInFlight) {
+        logger.warn({ lastDriverRefreshAt, cooldownMs: DRIVER_REFRESH_COOLDOWN_MS }, "YDB driver refresh already in flight; skipping");
+        return;
+    }
+    lastDriverRefreshAt = now;
+    logger.warn({ err: error }, "YDB session-related error detected; refreshing driver");
+    try {
+        const refreshPromise = refreshDriver();
+        driverRefreshInFlight = refreshPromise;
+        await refreshPromise;
+    }
+    catch (refreshErr) {
+        logger.error({ err: refreshErr }, "YDB driver refresh failed; keeping current driver");
+    }
+    finally {
+        driverRefreshInFlight = null;
+    }
+}
 export function __setDriverForTests(fake) {
     driver = fake;
 }
+export function __setDriverFactoryForTests(factory) {
+    driverFactoryOverride = factory;
+}
+export function __resetRefreshStateForTests() {
+    lastDriverRefreshAt = 0;
+    driverRefreshInFlight = null;
+}
 export function configureDriver(config) {
     if (driver) {
         // Driver already created; keep existing connection settings.
@@ -28,10 +84,23 @@ function getOrCreateDriver() {
             endpoint: overrideConfig?.endpoint ?? YDB_ENDPOINT,
             database: overrideConfig?.database ?? YDB_DATABASE,
         };
-    driver = new Driver({
+    const driverConfig = {
         ...base,
         authService: overrideConfig?.authService ?? getCredentialsFromEnv(),
-    });
+        poolSettings: {
+            minLimit: SESSION_POOL_MIN_SIZE,
+            maxLimit: SESSION_POOL_MAX_SIZE,
+            keepAlivePeriod: SESSION_KEEPALIVE_PERIOD_MS,
+        },
+    };
+    driver = driverFactoryOverride
+        ? driverFactoryOverride(driverConfig)
+        : new Driver(driverConfig);
+    logger.info({
+        poolMinSize: SESSION_POOL_MIN_SIZE,
+        poolMaxSize: SESSION_POOL_MAX_SIZE,
+        keepAlivePeriodMs: SESSION_KEEPALIVE_PERIOD_MS,
+    }, "YDB driver created with session pool settings");
     return driver;
 }
 export async function readyOrThrow() {
@@ -43,7 +112,13 @@ export async function readyOrThrow() {
 }
 export async function withSession(fn) {
     const d = getOrCreateDriver();
-    return await d.tableClient.withSession(fn, TABLE_SESSION_TIMEOUT_MS);
+    try {
+        return await d.tableClient.withSession(fn, TABLE_SESSION_TIMEOUT_MS);
+    }
+    catch (err) {
+        void maybeRefreshDriverOnSessionError(err);
+        throw err;
+    }
 }
 export async function isYdbAvailable(timeoutMs = YDB_HEALTHCHECK_READY_TIMEOUT_MS) {
     const d = getOrCreateDriver();
@@ -54,3 +129,30 @@ export async function isYdbAvailable(timeoutMs = YDB_HEALTHCHECK_READY_TIMEOUT_M
         return false;
     }
 }
+/**
+ * Destroys the current driver and its session pool.
+ * Next call to withSession or readyOrThrow will create a new driver.
+ */
+export async function destroyDriver() {
+    if (!driver) {
+        return;
+    }
+    logger.info("Destroying YDB driver and session pool");
+    try {
+        await driver.destroy();
+    }
+    catch (err) {
+        logger.warn({ err }, "Error during driver destruction (ignored)");
+    }
+    driver = undefined;
+}
+/**
+ * Destroys the current driver and immediately creates a fresh one.
+ * Use this to recover from session pool exhaustion or zombie sessions.
+ */
+export async function refreshDriver() {
+    logger.info("Refreshing YDB driver");
+    await destroyDriver();
+    await readyOrThrow();
+    logger.info("YDB driver refreshed successfully");
+}

package/package.json

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