Quick Start Guide

Prerequisites

💡 New to NeuronDB? For the fastest setup, use the Docker Quick Start which sets up the complete ecosystem (NeuronDB + NeuronAgent + NeuronMCP + NeuronDesktop) in 5 minutes.

Before you begin, make sure you have:

• ✅ NeuronDB installed - See Installation Guide for setup instructions
• ✅ PostgreSQL client - psql (or any SQL client)
• ✅ 5-10 minutes - For complete quickstart

# Check if psql is installed
psql --version

# Check if Docker is installed (if using Docker)
docker --version
docker compose version

Step 1: Install NeuronDB

If you haven't installed NeuronDB yet, choose your method:

Option A: Docker Compose (Recommended for Quick Start) 🐳

Fastest way to get started:

# From repository root
docker compose up -d neurondb

# Wait for service to be healthy (30-60 seconds)
docker compose ps neurondb

Expected output:

NAME                STATUS
neurondb-cpu        healthy

Option B: Native Installation 🔧

For production or custom setups: Follow the detailed Installation Guide for native PostgreSQL installation.

✅ Verify Installation

Test NeuronDB installation:

# With Docker Compose
docker compose exec neurondb psql -U neurondb -d neurondb -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

# Or with native PostgreSQL
psql -d your_database -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

# Check the version
docker compose exec neurondb psql -U neurondb -d neurondb -c "SELECT neurondb.version();"
# Or: psql -d your_database -c "SELECT neurondb.version();"

Expected output:

 version
---------
 3.0
(1 row)

Step 2: Load Quickstart Data Pack

The quickstart data pack provides ~500 sample documents with pre-generated embeddings, ready for immediate use.

Option 1: Using the CLI (Recommended) 🚀

Easiest method - handles everything automatically:

# From repository root
./scripts/neurondb-cli.sh quickstart

What it does:

1. Creates the quickstart_documents table
2. Loads ~500 sample documents
3. Creates HNSW index
4. Verifies data is loaded

Option 2: Using the Loader Script 📝

Manual control over the process:

# From repository root
./examples/quickstart/load_quickstart.sh

Option 3: Using psql Directly 💻

For maximum control:

# With Docker Compose
docker compose exec neurondb psql -U neurondb -d neurondb -f examples/quickstart/quickstart_data.sql

# Or with native PostgreSQL
psql -d your_database -f examples/quickstart/quickstart_data.sql

✅ Verify Data Loaded

Check that data was loaded successfully:

# Count documents
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" -c "SELECT COUNT(*) FROM quickstart_documents;"

Expected output:

 count
-------
   500
(1 row)

Check table structure:

\d quickstart_documents

Expected columns:

• id - Document ID
• title - Document title
• content - Document content
• embedding - Vector embedding (384 dimensions)

Step 3: Try SQL Recipes

The SQL recipe library provides ready-to-run queries for common operations.

Example 1: Basic Similarity Search 🎯

Find documents similar to a specific document:

-- Find documents similar to document #1
SELECT 
    id,
    title,
    embedding <=> (SELECT embedding FROM quickstart_documents WHERE id = 1) AS distance
FROM quickstart_documents
WHERE id != 1
ORDER BY embedding <=> (SELECT embedding FROM quickstart_documents WHERE id = 1)
LIMIT 10;

What this does:

1. Gets embedding of document #1
2. Calculates cosine distance to all other documents
3. Returns top 10 most similar documents

Example 2: Query with Text Embedding 🔤

Search using a text query:

-- Generate embedding for query text
WITH query AS (
  SELECT embed_text('machine learning algorithms', 'all-MiniLM-L6-v2') AS q_vec
)
-- Find similar documents
SELECT 
    id,
    title,
    embedding <=> q.q_vec AS distance
FROM quickstart_documents, query q
ORDER BY embedding <=> q.q_vec
LIMIT 10;

What this does:

1. Generates embedding for "machine learning algorithms"
2. Searches for documents with similar embeddings
3. Returns top 10 results

Example 3: Hybrid Search (Vector + Full-Text) 🔗

Combine vector similarity with PostgreSQL full-text search:

-- Hybrid search: vector + full-text
WITH query AS (
  SELECT 
    embed_text('machine learning', 'all-MiniLM-L6-v2') AS q_vec,
    to_tsquery('english', 'machine & learning') AS q_tsquery
)
SELECT 
    id,
    title,
    content,
    -- Combined score: 70% vector, 30% full-text
    (embedding <=> q.q_vec) * 0.7 + 
    (ts_rank(to_tsvector('english', content), q.q_tsquery) * 0.3) AS combined_score
FROM quickstart_documents, query q
WHERE to_tsvector('english', content) @@ q.q_tsquery
ORDER BY combined_score DESC
LIMIT 10;

What this does:

1. Generates vector embedding for query
2. Creates full-text search query
3. Combines both scores (70% vector, 30% text)
4. Returns top 10 results

Example 4: Filtered Search 🎛️

Add metadata filters to vector search:

-- Search with filters
WITH query AS (
  SELECT embed_text('technology', 'all-MiniLM-L6-v2') AS q_vec
)
SELECT 
    id,
    title,
    embedding <=> q.q_vec AS distance
FROM quickstart_documents, query q
WHERE id > 100  -- Example filter
  AND id < 200  -- Example filter
ORDER BY embedding <=> q.q_vec
LIMIT 10;

What this does:

1. Generates query embedding
2. Applies metadata filters (e.g., date range, category)
3. Searches only within filtered subset
4. Returns top 10 results

Understanding the Results

Next Steps

Continue your journey:

• 📐 Read Architecture Guide to understand components
• 🧪 Try more SQL Recipes
• 📚 Explore Complete Documentation
• 🔍 Check Troubleshooting Guide if needed
• 🤖 Try NeuronAgent Examples for agent workflows
• 🔌 Explore NeuronMCP Integration for MCP tools

CREATE INDEX ON quickstart_documents USING hnsw (embedding vector_cosine_ops);

SELECT embed_text('text', 'sentence-transformers/all-mpnet-base-v2');

CREATE TABLE my_docs (id SERIAL, content TEXT, embedding vector(384));

UPDATE my_docs SET embedding = embed_text(content, 'all-MiniLM-L6-v2');