Quick Start

Welcome to GoVector! This guide will help you get started with GoVector in just a few minutes. GoVector is a lightweight, embeddable vector database written entirely in Go, compatible with Qdrant's API.

📦 Installation

Option A: Install via Homebrew (Mac/Linux)

The easiest way to install GoVector and run it as a service:

brew tap DotNetAge/govector
brew install govector

# Start the background service (starts the REST API server)
brew services start govector

Option B: Build from Source

git clone https://github.com/DotNetAge/govector.git
cd govector
make build
# The binary will be available at ./bin/govector

Option C: Use as a Go Library

go get github.com/DotNetAge/govector/core

🚀 Quick Start Examples

Embedded Mode (Zero Network Overhead)

Use GoVector directly in your Go application:

package main

import (
    "fmt"
    "github.com/DotNetAge/govector/core"
)

func main() {
    // 1. Initialize local storage (creates a single .db file)
    store, _ := core.NewStorage("govector.db")
    defer store.Close()

    // 2. Create a Collection (Automatic Persistence)
    col, _ := core.NewCollection("documents", 384, core.Cosine, store, true)

    // 3. Upsert Data with Versioning
    col.Upsert([]core.PointStruct{
        {
            ID:      "doc_1",
            Vector:  []float32{0.1, 0.2, 0.3, /* ... 384 dimensions ... */},
            Payload: core.Payload{"category": "tech", "author": "John"},
        },
        {
            ID:      "doc_2",
            Vector:  []float32{0.4, 0.5, 0.6, /* ... 384 dimensions ... */},
            Payload: core.Payload{"category": "business", "author": "Jane"},
        },
    })

    // 4. Search with Metadata Filtering
    query := []float32{0.15, 0.25, 0.35, /* ... 384 dimensions ... */}
    filter := &core.Filter{
        Must: []core.Condition{
            {
                Key:   "category",
                Type:  core.MatchTypeExact,
                Match: core.MatchValue{Value: "tech"},
            },
        },
    }

    results, _ := col.Search(query, filter, 10)
    fmt.Printf("Best Match: %s (Score: %f)\n", results[0].ID, results[0].Score)
}

Microservice Mode (Qdrant Compatible)

Run GoVector as a standalone server with REST API:

# Start the server
govector serve ./govector.db -port 18080

# API Server ready on http://localhost:18080

Create a Collection

curl -X POST http://localhost:18080/collections -H "Content-Type: application/json" -d '{
  "name": "documents",
  "vector_size": 384,
  "distance": "cosine",
  "hnsw": true
}'

Upsert Vectors

curl -X PUT http://localhost:18080/collections/documents/points -H "Content-Type: application/json" -d '{
  "points": [
    {
      "id": "doc_1",
      "vector": [0.1, 0.2, 0.3, /* ... 384 dimensions ... */],
      "payload": {"category": "tech", "author": "John"}
    },
    {
      "id": "doc_2",
      "vector": [0.4, 0.5, 0.6, /* ... 384 dimensions ... */],
      "payload": {"category": "business", "author": "Jane"}
    }
  ]
}'

Search Vectors

curl -X POST http://localhost:18080/collections/documents/points/search -H "Content-Type: application/json" -d '{
  "vector": [0.15, 0.25, 0.35, /* ... 384 dimensions ... */],
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  },
  "limit": 10
}'

CLI Mode

GoVector comes with a powerful Command-Line Interface (CLI) and an interactive Terminal User Interface (TUI).

Interactive TUI

Run the binary without arguments to enter the Interactive TUI:

govector

(Provides a beautiful, green-themed environment with a /? help menu, auto-creation of DBs/collections, and graceful serve interruption).

Direct Commands

# General Syntax
govector <command> [dbfile] [options]

# Start the Qdrant-compatible REST API server
govector serve mydata.db -port 18080

# Insert data (auto-creates DB and HNSW-enabled collection if missing)
govector upsert mydata.db -c documents -j '{"id":"1", "vector":[0.1, 0.2], "payload":{"tag":"A"}}'

# Search data (with existence validation)
govector search mydata.db -c documents -v 0.1,0.2 -l 5

# List all collections
govector ls mydata.db

# Get point count in a collection
govector count mydata.db -c documents

# Delete a collection (safeguards protect the "default" collection)
govector rm mydata.db -c documents

🏗️ Architecture Overview

GoVector's architecture consists of several core components:

• Storage Engine: Uses go.etcd.io/bbolt with Protocol Buffers for persistent storage
• Index Module: Implements HNSW (Hierarchical Navigable Small World) and Flat indexes
• Collection Management: Provides namespace isolation and CRUD operations for collections
• API Layer: Offers both Go library API and HTTP REST API compatible with Qdrant
• Quantization Module: Implements SQ8 quantization for memory optimization

📊 Performance Benchmark

Measured on a standard machine with 16GB RAM, 128-dimensional vectors:

Index	Scale (N)	Build Time	Latency (Avg)	Throughput (QPS)	Memory (Alloc)
Flat	100K	186 ms	54.46 ms	18 QPS	59 MB
HNSW	100K	20.9 s	0.08 ms	11,812 QPS	311 MB
HNSW	1M	4m 17s	0.11 ms	8,709 QPS	3.32 GB

Note: HNSW maintained sub-millisecond latency even at 1 million scale, providing 480x speedup over Flat index at 100K.

🛠️ Key Features

• Pure Go & CGO-Free: Cross-compile to anywhere without messy C/C++ dependencies
• Qdrant Compatible API: Drop-in replacement with the same REST API endpoints
• High Performance: Optimized for single-node performance with sub-millisecond latency
• HNSW Indexing: Industrial-grade graph-based index for O(log N) search complexity
• Persistent Storage: Uses BoltDB and Protocol Buffers for ultra-fast persistence
• Advanced Filtering: Support for payload filtering (Exact, Range, Prefix, Regex, Contains)
• SQ8 Quantization: Built-in 8-bit scalar quantization to reduce disk footprint
• Dual Modes: Embedded library or standalone microservice with REST API
• Unified CLI & TUI: Powerful command-line interface with interactive Terminal User Interface

📖 Next Steps

• CLI Guide - Learn more about the command-line interface
• Embedded Mode - Deep dive into using GoVector as a library
• Microservice Mode - Learn about running GoVector as a server
• API Reference - Complete API documentation
• Architecture Overview - Understand GoVector's architecture in detail

🚩 Troubleshooting

Common Issues

• Port occupied: Modify the -port parameter when starting the server
• Vector dimension mismatch: Ensure the vector length matches the collection's dimension
• Collection not found: Create the collection before performing operations
• Permission issues: Ensure the database directory is readable/writable

Getting Help

• GitHub Issues - Report bugs or ask questions
• Go Documentation - API documentation
• Qdrant Documentation - For API compatibility reference