Install & Compatibility
Where this runs
tested against v0.0.4.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.289s · 89.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.9s · import 0.312s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NanoVectorDB
✓ from nano_vectordb import NanoVectorDB
✗ from nano_vectordb.core import NanoVectorDB
The primary class is exposed directly at the top level of the package, not in a submodule.
This quickstart demonstrates how to initialize NanoVectorDB, add vectors with associated metadata and unique IDs, perform a similarity search, and persist/load the database from disk. It also includes cleanup for the database directory.
import numpy as np
from nano_vectordb import NanoVectorDB
import os
import shutil
# Initialize the database
db_path = "my_nano_vectordb"
db = NanoVectorDB(db_path, dim=4)
# Add vectors with metadata and IDs
db.add(np.array([1.0, 2.0, 3.0, 4.0]), {"text": "The quick brown fox."}, "doc1")
db.add(np.array([1.1, 2.1, 3.1, 4.1]), {"text": "Jumps over the lazy dog."}, "doc2")
db.add(np.array([0.9, 1.9, 2.9, 3.9]), {"text": "Another relevant document."}, "doc3")
# Perform a similarity search
query_vector = np.array([1.0, 2.0, 3.0, 4.0])
k_results = 2
results = db.search(query_vector, k=k_results)
print(f"\nSearch Results for top {k_results} documents:")
for vector, metadata, vector_id, score in results:
print(f" ID: {vector_id}, Metadata: {metadata}, Score: {score:.4f}")
# Save the database to disk
db.save()
print(f"\nDatabase saved to '{db_path}'")
# Load the database from disk
loaded_db = NanoVectorDB(db_path, dim=4) # Re-initialize with path and dim
loaded_db.load()
print(f"Database loaded from '{db_path}'. Number of items: {len(loaded_db.store)}")
# Clean up database files (optional)
if os.path.exists(db_path):
shutil.rmtree(db_path)
print(f"Cleaned up database directory: {db_path}")
Errors
Common errors & fixes
TypeError: 'list' object cannot be interpreted as an array
Input vectors passed to `add` or `search` methods are Python lists instead of NumPy arrays.
fixConvert your list of floats into a NumPy array before passing it to NanoVectorDB. Example: `np.array([1.0, 2.0, 3.0])`.
ValueError: Vector dimension mismatch. Expected {expected_dim}, got {actual_dim}.
The dimension of the vector being added or queried does not match the `dim` specified during `NanoVectorDB` initialization.
fixEnsure all vectors added to the database and all query vectors have the exact same dimension (`dim`) as defined when the `NanoVectorDB` instance was created. If loading from disk, the `dim` parameter must match the original saved database.
FileNotFoundError: [Errno 2] No such file or directory: '{db_path}/index.npy'
Attempting to load a database that has not been saved yet, or the specified `db_path` is incorrect, or the directory was deleted/moved.
fixEnsure `db.save()` was called previously. Verify that the `db_path` provided to `NanoVectorDB` when loading is identical to the path used when saving, and that the directory and its contents still exist.
Upgrade
Version history
0.0.4.3latest on PyPI · released Nov 11, 2024
Audit
Dependencies
numpyrequiredEssential for handling vector (embedding) data.
scikit-learnrequiredUsed internally for similarity calculations or related utilities.
tqdmrequiredProvides progress bars for operations, enhancing user experience.