@wiscale/velesdb-sdk 1.10.0 → 1.12.0

package/README.md

@@ -2,17 +2,32 @@
 
 Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB) -- the local-first vector database for AI and RAG. Sub-millisecond semantic search in Browser and Node.js.
 
-**v1.10.0** | Node.js >= 18 | Browser (WASM) | MIT License
+**v1.12.0** | Node.js >= 18 | Browser (WASM) | MIT License
 
-## What's New in v1.10.0
+## What's New in v1.12.0
 
-- **VelesQL LET clause** -- named score bindings for custom scoring formulas
-- **Component scores** -- `vector_score`, `bm25_score`, `graph_score` resolve independently in ORDER BY
-- **WITH options functional** -- `mode`, `timeout_ms`, `rerank` now wired to execution (were parsed but ignored)
-- **Agent Memory VelesQL** -- query semantic/episodic/procedural memory via standard VelesQL
-- **USING FUSION k parameter** -- configurable RRF constant for hybrid text search
+- **Cross-collection MATCH queries** -- `@collection` annotation on MATCH node patterns enables cross-collection graph queries
+- **MATCH via `/query` endpoint** -- MATCH queries can now be executed via `Database::execute_query`
+- **BFS dedup** -- CSR and EdgeStore BFS no longer produce duplicate results for diamond graphs
+- **`rrf_k` propagation** -- now properly propagated to `hybrid_search_with_filter`
+- **`ComponentScores` optimization** -- changed to `&'static str` for zero-allocation score tagging
 
-### Previous (v1.9.2)
+### Previous (v1.11.1)
+
+- **Graph API parity** -- 7 new REST endpoints for complete graph operations (delete edge, edge count, list nodes, node edges, node payload, parallel BFS, graph search)
+- **Bitmap pre-filter** -- adaptive strategy selection for filtered search
+- **CSR graph traversal v2** -- lock-free adjacency with edge IDs and labels
+- **Bulk insert v2** -- DirectVectorWriter + AsyncIndexBuilder pipeline
+
+### Previous (v1.11.0)
+
+- **15 new VelesQL statements** -- SHOW COLLECTIONS, DESCRIBE, EXPLAIN, CREATE/DROP INDEX, ANALYZE, TRUNCATE, ALTER COLLECTION, FLUSH, multi-row INSERT, UPSERT, SELECT EDGES, INSERT NODE
+- **203 BDD E2E tests** -- comprehensive end-to-end test coverage for all VelesQL features
+- **TRUNCATE on graph collections** -- clears nodes + edges in a single statement
+- **Python `execute_query()`** -- full VelesQL execution from Python bindings
+- **Cyclomatic complexity ≤ 8** -- refactored 6 hotspots for Codacy compliance
+
+### Previous (v1.10.0)
 
 - **SearchQuality type** -- `SearchQuality` type and `quality` field in `SearchOptions`
 - **StorageMode in HnswParams** -- `storageMode` field in HNSW configuration
