Skip to content

Usage Patterns

This guide is for developers who want to use GoVector in different project forms, systematically explaining two main usage modes: embedded mode (zero network overhead) and microservice mode (Qdrant-compatible REST API). The document covers the complete path from installation, configuration, to integration examples, performance optimization, batch and concurrency, graceful shutdown, benchmark testing and analysis, and provides actual path references from the repository for quick source code location.

Project Structure

The repository uses organization by "function/layer":

  • Core library in core/, containing collection, index, storage, quantization, models and filters
  • API layer in api/, providing Qdrant-compatible HTTP interfaces
  • Command-line entry in cmd/, containing independent server and benchmark program
  • Examples in example/embedded/, demonstrating embedded usage
  • Protocol definitions in core/proto/, used for persistence serialization
  • Build and run provided through Makefile as unified entry
graph TB
subgraph "Application Layer"
App["Business Application
Embedded or HTTP Client"]
end
subgraph "GoVector Core"
Core_Collection["Collection
Collection management"]
Core_Index_HNSW["HNSWIndex
Graph index"]
Core_Index_Flat["FlatIndex
Brute-force index"]
Core_Storage["Storage
BoltDB+Protobuf"]
Core_Quant["SQ8Quantizer
8-bit quantization"]
Core_Models["Models and filters
Point/Filter/ScoredPoint"]
end
subgraph "API Layer"
API_Server["HTTP API Server
Qdrant-compatible endpoints"]
end
subgraph "Command-line and Tools"
CLI_Server["govector
Independent service"]
CLI_Bench["bench
Benchmark testing"]
end
App --> Core_Collection
Core_Collection --> Core_Index_HNSW
Core_Collection --> Core_Index_Flat
Core_Collection --> Core_Storage
Core_Storage --> Core_Quant
App --> API_Server
API_Server --> Core_Collection
CLI_Server --> API_Server
CLI_Bench --> Core_Collection

Core Components

  • Collection: Encapsulates dimension, metric, index and persistence, provides thread-safe interfaces for Upsert/Search/Delete
  • Index engine: HNSWIndex (graph index, supports parameterization), FlatIndex (brute-force index)
  • Storage: Local persistence based on bbolt, combined with Protobuf serialization; optional SQ8 quantization
  • Models and filtering: PointStruct/ScoredPoint, Filter/Condition, Payload
  • API server: Provides Qdrant-compatible REST interfaces for /collections, /points
  • Benchmark testing: cmd/bench, supports throughput/latency evaluation at different scales and metrics

Architecture Overview

The diagram below shows data flow and control flow in both embedded and microservice modes:

sequenceDiagram
participant App as "Application"
participant Coll as "Collection"]
participant Idx as "HNSW/Flat Index"]
participant Store as "Storage(BoltDB)"]
participant API as "API Server"]
participant Srv as "HTTP Service"]
App->>Coll : "Upsert/Search/Delete"
Coll->>Store : "Write/read(optional)"]
Coll->>Idx : "Update/query"
Note over Coll,Idx : "Thread-safe read-write lock protection"
App->>API : "HTTP request"
API->>Srv : "Start listening"]
API->>Coll : "Route to collection operations"]
Coll->>Idx : "Execute search/delete"]
Coll->>Store : "Persist(optional)"]

Detailed Component Analysis

Embedded Mode: Zero Network Overhead

Applicable scenarios - Desktop applications, edge devices, single-machine services - Latency-sensitive and no need for cross-process/cross-machine access - Want to minimize external dependencies and operational complexity

Key points - Directly import core package, initialize Storage and Collection - Complete CRUD through Collection's Upsert/Search/Delete - Optionally enable HNSW to obtain approximate but low-complexity retrieval performance

Integration steps and reference paths - Initialize storage and collection: example/embedded/main.go:14-24 - Write vectors and metadata: example/embedded/main.go:27-41 - Execute filtered search: example/embedded/main.go:44-61 - Collection lifecycle and consistency: core/collection.go:93-133 - HNSW parameters and defaults: core/hnsw_index.go:31-39

