@wiscale/velesdb-sdk 1.3.0 → 1.5.1

package/dist/index.mjs

@@ -25,6 +25,12 @@ var NotFoundError = class extends VelesDBError {
     this.name = "NotFoundError";
   }
 };
+var BackpressureError = class extends VelesDBError {
+  constructor(message = "Server backpressure: too many requests") {
+    super(message, "BACKPRESSURE");
+    this.name = "BackpressureError";
+  }
+};
 
 // src/backends/wasm.ts
 var WasmBackend = class {
@@ -56,6 +62,33 @@ var WasmBackend = class {
       throw new ConnectionError("WASM backend not initialized");
     }
   }
+  normalizeIdString(id) {
+    const trimmed = id.trim();
+    return /^\d+$/.test(trimmed) ? trimmed : null;
+  }
+  canonicalPayloadKeyFromResultId(id) {
+    if (typeof id === "bigint") {
+      return id.toString();
+    }
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
+  canonicalPayloadKey(id) {
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
   async createCollection(name, config) {
     this.ensureInitialized();
     if (this.collections.has(name)) {
@@ -121,9 +154,13 @@ var WasmBackend = class {
         "DIMENSION_MISMATCH"
       );
     }
-    collection.store.insert(BigInt(id), vector);
     if (doc.payload) {
-      collection.payloads.set(String(doc.id), doc.payload);
+      collection.store.insert_with_payload(BigInt(id), vector, doc.payload);
+    } else {
+      collection.store.insert(BigInt(id), vector);
+    }
+    if (doc.payload) {
+      collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
     }
   }
   async insertBatch(collectionName, docs) {
@@ -133,7 +170,7 @@ var WasmBackend = class {
       throw new NotFoundError(`Collection '${collectionName}'`);
     }
     for (const doc of docs) {
-      const vectorLen = Array.isArray(doc.vector) ? doc.vector.length : doc.vector.length;
+      const vectorLen = doc.vector.length;
       if (vectorLen !== collection.config.dimension) {
         throw new VelesDBError(
           `Vector dimension mismatch for doc ${doc.id}: expected ${collection.config.dimension}, got ${vectorLen}`,
@@ -142,14 +179,22 @@ var WasmBackend = class {
       }
     }
     collection.store.reserve(docs.length);
-    const batch = docs.map((doc) => [
-      BigInt(this.toNumericId(doc.id)),
-      Array.isArray(doc.vector) ? doc.vector : Array.from(doc.vector)
-    ]);
-    collection.store.insert_batch(batch);
+    const batch = [];
+    for (const doc of docs) {
+      const id = BigInt(this.toNumericId(doc.id));
+      const vector = doc.vector instanceof Float32Array ? doc.vector : new Float32Array(doc.vector);
+      if (doc.payload) {
+        collection.store.insert_with_payload(id, vector, doc.payload);
+      } else {
+        batch.push([id, Array.from(vector)]);
+      }
+    }
+    if (batch.length > 0) {
+      collection.store.insert_batch(batch);
+    }
     for (const doc of docs) {
       if (doc.payload) {
-        collection.payloads.set(String(doc.id), doc.payload);
+        collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
       }
     }
   }
@@ -167,12 +212,43 @@ var WasmBackend = class {
       );
     }
     const k = options?.k ?? 10;
+    if (options?.sparseVector) {
+      const { indices, values } = this.sparseVectorToArrays(options.sparseVector);
+      if (queryVector.length > 0 && collection.config.dimension && collection.config.dimension > 0) {
+        const denseResults = collection.store.search(queryVector, k);
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        const sparseArray = sparseResults;
+        const denseForFuse = denseResults.map(([id, score]) => [Number(id), score]);
+        const sparseForFuse = sparseArray.map((r) => [Number(r.doc_id), r.score]);
+        const fused = this.wasmModule.hybrid_search_fuse(denseForFuse, sparseForFuse, 60);
+        return fused.slice(0, k).map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      } else {
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        return sparseResults.map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      }
+    }
     if (options?.filter) {
       const results = collection.store.search_with_filter(queryVector, k, options.filter);
       return results.map((r) => ({
         id: String(r.id),
         score: r.score,
-        payload: r.payload || collection.payloads.get(String(r.id))
+        payload: r.payload || collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.id))
       }));
     }
     const rawResults = collection.store.search(queryVector, k);
@@ -182,7 +258,7 @@ var WasmBackend = class {
         id: stringId,
         score
       };
-      const payload = collection.payloads.get(stringId);
+      const payload = collection.payloads.get(this.canonicalPayloadKeyFromResultId(id));
       if (payload) {
         result.payload = payload;
       }
@@ -206,7 +282,7 @@ var WasmBackend = class {
     const numericId = this.toNumericId(id);
     const removed = collection.store.remove(BigInt(numericId));
     if (removed) {
-      collection.payloads.delete(String(id));
+      collection.payloads.delete(this.canonicalPayloadKey(id));
     }
     return removed;
   }
@@ -216,38 +292,140 @@ var WasmBackend = class {
     if (!collection) {
       throw new NotFoundError(`Collection '${collectionName}'`);
     }
-    const payload = collection.payloads.get(String(id));
-    if (!payload) {
+    const numericId = this.toNumericId(id);
+    const point = collection.store.get(BigInt(numericId));
+    if (!point) {
       return null;
     }
+    const payload = point.payload ?? collection.payloads.get(this.canonicalPayloadKey(numericId));
     return {
-      id,
-      vector: [],
-      // Not available in current WASM impl
+      id: String(point.id),
+      vector: Array.isArray(point.vector) ? point.vector : Array.from(point.vector),
       payload
     };
   }
   async textSearch(_collection, _query, _options) {
-    throw new VelesDBError(
-      "Text search is not supported in WASM backend. Use REST backend for BM25 search.",
-      "NOT_SUPPORTED"
-    );
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const k = _options?.k ?? 10;
+    const field = void 0;
+    const raw = collection.store.text_search(_query, k, field);
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
   }
   async hybridSearch(_collection, _vector, _textQuery, _options) {
-    throw new VelesDBError(
-      "Hybrid search is not supported in WASM backend. Use REST backend for hybrid search.",
-      "NOT_SUPPORTED"
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const queryVector = _vector instanceof Float32Array ? _vector : new Float32Array(_vector);
+    const k = _options?.k ?? 10;
+    const vectorWeight = _options?.vectorWeight ?? 0.5;
+    const raw = collection.store.hybrid_search(queryVector, _textQuery, k, vectorWeight);
+    return raw.map((r) => {
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return {
+        id: String(r.id),
+        score: r.score,
+        payload: r.payload ?? collection.payloads.get(key)
+      };
+    });
+  }
+  async query(_collection, _queryString, _params, _options) {
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const paramsVector = _params?.q;
+    if (!Array.isArray(paramsVector) && !(paramsVector instanceof Float32Array)) {
+      throw new VelesDBError(
+        "WASM query() expects params.q to contain the query embedding vector.",
+        "BAD_REQUEST"
+      );
+    }
+    const requestedK = _params?.k;
+    const k = typeof requestedK === "number" && Number.isInteger(requestedK) && requestedK > 0 ? requestedK : 10;
+    const raw = collection.store.query(
+      paramsVector instanceof Float32Array ? paramsVector : new Float32Array(paramsVector),
+      k
     );
+    return {
+      results: raw.map((r) => ({
+        nodeId: r.nodeId ?? r.node_id,
+        vectorScore: r.vectorScore ?? r.vector_score ?? null,
+        graphScore: r.graphScore ?? r.graph_score ?? null,
+        fusedScore: r.fusedScore ?? r.fused_score ?? 0,
+        bindings: r.bindings ?? {},
+        columnData: r.columnData ?? r.column_data ?? null
+      })),
+      stats: {
+        executionTimeMs: 0,
+        strategy: "wasm-query",
+        scannedNodes: raw.length
+      }
+    };
   }
-  async query(_queryString, _params) {
+  async multiQuerySearch(_collection, _vectors, _options) {
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    if (_vectors.length === 0) {
+      return [];
+    }
+    const numVectors = _vectors.length;
+    const dimension = collection.config.dimension ?? 0;
+    const flat = new Float32Array(numVectors * dimension);
+    _vectors.forEach((vector, idx) => {
+      const src = vector instanceof Float32Array ? vector : new Float32Array(vector);
+      flat.set(src, idx * dimension);
+    });
+    const strategy = _options?.fusion ?? "rrf";
+    if (strategy === "weighted") {
+      throw new VelesDBError(
+        "Fusion strategy 'weighted' is not supported in WASM backend.",
+        "NOT_SUPPORTED"
+      );
+    }
+    const raw = collection.store.multi_query_search(
+      flat,
+      numVectors,
+      _options?.k ?? 10,
+      strategy,
+      _options?.fusionParams?.k ?? 60
+    );
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
+  }
+  async queryExplain(_queryString, _params) {
+    this.ensureInitialized();
     throw new VelesDBError(
-      "VelesQL queries are not supported in WASM backend. Use REST backend for query support.",
+      "Query explain is not supported in WASM backend. Use REST backend for EXPLAIN support.",
       "NOT_SUPPORTED"
     );
   }
-  async multiQuerySearch(_collection, _vectors, _options) {
+  async collectionSanity(_collection) {
+    this.ensureInitialized();
     throw new VelesDBError(
-      "Multi-query fusion is not supported in WASM backend. Use REST backend for MQF search.",
+      "Collection sanity endpoint is not supported in WASM backend. Use REST backend for diagnostics.",
       "NOT_SUPPORTED"
     );
   }
@@ -273,13 +451,25 @@ var WasmBackend = class {
     this.collections.clear();
     this._initialized = false;
   }
+  sparseVectorToArrays(sv) {
+    const indices = [];
+    const values = [];
+    for (const [k, v] of Object.entries(sv)) {
+      indices.push(Number(k));
+      values.push(v);
+    }
+    return { indices, values };
+  }
   toNumericId(id) {
     if (typeof id === "number") {
       return id;
     }
-    const parsed = parseInt(id, 10);
-    if (!isNaN(parsed)) {
-      return parsed;
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      const parsed = Number(normalized);
+      if (Number.isSafeInteger(parsed)) {
+        return parsed;
+      }
     }
     let hash = 0;
     for (let i = 0; i < id.length; i++) {
@@ -343,6 +533,23 @@ var WasmBackend = class {
       "NOT_SUPPORTED"
     );
   }
+  // ========================================================================
+  // Sparse / PQ / Streaming (v1.5)
+  // ========================================================================
+  async trainPq(_collection, _options) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "PQ training is not available in WASM mode. Use REST backend for PQ training.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async streamInsert(_collection, _docs) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Streaming insert is not available in WASM mode. Use REST backend for streaming.",
+      "NOT_SUPPORTED"
+    );
+  }
 };
 
 // src/backends/rest.ts
@@ -405,11 +612,52 @@ var RestBackend = class {
       return {};
     }
     const payload = data;
-    const code = typeof payload.code === "string" ? payload.code : void 0;
-    const messageField = payload.message ?? payload.error;
+    const nestedError = payload.error && typeof payload.error === "object" ? payload.error : void 0;
+    const codeField = nestedError?.code ?? payload.code;
+    const code = typeof codeField === "string" ? codeField : void 0;
+    const messageField = nestedError?.message ?? payload.message ?? payload.error;
     const message = typeof messageField === "string" ? messageField : void 0;
     return { code, message };
   }
+  /**
+   * Parse node ID safely to handle u64 values above Number.MAX_SAFE_INTEGER.
+   * Returns bigint for large values, number for safe values.
+   */
+  parseNodeId(value) {
+    if (value === null || value === void 0) {
+      return 0;
+    }
+    if (typeof value === "bigint") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const num = Number(value);
+      if (num > Number.MAX_SAFE_INTEGER) {
+        return BigInt(value);
+      }
+      return num;
+    }
+    if (typeof value === "number") {
+      if (value > Number.MAX_SAFE_INTEGER) {
+        return value;
+      }
+      return value;
+    }
+    return 0;
+  }
+  parseRestPointId(id) {
+    if (typeof id !== "number" || !Number.isFinite(id) || id < 0 || !Number.isInteger(id) || id > Number.MAX_SAFE_INTEGER) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER}). Received: ${String(id)}`
+      );
+    }
+    return id;
+  }
+  isLikelyAggregationQuery(query) {
+    return /\bGROUP\s+BY\b|\bHAVING\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bMIN\s*\(|\bMAX\s*\(/i.test(
+      query
+    );
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -498,14 +746,17 @@ var RestBackend = class {
   }
   async insert(collection, doc) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(doc.id);
     const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
     const response = await this.request(
       "POST",
-      `/collections/${encodeURIComponent(collection)}/vectors`,
+      `/collections/${encodeURIComponent(collection)}/points`,
       {
-        id: doc.id,
-        vector,
-        payload: doc.payload
+        points: [{
+          id: restId,
+          vector,
+          payload: doc.payload
+        }]
       }
     );
     if (response.error) {
@@ -518,14 +769,14 @@ var RestBackend = class {
   async insertBatch(collection, docs) {
     this.ensureInitialized();
     const vectors = docs.map((doc) => ({
-      id: doc.id,
+      id: this.parseRestPointId(doc.id),
       vector: doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector,
       payload: doc.payload
     }));
     const response = await this.request(
       "POST",
-      `/collections/${encodeURIComponent(collection)}/vectors/batch`,
-      { vectors }
+      `/collections/${encodeURIComponent(collection)}/points`,
+      { points: vectors }
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -534,18 +785,29 @@ var RestBackend = class {
       throw new VelesDBError(response.error.message, response.error.code);
     }
   }
+  sparseVectorToRestFormat(sv) {
+    const result = {};
+    for (const [k, v] of Object.entries(sv)) {
+      result[String(k)] = v;
+    }
+    return result;
+  }
   async search(collection, query, options) {
     this.ensureInitialized();
     const queryVector = query instanceof Float32Array ? Array.from(query) : query;
+    const body = {
+      vector: queryVector,
+      top_k: options?.k ?? 10,
+      filter: options?.filter,
+      include_vectors: options?.includeVectors ?? false
+    };
+    if (options?.sparseVector) {
+      body.sparse_vector = this.sparseVectorToRestFormat(options.sparseVector);
+    }
     const response = await this.request(
       "POST",
       `/collections/${encodeURIComponent(collection)}/search`,
-      {
-        vector: queryVector,
-        k: options?.k ?? 10,
-        filter: options?.filter,
-        include_vectors: options?.includeVectors ?? false
-      }
+      body
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -553,7 +815,7 @@ var RestBackend = class {
       }
       throw new VelesDBError(response.error.message, response.error.code);
     }
-    return response.data ?? [];
+    return response.data?.results ?? [];
   }
   async searchBatch(collection, searches) {
     this.ensureInitialized();
@@ -577,9 +839,10 @@ var RestBackend = class {
   }
   async delete(collection, id) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(id);
     const response = await this.request(
       "DELETE",
-      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -591,9 +854,10 @@ var RestBackend = class {
   }
   async get(collection, id) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(id);
     const response = await this.request(
       "GET",
-      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -644,11 +908,63 @@ var RestBackend = class {
     }
     return response.data?.results ?? [];
   }
-  async query(queryString, params) {
+  async query(collection, queryString, params, options) {
     this.ensureInitialized();
+    const endpoint = this.isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
     const response = await this.request(
       "POST",
-      "/query",
+      endpoint,
+      {
+        query: queryString,
+        params: params ?? {},
+        collection,
+        timeout_ms: options?.timeoutMs,
+        stream: options?.stream ?? false
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    const rawData = response.data;
+    if (rawData && Object.prototype.hasOwnProperty.call(rawData, "result")) {
+      return {
+        result: rawData.result,
+        stats: {
+          executionTimeMs: rawData.timing_ms ?? 0,
+          strategy: "aggregation",
+          scannedNodes: 0
+        }
+      };
+    }
+    return {
+      results: (rawData?.results ?? []).map((r) => ({
+        // Server returns `id` (u64), map to nodeId with precision handling
+        nodeId: this.parseNodeId(r.id ?? r.node_id ?? r.nodeId),
+        // Server returns `score`, map to vectorScore (primary score for SELECT queries)
+        vectorScore: r.score ?? r.vector_score ?? r.vectorScore,
+        // graph_score not returned by SELECT queries, only by future MATCH queries
+        graphScore: r.graph_score ?? r.graphScore,
+        // Use score as fusedScore for compatibility
+        fusedScore: r.score ?? r.fused_score ?? r.fusedScore ?? 0,
+        // payload maps to bindings for compatibility
+        bindings: r.payload ?? r.bindings ?? {},
+        columnData: r.column_data ?? r.columnData
+      })),
+      stats: {
+        executionTimeMs: rawData?.timing_ms ?? 0,
+        strategy: "select",
+        scannedNodes: rawData?.rows_returned ?? 0
+      }
+    };
+  }
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      "/query/explain",
       {
         query: queryString,
         params: params ?? {}
@@ -657,7 +973,68 @@ var RestBackend = class {
     if (response.error) {
       throw new VelesDBError(response.error.message, response.error.code);
     }
-    return response.data?.results ?? [];
+    const data = response.data;
+    return {
+      query: data.query,
+      queryType: data.query_type,
+      collection: data.collection,
+      plan: data.plan.map((step) => ({
+        step: step.step,
+        operation: step.operation,
+        description: step.description,
+        estimatedRows: step.estimated_rows
+      })),
+      estimatedCost: {
+        usesIndex: data.estimated_cost.uses_index,
+        indexName: data.estimated_cost.index_name,
+        selectivity: data.estimated_cost.selectivity,
+        complexity: data.estimated_cost.complexity
+      },
+      features: {
+        hasVectorSearch: data.features.has_vector_search,
+        hasFilter: data.features.has_filter,
+        hasOrderBy: data.features.has_order_by,
+        hasGroupBy: data.features.has_group_by,
+        hasAggregation: data.features.has_aggregation,
+        hasJoin: data.features.has_join,
+        hasFusion: data.features.has_fusion,
+        limit: data.features.limit,
+        offset: data.features.offset
+      }
+    };
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/sanity`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    const data = response.data;
+    return {
+      collection: data.collection,
+      dimension: data.dimension,
+      metric: data.metric,
+      pointCount: data.point_count,
+      isEmpty: data.is_empty,
+      checks: {
+        hasVectors: data.checks.has_vectors,
+        searchReady: data.checks.search_ready,
+        dimensionConfigured: data.checks.dimension_configured
+      },
+      diagnostics: {
+        searchRequestsTotal: data.diagnostics.search_requests_total,
+        dimensionMismatchTotal: data.diagnostics.dimension_mismatch_total,
+        emptySearchResultsTotal: data.diagnostics.empty_search_results_total,
+        filterParseErrorsTotal: data.diagnostics.filter_parse_errors_total
+      },
+      hints: data.hints ?? []
+    };
   }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
