@wiscale/velesdb-wasm 1.3.1 → 1.5.1

package/README.md

@@ -89,18 +89,14 @@ class VectorStore {
 
   // Methods
   insert(id: bigint, vector: Float32Array): void;
-  insert_with_payload(id: bigint, vector: Float32Array, payload: object): void;  // v0.8.5+
-  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
+  insert_with_payload(id: bigint, vector: Float32Array, payload: object): void;  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
   search(query: Float32Array, k: number): Array<[bigint, number]>;
-  search_with_filter(query: Float32Array, k: number, filter: object): Array<{id, score, payload}>;  // v0.8.5+
-  text_search(query: string, k: number, field?: string): Array<{id, score, payload}>;  // v0.8.5+
-  get(id: bigint): {id, vector, payload} | null;  // v0.8.5+
-  remove(id: bigint): boolean;
+  search_with_filter(query: Float32Array, k: number, filter: object): Array<{id, score, payload}>;  text_search(query: string, k: number, field?: string): Array<{id, score, payload}>;  get(id: bigint): {id, vector, payload} | null;  remove(id: bigint): boolean;
   clear(): void;
   reserve(additional: number): void;  // Pre-allocate memory
   memory_usage(): number;  // Accurate for each storage mode
   
-  // ⭐ NEW v1.1.0
+  //
   multi_query_search(vectors: Float32Array, num_vectors: number, k: number, strategy?: string, rrf_k?: number): Array<[bigint, number]>;
   hybrid_search(vector: Float32Array, text_query: string, k: number, vector_weight?: number, field?: string): Array<{id, score, payload}>;
   batch_search(vectors: Float32Array, num_vectors: number, k: number): Array<Array<[bigint, number]>>;
@@ -111,7 +107,7 @@ class VectorStore {
 }
 ```
 
-### Filter Format (v0.8.5+)
+### Filter Format
 
 ```javascript
 // Equality filter
@@ -246,6 +242,82 @@ Ultra-fast serialization thanks to contiguous memory layout:
 - **Electron/Tauri apps** - Desktop AI without a server
 - **PWA applications** - Full offline support with service workers
 
+## ⚠️ Limitations vs REST Backend
+
+The WASM build is optimized for client-side use cases but has some limitations compared to the full REST server.
+
+### Feature Comparison
+
+| Feature | WASM | REST Server |
+|---------|------|-------------|
+| Vector search (NEAR) | ✅ | ✅ |
+| Metadata filtering | ✅ | ✅ |
+| Hybrid search (vector + BM25) | ✅ | ✅ |
+| Full-text search (BM25) | ✅ | ✅ |
+| Multi-query fusion (MQG) | ✅ | ✅ |
+| Batch search | ✅ | ✅ |
+| Full VelesQL queries | ❌ | ✅ |
+| Knowledge Graph operations | ❌ | ✅ |
+| JOIN operations | ❌ | ✅ |
+| Aggregations (GROUP BY) | ❌ | ✅ |
+| Persistence | IndexedDB | Disk (mmap) |
+| Max vectors | ~100K (browser RAM) | Millions |
+
+### Unsupported Operations
+
+When you try to use unsupported features, you'll get clear error messages:
+
+```javascript
+// ❌ VelesQL string queries not supported in WASM
+// Use the native API instead:
+
+// Instead of: store.query("SELECT * FROM docs WHERE vector NEAR $v")
+// Use:
+const results = store.search(queryVector, 10);
+
+// Instead of: store.query("SELECT * FROM docs WHERE category = 'tech'")
+// Use:
+const results = store.search_with_filter(queryVector, 10, {
+  condition: { type: "eq", field: "category", value: "tech" }
+});
+```
+
+### When to Use REST Backend
+
+Consider using the [REST server](https://github.com/cyberlife-coder/VelesDB) if you need:
+
+- **Full VelesQL support** - Complex SQL-like queries with JOINs and aggregations
+- **Knowledge Graph** - Entity relationships and graph traversal
+- **Large datasets** - More than 100K vectors
+- **Server-side processing** - Centralized vector database
+
+### Migration from WASM to REST
+
+```javascript
+// WASM (client-side)
+import { VectorStore } from '@wiscale/velesdb-wasm';
+const store = new VectorStore(768, 'cosine');
+const results = store.search(query, 10);
+
+// REST (server-side) - using fetch
+const response = await fetch('http://localhost:8080/collections/docs/search', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ vector: query, top_k: 10 })
+});
+const results = await response.json();
+
+// REST with VelesQL
+const response = await fetch('http://localhost:8080/query', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    query: "SELECT * FROM docs WHERE vector NEAR $v AND category = 'tech' LIMIT 10",
+    params: { v: query }
+  })
+});
+```
+
 ## Building from Source
 
 ```bash

package/package.json

@@ -5,7 +5,7 @@
     "Julien Lange <contact@wiscale.fr>"
   ],
   "description": "VelesDB for WebAssembly - Vector search in the browser",
-  "version": "1.3.1",
+  "version": "1.5.1",
   "license": "SEE LICENSE IN ../../LICENSE",
   "repository": {
     "type": "git",