@wiscale/velesdb-sdk 1.3.0 → 1.4.1

package/dist/index.js

@@ -36,7 +36,9 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   VelesDB: () => VelesDB,
   VelesDBError: () => VelesDBError,
-  WasmBackend: () => WasmBackend
+  VelesQLBuilder: () => VelesQLBuilder,
+  WasmBackend: () => WasmBackend,
+  velesql: () => velesql
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -175,7 +177,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}`,
@@ -281,7 +283,7 @@ var WasmBackend = class {
       "NOT_SUPPORTED"
     );
   }
-  async query(_queryString, _params) {
+  async query(_collection, _queryString, _params, _options) {
     throw new VelesDBError(
       "VelesQL queries are not supported in WASM backend. Use REST backend for query support.",
       "NOT_SUPPORTED"
@@ -452,6 +454,32 @@ var RestBackend = class {
     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;
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -543,11 +571,13 @@ var RestBackend = class {
     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: doc.id,
+          vector,
+          payload: doc.payload
+        }]
       }
     );
     if (response.error) {
@@ -566,8 +596,8 @@ var RestBackend = class {
     }));
     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") {
@@ -621,7 +651,7 @@ var RestBackend = class {
     this.ensureInitialized();
     const response = await this.request(
       "DELETE",
-      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -635,7 +665,7 @@ var RestBackend = class {
     this.ensureInitialized();
     const response = await this.request(
       "GET",
-      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -686,7 +716,7 @@ var RestBackend = class {
     }
     return response.data?.results ?? [];
   }
-  async query(queryString, params) {
+  async query(collection, queryString, params, _options) {
     this.ensureInitialized();
     const response = await this.request(
       "POST",
@@ -697,9 +727,32 @@ var RestBackend = class {
       }
     );
     if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
       throw new VelesDBError(response.error.message, response.error.code);
     }
-    return response.data?.results ?? [];
+    const rawData = response.data;
+    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 multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
@@ -1160,18 +1213,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
@@ -1409,6 +1480,308 @@ 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();
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectionError,
@@ -1417,5 +1790,7 @@ var VelesDB = class {
   ValidationError,
   VelesDB,
   VelesDBError,
-  WasmBackend
+  VelesQLBuilder,
+  WasmBackend,
+  velesql
 });