ydb-qdrant 5.2.1 → 6.0.0

package/dist/config/env.d.ts

@@ -20,3 +20,4 @@ export declare const SESSION_KEEPALIVE_PERIOD_MS: number;
 export declare const STARTUP_PROBE_SESSION_TIMEOUT_MS: number;
 export declare const UPSERT_OPERATION_TIMEOUT_MS: number;
 export declare const SEARCH_OPERATION_TIMEOUT_MS: number;
+export declare const LAST_ACCESS_MIN_WRITE_INTERVAL_MS: number;

package/dist/config/env.js

@@ -71,3 +71,4 @@ export const SESSION_KEEPALIVE_PERIOD_MS = parseIntegerEnv(process.env.YDB_SESSI
 export const STARTUP_PROBE_SESSION_TIMEOUT_MS = parseIntegerEnv(process.env.YDB_QDRANT_STARTUP_PROBE_SESSION_TIMEOUT_MS, 5000, { min: 1000 });
 export const UPSERT_OPERATION_TIMEOUT_MS = parseIntegerEnv(process.env.YDB_QDRANT_UPSERT_TIMEOUT_MS, 5000, { min: 1000 });
 export const SEARCH_OPERATION_TIMEOUT_MS = parseIntegerEnv(process.env.YDB_QDRANT_SEARCH_TIMEOUT_MS, 10000, { min: 1000 });
+export const LAST_ACCESS_MIN_WRITE_INTERVAL_MS = parseIntegerEnv(process.env.YDB_QDRANT_LAST_ACCESS_MIN_WRITE_INTERVAL_MS, 60000, { min: 1000 });

package/dist/repositories/collectionsRepo.d.ts

@@ -1,10 +1,14 @@
-import type { DistanceKind, VectorType } from "../types";
+import type { DistanceKind, VectorType, CollectionMeta } from "../types";
 export declare function createCollection(metaKey: string, dim: number, distance: DistanceKind, vectorType: VectorType): Promise<void>;
-export declare function getCollectionMeta(metaKey: string): Promise<{
-    table: string;
-    dimension: number;
-    distance: DistanceKind;
-    vectorType: VectorType;
-} | null>;
+export declare function getCollectionMeta(metaKey: string): Promise<CollectionMeta | null>;
 export declare function verifyCollectionsQueryCompilationForStartup(): Promise<void>;
 export declare function deleteCollection(metaKey: string, uid?: string): Promise<void>;
+/**
+ * Best-effort metadata update for a collection's last_accessed_at timestamp.
+ *
+ * - Uses an in-memory throttle (per metaKey) to avoid writing more often than
+ *   LAST_ACCESS_MIN_WRITE_INTERVAL_MS.
+ * - Accepts an optional now parameter (default: current time) to aid testing.
+ * - Logs and ignores YDB errors so callers' primary operations are not affected.
+ */
+export declare function touchCollectionLastAccess(metaKey: string, now?: Date): Promise<void>;

package/dist/repositories/collectionsRepo.js

@@ -1,15 +1,39 @@
 import { TypedValues, withSession, createExecuteQuerySettings, withStartupProbeSession, createExecuteQuerySettingsWithTimeout, } from "../ydb/client.js";
-import { STARTUP_PROBE_SESSION_TIMEOUT_MS } from "../config/env.js";
+import { STARTUP_PROBE_SESSION_TIMEOUT_MS, LAST_ACCESS_MIN_WRITE_INTERVAL_MS, } from "../config/env.js";
+import { logger } from "../logging/logger.js";
 import { uidFor } from "../utils/tenant.js";
 import { createCollectionOneTable, deleteCollectionOneTable, } from "./collectionsRepo.one-table.js";
 import { withRetry, isTransientYdbError } from "../utils/retry.js";
+const lastAccessWriteCache = new Map();
+const LAST_ACCESS_CACHE_MAX_SIZE = 10000;
+function evictOldestLastAccessEntry() {
+    if (lastAccessWriteCache.size < LAST_ACCESS_CACHE_MAX_SIZE) {
+        return;
+    }
+    const oldestKey = lastAccessWriteCache.keys().next().value;
+    if (oldestKey !== undefined) {
+        lastAccessWriteCache.delete(oldestKey);
+    }
+}
+function shouldWriteLastAccess(nowMs, key) {
+    const last = lastAccessWriteCache.get(key);
+    if (last === undefined) {
+        return true;
+    }
+    return nowMs - last >= LAST_ACCESS_MIN_WRITE_INTERVAL_MS;
+}
 export async function createCollection(metaKey, dim, distance, vectorType) {
     await createCollectionOneTable(metaKey, dim, distance, vectorType);
 }
 export async function getCollectionMeta(metaKey) {
     const qry = `
     DECLARE $collection AS Utf8;
-    SELECT table_name, vector_dimension, distance, vector_type
+    SELECT
+      table_name,
+      vector_dimension,
+      distance,
+      vector_type,
+      CAST(last_accessed_at AS Utf8) AS last_accessed_at
     FROM qdr__collections
     WHERE collection = $collection;
   `;
@@ -27,13 +51,31 @@ export async function getCollectionMeta(metaKey) {
     const dimension = Number(row.items?.[1]?.uint32Value ?? row.items?.[1]?.textValue);
     const distance = row.items?.[2]?.textValue ?? "Cosine";
     const vectorType = row.items?.[3]?.textValue ?? "float";
-    return { table, dimension, distance, vectorType };
+    const lastAccessRaw = row.items?.[4]?.textValue;
+    const lastAccessedAt = typeof lastAccessRaw === "string" && lastAccessRaw.length > 0
+        ? new Date(lastAccessRaw)
+        : undefined;
+    const result = {
+        table,
+        dimension,
+        distance,
+        vectorType,
+    };
+    if (lastAccessedAt) {
+        result.lastAccessedAt = lastAccessedAt;
+    }
+    return result;
 }
 export async function verifyCollectionsQueryCompilationForStartup() {
     const probeKey = "__startup_probe__/__startup_probe__";
     const qry = `
     DECLARE $collection AS Utf8;
-    SELECT table_name, vector_dimension, distance, vector_type
+    SELECT
+      table_name,
+      vector_dimension,
+      distance,
+      vector_type,
+      CAST(last_accessed_at AS Utf8) AS last_accessed_at
     FROM qdr__collections
     WHERE collection = $collection;
   `;
@@ -69,3 +111,38 @@ export async function deleteCollection(metaKey, uid) {
     }
     await deleteCollectionOneTable(metaKey, effectiveUid);
 }
+/**
+ * Best-effort metadata update for a collection's last_accessed_at timestamp.
+ *
+ * - Uses an in-memory throttle (per metaKey) to avoid writing more often than
+ *   LAST_ACCESS_MIN_WRITE_INTERVAL_MS.
+ * - Accepts an optional now parameter (default: current time) to aid testing.
+ * - Logs and ignores YDB errors so callers' primary operations are not affected.
+ */
+export async function touchCollectionLastAccess(metaKey, now = new Date()) {
+    const nowMs = now.getTime();
+    if (!shouldWriteLastAccess(nowMs, metaKey)) {
+        return;
+    }
+    const qry = `
+    DECLARE $collection AS Utf8;
+    DECLARE $last_accessed AS Timestamp;
+    UPDATE qdr__collections
+    SET last_accessed_at = $last_accessed
+    WHERE collection = $collection;
+  `;
+    try {
+        await withSession(async (s) => {
+            const settings = createExecuteQuerySettings();
+            await s.executeQuery(qry, {
+                $collection: TypedValues.utf8(metaKey),
+                $last_accessed: TypedValues.timestamp(now),
+            }, undefined, settings);
+        });
+        evictOldestLastAccessEntry();
+        lastAccessWriteCache.set(metaKey, nowMs);
+    }
+    catch (err) {
+        logger.warn({ err, collection: metaKey }, "touchCollectionLastAccess: failed to update last_accessed_at (ignored)");
+    }
+}

package/dist/repositories/collectionsRepo.shared.js

@@ -1,5 +1,6 @@
 import { TypedValues, withSession } from "../ydb/client.js";
 export async function upsertCollectionMeta(metaKey, dim, distance, vectorType, tableName) {
+    const now = new Date();
     const upsertMeta = `
     DECLARE $collection AS Utf8;
     DECLARE $table AS Utf8;
@@ -7,8 +8,9 @@ export async function upsertCollectionMeta(metaKey, dim, distance, vectorType, t
     DECLARE $distance AS Utf8;
     DECLARE $vtype AS Utf8;
     DECLARE $created AS Timestamp;
-    UPSERT INTO qdr__collections (collection, table_name, vector_dimension, distance, vector_type, created_at)
-    VALUES ($collection, $table, $dim, $distance, $vtype, $created);
+    DECLARE $last_accessed AS Timestamp;
+    UPSERT INTO qdr__collections (collection, table_name, vector_dimension, distance, vector_type, created_at, last_accessed_at)
+    VALUES ($collection, $table, $dim, $distance, $vtype, $created, $last_accessed);
   `;
     await withSession(async (s) => {
         await s.executeQuery(upsertMeta, {
@@ -17,7 +19,8 @@ export async function upsertCollectionMeta(metaKey, dim, distance, vectorType, t
             $dim: TypedValues.uint32(dim),
             $distance: TypedValues.utf8(distance),
             $vtype: TypedValues.utf8(vectorType),
-            $created: TypedValues.timestamp(new Date()),
+            $created: TypedValues.timestamp(now),
+            $last_accessed: TypedValues.timestamp(now),
         });
     });
 }

package/dist/services/CollectionService.js

@@ -1,6 +1,6 @@
 import { CreateCollectionReq } from "../types.js";
 import { ensureMetaTable } from "../ydb/schema.js";
-import { createCollection as repoCreateCollection, deleteCollection as repoDeleteCollection, getCollectionMeta, } from "../repositories/collectionsRepo.js";
+import { createCollection as repoCreateCollection, deleteCollection as repoDeleteCollection, getCollectionMeta, touchCollectionLastAccess, } from "../repositories/collectionsRepo.js";
 import { QdrantServiceError } from "./errors.js";
 import { normalizeCollectionContextShared } from "./CollectionService.shared.js";
 export async function putCollectionIndex(ctx) {
@@ -13,6 +13,7 @@ export async function putCollectionIndex(ctx) {
             error: "collection not found",
         });
     }
+    await touchCollectionLastAccess(normalized.metaKey);
     return { acknowledged: true };
 }
 export async function createCollection(ctx, body) {
@@ -33,6 +34,7 @@ export async function createCollection(ctx, body) {
         if (existing.dimension === dim &&
             existing.distance === distance &&
             existing.vectorType === vectorType) {
+            await touchCollectionLastAccess(normalized.metaKey);
             return { name: normalized.collection, tenant: normalized.tenant };
         }
         const errorMessage = `Collection already exists with different config: dimension=${existing.dimension}, distance=${existing.distance}, type=${existing.vectorType}`;
@@ -54,6 +56,7 @@ export async function getCollection(ctx) {
             error: "collection not found",
         });
     }
+    await touchCollectionLastAccess(normalized.metaKey);
     return {
         name: normalized.collection,
         vectors: {

package/dist/services/CollectionService.shared.d.ts

@@ -1,6 +1,7 @@
 export interface NormalizedCollectionContextLike {
     tenant: string;
     collection: string;
+    metaKey: string;
 }
 export declare function tableNameFor(tenantId: string, collection: string): string;
 export declare function uidFor(tenantId: string, collection: string): string;

package/dist/services/CollectionService.shared.js

@@ -1,4 +1,4 @@
-import { sanitizeCollectionName, sanitizeTenantId, metaKeyFor, tableNameFor as tableNameForInternal, uidFor as uidForInternal, hashApiKey, hashUserAgent, } from "../utils/tenant.js";
+import { sanitizeCollectionName, sanitizeTenantId, metaKeyFor, tableNameFor as tableNameForInternal, uidFor as uidForInternal, hashApiKey, normalizeUserAgent, } from "../utils/tenant.js";
 export function tableNameFor(tenantId, collection) {
     return tableNameForInternal(tenantId, collection);
 }
@@ -8,8 +8,8 @@ export function uidFor(tenantId, collection) {
 export function normalizeCollectionContextShared(tenant, collection, apiKey, userAgent) {
     const normalizedTenant = sanitizeTenantId(tenant);
     const apiKeyHash = hashApiKey(apiKey);
-    const userAgentHash = hashUserAgent(userAgent);
-    const normalizedCollection = sanitizeCollectionName(collection, apiKeyHash, userAgentHash);
+    const userAgentNormalized = normalizeUserAgent(userAgent);
+    const normalizedCollection = sanitizeCollectionName(collection, apiKeyHash, userAgentNormalized);
     const metaKey = metaKeyFor(normalizedTenant, normalizedCollection);
     return {
         tenant: normalizedTenant,

package/dist/services/PointsService.js

@@ -1,6 +1,6 @@
 import { UpsertPointsReq, SearchReq, DeletePointsReq } from "../types.js";
 import { ensureMetaTable } from "../ydb/schema.js";
-import { getCollectionMeta } from "../repositories/collectionsRepo.js";
+import { getCollectionMeta, touchCollectionLastAccess, } from "../repositories/collectionsRepo.js";
 import { deletePoints as repoDeletePoints, searchPoints as repoSearchPoints, upsertPoints as repoUpsertPoints, } from "../repositories/pointsRepo.js";
 import { logger } from "../logging/logger.js";
 import { QdrantServiceError, isVectorDimensionMismatchError, } from "./errors.js";
@@ -44,6 +44,7 @@ export async function upsertPoints(ctx, body) {
         }
         throw err;
     }
+    await touchCollectionLastAccess(normalized.metaKey);
     return { upserted };
 }
 async function executeSearch(ctx, normalizedSearch, source) {
@@ -108,6 +109,7 @@ async function executeSearch(ctx, normalizedSearch, source) {
         }
         throw err;
     }
+    await touchCollectionLastAccess(normalized.metaKey);
     const threshold = normalizedSearch.scoreThreshold;
     // For Cosine, repository hits use distance scores; convert to a
     // similarity-like score so API consumers and IDE thresholds see
@@ -162,5 +164,6 @@ export async function deletePoints(ctx, body) {
     }
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
     const deleted = await repoDeletePoints(tableName, parsed.data.points, uid);
+    await touchCollectionLastAccess(normalized.metaKey);
     return { deleted };
 }

package/dist/types.d.ts

@@ -1,6 +1,19 @@
 import { z } from "zod";
 export type DistanceKind = "Cosine" | "Euclid" | "Dot" | "Manhattan";
 export type VectorType = "float";
+/**
+ * Collection metadata from qdr__collections table.
+ *
+ * @property lastAccessedAt - Timestamp of last access; undefined for collections
+ * created before this feature, null if explicitly unset.
+ */
+export interface CollectionMeta {
+    table: string;
+    dimension: number;
+    distance: DistanceKind;
+    vectorType: VectorType;
+    lastAccessedAt?: Date | null;
+}
 export declare const CreateCollectionReq: z.ZodObject<{
     vectors: z.ZodObject<{
         size: z.ZodNumber;

package/dist/utils/tenant.d.ts

@@ -1,6 +1,6 @@
 export declare function hashApiKey(apiKey: string | undefined): string | undefined;
-export declare function hashUserAgent(userAgent: string | undefined): string | undefined;
-export declare function sanitizeCollectionName(name: string, apiKeyHash?: string, userAgentHash?: string): string;
+export declare function normalizeUserAgent(userAgent: string | undefined): string | undefined;
+export declare function sanitizeCollectionName(name: string, apiKeyHash?: string, userAgentNormalized?: string): string;
 export declare function sanitizeTenantId(tenantId: string | undefined): string;
 export declare function tableNameFor(sanitizedTenant: string, sanitizedCollection: string): string;
 export declare function metaKeyFor(sanitizedTenant: string, sanitizedCollection: string): string;

package/dist/utils/tenant.js

@@ -5,26 +5,41 @@ export function hashApiKey(apiKey) {
     const hash = createHash("sha256").update(apiKey).digest("hex");
     return hash.slice(0, 8);
 }
-export function hashUserAgent(userAgent) {
+export function normalizeUserAgent(userAgent) {
     if (!userAgent || userAgent.trim() === "")
         return undefined;
+    let lowered = userAgent
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (lowered.length === 0)
+        return undefined;
+    const MAX_LEN = 32;
+    if (lowered.length > MAX_LEN) {
+        lowered = lowered.slice(0, MAX_LEN).replace(/_+$/g, "");
+    }
+    if (lowered.length === 0)
+        return undefined;
     const hash = createHash("sha256").update(userAgent).digest("hex");
-    return hash.slice(0, 8);
+    const shortHash = hash.slice(0, 8);
+    return `${lowered}_${shortHash}`;
 }
-export function sanitizeCollectionName(name, apiKeyHash, userAgentHash) {
+export function sanitizeCollectionName(name, apiKeyHash, userAgentNormalized) {
     const cleaned = name.replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_");
     const lowered = cleaned.toLowerCase().replace(/^_+/, "");
     const base = lowered.length > 0 ? lowered : "collection";
     const hasApiKey = apiKeyHash !== undefined && apiKeyHash.trim().length > 0;
-    const hasUserAgent = userAgentHash !== undefined && userAgentHash.trim().length > 0;
+    const hasUserAgent = userAgentNormalized !== undefined && userAgentNormalized.trim().length > 0;
     if (hasApiKey && hasUserAgent) {
-        return `${base}_${apiKeyHash}_${userAgentHash}`;
+        return `${base}_${apiKeyHash}_${userAgentNormalized}`;
     }
     else if (hasApiKey) {
         return `${base}_${apiKeyHash}`;
     }
     else if (hasUserAgent) {
-        return `${base}_${userAgentHash}`;
+        return `${base}_${userAgentNormalized}`;
     }
     return base;
 }

package/dist/ydb/schema.js

@@ -14,13 +14,32 @@ export async function ensureMetaTable() {
         await withSession(async (s) => {
             // If table exists, describeTable will succeed
             try {
-                await s.describeTable("qdr__collections");
+                const tableDescription = await s.describeTable("qdr__collections");
+                const columns = tableDescription.columns ?? [];
+                const hasLastAccessedAt = columns.some((col) => col.name === "last_accessed_at");
+                if (!hasLastAccessedAt) {
+                    const alterDdl = `
+            ALTER TABLE qdr__collections
+            ADD COLUMN last_accessed_at Timestamp;
+          `;
+                    // NOTE: ydb-sdk's public TableSession type does not surface executeSchemeQuery,
+                    // but the underlying implementation provides it. This cast relies on the
+                    // current ydb-sdk internals (tested with ydb-sdk v5.11.1) to run ALTER TABLE
+                    // as a scheme query. If the SDK changes its internal API, this may need to be
+                    // revisited or replaced with an officially supported migration mechanism.
+                    const rawSession = s;
+                    await rawSession.api.executeSchemeQuery({
+                        sessionId: rawSession.sessionId,
+                        yqlText: alterDdl,
+                    });
+                    logger.info("added last_accessed_at column to metadata table qdr__collections");
+                }
                 return;
             }
             catch {
                 // create via schema API
                 const desc = new TableDescription()
-                    .withColumns(new Column("collection", Types.UTF8), new Column("table_name", Types.UTF8), new Column("vector_dimension", Types.UINT32), new Column("distance", Types.UTF8), new Column("vector_type", Types.UTF8), new Column("created_at", Types.TIMESTAMP))
+                    .withColumns(new Column("collection", Types.UTF8), new Column("table_name", Types.UTF8), new Column("vector_dimension", Types.UINT32), new Column("distance", Types.UTF8), new Column("vector_type", Types.UTF8), new Column("created_at", Types.TIMESTAMP), new Column("last_accessed_at", Types.TIMESTAMP))
                     .withPrimaryKey("collection");
                 await s.createTable("qdr__collections", desc);
                 logger.info("created metadata table qdr__collections");
@@ -28,7 +47,7 @@ export async function ensureMetaTable() {
         });
     }
     catch (err) {
-        logger.debug({ err }, "ensureMetaTable: ignored");
+        logger.warn({ err }, "ensureMetaTable: failed to verify or migrate qdr__collections; subsequent operations may fail if schema is incomplete");
     }
 }
 export async function ensureGlobalPointsTable() {
@@ -67,6 +86,11 @@ export async function ensureGlobalPointsTable() {
           ALTER TABLE ${GLOBAL_POINTS_TABLE}
           ADD COLUMN embedding_quantized String;
         `;
+            // NOTE: Same rationale as in ensureMetaTable: executeSchemeQuery is not part of
+            // the public TableSession TypeScript surface, so we reach into the underlying
+            // ydb-sdk implementation (verified with ydb-sdk v5.11.1) to apply schema changes.
+            // If future SDK versions alter this shape, this cast and migration path must be
+            // updated accordingly.
             const rawSession = s;
             await rawSession.api.executeSchemeQuery({
                 sessionId: rawSession.sessionId,

package/package.json

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