@wiscale/velesdb-sdk 1.2.0 → 1.4.1

package/dist/index.mjs

@@ -133,7 +133,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}`,
@@ -239,7 +239,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"
@@ -289,6 +289,60 @@ var WasmBackend = class {
     }
     return Math.abs(hash);
   }
+  // ========================================================================
+  // Index Management (EPIC-009) - Stubs for WASM backend
+  // Note: Full implementation requires velesdb-wasm support
+  // ========================================================================
+  async createIndex(_collection, _options) {
+    this.ensureInitialized();
+    throw new Error(
+      "WasmBackend: createIndex is not yet supported. Index operations require the REST backend with velesdb-server."
+    );
+  }
+  async listIndexes(_collection) {
+    this.ensureInitialized();
+    return [];
+  }
+  async hasIndex(_collection, _label, _property) {
+    this.ensureInitialized();
+    return false;
+  }
+  async dropIndex(_collection, _label, _property) {
+    this.ensureInitialized();
+    return false;
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041) - Stubs for WASM backend
+  // Note: Graph operations require server-side EdgeStore
+  // ========================================================================
+  async addEdge(_collection, _edge) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async getEdges(_collection, _options) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async traverseGraph(_collection, _request) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Graph traversal is not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async getNodeDegree(_collection, _nodeId) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Graph degree query is not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
 };
 
 // src/backends/rest.ts
@@ -324,6 +378,64 @@ var RestBackend = class {
       throw new ConnectionError("REST backend not initialized");
     }
   }
+  mapStatusToErrorCode(status) {
+    switch (status) {
+      case 400:
+        return "BAD_REQUEST";
+      case 401:
+        return "UNAUTHORIZED";
+      case 403:
+        return "FORBIDDEN";
+      case 404:
+        return "NOT_FOUND";
+      case 409:
+        return "CONFLICT";
+      case 429:
+        return "RATE_LIMITED";
+      case 500:
+        return "INTERNAL_ERROR";
+      case 503:
+        return "SERVICE_UNAVAILABLE";
+      default:
+        return "UNKNOWN_ERROR";
+    }
+  }
+  extractErrorPayload(data) {
+    if (!data || typeof data !== "object") {
+      return {};
+    }
+    const payload = data;
+    const code = typeof payload.code === "string" ? payload.code : void 0;
+    const messageField = 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;
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -342,12 +454,13 @@ var RestBackend = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      const data = await response.json();
+      const data = await response.json().catch(() => ({}));
       if (!response.ok) {
+        const errorPayload = this.extractErrorPayload(data);
         return {
           error: {
-            code: data.code ?? "UNKNOWN_ERROR",
-            message: data.message ?? `HTTP ${response.status}`
+            code: errorPayload.code ?? this.mapStatusToErrorCode(response.status),
+            message: errorPayload.message ?? `HTTP ${response.status}`
           }
         };
       }
@@ -414,11 +527,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) {
@@ -437,8 +552,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") {
@@ -492,7 +607,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") {
@@ -506,7 +621,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") {
@@ -557,7 +672,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",
@@ -568,9 +683,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();
@@ -583,8 +721,8 @@ var RestBackend = class {
       {
         vectors: formattedVectors,
         top_k: options?.k ?? 10,
-        fusion: options?.fusion ?? "rrf",
-        fusion_params: options?.fusionParams ?? { k: 60 },
+        strategy: options?.fusion ?? "rrf",
+        rrf_k: options?.fusionParams?.k ?? 60,
         filter: options?.filter
       }
     );
@@ -626,6 +764,158 @@ var RestBackend = class {
   async close() {
     this._initialized = false;
   }
+  // ========================================================================
+  // Index Management (EPIC-009)
+  // ========================================================================
+  async createIndex(collection, options) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/indexes`,
+      {
+        label: options.label,
+        property: options.property,
+        index_type: options.indexType ?? "hash"
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async listIndexes(collection) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/indexes`
+    );
+    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?.indexes ?? []).map((idx) => ({
+      label: idx.label,
+      property: idx.property,
+      indexType: idx.index_type,
+      cardinality: idx.cardinality,
+      memoryBytes: idx.memory_bytes
+    }));
+  }
+  async hasIndex(collection, label, property) {
+    const indexes = await this.listIndexes(collection);
+    return indexes.some((idx) => idx.label === label && idx.property === property);
+  }
+  async dropIndex(collection, label, property) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "DELETE",
+      `/collections/${encodeURIComponent(collection)}/indexes/${encodeURIComponent(label)}/${encodeURIComponent(property)}`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        return false;
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data?.dropped ?? true;
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041)
+  // ========================================================================
+  async addEdge(collection, edge) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/graph/edges`,
+      {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        label: edge.label,
+        properties: edge.properties ?? {}
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async getEdges(collection, options) {
+    this.ensureInitialized();
+    const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/graph/edges${queryParams}`
+    );
+    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?.edges ?? [];
+  }
+  // ========================================================================
+  // Graph Traversal (EPIC-016 US-050)
+  // ========================================================================
+  async traverseGraph(collection, request) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/graph/traverse`,
+      {
+        source: request.source,
+        strategy: request.strategy ?? "bfs",
+        max_depth: request.maxDepth ?? 3,
+        limit: request.limit ?? 100,
+        cursor: request.cursor,
+        rel_types: request.relTypes ?? []
+      }
+    );
+    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 {
+      results: data.results.map((r) => ({
+        targetId: r.target_id,
+        depth: r.depth,
+        path: r.path
+      })),
+      nextCursor: data.next_cursor ?? void 0,
+      hasMore: data.has_more,
+      stats: {
+        visited: data.stats.visited,
+        depthReached: data.stats.depth_reached
+      }
+    };
+  }
+  async getNodeDegree(collection, nodeId) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/graph/nodes/${nodeId}/degree`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return {
+      inDegree: response.data?.in_degree ?? 0,
+      outDegree: response.data?.out_degree ?? 0
+    };
+  }
 };
 
 // src/client.ts
@@ -879,18 +1169,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
@@ -965,7 +1273,471 @@ var VelesDB = class {
   get backendType() {
     return this.config.backend;
   }
+  // ========================================================================
+  // Index Management (EPIC-009)
+  // ========================================================================
+  /**
+   * Create a property index for O(1) equality lookups or O(log n) range queries
+   * 
+   * @param collection - Collection name
+   * @param options - Index configuration (label, property, indexType)
+   * 
+   * @example
+   * ```typescript
+   * // Create hash index for fast email lookups
+   * await db.createIndex('users', { label: 'Person', property: 'email' });
+   * 
+   * // Create range index for timestamp queries
+   * await db.createIndex('events', { label: 'Event', property: 'timestamp', indexType: 'range' });
+   * ```
+   */
+  async createIndex(collection, options) {
+    this.ensureInitialized();
+    if (!options.label || !options.property) {
+      throw new ValidationError("Index requires label and property");
+    }
+    await this.backend.createIndex(collection, options);
+  }
+  /**
+   * List all indexes on a collection
+   * 
+   * @param collection - Collection name
+   * @returns Array of index information
+   */
+  async listIndexes(collection) {
+    this.ensureInitialized();
+    return this.backend.listIndexes(collection);
+  }
+  /**
+   * Check if an index exists
+   * 
+   * @param collection - Collection name
+   * @param label - Node label
+   * @param property - Property name
+   * @returns true if index exists
+   */
+  async hasIndex(collection, label, property) {
+    this.ensureInitialized();
+    return this.backend.hasIndex(collection, label, property);
+  }
+  /**
+   * Drop an index
+   * 
+   * @param collection - Collection name
+   * @param label - Node label
+   * @param property - Property name
+   * @returns true if index was dropped, false if it didn't exist
+   */
+  async dropIndex(collection, label, property) {
+    this.ensureInitialized();
+    return this.backend.dropIndex(collection, label, property);
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041)
+  // ========================================================================
+  /**
+   * Add an edge to the collection's knowledge graph
+   * 
+   * @param collection - Collection name
+   * @param edge - Edge to add (id, source, target, label, properties)
+   * 
+   * @example
+   * ```typescript
+   * await db.addEdge('social', {
+   *   id: 1,
+   *   source: 100,
+   *   target: 200,
+   *   label: 'FOLLOWS',
+   *   properties: { since: '2024-01-01' }
+   * });
+   * ```
+   */
+  async addEdge(collection, edge) {
+    this.ensureInitialized();
+    if (!edge.label || typeof edge.label !== "string") {
+      throw new ValidationError("Edge label is required and must be a string");
+    }
+    if (typeof edge.source !== "number" || typeof edge.target !== "number") {
+      throw new ValidationError("Edge source and target must be numbers");
+    }
+    await this.backend.addEdge(collection, edge);
+  }
+  /**
+   * Get edges from the collection's knowledge graph
+   * 
+   * @param collection - Collection name
+   * @param options - Query options (filter by label)
+   * @returns Array of edges
+   * 
+   * @example
+   * ```typescript
+   * // Get all edges with label "FOLLOWS"
+   * const edges = await db.getEdges('social', { label: 'FOLLOWS' });
+   * ```
+   */
+  async getEdges(collection, options) {
+    this.ensureInitialized();
+    return this.backend.getEdges(collection, options);
+  }
+  // ========================================================================
+  // Graph Traversal (EPIC-016 US-050)
+  // ========================================================================
+  /**
+   * Traverse the graph using BFS or DFS from a source node
+   * 
+   * @param collection - Collection name
+   * @param request - Traversal request options
+   * @returns Traversal response with results and stats
+   * 
+   * @example
+   * ```typescript
+   * // BFS traversal from node 100
+   * const result = await db.traverseGraph('social', {
+   *   source: 100,
+   *   strategy: 'bfs',
+   *   maxDepth: 3,
+   *   limit: 100,
+   *   relTypes: ['FOLLOWS', 'KNOWS']
+   * });
+   * 
+   * for (const node of result.results) {
+   *   console.log(`Reached node ${node.targetId} at depth ${node.depth}`);
+   * }
+   * ```
+   */
+  async traverseGraph(collection, request) {
+    this.ensureInitialized();
+    if (typeof request.source !== "number") {
+      throw new ValidationError("Source node ID must be a number");
+    }
+    if (request.strategy && !["bfs", "dfs"].includes(request.strategy)) {
+      throw new ValidationError("Strategy must be 'bfs' or 'dfs'");
+    }
+    return this.backend.traverseGraph(collection, request);
+  }
+  /**
+   * Get the in-degree and out-degree of a node
+   * 
+   * @param collection - Collection name
+   * @param nodeId - Node ID
+   * @returns Degree response with inDegree and outDegree
+   * 
+   * @example
+   * ```typescript
+   * const degree = await db.getNodeDegree('social', 100);
+   * console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
+   * ```
+   */
+  async getNodeDegree(collection, nodeId) {
+    this.ensureInitialized();
+    if (typeof nodeId !== "number") {
+      throw new ValidationError("Node ID must be a number");
+    }
+    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 {
   ConnectionError,
   NotFoundError,
@@ -973,5 +1745,7 @@ export {
   ValidationError,
   VelesDB,
   VelesDBError,
-  WasmBackend
+  VelesQLBuilder,
+  WasmBackend,
+  velesql
 };