Usage Modes¶

GoVector supports multiple usage modes to adapt to different application scenarios. This document explains the different modes and how to use them effectively.

🚀 Embedded Mode¶

Embedded mode is the most lightweight way to use GoVector. In this mode, the vector database runs directly within your application process, eliminating network overhead.

Key Features¶

Zero network overhead: All operations are performed in-memory
Simple integration: Add as a dependency to your Go project
Fast performance: Direct access to data structures
Single-process deployment: No separate server required

Getting Started¶

Install the dependency:

go get github.com/yourusername/govector

Initialize the database:

import (
    "github.com/yourusername/govector/core"
)

// Create a new collection with default configuration
collection, err := core.NewCollection(core.CollectionConfig{
    Name:       "my-collection",
    VectorLen:  768, // Embedding dimension
    Metric:     core.Cosine, // Distance metric
    IndexType:  core.HNSW, // Index type
    Quantize:   false, // Disable quantization
})
if err != nil {
    log.Fatalf("Failed to create collection: %v", err)
}

Perform operations:

// Upsert points
points := []core.PointStruct{
    {
        ID:     "doc_1",
        Vector: []float32{0.1, 0.2, 0.3, /* ... */},
        Payload: core.Payload{
            "category": "tech",
        },
    },
    // Add more points...
}

if err := collection.Upsert(points); err != nil {
    log.Fatalf("Failed to upsert points: %v", err)
}

// Search
queryVector := []float32{0.1, 0.2, 0.3, /* ... */}
results, err := collection.Search(queryVector, nil, 10)
if err != nil {
    log.Fatalf("Failed to search: %v", err)
}

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

Persist and load:

// Save to disk
if err := collection.Save("/path/to/collection"); err != nil {
    log.Fatalf("Failed to save collection: %v", err)
}

// Load from disk
loadedCollection, err := core.LoadCollection("/path/to/collection")
if err != nil {
    log.Fatalf("Failed to load collection: %v", err)
}

Use Cases¶

Edge devices: Run directly on devices with limited resources
Single-user applications: Simplified deployment for personal tools
High-performance services: Eliminate network latency for critical operations
Testing and development: Easy setup for local development

🌐 Microservice Mode¶

Microservice mode allows GoVector to run as a standalone server, accessible via HTTP API. This mode is compatible with Qdrant's API, making it easy to integrate with existing Qdrant clients.

Key Features¶

Qdrant-compatible API: Use existing Qdrant clients and tools
Network accessibility: Access from multiple applications
Scalable deployment: Run as a separate service
Standard HTTP interface: Easy integration with any programming language

Getting Started¶

Start the server:

# From source
go run cmd/server/main.go --host 0.0.0.0 --port 6333 --data ./data

# Or using the compiled binary
govector-server --host 0.0.0.0 --port 6333 --data ./data

API Endpoints:

GoVector implements the same API endpoints as Qdrant, including:

POST /collections - Create collection
GET /collections - List collections
DELETE /collections/{collection_name} - Delete collection
PUT /collections/{collection_name}/points - Upsert points
POST /collections/{collection_name}/points/search - Search points
DELETE /collections/{collection_name}/points - Delete points
Using the API:

# Create collection
curl -X POST http://localhost:6333/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-collection",
    "vectors": {
      "size": 768,
      "distance": "Cosine"
    }
  }'

# Upsert points
curl -X PUT http://localhost:6333/collections/my-collection/points \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "id": "doc_1",
        "vector": [0.1, 0.2, 0.3, /* ... */],
        "payload": {
          "category": "tech"
        }
      }
    ]
  }'

# Search
curl -X POST http://localhost:6333/collections/my-collection/points/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, /* ... */],
    "limit": 10
  }'

Using Qdrant Clients:

You can use any Qdrant client library to interact with GoVector:

# Using Python client
from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", port=6333)

# Create collection
client.create_collection(
    collection_name="my-collection",
    vectors_config={"size": 768, "distance": "Cosine"}
)

# Upsert points
client.upsert(
    collection_name="my-collection",
    points=[
        {
            "id": "doc_1",
            "vector": [0.1, 0.2, 0.3, /* ... */],
            "payload": {"category": "tech"}
        }
    ]
)