@@ -532,6 +547,23 @@ const degree = await db.getNodeDegree('social', 100);
 console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
 ```
 
+#### `db.traverseParallel(collection, request)`
+
+Multi-source parallel BFS traversal with deduplication. Starts BFS from multiple source nodes simultaneously.
+
+```typescript
+const result = await db.traverseParallel('social', {
+  sources: [100, 200, 300],
+  maxDepth: 3,
+  limit: 50,
+  relTypes: ['FOLLOWS']
+});
+
+for (const node of result.results) {
+  console.log(`Node ${node.targetId} at depth ${node.depth}`);
+}
+```
+
 ---
 
 ### Property Indexes

package/dist/index.d.mts

@@ -180,6 +180,17 @@ interface TraverseRequest {
     /** Filter by relationship types (empty = all types) */
     relTypes?: string[];
 }
+/** Request for multi-source parallel BFS traversal */
+interface TraverseParallelRequest {
+    /** Source node IDs to start traversal from */
+    sources: number[];
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Filter by relationship types (empty = all types) */
+    relTypes?: string[];
+}
 /** A single traversal result item */
 interface TraversalResultItem {
     /** Target node ID reached */
@@ -321,7 +332,11 @@ interface AggregationQueryResponse {
     /** Execution statistics */
     stats: QueryStats;
 }
-/** Unified response type for `query()` (rows or aggregation). */
+/** Unified response type for `query()` (rows, aggregation, or DDL).
+ *
+ * DDL statements (CREATE, DROP) and mutations (INSERT EDGE, DELETE) return
+ * a standard `QueryResponse` with an empty `results` array.
+ */
 type QueryApiResponse = QueryResponse | AggregationQueryResponse;
 /** Query explain request/response metadata */
 interface ExplainPlanStep {
@@ -469,6 +484,8 @@ interface IVelesDBBackend {
     getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
     /** Traverse the graph using BFS or DFS from a source node */
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /** Multi-source parallel BFS traversal with deduplication */
+    traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
     /** Train Product Quantization on a collection */
@@ -721,7 +738,11 @@ declare class VelesDB {
      *
      * @param collection - Collection name
      * @param queryString - VelesQL query string
-     * @param params - Query parameters (vectors, scalars)
+     * @param params - Query parameters (vectors, scalars).
+     *   For cross-collection MATCH queries, pass `_collection` to specify the
+     *   primary collection (the one with graph edges). Nodes annotated with
+     *   `@collection` in the MATCH pattern will have their payloads enriched
+     *   from the named collection after traversal.
      * @param options - Query options (timeout, streaming)
      * @returns Query response with results and execution stats
      *
@@ -735,6 +756,16 @@ declare class VelesDB {
      *   console.log(`ID ${r.id}, title: ${r.title}`);
      * }
      * ```
+     *
+     * @example Cross-collection MATCH
+     * ```typescript
+     * // Enrich Product nodes with Inventory data from the 'inventory' collection
+     * const response = await db.query('catalog_graph', `
+     *   MATCH (p:Product)-[:STORED_IN]->(inv:Inventory@inventory)
+     *   RETURN p.name, inv.price, inv.stock
+     *   LIMIT 20
+     * `);
+     * ```
      */
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     /**
@@ -910,6 +941,26 @@ declare class VelesDB {
      * ```
      */
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /**
+     * Multi-source parallel BFS traversal with deduplication.
+     *
+     * Starts BFS from multiple source nodes simultaneously and deduplicates
+     * results by path signature.
+     *
+     * @param collection - Collection name
+     * @param request - Parallel traverse request with sources array
+     * @returns Traverse response with results, stats, and pagination
+     *
+     * @example
+     * ```typescript
+     * const result = await db.traverseParallel('social', {
+     *   sources: [100, 200, 300],
+     *   maxDepth: 3,
+     *   limit: 50,
+     * });
+     * ```
+     */
+    traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /**
      * Get the in-degree and out-degree of a node
      *
@@ -1034,6 +1085,7 @@ declare class WasmBackend implements IVelesDBBackend {
     addEdge(_collection: string, _edge: AddEdgeRequest): Promise<void>;
     getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(_collection: string, _request: TraverseParallelRequest): Promise<TraverseResponse>;
     getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
     trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
     streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
@@ -1120,6 +1172,7 @@ declare class RestBackend implements IVelesDBBackend {
     addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
     getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(collection: string, req: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(collection: string, req: TraverseParallelRequest): Promise<TraverseResponse>;
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
     createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
@@ -1328,4 +1381,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchQuality, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchQuality, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };

package/dist/index.d.ts

@@ -180,6 +180,17 @@ interface TraverseRequest {
     /** Filter by relationship types (empty = all types) */
     relTypes?: string[];
 }
