Your First 5 Minutes with LocalVectorDB

This tutorial gets you from zero to searching documents in under 5 minutes. No complex setup, no configuration files - just the essentials to see LocalVectorDB in action.

What You’ll Build

In the next 5 minutes, you’ll:

  1. Install LocalVectorDB

  2. Create your first database

  3. Add some sample documents

  4. Search and see results

  5. Understand what just happened

Let’s Go!

Step 1: Install (30 seconds)

pip install localvectordb

That installs the library itself. This tutorial’s default embedding provider is Ollama, which runs locally and is installed separately (see No Ollama? No Problem! to use a hosted provider instead, or the Ollama setup steps near the end to install it).

Tip

It is best practice to isolate your environments using a virtual environment. Before running pip install ..., try using:

$ python -m venv venv
$ source venv/bin/activate

Step 2: Create and Test (4.5 minutes)

Create a new Python file called quick_start.py and copy this code:

from localvectordb import VectorDB

# Create a database (this creates files in ./my_first_db/)
print("Creating database...")
db = VectorDB(
    name="my_first_db",
    base_path="./my_first_db",
    embedding_provider="ollama",  # Uses local Ollama
    embedding_model="nomic-embed-text"
)

# Add some sample documents
print("Adding documents...")
documents = [
    "Python is a versatile programming language used for web development, data science, and automation.",
    "JavaScript enables interactive web pages and runs both in browsers and on servers with Node.js.",
    "Machine learning algorithms can automatically improve through experience and learn from data.",
    "LocalVectorDB is a simple vector database that makes semantic search easy to implement.",
    "Cooking pasta requires boiling water, adding salt, and cooking until al dente."
]

# Insert all documents at once
doc_ids = db.upsert(documents)
print(f"Added {len(doc_ids)} documents with IDs: {doc_ids}")

# Search for something
print("\nSearching for 'programming languages'...")
results = db.query("programming languages", k=3)

print(f"Found {len(results)} results:")
for i, result in enumerate(results, 1):
    print(f"\n{i}. Score: {result.score:.3f}")
    print(f"   Content: {result.content}")

# Try another search
print("\nSearching for 'cooking food'...")
results = db.query("cooking food", k=2)

print(f"Found {len(results)} results:")
for i, result in enumerate(results, 1):
    print(f"\n{i}. Score: {result.score:.3f}")
    print(f"   Content: {result.content}")

# Check database stats
import json
print(f"\nDatabase stats:\n{json.dumps(db.get_stats(), indent=2)}")

# Clean up
db.close()
print("\nDone! You just created your first vector database!")

Run Your First Database

python quick_start.py

You should see output like this:

Creating database...
Adding documents...
Added 5 documents with IDs: ['doc_1', 'doc_2', 'doc_3', 'doc_4', 'doc_5']

Searching for 'programming languages'...
Found 3 results:

1. Score: 0.789
   Content: Python is a versatile programming language used for web development, data science, and automation.

2. Score: 0.712
   Content: JavaScript enables interactive web pages and runs both in browsers and servers with Node.js.

3. Score: 0.234
   Content: Machine learning algorithms can automatically improve through experience and learn from data.

Searching for 'cooking food'...
Found 2 results:

1. Score: 0.856
   Content: Cooking pasta requires boiling water, adding salt, and cooking until al dente.

2. Score: 0.123
   Content: LocalVectorDB is a simple vector database that makes semantic search easy to implement.

Database stats:
{
  "documents": 5,
  "chunks": 5,
  "sections": 0,
  "index_vectors": 5,
  "embedding_dimension": 768,
  "embedding_provider": "ollama",
  "embedding_model": "nomic-embed-text",
  "chunking_method": "sentences",
  "chunk_size": 500,
  "chunk_overlap": 1,
  "fts_enabled": true,
  "hierarchical_embeddings": false
}

Done! You just created your first vector database!

What Just Happened?

You created an AI-powered search engine! Here’s what LocalVectorDB did behind the scenes:

  1. Generated Embeddings: Converted your text into numerical vectors that capture semantic meaning

  2. Built an Index: Created a searchable index of these vectors using FAISS

  3. Performed Semantic Search: Found documents similar in meaning, not just exact word matches

Notice how:

  • “programming languages” found both Python and JavaScript docs

  • “cooking food” found the pasta document, even though the query didn’t contain those exact words

  • The scores show relevance (higher = more similar)

Try It Yourself

Modify the script to:

Add Your Own Documents

my_documents = [
    "Your first document here",
    "Add as many as you want",
    "Each will be searchable"
]

doc_ids = db.upsert(my_documents)

Try Different Searches

# These will work even if the exact words aren't in your documents
results = db.query("artificial intelligence")
results = db.query("web development")
results = db.query("data analysis")

See Different Search Types

# Vector search (semantic similarity)
vector_results = db.query("machine learning", search_type="vector")

# Keyword search (exact word matching)
keyword_results = db.query("machine learning", search_type="keyword")

# Hybrid search (combines both)
hybrid_results = db.query("machine learning", search_type="hybrid")

No Ollama? No Problem!

If you don’t have Ollama installed, use this version instead:

from localvectordb import VectorDB

# Use OpenAI embeddings (requires API key)
db = VectorDB(
    name="my_first_db",
    base_path="./my_first_db",
    embedding_provider="openai",
    embedding_model="text-embedding-3-small",
    embedding_config={"api_key": "your-openai-api-key"}
)

# Rest of the code is the same...

Or install Ollama for free local embeddings:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull the embedding model
ollama pull nomic-embed-text

What’s Next?

You just built a working vector database! This same pattern scales to:

  • Thousands of documents: PDFs, articles, notes, code files

  • Advanced search: Filter by metadata, combine search types

  • Real applications: Chatbots, knowledge bases, recommendation systems

Ready to go deeper? Check out these tutorials:

  • FAQ Bot in 20 Lines: Turn this into a question-answering system

  • Index Your Downloads Folder: Search through your actual files

  • Building a RAG Chat Application: Create a full chatbot with memory

Files Created

Your first database created these files: - ./my_first_db/my_first_db.sqlite - Document storage and metadata - ./my_first_db/my_first_db.faiss - Vector index for fast search

You can delete the my_first_db folder when you’re done experimenting.

Congratulations!

In just 5 minutes, you’ve:

  • Created an AI-powered database

  • Added documents and performed semantic search

  • Seen how LocalVectorDB works under the hood

  • Built something you can immediately use and extend

Welcome to the world of vector databases!