# Search
results = client.search(
    collection_name="my-collection",
    query_vector=[0.1, 0.2, 0.3, /* ... */],
    limit=10
)

Use Cases¶

Multi-application systems: Share vector database across multiple services
Language-agnostic applications: Use with non-Go programming languages
Centralized vector storage: Single source of truth for vector data
Existing Qdrant migrations: Drop-in replacement for Qdrant

🖥️ CLI Mode¶

GoVector provides a command-line interface for basic operations and management tasks.

Key Features¶

Interactive shell: Explore and manage collections
Batch operations: Import/export data
Collection management: Create, list, and delete collections
Status monitoring: Check database health and statistics

Getting Started¶

Start the CLI:

# From source
go run cmd/cli/main.go

# Or using the compiled binary
govector-cli

Basic Commands:

# Create collection
create-collection --name my-collection --vector-len 768 --metric cosine

# Upsert points from file
upsert --collection my-collection --file points.json

# Search
search --collection my-collection --vector "[0.1, 0.2, 0.3]" --limit 10

# List collections
list-collections

# Delete collection
delete-collection --name my-collection

Interactive Mode:

$ govector-cli

GoVector CLI v1.0.0
Type 'help' for available commands

> create-collection --name my-collection --vector-len 768
Collection 'my-collection' created successfully

> upsert --collection my-collection --points '{"id": "doc_1", "vector": [0.1, 0.2, 0.3], "payload": {"category": "tech"}}'
1 point upserted successfully

> search --collection my-collection --vector "[0.1, 0.2, 0.3]" --limit 5
Results:
ID: doc_1, Score: 1.0000, Payload: map[category:tech]

> exit

Use Cases¶

Administrative tasks: Manage collections and data
Data migration: Import/export between systems
Testing and debugging: Verify functionality
Quick prototyping: Test vector search without writing code

📊 Mode Comparison¶

Feature	Embedded Mode	Microservice Mode	CLI Mode
Network Overhead	None	HTTP requests	None (local)
Integration	Go code only	Any language	Command line
Deployment	Single process	Separate service	Local tool
Performance	Highest	Moderate	Moderate
Ease of Setup	Very easy	Easy	Very easy
Scalability	Limited	High	Limited

💡 Best Practices¶

Choosing the Right Mode¶

Embedded Mode: Best for single-application, high-performance scenarios
Microservice Mode: Best for multi-application, language-agnostic scenarios
CLI Mode: Best for administrative tasks and debugging

Performance Considerations¶

Embedded Mode:
Use HNSW index for large datasets
Enable SQ8 quantization for memory optimization
Batch operations for bulk inserts
Microservice Mode:
Use proper HTTP client configuration (timeouts, retries)
Batch requests to reduce network overhead
Consider load balancing for high-traffic scenarios

Security Considerations¶

Microservice Mode:
Use HTTPS in production
Implement authentication if exposed to external networks
Limit network access to trusted clients

🚩 Common Issues¶

Embedded Mode¶

Memory Usage: Large collections may consume significant memory
Solution: Enable SQ8 quantization, use appropriate index parameters
Concurrency: Multiple goroutines accessing the same collection
Solution: Use proper synchronization, consider read-only replicas

Microservice Mode¶

Network Latency: HTTP overhead for frequent operations
Solution: Batch requests, use persistent connections
API Compatibility: Differences from Qdrant API
Solution: Refer to the API reference for supported endpoints

CLI Mode¶

Large Datasets: Import/export performance
Solution: Use batch processing, split large files

Quick Start - Getting started with GoVector
API Reference - Complete API documentation
Collection Management - Collection creation and management
Storage Engine - Persistence and serialization details

Usage Modes¶

🚀 Embedded Mode¶

Key Features¶

Getting Started¶

Use Cases¶

🌐 Microservice Mode¶

Key Features¶

Getting Started¶

Use Cases¶

🖥️ CLI Mode¶

Key Features¶

Getting Started¶

Use Cases¶

📊 Mode Comparison¶

💡 Best Practices¶

Choosing the Right Mode¶

Performance Considerations¶

Security Considerations¶

🚩 Common Issues¶

Embedded Mode¶

Microservice Mode¶

CLI Mode¶

🔗 Related Documentation¶