+/** Request for multi-source parallel BFS traversal */
+interface TraverseParallelRequest {
+    /** Source node IDs to start traversal from */
+    sources: number[];
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Filter by relationship types (empty = all types) */
+    relTypes?: string[];
+}
 /** A single traversal result item */
 interface TraversalResultItem {
     /** Target node ID reached */
@@ -321,7 +332,11 @@ interface AggregationQueryResponse {
     /** Execution statistics */
     stats: QueryStats;
 }
-/** Unified response type for `query()` (rows or aggregation). */
+/** Unified response type for `query()` (rows, aggregation, or DDL).
+ *
+ * DDL statements (CREATE, DROP) and mutations (INSERT EDGE, DELETE) return
+ * a standard `QueryResponse` with an empty `results` array.
+ */
 type QueryApiResponse = QueryResponse | AggregationQueryResponse;
 /** Query explain request/response metadata */
 interface ExplainPlanStep {
@@ -469,6 +484,8 @@ interface IVelesDBBackend {
     getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
     /** Traverse the graph using BFS or DFS from a source node */
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /** Multi-source parallel BFS traversal with deduplication */
+    traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
     /** Train Product Quantization on a collection */
@@ -721,7 +738,11 @@ declare class VelesDB {
      *
      * @param collection - Collection name
      * @param queryString - VelesQL query string
-     * @param params - Query parameters (vectors, scalars)
+     * @param params - Query parameters (vectors, scalars).
+     *   For cross-collection MATCH queries, pass `_collection` to specify the
+     *   primary collection (the one with graph edges). Nodes annotated with
+     *   `@collection` in the MATCH pattern will have their payloads enriched
+     *   from the named collection after traversal.
      * @param options - Query options (timeout, streaming)
      * @returns Query response with results and execution stats
      *
@@ -735,6 +756,16 @@ declare class VelesDB {
      *   console.log(`ID ${r.id}, title: ${r.title}`);
      * }
      * ```
+     *
+     * @example Cross-collection MATCH
+     * ```typescript
+     * // Enrich Product nodes with Inventory data from the 'inventory' collection
+     * const response = await db.query('catalog_graph', `
+     *   MATCH (p:Product)-[:STORED_IN]->(inv:Inventory@inventory)
+     *   RETURN p.name, inv.price, inv.stock
+     *   LIMIT 20
+     * `);
+     * ```
      */
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     /**
@@ -910,6 +941,26 @@ declare class VelesDB {
      * ```
      */
     traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
+    /**
+     * Multi-source parallel BFS traversal with deduplication.
+     *
+     * Starts BFS from multiple source nodes simultaneously and deduplicates
+     * results by path signature.
+     *
+     * @param collection - Collection name
+     * @param request - Parallel traverse request with sources array
+     * @returns Traverse response with results, stats, and pagination
+     *
+     * @example
+     * ```typescript
+     * const result = await db.traverseParallel('social', {
+     *   sources: [100, 200, 300],
+     *   maxDepth: 3,
+     *   limit: 50,
+     * });
+     * ```
+     */
+    traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /**
      * Get the in-degree and out-degree of a node
      *
@@ -1034,6 +1085,7 @@ declare class WasmBackend implements IVelesDBBackend {
     addEdge(_collection: string, _edge: AddEdgeRequest): Promise<void>;
     getEdges(_collection: string, _options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(_collection: string, _request: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(_collection: string, _request: TraverseParallelRequest): Promise<TraverseResponse>;
     getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
     trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
     streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
@@ -1120,6 +1172,7 @@ declare class RestBackend implements IVelesDBBackend {
     addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
     getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
     traverseGraph(collection: string, req: TraverseRequest): Promise<TraverseResponse>;
+    traverseParallel(collection: string, req: TraverseParallelRequest): Promise<TraverseResponse>;
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
     createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
@@ -1328,4 +1381,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchQuality, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchQuality, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };

package/dist/index.js

@@ -582,6 +582,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     wasmNotSupported("Graph traversal");
   }
+  async traverseParallel(_collection, _request) {
+    this.ensureInitialized();
+    wasmNotSupported("Graph parallel traversal");
+  }
   async getNodeDegree(_collection, _nodeId) {
     this.ensureInitialized();
     wasmNotSupported("Graph degree query");
@@ -902,6 +906,33 @@ async function createGraphCollection(transport, name, config) {
   });
   throwOnError(response);
 }
+async function traverseParallel(transport, collection, request) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/graph/traverse/parallel`,
+    {
+      sources: request.sources,
+      max_depth: request.maxDepth ?? 3,
+      limit: request.limit ?? 100,
+      rel_types: request.relTypes ?? []
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  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
+    }
+  };
+}
 
 // src/backends/query-backend.ts
 function isLikelyAggregationQuery(queryString) {
@@ -909,8 +940,11 @@ function isLikelyAggregationQuery(queryString) {
     queryString
   );
 }
+function isLikelyDdlOrMutationQuery(queryString) {
+  return /^\s*(CREATE|DROP)\s+(COLLECTION|GRAPH|METADATA|INDEX)\b/i.test(queryString) || /^\s*DELETE\s+(FROM|EDGE)\b/i.test(queryString) || /^\s*INSERT\s+(INTO|EDGE|NODE)\b/i.test(queryString) || /^\s*UPSERT\s+INTO\b/i.test(queryString) || /^\s*(SHOW|DESCRIBE|EXPLAIN)\b/i.test(queryString) || /^\s*(FLUSH|ANALYZE|TRUNCATE)\b/i.test(queryString) || /^\s*ALTER\s+COLLECTION\b/i.test(queryString) || /^\s*SELECT\s+EDGES\b/i.test(queryString);
+}
 async function query(transport, collection, queryString, params, options) {
-  const endpoint = isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
+  const endpoint = isLikelyDdlOrMutationQuery(queryString) ? "/query" : isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
   const response = await transport.requestJson(
     "POST",
     endpoint,
@@ -1543,6 +1577,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return traverseGraph(this.asCrudTransport(), collection, req);
   }
+  async traverseParallel(collection, req) {
+    this.ensureInitialized();
+    return traverseParallel(this.asCrudTransport(), collection, req);
+  }
   async getNodeDegree(collection, nodeId) {
     this.ensureInitialized();
     return getNodeDegree(this.asCrudTransport(), collection, nodeId);
@@ -1919,7 +1957,11 @@ var VelesDB = class {
    * 
    * @param collection - Collection name
    * @param queryString - VelesQL query string
-   * @param params - Query parameters (vectors, scalars)
+   * @param params - Query parameters (vectors, scalars).
+   *   For cross-collection MATCH queries, pass `_collection` to specify the
+   *   primary collection (the one with graph edges). Nodes annotated with
+   *   `@collection` in the MATCH pattern will have their payloads enriched
+   *   from the named collection after traversal.
    * @param options - Query options (timeout, streaming)
    * @returns Query response with results and execution stats
    * 
@@ -1933,6 +1975,16 @@ var VelesDB = class {
    *   console.log(`ID ${r.id}, title: ${r.title}`);
    * }
    * ```
+   *
+   * @example Cross-collection MATCH
+   * ```typescript
+   * // Enrich Product nodes with Inventory data from the 'inventory' collection
+   * const response = await db.query('catalog_graph', `
+   *   MATCH (p:Product)-[:STORED_IN]->(inv:Inventory@inventory)
+   *   RETURN p.name, inv.price, inv.stock
+   *   LIMIT 20
+   * `);
+   * ```
    */
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
@@ -2195,6 +2247,32 @@ var VelesDB = class {
     }
     return this.backend.traverseGraph(collection, request);
   }
+  /**
+   * Multi-source parallel BFS traversal with deduplication.
+   * 
+   * Starts BFS from multiple source nodes simultaneously and deduplicates
+   * results by path signature.
+   * 
+   * @param collection - Collection name
+   * @param request - Parallel traverse request with sources array
+   * @returns Traverse response with results, stats, and pagination
+   * 
+   * @example
+   * ```typescript
+   * const result = await db.traverseParallel('social', {
+   *   sources: [100, 200, 300],
+   *   maxDepth: 3,
+   *   limit: 50,
+   * });
+   * ```
+   */
+  async traverseParallel(collection, request) {
+    this.ensureInitialized();
+    if (!Array.isArray(request.sources) || request.sources.length === 0) {
+      throw new ValidationError("At least one source node ID is required");
+    }
+    return this.backend.traverseParallel(collection, request);
+  }
   /**
    * Get the in-degree and out-degree of a node
    * 

package/dist/index.mjs

@@ -536,6 +536,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     wasmNotSupported("Graph traversal");
   }
+  async traverseParallel(_collection, _request) {
+    this.ensureInitialized();
+    wasmNotSupported("Graph parallel traversal");
+  }
   async getNodeDegree(_collection, _nodeId) {
     this.ensureInitialized();
     wasmNotSupported("Graph degree query");
@@ -856,6 +860,33 @@ async function createGraphCollection(transport, name, config) {
   });
   throwOnError(response);
 }
+async function traverseParallel(transport, collection, request) {
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/graph/traverse/parallel`,
+    {
+      sources: request.sources,
+      max_depth: request.maxDepth ?? 3,
+      limit: request.limit ?? 100,
+      rel_types: request.relTypes ?? []
+    }
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  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
+    }
+  };
+}
 
 // src/backends/query-backend.ts
 function isLikelyAggregationQuery(queryString) {
@@ -863,8 +894,11 @@ function isLikelyAggregationQuery(queryString) {
     queryString
   );
 }
+function isLikelyDdlOrMutationQuery(queryString) {
+  return /^\s*(CREATE|DROP)\s+(COLLECTION|GRAPH|METADATA|INDEX)\b/i.test(queryString) || /^\s*DELETE\s+(FROM|EDGE)\b/i.test(queryString) || /^\s*INSERT\s+(INTO|EDGE|NODE)\b/i.test(queryString) || /^\s*UPSERT\s+INTO\b/i.test(queryString) || /^\s*(SHOW|DESCRIBE|EXPLAIN)\b/i.test(queryString) || /^\s*(FLUSH|ANALYZE|TRUNCATE)\b/i.test(queryString) || /^\s*ALTER\s+COLLECTION\b/i.test(queryString) || /^\s*SELECT\s+EDGES\b/i.test(queryString);
+}
 async function query(transport, collection, queryString, params, options) {
-  const endpoint = isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
+  const endpoint = isLikelyDdlOrMutationQuery(queryString) ? "/query" : isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
   const response = await transport.requestJson(
     "POST",
     endpoint,
@@ -1497,6 +1531,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return traverseGraph(this.asCrudTransport(), collection, req);
   }
+  async traverseParallel(collection, req) {
+    this.ensureInitialized();
+    return traverseParallel(this.asCrudTransport(), collection, req);
+  }
   async getNodeDegree(collection, nodeId) {
     this.ensureInitialized();
     return getNodeDegree(this.asCrudTransport(), collection, nodeId);
@@ -1873,7 +1911,11 @@ var VelesDB = class {
    * 
    * @param collection - Collection name
    * @param queryString - VelesQL query string
-   * @param params - Query parameters (vectors, scalars)
+   * @param params - Query parameters (vectors, scalars).
+   *   For cross-collection MATCH queries, pass `_collection` to specify the
+   *   primary collection (the one with graph edges). Nodes annotated with
+   *   `@collection` in the MATCH pattern will have their payloads enriched
+   *   from the named collection after traversal.
    * @param options - Query options (timeout, streaming)
    * @returns Query response with results and execution stats
    * 
@@ -1887,6 +1929,16 @@ var VelesDB = class {
    *   console.log(`ID ${r.id}, title: ${r.title}`);
    * }
    * ```
+   *
+   * @example Cross-collection MATCH
+   * ```typescript
+   * // Enrich Product nodes with Inventory data from the 'inventory' collection
+   * const response = await db.query('catalog_graph', `
+   *   MATCH (p:Product)-[:STORED_IN]->(inv:Inventory@inventory)
+   *   RETURN p.name, inv.price, inv.stock
+   *   LIMIT 20
+   * `);
+   * ```
    */
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
@@ -2149,6 +2201,32 @@ var VelesDB = class {
     }
     return this.backend.traverseGraph(collection, request);
   }
+  /**
+   * Multi-source parallel BFS traversal with deduplication.
+   * 
+   * Starts BFS from multiple source nodes simultaneously and deduplicates
+   * results by path signature.
+   * 
+   * @param collection - Collection name
+   * @param request - Parallel traverse request with sources array
+   * @returns Traverse response with results, stats, and pagination
+   * 
+   * @example
+   * ```typescript
+   * const result = await db.traverseParallel('social', {
+   *   sources: [100, 200, 300],
+   *   maxDepth: 3,
+   *   limit: 50,
+   * });
+   * ```
+   */
+  async traverseParallel(collection, request) {
+    this.ensureInitialized();
+    if (!Array.isArray(request.sources) || request.sources.length === 0) {
+      throw new ValidationError("At least one source node ID is required");
+    }
+    return this.backend.traverseParallel(collection, request);
+  }
   /**
    * Get the in-degree and out-degree of a node
    * 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "VelesDB TypeScript SDK: The Local Vector Database for AI & RAG. Microsecond semantic search in Browser & Node.js.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",