@wiscale/velesdb-sdk 1.3.0 → 1.4.1

package/README.md

@@ -165,24 +165,27 @@ const results = await db.hybridSearch(
 );
 ```
 
-### `db.query(queryString, params)` (v0.8.5+)
+### `db.query(collection, queryString, params?, options?)` (v0.8.5+)
 
 Execute a VelesQL query.
 
 ```typescript
 // Simple query
 const results = await db.query(
+  'documents',
   "SELECT * FROM documents WHERE category = 'tech' LIMIT 10"
 );
 
 // With vector parameter
 const results = await db.query(
+  'documents',
   "SELECT * FROM documents WHERE VECTOR NEAR $query LIMIT 5",
   { query: [0.1, 0.2, ...] }
 );
 
 // Hybrid query
 const results = await db.query(
+  'docs',
   "SELECT * FROM docs WHERE VECTOR NEAR $v AND content MATCH 'rust' LIMIT 10",
   { v: queryVector }
 );
@@ -246,6 +249,147 @@ await db.flush('documents');
 
 Close the client and release resources.
 
+## Knowledge Graph API (v1.2.0+)
+
+VelesDB supports hybrid vector + graph queries.
+
+### `db.addEdge(collection, edge)`
+
+```typescript
+await db.addEdge('social', {
+  id: 1, source: 100, target: 200,
+  label: 'FOLLOWS',
+  properties: { since: '2024-01-01' }
+});
+```
+
+### `db.getEdges(collection, options?)`
+
+```typescript
+const edges = await db.getEdges('social', { label: 'FOLLOWS' });
+```
+
+### `db.traverseGraph(collection, request)`
+
+```typescript
+const result = await db.traverseGraph('social', {
+  source: 100, strategy: 'bfs', maxDepth: 3
+});
+```
+
+### `db.getNodeDegree(collection, nodeId)`
+
+```typescript
+const degree = await db.getNodeDegree('social', 100);
+```
+
+## VelesQL v2.0 Queries (v1.4.0+)
+
+Execute advanced SQL-like queries with aggregation, joins, and set operations.
+
+### Aggregation with GROUP BY / HAVING
+
+```typescript
+// Group by with aggregates
+const result = await db.query('products', `
+  SELECT category, COUNT(*), AVG(price) 
+  FROM products 
+  GROUP BY category 
+  HAVING COUNT(*) > 5 AND AVG(price) > 50
+`);
+
+// Access results
+for (const row of result.results) {
+  console.log(row.payload.category, row.payload.count);
+}
+```
+
+### ORDER BY with similarity()
+
+```typescript
+// Order by semantic similarity
+const result = await db.query('docs', `
+  SELECT * FROM docs 
+  ORDER BY similarity(vector, $v) DESC 
+  LIMIT 10
+`, { v: queryVector });
+```
+
+### JOIN across collections
+
+```typescript
+// Cross-collection join
+const result = await db.query('orders', `
+  SELECT * FROM orders 
+  JOIN customers AS c ON orders.customer_id = c.id 
+  WHERE status = $status
+`, { status: 'active' });
+```
+
+### Set Operations (UNION / INTERSECT / EXCEPT)
+
+```typescript
+// Combine query results
+const result = await db.query('users', `
+  SELECT * FROM active_users 
+  UNION 
+  SELECT * FROM archived_users
+`);
+
+// Find common elements
+const result = await db.query('users', `
+  SELECT id FROM premium_users 
+  INTERSECT 
+  SELECT id FROM active_users
+`);
+```
+
+### Hybrid Search with USING FUSION
+
+```typescript
+// RRF fusion (default)
+const result = await db.query('docs', `
+  SELECT * FROM docs 
+  USING FUSION(strategy = 'rrf', k = 60) 
+  LIMIT 20
+`);
+
+// Weighted fusion
+const result = await db.query('docs', `
+  SELECT * FROM docs 
+  USING FUSION(strategy = 'weighted', vector_weight = 0.7, graph_weight = 0.3) 
+  LIMIT 20
+`);
+```
+
+## VelesQL Query Builder (v1.2.0+)
+
+Build type-safe VelesQL queries with the fluent builder API.
+
+```typescript
+import { velesql } from '@wiscale/velesdb-sdk';
+
+// Graph pattern query
+const builder = velesql()
+  .match('d', 'Document')
+  .nearVector('$queryVector', queryVector)
+  .andWhere('d.category = $cat', { cat: 'tech' })
+  .limit(10);
+
+const queryString = builder.toVelesQL();
+const params = builder.getParams();
+const results = await db.query('documents', queryString, params);
+
+// Graph traversal with relationships
+const graphQuery = velesql()
+  .match('p', 'Person')
+  .rel('KNOWS')
+  .to('f', 'Person')
+  .where('p.age > 25')
+  .return(['p.name', 'f.name'])
+  .toVelesQL();
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -72,13 +72,13 @@ interface SearchOptions {
     includeVectors?: boolean;
 }
 /** Fusion strategy for multi-query search */
-type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
+type FusionStrategy$1 = 'rrf' | 'average' | 'maximum' | 'weighted';
 /** Multi-query search options */
 interface MultiQuerySearchOptions {
     /** Number of results to return (default: 10) */
     k?: number;
     /** Fusion strategy (default: 'rrf') */
-    fusion?: FusionStrategy;
+    fusion?: FusionStrategy$1;
     /** Fusion parameters */
     fusionParams?: {
         /** RRF k parameter (default: 60) */
@@ -191,6 +191,44 @@ interface DegreeResponse {
     /** Number of outgoing edges */
     outDegree: number;
 }
+/** VelesQL query options */
+interface QueryOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** Enable streaming response */
+    stream?: boolean;
+}
+/** Query result from multi-model VelesQL query */
+interface QueryResult {
+    /** Node/point ID */
+    nodeId: bigint | number;
+    /** Vector similarity score (if applicable) */
+    vectorScore: number | null;
+    /** Graph relevance score (if applicable) */
+    graphScore: number | null;
+    /** Combined fused score */
+    fusedScore: number;
+    /** Variable bindings from MATCH clause */
+    bindings: Record<string, unknown>;
+    /** Column data from JOIN (if applicable) */
+    columnData: Record<string, unknown> | null;
+}
+/** Query execution statistics */
+interface QueryStats {
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Execution strategy used */
+    strategy: string;
+    /** Number of nodes scanned */
+    scannedNodes: number;
+}
+/** Full query response with results and stats */
+interface QueryResponse {
+    /** Query results */
+    results: QueryResult[];
+    /** Execution statistics */
+    stats: QueryStats;
+}
 /** Index type for property indexes */
 type IndexType = 'hash' | 'range';
 /** Index information */
@@ -256,8 +294,8 @@ interface IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    /** Execute VelesQL query */
-    query(queryString: string, params?: Record<string, unknown>): Promise<SearchResult[]>;
+    /** Execute VelesQL multi-model query (EPIC-031 US-011) */
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
     /** Multi-query fusion search */
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     /** Check if collection is empty */
@@ -462,13 +500,28 @@ declare class VelesDB {
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
     /**
-     * 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}`);
+     * }
+     * ```
      */
-    query(queryString: string, params?: Record<string, unknown>): Promise<SearchResult[]>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryResponse>;
     /**
      * Multi-query fusion search combining results from multiple query vectors
      *
@@ -673,7 +726,7 @@ declare class WasmBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(_queryString: string, _params?: Record<string, unknown>): Promise<SearchResult[]>;
+    query(_collection: string, _queryString: string, _params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
     multiQuerySearch(_collection: string, _vectors: Array<number[] | Float32Array>, _options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     isEmpty(collectionName: string): Promise<boolean>;
     flush(collectionName: string): Promise<void>;
@@ -711,6 +764,11 @@ declare class RestBackend implements IVelesDBBackend {
     private ensureInitialized;
     private mapStatusToErrorCode;
     private extractErrorPayload;
+    /**
+     * Parse node ID safely to handle u64 values above Number.MAX_SAFE_INTEGER.
+     * Returns bigint for large values, number for safe values.
+     */
+    private parseNodeId;
     private request;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
@@ -735,7 +793,7 @@ declare class RestBackend implements IVelesDBBackend {
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(queryString: string, params?: Record<string, unknown>): Promise<SearchResult[]>;
+    query(collection: string, queryString: string, params?: Record<string, unknown>, _options?: QueryOptions): Promise<QueryResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     isEmpty(collection: string): Promise<boolean>;
     flush(collection: string): Promise<void>;
@@ -750,4 +808,194 @@ declare class RestBackend implements IVelesDBBackend {
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
 }
 
-export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, NotFoundError, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };
+/**
+ * VelesQL Query Builder (EPIC-012/US-004)
+ *
+ * Fluent, type-safe API for building VelesQL queries.
+ *
+ * @example
+ * ```typescript
+ * import { velesql } from '@velesdb/sdk';
+ *
+ * const query = velesql()
+ *   .match('d', 'Document')
+ *   .nearVector('$q', embedding)
+ *   .andWhere('d.category = $cat', { cat: 'tech' })
+ *   .limit(20)
+ *   .toVelesQL();
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** Direction for relationship traversal */
+type RelDirection = 'outgoing' | 'incoming' | 'both';
+/** Fusion strategy for hybrid queries */
+type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
+/** Options for relationship patterns */
+interface RelOptions {
+    direction?: RelDirection;
+    minHops?: number;
+    maxHops?: number;
+}
+/** Options for vector NEAR clause */
+interface NearVectorOptions {
+    topK?: number;
+}
+/** Fusion configuration */
+interface FusionOptions {
+    strategy: FusionStrategy;
+    k?: number;
+    vectorWeight?: number;
+    graphWeight?: number;
+}
+/** Internal state for the query builder */
+interface BuilderState {
+    matchClauses: string[];
+    whereClauses: string[];
+    whereOperators: string[];
+    params: Record<string, unknown>;
+    limitValue?: number;
+    offsetValue?: number;
+    orderByClause?: string;
+    returnClause?: string;
+    fusionOptions?: FusionOptions;
+    currentNode?: string;
+    pendingRel?: {
+        type: string;
+        alias?: string;
+        options?: RelOptions;
+    };
+}
+/**
+ * VelesQL Query Builder
+ *
+ * Immutable builder for constructing VelesQL queries with type safety.
+ */
+declare class VelesQLBuilder {
+    private readonly state;
+    constructor(state?: Partial<BuilderState>);
+    private clone;
+    /**
+     * Start a MATCH clause with a node pattern
+     *
+     * @param alias - Node alias (e.g., 'n', 'person')
+     * @param label - Optional node label(s)
+     */
+    match(alias: string, label?: string | string[]): VelesQLBuilder;
+    /**
+     * 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: string, alias?: string, options?: RelOptions): VelesQLBuilder;
+    /**
+     * Complete a relationship pattern with target node
+     *
+     * @param alias - Target node alias
+     * @param label - Optional target node label(s)
+     */
+    to(alias: string, label?: string | string[]): VelesQLBuilder;
+    /**
+     * Add a WHERE clause
+     *
+     * @param condition - WHERE condition
+     * @param params - Optional parameters
+     */
+    where(condition: string, params?: Record<string, unknown>): VelesQLBuilder;
+    /**
+     * Add an AND WHERE clause
+     *
+     * @param condition - WHERE condition
+     * @param params - Optional parameters
+     */
+    andWhere(condition: string, params?: Record<string, unknown>): VelesQLBuilder;
+    /**
+     * Add an OR WHERE clause
+     *
+     * @param condition - WHERE condition
+     * @param params - Optional parameters
+     */
+    orWhere(condition: string, params?: Record<string, unknown>): VelesQLBuilder;
+    /**
+     * 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: string, vector: number[] | Float32Array, options?: NearVectorOptions): VelesQLBuilder;
+    /**
+     * Add LIMIT clause
+     *
+     * @param value - Maximum number of results
+     */
+    limit(value: number): VelesQLBuilder;
+    /**
+     * Add OFFSET clause
+     *
+     * @param value - Number of results to skip
+     */
+    offset(value: number): VelesQLBuilder;
+    /**
+     * Add ORDER BY clause
+     *
+     * @param field - Field to order by
+     * @param direction - Sort direction (ASC or DESC)
+     */
+    orderBy(field: string, direction?: 'ASC' | 'DESC'): VelesQLBuilder;
+    /**
+     * Add RETURN clause with specific fields
+     *
+     * @param fields - Fields to return (array or object with aliases)
+     */
+    return(fields: string[] | Record<string, string>): VelesQLBuilder;
+    /**
+     * Add RETURN * clause
+     */
+    returnAll(): VelesQLBuilder;
+    /**
+     * Set fusion strategy for hybrid queries
+     *
+     * @param strategy - Fusion strategy
+     * @param options - Fusion parameters
+     */
+    fusion(strategy: FusionStrategy, options?: {
+        k?: number;
+        vectorWeight?: number;
+        graphWeight?: number;
+    }): VelesQLBuilder;
+    /**
+     * Get the fusion options
+     */
+    getFusionOptions(): FusionOptions | undefined;
+    /**
+     * Get all parameters
+     */
+    getParams(): Record<string, unknown>;
+    /**
+     * Build the VelesQL query string
+     */
+    toVelesQL(): string;
+    private formatLabel;
+    private formatRelationship;
+    private formatHops;
+    private buildWhereClause;
+}
+/**
+ * Create a new VelesQL query builder
+ *
+ * @example
+ * ```typescript
+ * const query = velesql()
+ *   .match('n', 'Person')
+ *   .where('n.age > 21')
+ *   .limit(10)
+ *   .toVelesQL();
+ * // => "MATCH (n:Person) WHERE n.age > 21 LIMIT 10"
+ * ```
+ */
+declare function velesql(): VelesQLBuilder;
+
+export { type AddEdgeRequest, type BackendType, type Collection, type CollectionConfig, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type SearchOptions, type SearchResult, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };