### Local Development Commands for VectraDB

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Details the commands for building and running VectraDB locally for development and testing purposes. It covers building the binary, starting the server, initializing a new Raft cluster with a bootstrap flag, and cleaning up build artifacts and data. This enables a streamlined local development workflow.

```bash
# Build the binary
make build
# Output: bin/vectradb

# Run the server on port 8080
make run

# Run with bootstrap flag to initialize a new Raft cluster
./bin/vectradb -bootstrap

# Clean up build artifacts and data
make clean

# Server startup output:
# Initializing VectraDB (High-Perf) mode...
# Replaying WAL to restore data....
# Recovered 0 records from WAL
# VectraDB listening on port : 8080
```

--------------------------------

### GET /metrics

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Access Prometheus-compatible metrics for monitoring database performance including request counts, latency histograms, and vector counts.

```APIDOC
## GET /metrics

### Description
Access Prometheus-compatible metrics for monitoring database performance including request counts, latency histograms, and vector counts.

### Method
GET

### Endpoint
/metrics

### Parameters
None

### Response
#### Success Response (200)
- Metrics in Prometheus text format.

#### Response Example
```text
vectradb_insert_requests_total 15000
vectradb_search_requests_total 5000
vectradb_insert_duration_seconds_bucket{le="0.01"} 14500
vectradb_search_duration_seconds_bucket{le="0.1"} 4950
vectradb_vectors_total 15000
vectradb_raft_state 2
```
```

--------------------------------

### Create Sharded VectraDB Cluster

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Creates a sharded VectraDB cluster using consistent hashing to distribute vectors across multiple shards. Each shard can optionally be backed by a Raft node for distributed consensus, ensuring data consistency and availability. The example demonstrates initializing shards, setting up Raft nodes, and performing distributed insertions and searches.

```go
package main

import (
    "fmt"
    "github.com/rupamthxt/vectradb/internal/store"
    "github.com/rupamthxt/vectradb/internal/cluster"
)

func main() {
    numShards := 3
    var shards []store.ShardHandler

    // Initialize shards with Raft consensus
    for i := 0; i < numShards; i++ {
        dbPath := fmt.Sprintf("data/node1/shard_%d/meta.bin", i)
        db, _ := store.NewVectraDB(128, dbPath)

        // Create Raft node for distributed consensus
        raftNode, _ := cluster.NewRaftNode(i, "node1", "data/node1", 9000+i, db)
        shards = append(shards, raftNode)
    }

    // Create cluster from shards
    c := store.NewCluster(shards)

    // Insert - automatically routed to correct shard via consistent hashing
    c.Insert("user_embedding_001", []float32{0.5, 0.6, 0.7 /* ... */}, map[string]any{
        "user_id": 12345,
    })

    // Search - queries all shards in parallel, merges and ranks results
    results := c.Search([]float32{0.5, 0.6, 0.7 /* ... */}, 10)
    for _, r := range results {
        fmt.Printf("Found: %s (score: %.4f)\n", r.ID, r.Score)
    }
}
```

--------------------------------

### Perform Approximate Nearest Neighbor Search with HNSWIndex

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Implements an HNSW (Hierarchical Navigable Small World) index for efficient O(log N) approximate nearest neighbor searches. It uses a multi-layer graph structure with configurable parameters for search quality. The example demonstrates creating an HNSW index, adding vectors (which are first stored in a VectorArena), and performing similarity searches.

```go
package main

import (
    "fmt"
    "github.com/rupamthxt/vectradb/internal/store"
)

func main() {
    // Create arena first (HNSW stores vectors in arena)
    arena := store.NewVectorArena(128)

    // Create HNSW index with default parameters:
    // HNSW_M = 16 (max neighbors per node)
    // HNSW_M0 = 32 (max neighbors at layer 0)
    // HNSW_EfConstruct = 100 (candidates during construction)
    hnsw := store.NewHNSWIndex(arena)

    // Add vectors to both arena and HNSW index
    vectors := [][]float32{
        {0.1, 0.2, 0.3 /* ... */},
        {0.4, 0.5, 0.6 /* ... */},
        {0.7, 0.8, 0.9 /* ... */},
    }

    for i, vec := range vectors {
        idx, _ := arena.Add(vec)
        hnsw.Add(vec, fmt.Sprintf("vec_%d", i), idx)
    }

    // Search for nearest neighbors
    query := []float32{0.15, 0.25, 0.35 /* ... */}
    results := hnsw.Search(query, 5) // Top 5 results

    for _, r := range results {
        fmt.Printf("ID: %s, Score: %.4f\n", r.ID, r.Score)
    }
}
```

--------------------------------

