Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Fixed
- BQ initialization rejects packed binary storage before mutation instead of trapping in WASM. Binary search and buffer persistence remain usable after rejection.
- Runnable README/API examples construct `EdgeVecConfig` and enable BQ explicitly. BQ guidance distinguishes binary-code compression from retained F32 memory; Node examples verify real file save/load roundtrips.
- Binary HNSW compaction preserves packed storage; compaction also retains scalar calibration and enabled BQ state. WASM metadata follows surviving vectors when IDs are reassigned.
- Loaded TypeScript clients and indexes report saved dimensions and live counts. `EdgeVecIndex` exposes persistence buffers and the documented parsed sparse/hybrid methods.
- Hybrid search pairs sparse and dense document IDs, filters deleted documents before sparse top-k, and updates pairings after compaction. `insertSparseForVector()` supports explicit pairing.
Expand Down
85 changes: 54 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
> **The first WASM-native vector database.**
> Dense + sparse vectors, hybrid search, binary quantization, metadata filtering — all in the browser.

EdgeVec is an embedded vector database built in Rust with first-class WebAssembly support. It brings server-grade vector database features to the browser: **HNSW + FlatIndex**, **sparse vectors with BM25**, **hybrid search (RRF fusion)**, **32x memory reduction** via binary quantization, metadata filtering, soft delete, persistence, and sub-millisecond search.
EdgeVec is an embedded vector database built in Rust with first-class WebAssembly support. It brings server-grade vector database features to the browser: **HNSW + FlatIndex**, **sparse vectors with BM25**, **hybrid search (RRF fusion)**, **32x smaller binary codes**, metadata filtering, soft delete, persistence, and sub-millisecond search.

---

Expand Down Expand Up @@ -55,12 +55,14 @@ npm install edgevec
```

```typescript
import init, { EdgeVec } from 'edgevec';
import init, { EdgeVec, EdgeVecConfig } from 'edgevec';

await init();

// Create index (768D for embeddings like OpenAI, Cohere)
const db = new EdgeVec({ dimensions: 768 });
const config = new EdgeVecConfig(768);
const db = new EdgeVec(config);
config.free();

