Quickstart

Overview

LocalVectorDB is a document-first vector database that combines the simplicity of SQLite with the power of FAISS for vector similarity search. Its architecture is focused on documents rather than chunks, making it easier to work with while providing more powerful features.

Key Features:

• Document-First API: Work with documents, not chunks - chunking is handled automatically

• Unified Search Interface: Vector, keyword, and hybrid search with normalized scoring

• Position-Tracking Chunking: Perfect document reconstruction with precise highlighting

• Structured Metadata: SQLite-backed metadata with indexed columns and schema validation

• Plugin-Based Embeddings: Support for Ollama, OpenAI, and custom embedding providers

• Full-Text Search: Built-in FTS5 support for keyword search

• Remote Client: HTTP API client for distributed deployments

• Production Ready: Comprehensive CLI, configuration management, and server deployment

Quick Installation

# Basic installation (uv recommended; pip works too)
uv add localvectordb
# pip install localvectordb

# With server dependencies
uv add "localvectordb[server]"
# pip install "localvectordb[server]"

# Development environment (dev tooling + test extras), via uv
uv sync --dev

# The whole kit and kaboodle:
uv add "localvectordb[all]"
# pip install "localvectordb[all]"

5-Minute Example

Note

This example uses the default embedding provider, Ollama, which must be running locally with the model pulled (ollama pull nomic-embed-text). To use a different backend, pass embedding_provider= (e.g. "openai", "sentence_transformers") with the matching embedding_model. See Embeddings for all providers.

from localvectordb import VectorDB
from localvectordb.core import MetadataField, MetadataFieldType

# Create a document database with metadata schema
db = VectorDB(
    name="my_documents",
    base_path="./my_vectordb",
    metadata_schema={
        'title': MetadataField(type=MetadataFieldType.TEXT, indexed=True,
                             embedding_enabled=True),  # Enable embeddings for title
        'author': MetadataField(type=MetadataFieldType.TEXT, indexed=True),
        'abstract': MetadataField(type=MetadataFieldType.TEXT,
                                embedding_enabled=True),  # Enable embeddings for abstract
        'date': MetadataField(type=MetadataFieldType.DATE, indexed=True),
        'tags': MetadataField(type=MetadataFieldType.JSON)
    },
    embedding_model="nomic-embed-text",
    chunk_size=500
)

# You can also define schema with shorthand:
#   metadata_schema = {
#       "title": ("text", True),   # type, indexed
#       "author": ("text", True, True),  # type, indexed, required
#       # ... etc.
#   }

# Add documents with metadata
documents = [
    "LocalVectorDB is a document-first vector database...",
    "Python is a powerful programming language...",
    "Machine learning enables computers to learn..."
]

metadata = [
    {"title": "LocalVectorDB Guide", "author": "AI Assistant", "date": "2024-01-01"},
    {"title": "Python Basics", "author": "Developer", "date": "2024-01-02"},
    {"title": "ML Introduction", "author": "Data Scientist", "date": "2024-01-03"}
]

# Insert documents
doc_ids = db.upsert(documents, metadata=metadata)
print(f"Added documents: {doc_ids}")

# Search documents
results = db.query("vector database", search_type="vector", k=3)
for result in results:
    print(f"Score: {result.score:.3f} | {result.content[:100]}...")

# Hybrid search combining vector and keyword search
results = db.query("python programming", search_type="hybrid", k=2)

# Multi-column search - searches document content AND metadata fields
# This searches across content, title, and abstract simultaneously
multi_results = db.query_multi_column("machine learning", k=5)
for result in multi_results:
    column = result.metadata.get('_search_column', 'unknown')
    print(f"Found in {column}: Score {result.score:.3f}")

# Search specific columns only
title_results = db.query_multi_column(
    "database",
    columns=['title', 'abstract'],  # Only search these fields
    k=3
)

# Filter by metadata
python_docs = db.filter(where={"author": "Developer"})

# Close database
db.close()

Server Example

# Start LocalVectorDB server
lvdb serve --host 127.0.0.1 --port 8000

# Create database via CLI
lvdb create my_database --embedding-model nomic-embed-text

# Add documents
lvdb db my_database add document.txt

# Search documents
lvdb db my_database search "query text" --limit 5

Remote Database Example

You can connect to the LocalVectorDB server using the VectorDB class, which allows for connecting to local or remote databases.

from localvectordb import VectorDB

# Connect to remote LocalVectorDB server
db = VectorDB(
    name="my_remote_db",
    base_path="http://localhost:8000",
    # Include api_key if you configured the server with api keys.
    # api_key="your_api_key"
)

# Same API as local database!
doc_ids = db.upsert(["Remote document content"])
results = db.query("search query")