ydb-qdrant 6.0.0 → 7.0.1

package/dist/server.js

@@ -22,18 +22,86 @@ export async function healthHandler(_req, res) {
         logger.error({ err }, isTimeout
             ? "YDB compilation timeout during health probe; scheduling process exit"
             : "YDB health probe failed; scheduling process exit");
-        res.status(503).json({ status: "error", error: "YDB health probe failed" });
+        res.status(503).json({
+            status: "error",
+            error: "YDB health probe failed",
+        });
         scheduleExit(1);
         return;
     }
     res.json({ status: "ok" });
 }
+export function rootHandler(_req, res) {
+    const version = process.env.npm_package_version ?? "unknown";
+    res.json({ title: "ydb-qdrant", version });
+}
 export function buildServer() {
     const app = express();
-    app.use(express.json({ limit: "20mb" }));
     app.use(requestLogger);
+    app.use(express.json({ limit: "20mb" }));
+    app.get("/", rootHandler);
     app.get("/health", healthHandler);
     app.use("/collections", collectionsRouter);
     app.use("/collections", pointsRouter);
+    app.use((err, req, res, next) => {
+        if (!isRequestAbortedError(err)) {
+            next(err);
+            return;
+        }
+        // Client closed the connection while the request body was being read.
+        // Avoid Express default handler printing a stacktrace to stderr.
+        if (res.headersSent || res.writableEnded) {
+            return;
+        }
+        res.status(400).json({ status: "error", error: "request aborted" });
+    });
+    // Catch-all error handler: avoid Express default handler printing stacktraces to stderr
+    // and provide consistent JSON error responses.
+    app.use((err, _req, res, _next) => {
+        logger.error({ err }, "Unhandled error in Express middleware");
+        void _next;
+        if (res.headersSent || res.writableEnded) {
+            return;
+        }
+        const statusCode = extractHttpStatusCode(err) ?? 500;
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        res.status(statusCode).json({
+            status: "error",
+            error: errorMessage,
+        });
+    });
     return app;
 }
+function isRequestAbortedError(err) {
+    if (!err || typeof err !== "object") {
+        return false;
+    }
+    const typeValue = "type" in err && typeof err.type === "string" ? err.type : undefined;
+    if (typeValue === "request.aborted") {
+        return true;
+    }
+    if ("message" in err && typeof err.message === "string") {
+        return err.message.includes("request aborted");
+    }
+    return false;
+}
+function extractHttpStatusCode(err) {
+    if (!err || typeof err !== "object") {
+        return undefined;
+    }
+    const obj = err;
+    let statusCodeValue;
+    if (typeof obj.statusCode === "number") {
+        statusCodeValue = obj.statusCode;
+    }
+    else if (typeof obj.status === "number") {
+        statusCodeValue = obj.status;
+    }
+    if (statusCodeValue === undefined ||
+        !Number.isInteger(statusCodeValue) ||
+        statusCodeValue < 400 ||
+        statusCodeValue > 599) {
+        return undefined;
+    }
+    return statusCodeValue;
+}

package/dist/services/CollectionService.d.ts

@@ -24,6 +24,15 @@ export declare function getCollection(ctx: CollectionContextInput): Promise<{
         distance: DistanceKind;
         data_type: string;
     };
