https://github.com/observedobserver/vecal
vector database in browser based on indexeddb
https://github.com/observedobserver/vecal
Last synced: 7 months ago
JSON representation
vector database in browser based on indexeddb
- Host: GitHub
- URL: https://github.com/observedobserver/vecal
- Owner: ObservedObserver
- License: apache-2.0
- Created: 2024-04-28T16:55:04.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-17T03:12:03.000Z (7 months ago)
- Last Synced: 2025-06-17T04:21:56.911Z (7 months ago)
- Language: TypeScript
- Homepage: https://vecal-docs.vercel.app
- Size: 322 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vecal
Vector database in browser based on IndexedDB.
## Features
- CRUD operations for vectors
- Similarity search using multiple distance metrics
- Optional LSH based index with approximate nearest neighbour (ANN) search
## Installation
```bash
npm install vecal
# or
yarn add vecal
```
## Basic Usage
```ts
import { VectorDB } from 'vecal';
const db = new VectorDB({ dbName: 'example', dimension: 3 });
const id = await db.add(new Float32Array([0.9, 0.1, 0.1]), { label: 'Apple' });
const results = await db.search(new Float32Array([0.85, 0.2, 0.15]), 2);
console.log(results);
```
### Using the LSH index
```ts
await db.buildIndex(8);
const ann = await db.annSearch(new Float32Array([0.85, 0.2, 0.15]), 2);
```
### Closing the database
```ts
await db.close();
```
## API Reference
### `new VectorDB(config: VectorDBConfig)`
Creates a database instance. `config` fields:
- `dbName` – name of the IndexedDB database.
- `dimension` – length of the stored vectors.
- `storeName` – optional object store name (defaults to `"vectors"`).
- `distanceType` – optional default distance metric.
- `minkowskiP` – power parameter when using Minkowski distance (default `3`).
### `add(vector, metadata?) => Promise`
Add a vector with optional metadata. Returns the generated id.
### `get(id) => Promise`
Retrieve a stored entry.
### `update(id, update) => Promise`
Partially update an entry.
### `delete(id) => Promise`
Remove an entry from the database.
### `buildIndex(numHashes?) => Promise`
Build an LSH index from all entries. `numHashes` controls the number of hyperplanes (default `10`).
### `search(query, k?, distanceType?) => Promise`
Exact similarity search. `distanceType` can be `"cosine"`, `"l2"`, `"l1"`, `"dot"`, `"hamming"`, or `"minkowski"`.
### `annSearch(query, k?, radius?, distanceType?) => Promise`
Approximate nearest neighbour search using the LSH index. The index is built lazily when first needed. `distanceType` uses the same options as `search`.
### `close() => Promise`
Close the underlying IndexedDB connection.
### Types
- `VectorDBConfig`
- `VectorEntry`
- `SearchResult`
- `DistanceType`
## Tutorial: indexing text with OpenAI embeddings
The `src/main.ts` file in this repository demonstrates how to build a small Hacker News search tool. The high level steps are:
1. obtain an OpenAI API key;
2. fetch items to index;
3. convert each title to an embedding using the API;
4. create a `VectorDB` with the embedding dimension and store each vector;
5. run searches with `db.search` or `db.annSearch`.
Refer to the code for a full example.