### Manage Vector Storage with VectorArena

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Utilizes VectorArena for high-performance vector storage by allocating memory in contiguous 4MB pages. This bypasses Go's garbage collector for improved speed. Vectors are stored as raw float32 bytes using unsafe pointer operations. The example shows creating an arena, adding vectors, retrieving them by index, and checking the total vector count.

```go
package main

import (
    "fmt"
    "github.com/rupamthxt/vectradb/internal/store"
)

func main() {
    // Create arena for 128-dimensional vectors
    // Each 4MB page holds ~8000 vectors (4MB / (128 * 4 bytes))
    arena := store.NewVectorArena(128)

    // Add vectors to arena - returns global index
    idx1, _ := arena.Add([]float32{0.1, 0.2, 0.3 /* ... 128 floats */})
    idx2, _ := arena.Add([]float32{0.4, 0.5, 0.6 /* ... 128 floats */})

    fmt.Printf("Vector 1 stored at index: %d\n", idx1)
    fmt.Printf("Vector 2 stored at index: %d\n", idx2)

    // Retrieve vector by index
    vec, err := arena.Get(idx1)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Retrieved vector: %v\n", vec[:5]) // First 5 elements

    // Get total vector count
    fmt.Printf("Total vectors in arena: %d\n", arena.Size())
}
```

--------------------------------

### Initialize VectraDB Instance

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Initializes a new VectraDB instance, setting up the vector dimension, storage path for metadata, and enabling Write-Ahead Logging for durability. It also demonstrates inserting vectors with associated metadata and performing similarity searches.

```go
package main

import (
    "fmt"
    "log"
    "github.com/rupamthxt/vectradb/internal/store"
)

func main() {
    // Create a new VectraDB instance with 128-dimensional vectors
    // The storagePath is used for metadata persistence and WAL
    db, err := store.NewVectraDB(128, "./data/meta.bin")
    if err != nil {
        log.Fatalf("Failed to initialize VectraDB: %v", err)
    }

    // Insert vectors
    err = db.Insert("vec_001", []float32{0.1, 0.2, 0.3 /* ... 128 dimensions */}, map[string]any{
        "category": "document",
        "source":   "embedding_model",
    })
    if err != nil {
        log.Printf("Insert failed: %v", err)
    }

    // Search for similar vectors
    results := db.Search([]float32{0.1, 0.2, 0.3 /* ... query vector */}, 5)
    for _, r := range results {
        fmt.Printf("ID: %s, Score: %.4f\n", r.ID, r.Score)
    }

    // Get a specific vector by ID
    vec, meta, exists := db.Get("vec_001")
    if exists {
        fmt.Printf("Vector: %v, Metadata: %s\n", vec, string(meta))
    }
}
```

--------------------------------

### Docker Deployment Commands for VectraDB

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Provides essential commands for building and running VectraDB using Docker. It includes instructions for building the Docker image, running the container with persistent storage, viewing logs, and stopping the container. This facilitates easy deployment and management in containerized environments.

```bash
# Build the Docker image
make docker-build
# Or manually:
docker build --network=host -t vectradb:latest .

# Run the container with persistent storage
make docker-run
# Or manually:
docker run -d --rm \
  -p 8080:8080 \
  -v $(pwd)/data:/root/ \
  --name vectra_instance \
  vectradb:latest

# View container logs
docker logs vectra_instance

# Stop the container
docker stop vectra_instance

# Dockerfile configuration:
# FROM golang:1.25-alpine AS builder
# WORKDIR /app
# COPY go.mod go.sum ./
# RUN go mod download
# COPY . .
# RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o vectradb ./cmd/server/main.go
# 
# FROM alpine:latest
# WORKDIR /root/
# COPY --from=builder /app/vectradb .
# EXPOSE 8080
# CMD ["./vectradb"]
```

--------------------------------

### WAL Operations in Go

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Demonstrates how to use the Write-Ahead Log (WAL) for data durability in VectraDB. It covers opening the WAL file, writing insert operations before they are applied to the database, and recovering the database state by replaying the WAL on startup. This ensures data integrity even after restarts.

```go
package main

import (
    "fmt"
    "github.com/rupamthxt/vectradb/internal/store"
)

func main() {
    // Open WAL file (creates if doesn't exist)
    wal, err := store.OpenWal("./data/vectradb.wal")
    if err != nil {
        panic(err)
    }
    defer wal.Close()

    // Write entry to WAL before applying to database
    err = wal.WriteEntry(
        store.OpInsert,                           // Operation type
        "vec_001",                                // Vector ID
        []float32{0.1, 0.2, 0.3},                // Vector data
        []byte(`{"category": "test"}`),           // Metadata JSON
        store.FileLocation{Offset: 0, Length: 23}, // Disk location of metadata
    )
    if err != nil {
        fmt.Printf("WAL write failed: %v\n", err)
    }

    // Recover from WAL on startup
    err = wal.Recover(func(id string, vector []float32, meta []byte, loc store.FileLocation) {
        fmt.Printf("Recovering: ID=%s, VectorLen=%d\n", id, len(vector))
        // Re-insert into in-memory structures
    })
    if err != nil {
        fmt.Printf("Recovery failed: %v\n", err)
    }
}
```