// Insert vectors with metadata (v0.6.0)
const vector = new Float32Array(768).map(() => Math.random());
Expand All @@ -74,8 +76,9 @@ const id = db.insertWithMetadata(vector, {
const query = new Float32Array(768).map(() => Math.random());
const results = db.searchWithFilter(query, 'category = "books" AND price < 50', 10);

// Fast BQ search with rescoring — 32x less memory, 95% recall (v0.6.0)
const fastResults = db.searchBQ(query, 10);
// Enable BQ explicitly, then rescore binary candidates with retained F32 vectors
db.enableBQ();
const fastResults = db.searchBQRescored(query, 10, 5);

// Monitor memory pressure (v0.6.0)
const pressure = db.getMemoryPressure();
Expand Down Expand Up @@ -139,7 +142,10 @@ Read more: [Entity-Enhanced RAG in 300KB](docs/blog/entity-enhanced-rag.md)

## Performance

EdgeVec v0.9.0 uses **SIMD instructions** for 2x+ faster vector operations on modern browsers.
EdgeVec supports SIMD builds for modern browsers. The checked-in package and
GitHub Pages demo intentionally use a scalar compatibility build for older
Safari versions. The native benchmark figures below are separate from that
browser artifact.

### Distance Calculation (Native Benchmark)

Expand All @@ -166,22 +172,33 @@ EdgeVec v0.9.0 uses **SIMD instructions** for 2x+ faster vector operations on mo

### Browser Support

| Browser | SIMD | Performance |
|:--------|:-----|:------------|
| Chrome 91+ | YES | Full speed |
| Firefox 89+ | YES | Full speed |
| Safari 16.4+ | YES | Full speed (macOS) |
| Edge 91+ | YES | Full speed |
| iOS Safari | NO | Scalar fallback |
| Browser | SIMD build support |
|:--------|:-------------------|
| Chrome 91+ | Yes |
| Firefox 89+ | Yes |
| Safari 16.4+ (macOS, iOS, iPadOS) | Yes |
| Edge 91+ | Yes |
| Safari 15–16.3 | Use the scalar build |

[Safari 16.4 added WebAssembly SIMD](https://webkit.org/blog/13966/webkit-features-in-safari-16-4/).
SIMD and scalar are separate compile-time builds; there is no automatic runtime
fallback. The default source build (`npm run build`) enables SIMD. To reproduce
the checked-in compatibility artifact, use this Bash command:

> **Note:** iOS Safari doesn't support WASM SIMD. EdgeVec automatically uses scalar
> fallback, which is ~2x slower but still functional.
```bash
RUSTFLAGS="-C target-feature=-simd128" npm run build
```

### Bundle Size

| Package | Size (gzip) | Notes |
|:--------|:------------|:------|
| edgevec | **217 KB** | SIMD enabled (541 KB uncompressed) |
| Checked-in scalar artifact | Bytes | Bytes (gzip) |
|:---------------------------|------:|-------------:|
| WASM | 698,412 | 266,010 |
| JavaScript glue | 162,843 | 29,492 |
| Combined | 861,255 | 295,502 |

[Current artifact validation](docs/benchmarks/2026-10-20_onboarding.json) records
the compiler, build flags, hashes, and measured performance.

[Full benchmark report ->](docs/benchmarks/2025-12-24_simd_benchmark.md)

Expand All @@ -191,11 +208,16 @@ EdgeVec v0.9.0 uses **SIMD instructions** for 2x+ faster vector operations on mo

### Binary Quantization (v0.6.0)

32x memory reduction with minimal recall loss:
Binary codes use 1 bit per dimension, 32x smaller than F32 payloads. Enabling BQ
on a float index retains the original F32 vectors for rescoring.

```javascript
// BQ is auto-enabled for dimensions divisible by 8
const db = new EdgeVec({ dimensions: 768 });
// BQ requires dimensions divisible by 8 and explicit enablement
const config = new EdgeVecConfig(768);
const db = new EdgeVec(config);
config.free();
db.enableBQ();
db.insert(vector);

// Raw BQ search (~85% recall, ~5x faster)
const bqResults = db.searchBQ(query, 10);
Expand All @@ -204,11 +226,14 @@ const bqResults = db.searchBQ(query, 10);
const rescoredResults = db.searchBQRescored(query, 10, 5);
```

| Mode | Memory (100k × 768D) | Speed | Recall@10 |
| Mode | Vector payloads (100k × 768D) | Speed | Recall@10 |
|:-----|:---------------------|:------|:----------|
| F32 (baseline) | ~300 MB | 1x | 100% |
| BQ raw | **~10 MB** | 5x | ~85% |
| BQ + rescore(5) | **~10 MB** | 3x | ~95% |
| F32 (baseline) | ~293 MiB | 1x | 100% |
| BQ raw on a float index | ~302 MiB (F32 + codes) | 5x | ~85% |
| BQ + rescore(5) | ~302 MiB (F32 + codes) | 3x | ~95% |

Payload sizes exclude graph, metadata, and capacity overhead. Speed and recall
depend on the data and hardware. [BQ memory details](docs/guides/BINARY_QUANTIZATION.md#memory-savings).

### Metadata Filtering (v0.6.0)

Expand Down Expand Up @@ -287,12 +312,10 @@ const restored = EdgeVec.fromBytes(bytes);

### Scalar Quantization

```javascript
const config = new EdgeVecConfig(768);
config.quantized = true; // Enable SQ8 quantization

// 3.6x memory reduction: 3.03 GB -> 832 MB at 1M vectors
```
SQ8 is available in the native Rust storage API through
`StorageType::QuantizedU8(QuantizerConfig { min, max })`. The WASM
`EdgeVecConfig` has no SQ8 option; assigning `config.quantized` does not enable
quantization. For WASM, use the explicit BQ API shown above.

### FlatIndex (v0.9.0)

Expand Down
5 changes: 4 additions & 1 deletion docs/api/FLAT_INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -397,7 +397,10 @@ assert_eq!(index.capacity(), 2); // Reclaimed

## Binary Quantization

FlatIndex supports optional binary quantization (BQ) for approximate search with reduced memory usage.
Native FlatIndex supports optional binary quantization (BQ) for approximate
search using compact codes. It retains the original float vectors for rescoring.
The WASM Flat index uses packed binary storage and does not expose this native
float-index quantization option.

### How It Works

Expand Down
22 changes: 13 additions & 9 deletions docs/api/MEMORY.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,17 +159,21 @@ if (recommendation.includes('compact')) {

## Memory Optimization Strategies

### 1. Enable Binary Quantization
### 1. Budget for Binary Quantization

The most effective way to reduce memory: 32x reduction.
Binary codes are 32x smaller than F32 vector payloads. Enabling BQ on a float
index retains the original F32 vectors for rescoring, so it adds a code cache
rather than reducing total index memory.

```typescript
// BQ is auto-enabled for dimensions divisible by 8
const index = new EdgeVec({ dimensions: 768 });

// Memory comparison (100k vectors, 768D):
// - F32: ~300 MB
// - BQ: ~10 MB
const config = new EdgeVecConfig(768);
const index = new EdgeVec(config);
config.free();
index.enableBQ();

// Vector payloads (100k vectors, 768D; excludes graph and metadata):
// - F32: ~293 MiB
// - BQ codes: ~9 MiB, in addition to retained F32 vectors
```

### 2. Periodic Compaction
Expand Down Expand Up @@ -333,7 +337,7 @@ console.log(JSON.stringify(dashboard, null, 2));

1. **Monitor regularly** - Check memory pressure before bulk operations
2. **Compact proactively** - Don't wait for critical pressure
3. **Use BQ when possible** - 32x memory savings with minimal recall loss
3. **Budget for BQ** - Binary codes are 32x smaller than F32 payloads; float indexes retain both for rescoring
4. **Set appropriate thresholds** - Lower on mobile, higher on desktop
5. **Handle insert blocks gracefully** - Provide user feedback

Expand Down
40 changes: 25 additions & 15 deletions docs/api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,14 @@ npm install edgevec
```

```typescript
import init, { EdgeVec } from 'edgevec';
import init, { EdgeVec, EdgeVecConfig } from 'edgevec';

await init();

// Create index (768D for embeddings like OpenAI, Cohere)
const db = new EdgeVec({ dimensions: 768 });
const config = new EdgeVecConfig(768);
const db = new EdgeVec(config);
config.free();

// Insert vectors with metadata (v0.6.0)
const vector = new Float32Array(768).map(() => Math.random());
Expand All @@ -52,10 +54,11 @@ const id = db.insertWithMetadata(vector, {

// Search with filter expression (v0.6.0)
const query = new Float32Array(768).map(() => Math.random());
const results = db.searchFiltered(query, 'category = "books" AND price < 50', 10);
const results = db.searchWithFilter(query, 'category = "books" AND price < 50', 10);

// Fast BQ search with rescoring (v0.6.0)
const fastResults = db.searchBQ(query, 10);
// Enable BQ explicitly, then rescore using retained F32 vectors
db.enableBQ();
const fastResults = db.searchBQRescored(query, 10, 5);

// Monitor memory pressure (v0.6.0)
const pressure = db.getMemoryPressure();
Expand Down Expand Up @@ -94,11 +97,15 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {

## v0.6.0 Features Summary

### Binary Quantization (32x Memory Reduction)
### Binary Quantization (32x Smaller Codes)

```javascript
// BQ is auto-enabled for dimensions divisible by 8
const db = new EdgeVec({ dimensions: 768 });
// BQ requires dimensions divisible by 8 and explicit enablement
const config = new EdgeVecConfig(768);
const db = new EdgeVec(config);
config.free();
db.enableBQ();
db.insert(vector);

// Raw BQ search (~85% recall, ~5x faster)
const bqResults = db.searchBQ(query, 10);
Expand All @@ -107,11 +114,14 @@ const bqResults = db.searchBQ(query, 10);
const rescoredResults = db.searchBQRescored(query, 10, 5);
```

| Mode | Memory (100k x 768D) | Speed | Recall@10 |
| Mode | Vector payloads (100k x 768D) | Speed | Recall@10 |
|:-----|:---------------------|:------|:----------|
| F32 (baseline) | ~300 MB | 1x | 100% |
| BQ raw | **~10 MB** | 5x | ~85% |
| BQ + rescore(5) | **~10 MB** | 3x | ~95% |
| F32 (baseline) | ~293 MiB | 1x | 100% |
| BQ raw on a float index | ~302 MiB (F32 + codes) | 5x | ~85% |
| BQ + rescore(5) | ~302 MiB (F32 + codes) | 3x | ~95% |

Float indexes retain their F32 vectors when BQ is enabled. Payload sizes exclude
graph, metadata, and capacity overhead; speed and recall depend on data/hardware.

### Metadata Filtering

Expand All @@ -124,8 +134,8 @@ db.insertWithMetadata(vector, {
});

// Search with filter
db.searchFiltered(query, 'category = "electronics" AND price < 500', 10);
db.searchFiltered(query, 'tags ANY ["featured"]', 10);
db.searchWithFilter(query, 'category = "electronics" AND price < 500', 10);
db.searchWithFilter(query, 'tags ANY ["featured"]', 10);
```

**Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, `NOT`, `ANY`
Expand Down Expand Up @@ -225,7 +235,7 @@ if (!db.canInsert()) {
| Search (100k vectors) | <10 ms | 329 us |
| Insert latency | <5 ms | ~2 ms |
| Bundle size (gzip) | <500 KB | 227 KB |
| BQ memory reduction | 8-32x | 32x |
| Binary-code compression relative to F32 payloads | 32x | 32x (float index retains both) |
| BQ recall@10 | >0.90 | 0.95 |

---
Expand Down
Loading
Loading