Skip to content

Installation Issues

This guide focuses on GoVector installation and running troubleshooting on different operating systems, covering the following typical scenarios:

  • Compilation failure due to incompatible Go version
  • Dependency package download failure or network restrictions
  • CGO-related limitations and build failures
  • Server startup failure and port conflicts
  • Dependency version conflicts and module cache issues
  • Reinstallation and cleanup steps
  • Common error message interpretation and corresponding solutions

GoVector provides two usage methods:

  • As an embedded Go library imported into project
  • Running as an independent service (supports Homebrew installation and system service)

Project Structure

GoVector uses modular organization with core directories and responsibilities as follows:

  • cmd/govector: Independent service entry, providing HTTP API
  • api: HTTP API layer, implementing collection management and vector operations
  • core: Core engine, containing storage, index, model definitions and quantization
  • scripts: Build and release scripts, including Homebrew Formula and systemd service template
  • go.mod: Module and dependency declarations
  • Makefile: Common build, run, cleanup commands
graph TB
subgraph "Application Layer"
CLI["Command-line entry
cmd/govector/main.go"]
API["HTTP API layer
api/server.go"]
end
subgraph "Core Engine"
CORE["Core modules
core/"]
STORAGE["Storage engine
core/storage.go"]
MODELS["Data model
core/models.go"]
PROTO["Protocol definition
core/proto/point.proto"]
end
subgraph "Tools and Scripts"
MOD["Module and version
go.mod"]
MK["Build and cleanup
Makefile"]
BUILD["Release script
scripts/build_release.sh"]
BREW["Homebrew Formula
scripts/release/govector.rb"]
SVC["System service template
scripts/release/govector.service"]
end
CLI --> API
API --> CORE
CORE --> STORAGE
CORE --> MODELS
CORE --> PROTO
MK --> CLI
BUILD --> CLI
BREW --> CLI
SVC --> CLI
MOD --> CORE

Core Components

  • Service entry and parameter parsing: Command-line parameters are used to specify port, database path and index type, initialize storage and collections, and start HTTP server.
  • API layer: Provides interfaces for collection create/delete, point write, search and delete; supports loading collection metadata from persistence.
  • Storage layer: Local persistence based on bbolt, combined with Protobuf serialization; supports optional vector quantization.
  • Data model: Qdrant-compatible data structure, including filter conditions, range matching, regular expressions, etc.

Architecture Overview

The diagram below shows the overall flow from command-line to API to storage, as well as key error points:

sequenceDiagram
participant U as "User"
participant M as "main.go"
participant S as "api.Server"
participant ST as "core.Storage"
U->>M : Start service(port/database/index parameters)
M->>ST : Initialize storage(NewStorage)
ST-->>M : Return storage instance or error
M->>M : Load/create collection
M->>S : Create and register collection
M->>S : Start HTTP service
S->>ST : Load collection metadata on startup
ST-->>S : Return collection metadata
S-->>U : Service ready

Detailed Component Analysis

Component 1: Command-line Entry and Service Startup

  • Parameter parsing: Port, database path, whether to enable HNSW index
  • Storage initialization: Open bbolt database file, created automatically if does not exist
  • Collection loading/creation: Create default collection or recover from persistence based on parameters
  • HTTP service: Start listening, handle collection and point operation requests
flowchart TD
START(["Startup entry"]) --> PARSE["Parse command-line parameters"]
PARSE --> INITSTORE["Initialize storage(NewStorage)"]
INITSTORE --> STOREOK{"Storage initialization successful?"}
STOREOK --> |No| ERR1["Log error and exit"]
STOREOK --> |Yes| CREATECOL["Create/load collection"]
CREATECOL --> APISRV["Create and start HTTP service"]
APISRV --> RUN["Listen on port for requests"]
RUN --> END(["Service running"])
ERR1 --> END

Component 2: API Layer and Collection Management

  • Collection management: Create, delete, list, query collection metadata
  • Point operations: Batch write, search, delete by ID or filter
  • Startup loading: Read collection metadata from storage and rebuild memory collection
sequenceDiagram
participant C as "Client"
participant H as "HTTP routing"
participant SVR as "api.Server"
participant COL as "core.Collection"
participant ST as "core.Storage"
C->>H : POST /collections
H->>SVR : handleCreateCollection
SVR->>COL : NewCollectionWithParams
COL-->>SVR : Return collection instance
SVR-->>C : 200 OK
C->>H : PUT /collections/{name}/points
H->>SVR : handleUpsert
SVR->>COL : Upsert(points)
COL->>ST : Persist write
ST-->>COL : Success/failure
COL-->>SVR : Result
SVR-->>C : 200 OK
C->>H : POST /collections/{name}/points/search
H->>SVR : handleSearch
SVR->>COL : Search(vector, filter, limit)
COL-->>SVR : Return TopK results
SVR-->>C : 200 OK

Component 3: Storage Layer and Persistence

  • Storage initialization: Open bbolt database file, permissions and concurrency control
  • Collection and metadata: Each collection is an independent bucket; metadata saved in special bucket
  • Point write/read: Protobuf serialization; optional quantization compression
  • Close and cleanup: Graceful shutdown of database connections
flowchart TD
OPEN["Open bbolt database"] --> META["Read/write collection metadata"]
META --> UPSERT["Batch write points(UpsertPoints)"]
UPSERT --> SER["Protobuf serialization"]
SER --> SAVE["Write to bucket"]
SAVE --> LOAD["Load collection(LoadCollection)"]
LOAD --> DESER["Deserialize Protobuf"]
DESER --> CLOSE["Close database"]

Component 4: Data Model and Filtering

  • Model definition: Point structure, scored point, filter, condition types
  • Filter logic: Exact match, range, prefix, contains, regex
  • Compatibility: Maintains consistency with Qdrant data model
classDiagram
class PointStruct {
    +string ID
    +uint64 Version
    +[]float32 Vector
    +Payload Payload
}
class Filter {
    +[]Condition Must
    +[]Condition MustNot
}
class Condition {
    +string Key
    +ConditionType Type
    +MatchValue Match
    +RangeValue Range
}
class MatchValue {
    +interface{} Value
}
class RangeValue {
    +interface{} GT
    +interface{} GTE
    +interface{} LT
    +interface{} LTE
}
Filter --> Condition : "contains"
PointStruct --> Payload : "carries"

Dependency Analysis