@@ -672,6 +1049,9 @@ var RestBackend = class {
         top_k: options?.k ?? 10,
         strategy: options?.fusion ?? "rrf",
         rrf_k: options?.fusionParams?.k ?? 60,
+        avg_weight: options?.fusionParams?.avgWeight,
+        max_weight: options?.fusionParams?.maxWeight,
+        hit_weight: options?.fusionParams?.hitWeight,
         filter: options?.filter
       }
     );
@@ -710,6 +1090,81 @@ var RestBackend = class {
       throw new VelesDBError(response.error.message, response.error.code);
     }
   }
+  // ========================================================================
+  // Sparse / PQ / Streaming (v1.5)
+  // ========================================================================
+  async trainPq(collection, options) {
+    this.ensureInitialized();
+    const m = options?.m ?? 8;
+    const k = options?.k ?? 256;
+    const withClause = options?.opq ? `WITH (m=${m}, k=${k}, opq=true)` : `WITH (m=${m}, k=${k})`;
+    const queryString = `TRAIN QUANTIZER ON ${collection} ${withClause}`;
+    const response = await this.request(
+      "POST",
+      "/query",
+      { query: queryString }
+    );
+    if (response.error) {
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data?.message ?? "PQ training initiated";
+  }
+  async streamInsert(collection, docs) {
+    this.ensureInitialized();
+    for (const doc of docs) {
+      const restId = this.parseRestPointId(doc.id);
+      const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
+      const body = {
+        id: restId,
+        vector,
+        payload: doc.payload
+      };
+      if (doc.sparseVector) {
+        body.sparse_vector = this.sparseVectorToRestFormat(doc.sparseVector);
+      }
+      const url = `${this.baseUrl}/collections/${encodeURIComponent(collection)}/stream/insert`;
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.status === 429) {
+          throw new BackpressureError();
+        }
+        if (!response.ok && response.status !== 202) {
+          const data = await response.json().catch(() => ({}));
+          const errorPayload = this.extractErrorPayload(data);
+          throw new VelesDBError(
+            errorPayload.message ?? `HTTP ${response.status}`,
+            errorPayload.code ?? this.mapStatusToErrorCode(response.status)
+          );
+        }
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof BackpressureError || error instanceof VelesDBError) {
+          throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new ConnectionError("Request timeout");
+        }
+        throw new ConnectionError(
+          `Stream insert failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+          error instanceof Error ? error : void 0
+        );
+      }
+    }
+  }
   async close() {
     this._initialized = false;
   }
@@ -1026,6 +1481,18 @@ var VelesDB = class {
     if (!Array.isArray(doc.vector) && !(doc.vector instanceof Float32Array)) {
       throw new ValidationError("Vector must be an array or Float32Array");
     }
+    if (this.config.backend === "rest" && (typeof doc.id !== "number" || !Number.isInteger(doc.id) || doc.id < 0 || doc.id > Number.MAX_SAFE_INTEGER)) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
+      );
+    }
+  }
+  validateRestPointId(id) {
+    if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
+      );
+    }
   }
   /**
    * Search for similar vectors
@@ -1070,6 +1537,7 @@ var VelesDB = class {
    */
   async delete(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.delete(collection, id);
   }
   /**
@@ -1081,6 +1549,7 @@ var VelesDB = class {
    */
   async get(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.get(collection, id);
   }
   /**
@@ -1118,18 +1587,36 @@ var VelesDB = class {
     return this.backend.hybridSearch(collection, vector, textQuery, options);
   }
   /**
-   * Execute a VelesQL query
+   * Execute a VelesQL multi-model query (EPIC-031 US-011)
+   * 
+   * Supports hybrid vector + graph queries with VelesQL syntax.
    * 
+   * @param collection - Collection name
    * @param queryString - VelesQL query string
-   * @param params - Optional query parameters
-   * @returns Query results
+   * @param params - Query parameters (vectors, scalars)
+   * @param options - Query options (timeout, streaming)
+   * @returns Query response with results and execution stats
+   * 
+   * @example
+   * ```typescript
+   * const response = await db.query('docs', `
+   *   MATCH (d:Doc) WHERE vector NEAR $q LIMIT 20
+   * `, { q: queryVector });
+   * 
+   * for (const r of response.results) {
+   *   console.log(`Node ${r.nodeId}: ${r.fusedScore}`);
+   * }
+   * ```
    */
-  async query(queryString, params) {
+  async query(collection, queryString, params, options) {
     this.ensureInitialized();
+    if (!collection || typeof collection !== "string") {
+      throw new ValidationError("Collection name must be a non-empty string");
+    }
     if (!queryString || typeof queryString !== "string") {
       throw new ValidationError("Query string must be a non-empty string");
     }
-    return this.backend.query(queryString, params);
+    return this.backend.query(collection, queryString, params, options);
   }
   /**
    * Multi-query fusion search combining results from multiple query vectors
@@ -1158,6 +1645,20 @@ var VelesDB = class {
    * });
    * ```
    */
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    if (!queryString || typeof queryString !== "string") {
+      throw new ValidationError("Query string must be a non-empty string");
+    }
+    return this.backend.queryExplain(queryString, params);
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    if (!collection || typeof collection !== "string") {
+      throw new ValidationError("Collection name must be a non-empty string");
+    }
+    return this.backend.collectionSanity(collection);
+  }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
     if (!Array.isArray(vectors) || vectors.length === 0) {
@@ -1170,9 +1671,39 @@ var VelesDB = class {
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
+  /**
+   * Train Product Quantization on a collection
+   *
+   * @param collection - Collection name
+   * @param options - PQ training options (m, k, opq)
+   * @returns Server response message
+   */
+  async trainPq(collection, options) {
+    this.ensureInitialized();
+    return this.backend.trainPq(collection, options);
+  }
+  /**
+   * Stream-insert documents with backpressure support
+   *
+   * Sends documents sequentially to respect server backpressure.
+   * Throws BackpressureError on 429 responses.
+   *
+   * @param collection - Collection name
+   * @param docs - Documents to insert
+   */
+  async streamInsert(collection, docs) {
+    this.ensureInitialized();
+    if (!Array.isArray(docs)) {
+      throw new ValidationError("Documents must be an array");
+    }
+    for (const doc of docs) {
+      this.validateDocument(doc);
+    }
+    await this.backend.streamInsert(collection, docs);
+  }
   /**
    * Check if a collection is empty
-   * 
+   *
    * @param collection - Collection name
    * @returns true if empty, false otherwise
    */
@@ -1367,12 +1898,317 @@ var VelesDB = class {
     return this.backend.getNodeDegree(collection, nodeId);
   }
 };
+
+// src/query-builder.ts
+var VelesQLBuilder = class _VelesQLBuilder {
+  constructor(state) {
+    this.state = {
+      matchClauses: state?.matchClauses ?? [],
+      whereClauses: state?.whereClauses ?? [],
+      whereOperators: state?.whereOperators ?? [],
+      params: state?.params ?? {},
+      limitValue: state?.limitValue,
+      offsetValue: state?.offsetValue,
+      orderByClause: state?.orderByClause,
+      returnClause: state?.returnClause,
+      fusionOptions: state?.fusionOptions,
+      currentNode: state?.currentNode,
+      pendingRel: state?.pendingRel
+    };
+  }
+  clone(updates) {
+    return new _VelesQLBuilder({
+      ...this.state,
+      matchClauses: [...this.state.matchClauses],
+      whereClauses: [...this.state.whereClauses],
+      whereOperators: [...this.state.whereOperators],
+      params: { ...this.state.params },
+      ...updates
+    });
+  }
+  /**
+   * Start a MATCH clause with a node pattern
+   * 
+   * @param alias - Node alias (e.g., 'n', 'person')
+   * @param label - Optional node label(s)
+   */
+  match(alias, label) {
+    const labelStr = this.formatLabel(label);
+    const nodePattern = `(${alias}${labelStr})`;
+    return this.clone({
+      matchClauses: [...this.state.matchClauses, nodePattern],
+      currentNode: alias
+    });
+  }
+  /**
+   * Add a relationship pattern
+   * 
+   * @param type - Relationship type (e.g., 'KNOWS', 'FOLLOWS')
+   * @param alias - Optional relationship alias
+   * @param options - Relationship options (direction, hops)
+   */
+  rel(type, alias, options) {
+    return this.clone({
+      pendingRel: { type, alias, options }
+    });
+  }
+  /**
+   * Complete a relationship pattern with target node
+   * 
+   * @param alias - Target node alias
+   * @param label - Optional target node label(s)
+   */
+  to(alias, label) {
+    if (!this.state.pendingRel) {
+      throw new Error("to() must be called after rel()");
+    }
+    const { type, alias: relAlias, options } = this.state.pendingRel;
+    const direction = options?.direction ?? "outgoing";
+    const labelStr = this.formatLabel(label);
+    const relPattern = this.formatRelationship(type, relAlias, options);
+    const targetNode = `(${alias}${labelStr})`;
+    let fullPattern;
+    switch (direction) {
+      case "incoming":
+        fullPattern = `<-${relPattern}-${targetNode}`;
+        break;
+      case "both":
+        fullPattern = `-${relPattern}-${targetNode}`;
+        break;
+      default:
+        fullPattern = `-${relPattern}->${targetNode}`;
+    }
+    const lastMatch = this.state.matchClauses[this.state.matchClauses.length - 1];
+    const updatedMatch = lastMatch + fullPattern;
+    const newMatchClauses = [...this.state.matchClauses.slice(0, -1), updatedMatch];
+    return this.clone({
+      matchClauses: newMatchClauses,
+      currentNode: alias,
+      pendingRel: void 0
+    });
+  }
+  /**
+   * Add a WHERE clause
+   * 
+   * @param condition - WHERE condition
+   * @param params - Optional parameters
+   */
+  where(condition, params) {
+    const newParams = params ? { ...this.state.params, ...params } : this.state.params;
+    return this.clone({
+      whereClauses: [...this.state.whereClauses, condition],
+      whereOperators: [...this.state.whereOperators],
+      params: newParams
+    });
+  }
+  /**
+   * Add an AND WHERE clause
+   * 
+   * @param condition - WHERE condition
+   * @param params - Optional parameters
+   */
+  andWhere(condition, params) {
+    const newParams = params ? { ...this.state.params, ...params } : this.state.params;
+    return this.clone({
+      whereClauses: [...this.state.whereClauses, condition],
+      whereOperators: [...this.state.whereOperators, "AND"],
+      params: newParams
+    });
+  }
+  /**
+   * Add an OR WHERE clause
+   * 
+   * @param condition - WHERE condition
+   * @param params - Optional parameters
+   */
+  orWhere(condition, params) {
+    const newParams = params ? { ...this.state.params, ...params } : this.state.params;
+    return this.clone({
+      whereClauses: [...this.state.whereClauses, condition],
+      whereOperators: [...this.state.whereOperators, "OR"],
+      params: newParams
+    });
+  }
+  /**
+   * Add a vector NEAR clause for similarity search
+   * 
+   * @param paramName - Parameter name (e.g., '$query', '$embedding')
+   * @param vector - Vector data
+   * @param options - NEAR options (topK)
+   */
+  nearVector(paramName, vector, options) {
+    const cleanParamName = paramName.startsWith("$") ? paramName.slice(1) : paramName;
+    const topKSuffix = options?.topK ? ` TOP ${options.topK}` : "";
+    const condition = `vector NEAR $${cleanParamName}${topKSuffix}`;
+    const newParams = { ...this.state.params, [cleanParamName]: vector };
+    if (this.state.whereClauses.length === 0) {
+      return this.clone({
+        whereClauses: [condition],
+        params: newParams
+      });
+    }
+    return this.clone({
+      whereClauses: [...this.state.whereClauses, condition],
+      whereOperators: [...this.state.whereOperators, "AND"],
+      params: newParams
+    });
+  }
+  /**
+   * Add LIMIT clause
+   * 
+   * @param value - Maximum number of results
+   */
+  limit(value) {
+    if (value < 0) {
+      throw new Error("LIMIT must be non-negative");
+    }
+    return this.clone({ limitValue: value });
+  }
+  /**
+   * Add OFFSET clause
+   * 
+   * @param value - Number of results to skip
+   */
+  offset(value) {
+    if (value < 0) {
+      throw new Error("OFFSET must be non-negative");
+    }
+    return this.clone({ offsetValue: value });
+  }
+  /**
+   * Add ORDER BY clause
+   * 
+   * @param field - Field to order by
+   * @param direction - Sort direction (ASC or DESC)
+   */
+  orderBy(field, direction) {
+    const orderClause = direction ? `${field} ${direction}` : field;
+    return this.clone({ orderByClause: orderClause });
+  }
+  /**
+   * Add RETURN clause with specific fields
+   * 
+   * @param fields - Fields to return (array or object with aliases)
+   */
+  return(fields) {
+    let returnClause;
+    if (Array.isArray(fields)) {
+      returnClause = fields.join(", ");
+    } else {
+      returnClause = Object.entries(fields).map(([field, alias]) => `${field} AS ${alias}`).join(", ");
+    }
+    return this.clone({ returnClause });
+  }
+  /**
+   * Add RETURN * clause
+   */
+  returnAll() {
+    return this.clone({ returnClause: "*" });
+  }
+  /**
+   * Set fusion strategy for hybrid queries
+   * 
+   * @param strategy - Fusion strategy
+   * @param options - Fusion parameters
+   */
+  fusion(strategy, options) {
+    return this.clone({
+      fusionOptions: {
+        strategy,
+        ...options
+      }
+    });
+  }
+  /**
+   * Get the fusion options
+   */
+  getFusionOptions() {
+    return this.state.fusionOptions;
+  }
+  /**
+   * Get all parameters
+   */
+  getParams() {
+    return { ...this.state.params };
+  }
+  /**
+   * Build the VelesQL query string
+   */
+  toVelesQL() {
+    if (this.state.matchClauses.length === 0) {
+      throw new Error("Query must have at least one MATCH clause");
+    }
+    const parts = [];
+    parts.push(`MATCH ${this.state.matchClauses.join(", ")}`);
+    if (this.state.whereClauses.length > 0) {
+      const whereStr = this.buildWhereClause();
+      parts.push(`WHERE ${whereStr}`);
+    }
+    if (this.state.orderByClause) {
+      parts.push(`ORDER BY ${this.state.orderByClause}`);
+    }
+    if (this.state.limitValue !== void 0) {
+      parts.push(`LIMIT ${this.state.limitValue}`);
+    }
+    if (this.state.offsetValue !== void 0) {
+      parts.push(`OFFSET ${this.state.offsetValue}`);
+    }
+    if (this.state.returnClause) {
+      parts.push(`RETURN ${this.state.returnClause}`);
+    }
+    if (this.state.fusionOptions) {
+      parts.push(`/* FUSION ${this.state.fusionOptions.strategy} */`);
+    }
+    return parts.join(" ");
+  }
+  formatLabel(label) {
+    if (!label) return "";
+    if (Array.isArray(label)) {
+      return label.map((l) => `:${l}`).join("");
+    }
+    return `:${label}`;
+  }
+  formatRelationship(type, alias, options) {
+    const aliasStr = alias ? alias : "";
+    const hopsStr = this.formatHops(options);
+    if (alias) {
+      return `[${aliasStr}:${type}${hopsStr}]`;
+    }
+    return `[:${type}${hopsStr}]`;
+  }
+  formatHops(options) {
+    if (!options?.minHops && !options?.maxHops) return "";
+    const min = options.minHops ?? 1;
+    const max = options.maxHops ?? "";
+    return `*${min}..${max}`;
+  }
+  buildWhereClause() {
+    if (this.state.whereClauses.length === 0) return "";
+    const first = this.state.whereClauses[0];
+    if (!first) return "";
+    let result = first;
+    for (let i = 1; i < this.state.whereClauses.length; i++) {
+      const operator = this.state.whereOperators[i - 1] ?? "AND";
+      const clause = this.state.whereClauses[i];
+      if (clause) {
+        result += ` ${operator} ${clause}`;
+      }
+    }
+    return result;
+  }
+};
+function velesql() {
+  return new VelesQLBuilder();
+}
 export {
+  BackpressureError,
   ConnectionError,
   NotFoundError,
   RestBackend,
   ValidationError,
   VelesDB,
   VelesDBError,
-  WasmBackend
+  VelesQLBuilder,
+  WasmBackend,
+  velesql
 };