+    config: {
+        params: {
+            vectors: {
+                size: number;
+                distance: DistanceKind;
+                data_type: string;
+            };
+        };
+    };
 }>;
 export declare function deleteCollection(ctx: CollectionContextInput): Promise<{
     acknowledged: boolean;

package/dist/services/CollectionService.js

@@ -64,6 +64,15 @@ export async function getCollection(ctx) {
             distance: meta.distance,
             data_type: meta.vectorType,
         },
+        config: {
+            params: {
+                vectors: {
+                    size: meta.dimension,
+                    distance: meta.distance,
+                    data_type: meta.vectorType,
+                },
+            },
+        },
     };
 }
 export async function deleteCollection(ctx) {

package/dist/services/PointsService.d.ts

@@ -1,21 +1,19 @@
 import { type CollectionContextInput } from "./CollectionService.js";
+import type { QdrantPayload } from "../qdrant/QdrantTypes.js";
 type PointsContextInput = CollectionContextInput;
+type InternalScoredPoint = {
+    id: string;
+    score: number;
+    payload?: QdrantPayload;
+};
 export declare function upsertPoints(ctx: PointsContextInput, body: unknown): Promise<{
     upserted: number;
 }>;
 export declare function searchPoints(ctx: PointsContextInput, body: unknown): Promise<{
-    points: Array<{
-        id: string;
-        score: number;
-        payload?: Record<string, unknown>;
-    }>;
+    points: InternalScoredPoint[];
 }>;
 export declare function queryPoints(ctx: PointsContextInput, body: unknown): Promise<{
-    points: Array<{
-        id: string;
-        score: number;
-        payload?: Record<string, unknown>;
-    }>;
+    points: InternalScoredPoint[];
 }>;
 export declare function deletePoints(ctx: PointsContextInput, body: unknown): Promise<{
     deleted: number;

package/dist/services/PointsService.js

@@ -1,12 +1,70 @@
 import { UpsertPointsReq, SearchReq, DeletePointsReq } from "../types.js";
 import { ensureMetaTable } from "../ydb/schema.js";
 import { getCollectionMeta, touchCollectionLastAccess, } from "../repositories/collectionsRepo.js";
-import { deletePoints as repoDeletePoints, searchPoints as repoSearchPoints, upsertPoints as repoUpsertPoints, } from "../repositories/pointsRepo.js";
+import { deletePoints as repoDeletePoints, deletePointsByPathSegments as repoDeletePointsByPathSegments, searchPoints as repoSearchPoints, upsertPoints as repoUpsertPoints, } from "../repositories/pointsRepo.js";
 import { logger } from "../logging/logger.js";
 import { QdrantServiceError, isVectorDimensionMismatchError, } from "./errors.js";
 import { normalizeCollectionContextShared } from "./CollectionService.shared.js";
 import { resolvePointsTableAndUidOneTable } from "./CollectionService.one-table.js";
 import { normalizeSearchBodyForSearch, normalizeSearchBodyForQuery, } from "../utils/normalization.js";
+import { isRecord } from "../utils/typeGuards.js";
+function parsePathSegmentsFilterToPaths(filter) {
+    const extractMust = (must) => {
+        if (!Array.isArray(must) || must.length === 0)
+            return null;
+        const pairs = [];
+        for (const cond of must) {
+            if (!isRecord(cond))
+                return null;
+            const key = cond.key;
+            if (typeof key !== "string")
+                return null;
+            const m = /^pathSegments\.(\d+)$/.exec(key);
+            if (!m)
+                return null;
+            const idx = Number(m[1]);
+            if (!Number.isInteger(idx) || idx < 0)
+                return null;
+            const match = cond.match;
+            if (!isRecord(match))
+                return null;
+            const value = match.value;
+            if (typeof value !== "string")
+                return null;
+            pairs.push({ idx, value });
+        }
+        pairs.sort((a, b) => a.idx - b.idx);
+        // Require contiguous indexes starting from 0 to avoid ambiguous matches.
+        for (let i = 0; i < pairs.length; i += 1) {
+            if (pairs[i].idx !== i)
+                return null;
+        }
+        return pairs.map((p) => p.value);
+    };
+    if (!isRecord(filter))
+        return null;
+    const must = filter.must;
+    if (must !== undefined) {
+        const path = extractMust(must);
+        return path ? [path] : null;
+    }
+    const should = filter.should;
+    if (should !== undefined) {
+        if (!Array.isArray(should) || should.length === 0)
+            return null;
+        const paths = [];
+        for (const g of should) {
+            if (!isRecord(g))
+                return null;
+            const path = extractMust(g.must);
+            if (!path)
+                return null;
+            paths.push(path);
+        }
+        return paths;
+    }
+    return null;
+}
 export async function upsertPoints(ctx, body) {
     await ensureMetaTable();
     const normalized = normalizeCollectionContextShared(ctx.tenant, ctx.collection, ctx.apiKey, ctx.userAgent);
@@ -27,7 +85,9 @@ export async function upsertPoints(ctx, body) {
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
     let upserted;
     try {
-        upserted = await repoUpsertPoints(tableName, parsed.data.points, meta.dimension, uid);
+        // Narrow Qdrant OpenAPI types to the dense-vector subset we support.
+        const points = parsed.data.points;
+        upserted = await repoUpsertPoints(tableName, points, meta.dimension, uid);
     }
     catch (err) {
         if (isVectorDimensionMismatchError(err)) {
@@ -89,9 +149,10 @@ async function executeSearch(ctx, normalizedSearch, source) {
         distance: meta.distance,
         vectorType: meta.vectorType,
     }, `${source}: executing`);
+    const filterPaths = parsePathSegmentsFilterToPaths(normalizedSearch.filter);
     let hits;
     try {
-        hits = await repoSearchPoints(tableName, parsed.data.vector, parsed.data.top, parsed.data.with_payload, meta.distance, meta.dimension, uid);
+        hits = await repoSearchPoints(tableName, parsed.data.vector, parsed.data.top, parsed.data.with_payload, meta.distance, meta.dimension, uid, filterPaths ?? undefined);
     }
     catch (err) {
         if (isVectorDimensionMismatchError(err)) {
@@ -163,7 +224,20 @@ export async function deletePoints(ctx, body) {
         });
     }
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
-    const deleted = await repoDeletePoints(tableName, parsed.data.points, uid);
+    let deleted;
+    if ("points" in parsed.data) {
+        deleted = await repoDeletePoints(tableName, parsed.data.points, uid);
+    }
+    else {
+        const paths = parsePathSegmentsFilterToPaths(parsed.data.filter);
+        if (!paths) {
+            throw new QdrantServiceError(400, {
+                status: "error",
+                error: "unsupported delete filter: only pathSegments.N match filters with must/should are supported",
+            });
+        }
+        deleted = await repoDeletePointsByPathSegments(tableName, uid, paths);
+    }
     await touchCollectionLastAccess(normalized.metaKey);
     return { deleted };
 }

package/dist/types.d.ts

@@ -1,6 +1,18 @@
 import { z } from "zod";
-export type DistanceKind = "Cosine" | "Euclid" | "Dot" | "Manhattan";
-export type VectorType = "float";
+import type { QdrantDistance, QdrantPointId, QdrantDenseVector } from "./qdrant/QdrantTypes.js";
+export declare const DistanceKindSchema: z.ZodEnum<{
+    Cosine: "Cosine";
+    Euclid: "Euclid";
+    Dot: "Dot";
+    Manhattan: "Manhattan";
+}>;
+export type DistanceKind = QdrantDistance;
+export declare const VectorTypeSchema: z.ZodLiteral<"float">;
+export type VectorType = z.infer<typeof VectorTypeSchema>;
+export declare const PointIdSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+export type PointId = QdrantPointId;
+export declare const DenseVectorSchema: z.ZodArray<z.ZodNumber>;
+export type DenseVector = QdrantDenseVector;
 /**
  * Collection metadata from qdr__collections table.
  *
@@ -17,17 +29,25 @@ export interface CollectionMeta {
 export declare const CreateCollectionReq: z.ZodObject<{
     vectors: z.ZodObject<{
         size: z.ZodNumber;
-        distance: z.ZodType<DistanceKind>;
-        data_type: z.ZodOptional<z.ZodEnum<{
-            float: "float";
-        }>>;
+        distance: z.ZodEnum<{
+            Cosine: "Cosine";
+            Euclid: "Euclid";
+            Dot: "Dot";
+            Manhattan: "Manhattan";
+        }>;
+        data_type: z.ZodOptional<z.ZodLiteral<"float">>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const UpsertPointSchema: z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    vector: z.ZodArray<z.ZodNumber>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
 export declare const UpsertPointsReq: z.ZodObject<{
     points: z.ZodArray<z.ZodObject<{
         id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
         vector: z.ZodArray<z.ZodNumber>;
-        payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SearchReq: z.ZodObject<{
@@ -35,6 +55,50 @@ export declare const SearchReq: z.ZodObject<{
     top: z.ZodNumber;
     with_payload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
-export declare const DeletePointsReq: z.ZodObject<{
+export declare const DeletePointsByIdsReq: z.ZodObject<{
     points: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
 }, z.core.$strip>;
+export declare const DeletePointsByFilterReq: z.ZodObject<{
+    filter: z.ZodUnion<readonly [z.ZodObject<{
+        must: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            match: z.ZodObject<{
+                value: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        should: z.ZodArray<z.ZodObject<{
+            must: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                match: z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+export declare const DeletePointsReq: z.ZodUnion<readonly [z.ZodObject<{
+    points: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>, z.ZodObject<{
+    filter: z.ZodUnion<readonly [z.ZodObject<{
+        must: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            match: z.ZodObject<{
+                value: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        should: z.ZodArray<z.ZodObject<{
+            must: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                match: z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>]>;
+export type CreateCollectionBody = z.infer<typeof CreateCollectionReq>;
+export type UpsertPointsBody = z.infer<typeof UpsertPointsReq>;
+export type SearchBody = z.infer<typeof SearchReq>;
+export type DeletePointsBody = z.infer<typeof DeletePointsReq>;

package/dist/types.js

@@ -1,30 +1,56 @@
 import { z } from "zod";
+const DISTANCE_KIND_VALUES = [
+    "Cosine",
+    "Euclid",
+    "Dot",
+    "Manhattan",
+];
+export const DistanceKindSchema = z.enum(DISTANCE_KIND_VALUES);
+export const VectorTypeSchema = z.literal("float");
+export const PointIdSchema = z.union([z.string(), z.number()]);
+export const DenseVectorSchema = z.array(z.number());
 export const CreateCollectionReq = z.object({
     vectors: z.object({
         size: z.number().int().positive(),
-        distance: z.enum([
-            "Cosine",
-            "Euclid",
-            "Dot",
-            "Manhattan",
-        ]),
-        data_type: z.enum(["float"]).optional(),
+        distance: DistanceKindSchema,
+        data_type: VectorTypeSchema.optional(),
     }),
 });
+export const UpsertPointSchema = z.object({
+    id: PointIdSchema,
+    vector: DenseVectorSchema,
+    payload: z.record(z.string(), z.unknown()).optional(),
+});
 export const UpsertPointsReq = z.object({
-    points: z
-        .array(z.object({
-        id: z.union([z.string(), z.number()]),
-        vector: z.array(z.number()),
-        payload: z.record(z.string(), z.any()).optional(),
-    }))
-        .min(1),
+    points: z.array(UpsertPointSchema).min(1),
 });
 export const SearchReq = z.object({
-    vector: z.array(z.number()).min(1),
+    vector: DenseVectorSchema.min(1),
     top: z.number().int().positive().max(1000),
     with_payload: z.boolean().optional(),
 });
-export const DeletePointsReq = z.object({
-    points: z.array(z.union([z.string(), z.number()])).min(1),
+export const DeletePointsByIdsReq = z.object({
+    points: z.array(PointIdSchema).min(1),
+});
+const DeletePointsFilterCondition = z.object({
+    key: z.string(),
+    match: z.object({
+        value: z.string(),
+    }),
+});
+const DeletePointsFilterMust = z.object({
+    must: z.array(DeletePointsFilterCondition).min(1),
+});
+const DeletePointsFilter = z.union([
+    DeletePointsFilterMust,
+    z.object({
+        should: z.array(DeletePointsFilterMust).min(1),
+    }),
+]);
+export const DeletePointsByFilterReq = z.object({
+    filter: DeletePointsFilter,
 });
+export const DeletePointsReq = z.union([
+    DeletePointsByIdsReq,
+    DeletePointsByFilterReq,
+]);

package/dist/utils/normalization.d.ts

@@ -3,6 +3,7 @@ export interface SearchNormalizationResult {
     top: number | undefined;
     withPayload: boolean | undefined;
     scoreThreshold: number | undefined;
+    filter?: unknown;
 }
 export declare function isNumberArray(value: unknown): value is number[];
 export declare function extractVectorLoose(body: unknown, depth?: number): number[] | undefined;

package/dist/utils/normalization.js

@@ -1,8 +1,9 @@
+import { isRecord } from "./typeGuards.js";
 export function isNumberArray(value) {
     return Array.isArray(value) && value.every((x) => typeof x === "number");
 }
 export function extractVectorLoose(body, depth = 0) {
-    if (!body || typeof body !== "object" || depth > 3) {
+    if (!isRecord(body) || depth > 3) {
         return undefined;
     }
     const obj = body;
@@ -10,17 +11,17 @@ export function extractVectorLoose(body, depth = 0) {
         return obj.vector;
     if (isNumberArray(obj.embedding))
         return obj.embedding;
-    const query = obj.query;
+    const query = isRecord(obj.query) ? obj.query : undefined;
     if (query) {
-        const queryVector = query["vector"];
+        const queryVector = query.vector;
         if (isNumberArray(queryVector))
             return queryVector;
-        const nearest = query["nearest"];
+        const nearest = isRecord(query.nearest) ? query.nearest : undefined;
         if (nearest && isNumberArray(nearest.vector)) {
             return nearest.vector;
         }
     }
-    const nearest = obj.nearest;
+    const nearest = isRecord(obj.nearest) ? obj.nearest : undefined;
     if (nearest && isNumberArray(nearest.vector)) {
         return nearest.vector;
     }
@@ -42,7 +43,7 @@ export function extractVectorLoose(body, depth = 0) {
     return undefined;
 }
 export function normalizeSearchBodyForSearch(body) {
-    if (!body || typeof body !== "object") {
+    if (!isRecord(body)) {
         return {
             vector: undefined,
             top: undefined,
@@ -51,12 +52,12 @@ export function normalizeSearchBodyForSearch(body) {
         };
     }
     const b = body;
-    const rawVector = b["vector"];
+    const rawVector = b.vector;
     const vector = isNumberArray(rawVector) ? rawVector : undefined;
     return normalizeSearchCommon(b, vector);
 }
 export function normalizeSearchBodyForQuery(body) {
-    if (!body || typeof body !== "object") {
+    if (!isRecord(body)) {
         return {
             vector: undefined,
             top: undefined,
@@ -69,13 +70,14 @@ export function normalizeSearchBodyForQuery(body) {
     return normalizeSearchCommon(b, vector);
 }
 function normalizeSearchCommon(b, vector) {
-    const rawTop = b["top"];
-    const rawLimit = b["limit"];
+    const rawTop = b.top;
+    const rawLimit = b.limit;
     const topFromTop = typeof rawTop === "number" ? rawTop : undefined;
     const topFromLimit = typeof rawLimit === "number" ? rawLimit : undefined;
     const top = topFromTop ?? topFromLimit;
+    const filter = b.filter;
     let withPayload;
-    const rawWithPayload = b["with_payload"];
+    const rawWithPayload = b.with_payload;
     if (typeof rawWithPayload === "boolean") {
         withPayload = rawWithPayload;
     }
@@ -83,10 +85,10 @@ function normalizeSearchCommon(b, vector) {
         typeof rawWithPayload === "object") {
         withPayload = true;
     }
-    const thresholdRaw = b["score_threshold"];
+    const thresholdRaw = b.score_threshold;
     const thresholdValue = typeof thresholdRaw === "number" ? thresholdRaw : Number(thresholdRaw);
     const scoreThreshold = Number.isFinite(thresholdValue)
         ? thresholdValue
         : undefined;
-    return { vector, top, withPayload, scoreThreshold };
+    return { vector, top, withPayload, scoreThreshold, filter };
 }

package/dist/utils/retry.js

@@ -1,4 +1,5 @@
 import { logger } from "../logging/logger.js";
+import { retry as ydbRetry } from "@ydbjs/retry";
 const DEFAULT_MAX_RETRIES = 6;
 const DEFAULT_BASE_DELAY_MS = 250;
 export function isTransientYdbError(error) {
@@ -22,26 +23,35 @@ export async function withRetry(fn, options = {}) {
     const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
     const isTransient = options.isTransient ?? isTransientYdbError;
     const context = options.context ?? {};
-    let attempt = 0;
-    while (true) {
-        try {
-            return await fn();
-        }
-        catch (e) {
-            if (!isTransient(e) || attempt >= maxRetries) {
-                throw e;
-            }
-            const backoffMs = Math.floor(baseDelayMs * Math.pow(2, attempt) + Math.random() * 100);
+    // We keep the public API in terms of `maxRetries`, but @ydbjs/retry uses a budget
+    // in terms of total attempts. Convert retries→attempts.
+    const attemptsBudget = Math.max(0, maxRetries) + 1;
+    const delayByAttempt = new Map();
+    return await ydbRetry({
+        budget: attemptsBudget,
+        retry: (error) => isTransient(error),
+        strategy: (ctx) => {
+            // Preserve previous backoff shape: baseDelayMs * 2^attemptIndex + jitter(0..100)
+            // where attemptIndex started at 0 for the first retry.
+            const attemptIndex = Math.max(0, ctx.attempt - 1);
+            const delayMs = Math.floor(baseDelayMs * Math.pow(2, attemptIndex) + Math.random() * 100);
+            delayByAttempt.set(ctx.attempt, delayMs);
+            return delayMs;
+        },
+        onRetry: (ctx) => {
+            const attemptIndex = Math.max(0, ctx.attempt - 1);
             logger.warn({
                 ...context,
-                attempt,
-                backoffMs,
-                err: e instanceof Error
-                    ? e
-                    : new Error(typeof e === "string" ? e : JSON.stringify(e)),
+                attempt: attemptIndex,
+                backoffMs: delayByAttempt.get(ctx.attempt),
+                err: ctx.error instanceof Error
+                    ? ctx.error
+                    : new Error(typeof ctx.error === "string"
+                        ? ctx.error
+                        : JSON.stringify(ctx.error)),
             }, "operation aborted due to transient error; retrying");
-            await new Promise((r) => setTimeout(r, backoffMs));
-            attempt += 1;
-        }
-    }
+        },
+    }, async () => {
+        return await fn();
+    });
 }

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/utils/typeGuards.js

@@ -0,0 +1,3 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}