sequenceDiagram
participant App as "Application"]
participant Store as "Storage"]
participant Coll as "Collection"]
participant Idx as "HNSW/Flat"]
App->>Store : "NewStorage(...)"
App->>Coll : "NewCollection(name,dim,metric,store,hnsw)"
App->>Coll : "Upsert(points)"
Coll->>Store : "Persist"]
Coll->>Idx : "Update index"]
App->>Coll : "Search(query,filter,topK)"
Coll->>Idx : "Retrieve"]
Idx-->>Coll : "Result set"]
Coll-->>App : "ScoredPoint list"

Microservice Mode: Qdrant-compatible REST API

Applicable scenarios - Multi-language/multi-process client access - Called by other services as independent service - Need standard REST interface and observability

Key points - Start govector, bind port and database path - Create collection via /collections, set dimension, metric and HNSW parameters - Perform Upsert/Search/Delete via /points - Support graceful shutdown and signal handling

Integration steps and reference paths - Startup and signal handling: cmd/govector/main.go:18-91 - API routing and collection loading: api/server.go:64-129 - Create collection (with parameter parsing): api/server.go:260-352 - Upsert/Search/Delete implementation: api/server.go:145-258 - Graceful shutdown flow: api/server.go:131-143

sequenceDiagram
participant Client as "HTTP Client"]
participant Srv as "API Server"]
participant Coll as "Collection"]
participant Idx as "HNSW/Flat"]
participant Store as "Storage"]
Client->>Srv : "POST /collections"
Srv->>Coll : "Create collection(parameter parsing)"
Client->>Srv : "PUT /collections/{name}/points"
Srv->>Coll : "Upsert(points)"]
Coll->>Store : "Persist"]
Coll->>Idx : "Update index"]
Client->>Srv : "POST /collections/{name}/points/search"
Srv->>Coll : "Search(vector,filter,limit)"]
Coll->>Idx : "Retrieve"]
Idx-->>Coll : "Result set"]
Coll-->>Srv : "Return"]
Srv-->>Client : "JSON response"

Data Model and Filtering

  • PointStruct/ScoredPoint: Vector, version number, metadata
  • Filter/Condition: Supports Must/MustNot, exact match, range, prefix, contains, regex
  • Payload: Key-value metadata, used for filtering during retrieval

Reference paths - Data model and filter definitions: core/models.go:5-280 - Filter matching logic: core/models.go:81-280

Storage and Persistence

  • Storage based on bbolt, one bucket per collection
  • Uses Protobuf to serialize points, supports optional SQ8 quantization
  • Automatically saves/loads collection metadata, recovers after restart

Reference paths - Storage initialization and close: core/storage.go:88-129 - Write/read and quantization: core/storage.go:144-235 - Metadata save/load: core/storage.go:261-307

Index Implementation and Parameters

  • HNSWIndex: Supports custom M/EfConstruction/EfSearch/K
  • FlatIndex: Brute-force search, suitable for small scale or scenarios requiring exact results
  • Search post-filter strategy: For HNSW, "oversampling + post-filter" to balance performance and correctness

Reference paths - HNSW parameters and defaults: core/hnsw_index.go:11-39 - HNSW search and post-filter: core/hnsw_index.go:126-176 - Flat brute-force search: core/flat_index.go:40-74

Quantization and Memory Optimization

  • SQ8 quantization: Compresses 32-bit floating-point vectors to 8-bit integers, saving storage and memory
  • Compress on storage, decompress on load, automatically handles metadata fields

Reference paths - Quantization interface and implementation: core/quantization.go:5-125 - Storage-side quantization switch and processing: core/storage.go:95-114, core/storage.go:162-175

Concurrency, Batch and Consistency

  • Collection uses RWMutex to ensure concurrency safety for Upsert/Search/Delete
  • Upsert persists to storage first then updates in-memory index, best-effort rollback on failure
  • Batch write recommends batching to reduce peak memory usage

Reference paths - Concurrency and consistency: core/collection.go:97-133 - Batch write example (benchmark): cmd/bench/main.go:52-82

Graceful Shutdown and Signal Handling