@wiscale/velesdb-sdk 1.3.0 → 1.5.1

package/README.md

@@ -62,7 +62,7 @@ await db.init();
 
 // Same API as WASM backend
 await db.createCollection('products', { dimension: 1536 });
-await db.insert('products', { id: 'p1', vector: [...] });
+await db.insert('products', { id: 1, vector: [...] });
 const results = await db.search('products', query, { k: 10 });
 ```
 
@@ -120,6 +120,10 @@ await db.insert('docs', {
   vector: [0.1, 0.2, ...],  // or Float32Array
   payload: { key: 'value' } // optional metadata
 });
+
+// REST backend note:
+// IDs must be numeric and within JS safe integer range (0..Number.MAX_SAFE_INTEGER).
+// Non-numeric strings are rejected.
 ```
 
 ### `db.insertBatch(collection, documents)`
@@ -165,27 +169,36 @@ 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 }
 );
+
+// Aggregation query (returns { result, stats })
+const agg = await db.query(
+  'documents',
+  "SELECT COUNT(*) AS total FROM documents"
+);
 ```
 
 ### `db.multiQuerySearch(collection, vectors, options)` (v1.1.0+) ⭐ NEW
@@ -221,7 +234,7 @@ const results = await db.multiQuerySearch('docs', vectors, {
 });
 ```
 
-> **Note:** Multi-query fusion is only available with the REST backend.
+> **Note:** WASM supports `rrf`, `average`, `maximum`. `weighted` is REST-only.
 
 ### `db.isEmpty(collection)` (v0.8.11+)
 
@@ -246,6 +259,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