264 lines
4.5 KiB
Markdown
264 lines
4.5 KiB
Markdown
# @ruvector/wasm
|
|
|
|
WebAssembly bindings for Ruvector - High-performance vector database for browsers and Node.js.
|
|
|
|
## Features
|
|
|
|
- 🚀 **High Performance**: SIMD-accelerated vector operations
|
|
- 🌐 **Universal**: Works in browsers and Node.js
|
|
- 🎯 **Multiple Distance Metrics**: Cosine, Euclidean, Dot Product, Manhattan
|
|
- 🔍 **Fast Search**: HNSW indexing for approximate nearest neighbor search
|
|
- 💾 **Persistent Storage**: IndexedDB (browser) and file system (Node.js)
|
|
- 🦀 **Rust-powered**: Built with Rust and WebAssembly
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @ruvector/wasm
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Browser
|
|
|
|
```javascript
|
|
import { VectorDB } from '@ruvector/wasm/browser';
|
|
|
|
// Create database
|
|
const db = new VectorDB({ dimensions: 128 });
|
|
await db.init();
|
|
|
|
// Insert vectors
|
|
const vector = new Float32Array(128).fill(0.5);
|
|
const id = db.insert(vector, 'my-vector', { label: 'example' });
|
|
|
|
// Search
|
|
const results = db.search(vector, 10);
|
|
console.log(results);
|
|
|
|
// Save to IndexedDB
|
|
await db.saveToIndexedDB();
|
|
```
|
|
|
|
### Node.js
|
|
|
|
```javascript
|
|
import { VectorDB } from '@ruvector/wasm/node';
|
|
|
|
// Create database
|
|
const db = new VectorDB({ dimensions: 128 });
|
|
await db.init();
|
|
|
|
// Insert vectors
|
|
const vector = new Float32Array(128).fill(0.5);
|
|
const id = db.insert(vector, 'my-vector', { label: 'example' });
|
|
|
|
// Search
|
|
const results = db.search(vector, 10);
|
|
console.log(results);
|
|
```
|
|
|
|
### Universal (Auto-detect)
|
|
|
|
```javascript
|
|
import { VectorDB } from '@ruvector/wasm';
|
|
|
|
// Works in both browser and Node.js
|
|
const db = new VectorDB({ dimensions: 128 });
|
|
await db.init();
|
|
|
|
const vector = new Float32Array(128).fill(0.5);
|
|
const id = db.insert(vector);
|
|
const results = db.search(vector, 10);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### VectorDB
|
|
|
|
#### Constructor
|
|
|
|
```typescript
|
|
new VectorDB(options: DbOptions)
|
|
```
|
|
|
|
Options:
|
|
- `dimensions: number` - Vector dimensions (required)
|
|
- `metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan'` - Distance metric (default: 'cosine')
|
|
- `useHnsw?: boolean` - Use HNSW index (default: true)
|
|
|
|
#### Methods
|
|
|
|
##### init()
|
|
|
|
Initialize the database (must be called before use).
|
|
|
|
```typescript
|
|
await db.init(): Promise<void>
|
|
```
|
|
|
|
##### insert()
|
|
|
|
Insert a single vector.
|
|
|
|
```typescript
|
|
db.insert(
|
|
vector: Float32Array | number[],
|
|
id?: string,
|
|
metadata?: Record<string, any>
|
|
): string
|
|
```
|
|
|
|
##### insertBatch()
|
|
|
|
Insert multiple vectors efficiently.
|
|
|
|
```typescript
|
|
db.insertBatch(entries: VectorEntry[]): string[]
|
|
```
|
|
|
|
##### search()
|
|
|
|
Search for similar vectors.
|
|
|
|
```typescript
|
|
db.search(
|
|
query: Float32Array | number[],
|
|
k: number,
|
|
filter?: Record<string, any>
|
|
): SearchResult[]
|
|
```
|
|
|
|
##### delete()
|
|
|
|
Delete a vector by ID.
|
|
|
|
```typescript
|
|
db.delete(id: string): boolean
|
|
```
|
|
|
|
##### get()
|
|
|
|
Get a vector by ID.
|
|
|
|
```typescript
|
|
db.get(id: string): VectorEntry | null
|
|
```
|
|
|
|
##### len()
|
|
|
|
Get the number of vectors.
|
|
|
|
```typescript
|
|
db.len(): number
|
|
```
|
|
|
|
##### isEmpty()
|
|
|
|
Check if database is empty.
|
|
|
|
```typescript
|
|
db.isEmpty(): boolean
|
|
```
|
|
|
|
##### getDimensions()
|
|
|
|
Get vector dimensions.
|
|
|
|
```typescript
|
|
db.getDimensions(): number
|
|
```
|
|
|
|
##### save()
|
|
|
|
Save database to persistent storage.
|
|
|
|
```typescript
|
|
await db.save(path?: string): Promise<void>
|
|
```
|
|
|
|
### Utility Functions
|
|
|
|
#### detectSIMD()
|
|
|
|
Check if SIMD is supported.
|
|
|
|
```typescript
|
|
const hasSIMD = await detectSIMD();
|
|
```
|
|
|
|
#### version()
|
|
|
|
Get library version.
|
|
|
|
```typescript
|
|
const ver = await version();
|
|
```
|
|
|
|
#### benchmark()
|
|
|
|
Run performance benchmark.
|
|
|
|
```typescript
|
|
const opsPerSec = await benchmark('insert', 1000, 128);
|
|
```
|
|
|
|
## Types
|
|
|
|
### VectorEntry
|
|
|
|
```typescript
|
|
interface VectorEntry {
|
|
id?: string;
|
|
vector: Float32Array | number[];
|
|
metadata?: Record<string, any>;
|
|
}
|
|
```
|
|
|
|
### SearchResult
|
|
|
|
```typescript
|
|
interface SearchResult {
|
|
id: string;
|
|
score: number;
|
|
vector?: Float32Array;
|
|
metadata?: Record<string, any>;
|
|
}
|
|
```
|
|
|
|
### DbOptions
|
|
|
|
```typescript
|
|
interface DbOptions {
|
|
dimensions: number;
|
|
metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan';
|
|
useHnsw?: boolean;
|
|
}
|
|
```
|
|
|
|
## Performance
|
|
|
|
Ruvector WASM delivers exceptional performance:
|
|
|
|
- **SIMD Acceleration**: Up to 4x faster with WebAssembly SIMD
|
|
- **HNSW Index**: Sub-linear search complexity
|
|
- **Zero-copy**: Efficient memory usage with transferable objects
|
|
- **Batch Operations**: Optimized bulk inserts
|
|
|
|
## Browser Compatibility
|
|
|
|
- Chrome 91+ (SIMD support)
|
|
- Firefox 89+ (SIMD support)
|
|
- Safari 16.4+ (SIMD support)
|
|
- Edge 91+ (SIMD support)
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Links
|
|
|
|
- [GitHub Repository](https://github.com/ruvnet/ruvector)
|
|
- [Documentation](https://github.com/ruvnet/ruvector#readme)
|
|
- [Issues](https://github.com/ruvnet/ruvector/issues)
|