--------------------------------

### Benchmark Suite Commands for VectraDB

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Explains how to use the built-in benchmark tool for VectraDB to measure ingestion and search performance. It includes commands for running the benchmark with default settings and custom parameters, such as dimensionality, number of items, queries, and shards. It also shows how to query Prometheus metrics exported during the benchmark.

```bash
# Run benchmark with default settings
make benchmark

# Run benchmark with custom parameters
go run ./cmd/benchmark/main.go \
  -dim 128 \
  -items 50000 \
  -queries 1000 \
  -shards 3 \
  -metrics-port 9091

# Benchmark output:
# 🔥 Starting VectraDB Distributed Benchmark (Raft + IVF)
# Config: Dim=128 | Items=50000 | Shards=3
# ⚡ Initializing Raft Groups...
# --- Phase 1: Ingestion (Raft Log Replication) ---
# ✅ Ingestion Complete: 2.35s
# --- Phase 2: Search (HNSW) ---
# 🚀 HNSW QPS: 14235.67
# 🔋 benchmark complete – metrics remain available at :9091/metrics

# Query Prometheus metrics during benchmark
curl http://localhost:9091/metrics | grep vectradb
```

--------------------------------

### Run VectraDB via Docker

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

This command initiates the VectraDB service using Docker, mapping the host's data directory to the container's data volume and exposing the default port 8080. It assumes a Docker image named 'vectradb:latest' is available.

```bash
make docker-run
# Or manually:
docker run -p 8080:8080 -v $(pwd)/data:/root/ vectradb:latest
```

--------------------------------

### Prometheus Scrape Configuration for VectraDB Metrics

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

This YAML snippet configures Prometheus to scrape metrics from a VectraDB benchmark instance. It specifies the job name and the target address where the metrics are exposed (localhost:9091).

```yaml
# prometheus.yml snippet
scrape_configs:
  - job_name: vectradb_bench
    static_configs:
      - targets: ['localhost:9091']
```

--------------------------------

### Search Vector API

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

Searches for the nearest neighbors to a given query vector within VectraDB.

```APIDOC
## POST /api/v1/search

### Description
Searches for the nearest neighbors to a given query vector within VectraDB.

### Method
POST

### Endpoint
/api/v1/search

### Parameters
#### Request Body
- **vector** (array of float) - Required - The query vector for the search.
- **k** (integer) - Required - The number of nearest neighbors to return.

### Request Example
```json
{
  "vector": [0.1, 0.5, 0.8],
  "k": 3
}
```

### Response
#### Success Response (200)
- **matches** (array of objects) - A list of the nearest neighbor matches.
  - **id** (string) - The ID of the matched vector.
  - **score** (float) - The similarity score of the match.
  - **metadata** (object) - The metadata associated with the matched vector.

#### Response Example
```json
{
  "matches": [
    {
      "id": "user_456",
      "score": 0.95,
      "metadata": {"role": "designer"}
    },
    {
      "id": "user_789",
      "score": 0.92,
      "metadata": {"role": "manager"}
    }
  ]
}
```
```

--------------------------------

### Insert Vector API

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

Inserts a vector with an associated ID and optional metadata into VectraDB.

```APIDOC
## POST /api/v1/insert

### Description
Inserts a vector with an associated ID and optional metadata into VectraDB.

### Method
POST

### Endpoint
/api/v1/insert

### Parameters
#### Request Body
- **id** (string) - Required - A unique identifier for the vector.
- **vector** (array of float) - Required - The vector data to insert.
- **metadata** (object) - Optional - Additional key-value metadata associated with the vector.

### Request Example
```json
{
  "id": "user_123",
  "vector": [0.1, 0.5, 0.9],
  "metadata": {"role": "engineer"}
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful insertion.

#### Response Example
```json
{
  "message": "Vector inserted successfully"
}
```
```

--------------------------------

### Access Prometheus Metrics from VectraDB (REST API)

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Retrieves Prometheus-compatible metrics for monitoring VectraDB's performance. This includes request counts, latency histograms, and vector counts, enabling integration with monitoring systems like Prometheus.

```bash
# Get all metrics
curl http://localhost:8080/metrics
```

```yaml
# Prometheus scrape configuration (prometheus.yml):
scrape_configs:
  - job_name: 'vectradb'
    static_configs:
      - targets: ['localhost:8080']
```

--------------------------------

### Insert a Vector using cURL

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

This cURL command demonstrates how to insert a vector into VectraDB via its REST API. It sends a POST request to the /api/v1/insert endpoint with a JSON payload containing the vector's ID, the vector data, and optional metadata.

```bash
curl -X POST http://localhost:8080/api/v1/insert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_123",
    "vector": [0.1, 0.5, 0.9],
    "metadata": {"role": "engineer"}
  }'
