Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
EdgeVec is a high-performance, WebAssembly (WASM)-first vector database designed for use in both web browsers and Node.js environments. It utilizes the Hierarchical Navigable Small World (HNSW) graph algorithm to provide $O(\log n)$ search complexity and efficient vector similarity searches. This guide provides the necessary steps to set up the environment, initialize the database, and perform core operations such as insertion and filtered search.
Sources: GATE_1_COMPLETE.md:104-107, wasm/examples/index.html:1056-1065
Environment Setup
EdgeVec requires specific toolchains depending on the target environment. For Node.js, version 16.0.0 or higher is required. For browser-based environments, the WASM module must be served via a web server (e.g., Python's http.server) to ensure correct access to the /pkg/ directory.
Prerequisites
| Tool | Version/Requirement | Context |
|---|---|---|
| Node.js | >= 16.0.0 | Required for Node.js examples |
| wasm-pack | Latest | Required for building WASM package |
| Web Server | Project Root access | Required for browser WASM loading |
| Cargo/Rust | Latest stable | Required for local builds and tests |
Sources: examples/nodejs/README.md:5-7, scripts/pre-release-check.sh:65-72, wasm/examples/index.html:1063-1065
Installation and Build
To use EdgeVec in a local project, you must first build the WASM package.
# From the project root
cargo install wasm-pack
wasm-pack build --release
# For Node.js examples
cd examples/nodejs
npm install
Sources: scripts/pre-release-check.sh:160-165, examples/nodejs/README.md:12-15
Database Initialization
Initialization involves loading the WASM module and configuring the EdgeVec instance. The EdgeVecConfig object defines the vector dimensionality and optional HNSW parameters.
Configuration Parameters
The EdgeVecConfig defines the technical constraints of the index.
| Parameter | Type | Description |
|---|---|---|
| dimensions | number | The size of the vector space (e.g., 128, 768) |
| m | number | Max number of neighbors per node (default 16) |
| ef_construction | number | Search buffer size during index building |
Sources: wasm/examples/stress-test.html:618-621, wasm/examples/v070_filter_playground.html:236-241
Initialization Flow
The following diagram illustrates the sequence for initializing the database in a JavaScript environment.
Core Operations
Vector Insertion
Vectors can be inserted individually or in batches. Batch insertion is recommended for large datasets to minimize the overhead of the JavaScript-WASM boundary.
// Single insertion
const id = index.insert(new Float32Array([0.1, 0.2, ...]));
// Batch insertion
const vectors = [new Float32Array([...]), new Float32Array([...])];
const result = index.insertBatch(vectors);
Sources: wasm/examples/batch_insert.js:296-302, wasm/examples/index.html:1174-1180
Metadata Filtering
EdgeVec supports SQL-like metadata filtering. Metadata must be associated with vectors during insertion or via specific setter functions.
Common Filter Operators
| Operator | Description | Example |
|---|---|---|
=, != | Equality | category = "tech" |
>, < | Numeric comparison | price < 500 |
AND, OR | Logical operators | price < 100 AND inStock = true |
IN | Array membership | status IN ["active", "pending"] |
Sources: wasm/examples/v070_filter_playground.html:137-160, wasm/examples/index.html:1240-1250
Persistence
EdgeVec provides a platform-agnostic persistence layer. In browser environments, it utilizes IndexedDB, while native environments can use file-based storage.
// Saving to persistence
await index.save("my_database_name");
// Loading from persistence
const loadedIndex = await EdgeVec.load("my_database_name");
Sources: wasm/examples/stress-test.html:663-678, examples/nodejs/README.md:77-83
Summary
To get started with EdgeVec, developers must build the WASM binary using wasm-pack, initialize an EdgeVec instance with a defined dimensionality, and use the provided JavaScript/TypeScript APIs for vector management. The system is optimized for browser performance, offering features like batch insertion and metadata filtering with minimal memory overhead (approximately 82 bytes per vector).
Sources: GATE_1_COMPLETE.md:82, examples/nodejs/README.md:103-105