```

--------------------------------

### POST /api/v1/insert

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Insert a new vector with an ID and optional metadata into the database. The vector is stored in the arena memory allocator and indexed using HNSW for fast similarity search. Metadata is persisted to disk storage.

```APIDOC
## POST /api/v1/insert

### Description
Insert a new vector with an ID and optional metadata into the database. The vector is stored in the arena memory allocator and indexed using HNSW for fast similarity search. Metadata is persisted to disk storage.

### Method
POST

### Endpoint
/api/v1/insert

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier for the vector.
- **vector** (array of numbers) - Required - The vector data.
- **metadata** (object) - Optional - Key-value pairs for associated metadata.

### Request Example
```json
{
  "id": "user_123",
  "vector": [0.1, 0.5, 0.9, 0.2, 0.8, 0.3, 0.7, 0.4],
  "metadata": {"role": "engineer", "department": "ai"}
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful insertion.

#### Response Example
```json
{
  "message": "data inserted successfully"
}
```
```

--------------------------------

### Search for Vectors using cURL

Source: https://github.com/rupamthxt/vectradb/blob/main/readme.md

This cURL command illustrates how to perform a nearest neighbor search in VectraDB using its REST API. It sends a POST request to the /api/v1/search endpoint with a JSON payload specifying the query vector and the number of nearest neighbors (k) to retrieve.

```bash
curl -X POST http://localhost:8080/api/v1/search \
  -d '{"vector": [0.1, 0.5, 0.8], "k": 3}'
```

--------------------------------

### POST /api/v1/search

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Search for the k most similar vectors to a query vector using HNSW approximate nearest neighbor search. Results are returned sorted by similarity score in descending order. The search is distributed across all shards and results are merged.

```APIDOC
## POST /api/v1/search

### Description
Search for the k most similar vectors to a query vector using HNSW approximate nearest neighbor search. Results are returned sorted by similarity score in descending order. The search is distributed across all shards and results are merged.

### Method
POST

### Endpoint
/api/v1/search

### Parameters
#### Request Body
- **vector** (array of numbers) - Required - The query vector.
- **k** (integer) - Optional - The number of nearest neighbors to return. Defaults to 5.

### Request Example
```json
{
  "vector": [0.1, 0.5, 0.8, 0.2, 0.7, 0.3, 0.6, 0.4],
  "k": 3
}
```

### Response
#### Success Response (200)
- **results** (array of objects) - A list of the k most similar vectors found.
  - **id** (string) - The ID of the similar vector.
  - **score** (number) - The similarity score.
  - **metadata** (object or null) - The metadata associated with the vector, or null if none exists.

#### Response Example
```json
{
  "results": [
    {"id": "user_123", "score": 0.95, "metadata": {"role": "engineer", "department": "ai"}},
    {"id": "product_456", "score": 0.82, "metadata": {"category": "electronics"}},
    {"id": "embedding_789", "score": 0.71, "metadata": null}
  ]
}
```
```

--------------------------------

### Search Vectors in VectraDB (REST API)

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Performs an Approximate Nearest Neighbor (ANN) search using the HNSW index to find the k most similar vectors to a given query vector. Results are returned sorted by similarity score. This is essential for recommendation systems and similarity-based retrieval.

```bash
curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.5, 0.8, 0.2, 0.7, 0.3, 0.6, 0.4],
    "k": 3
  }'
```

```bash
curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
  }'
```

```bash
curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 0.85],
    "k": 10
  }'
```

--------------------------------

### Insert Vector into VectraDB (REST API)

Source: https://context7.com/rupamthxt/vectradb/llms.txt

Inserts a new vector with an ID and optional metadata into VectraDB. The vector is stored in memory and indexed for fast search, while metadata is persisted. This endpoint is crucial for populating the database with embedding data.

```bash
curl -X POST http://localhost:8080/api/v1/insert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_123",
    "vector": [0.1, 0.5, 0.9, 0.2, 0.8, 0.3, 0.7, 0.4],
    "metadata": {"role": "engineer", "department": "ai"}
  }'
```

```bash
curl -X POST http://localhost:8080/api/v1/insert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product_456",
    "vector": [0.25, 0.75, 0.15, 0.85, 0.45, 0.55, 0.35, 0.65],
    "metadata": {"category": "electronics", "price": 299.99, "name": "Wireless Headphones"}
  }'
```

```bash
curl -X POST http://localhost:8080/api/v1/insert \
  -H "Content-Type: application/json" \
  -d '{
    "id": "embedding_789",
    "vector": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
  }'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.