Skip to content

Quick Start

This guide is for users first encountering GoVector, with the goal of completing environment setup and running the first vector search example in approximately 15 minutes. Content covers:

  • Two installation methods: importing as a Go library and Homebrew installation
  • Complete flow for embedded mode (zero network overhead): initialize storage, create collection, insert vectors, query and filter
  • Microservice mode (HTTP API) startup and basic calls
  • Common initialization steps, error handling, and best practices
  • Troubleshooting and FAQs

Project Structure

The repository follows a "function domain + layer" hybrid organization:

  • Core library at core/, providing storage, collection, index, models and other capabilities
  • API layer at api/, providing Qdrant-compatible HTTP interface
  • Executable at cmd/govector/main.go, as a standalone service
  • Examples at example/embedded/main.go, demonstrating embedded usage
  • Homebrew script at scripts/release/govector.rb
  • Performance benchmarks and scripts at cmd/bench/ and demo.sh
graph TB
subgraph "Application Layer"
APP["Your Go application
or command-line script"]
end
subgraph "GoVector Core"
CORE_STORAGE["core/Storage
Persistence (BoltDB)"]
CORE_COLLECTION["core/Collection
Collection management"]
CORE_MODELS["core/* Models and filters"]
CORE_INDEX["core/VectorIndex interface"]
end
subgraph "API Layer"
API_SERVER["api/Server
HTTP API"]
end
subgraph "Executable"
BIN_MAIN["cmd/govector/main.go
Microservice entry"]
end
APP --> CORE_COLLECTION
CORE_COLLECTION --> CORE_STORAGE
CORE_COLLECTION --> CORE_INDEX
API_SERVER --> CORE_COLLECTION
BIN_MAIN --> API_SERVER
BIN_MAIN --> CORE_STORAGE

Core Components

  • Storage Engine Storage: Local persistence based on bbolt, supporting point CRUD, collection metadata management, optional vector quantization
  • Collection: Logical collection encapsulating index and storage, providing thread-safe operations like Upsert/Search/Delete
  • Models and Filters: PointStruct, ScoredPoint, Filter, Condition, supporting multiple match types
  • Index Interface VectorIndex: Unifying Flat/HNSW and other index strategies
  • API Server: Provides Qdrant-compatible REST interface, supporting collection management and point operations

Architecture Overview

The diagram shows the interaction relationship and data flow between embedded and microservice modes.

graph TB
subgraph "Embedded Mode"
E_APP["Your application code"]
E_STORE["core/Storage"]
E_COL["core/Collection"]
E_IDX["VectorIndex (HNSW/Flat)"]
E_APP --> E_STORE
E_APP --> E_COL
E_COL --> E_IDX
E_COL --> E_STORE
end
subgraph "Microservice Mode"
S_CLI["Client/script (curl)"]
S_API["api/Server (HTTP)"]
S_BIN["cmd/govector/main.go"]
S_STORE["core/Storage"]
S_COL["core/Collection"]
S_IDX["VectorIndex (HNSW/Flat)"]
S_CLI --> S_API
S_BIN --> S_API
S_BIN --> S_STORE
S_API --> S_COL
S_COL --> S_STORE
S_COL --> S_IDX
end

Detailed Component Analysis

Embedded Mode: Complete Example from Zero to One

Embedded mode is suitable for direct use in your Go application without network overhead. Typical flow: 1) Initialize local storage (create database file) 2) Create collection (specify dimension, distance metric, whether to enable HNSW) 3) Batch write vectors (Upsert) 4) Execute similarity retrieval (Search), with optional Payload filtering 5) Close storage to release resources

sequenceDiagram
participant App as "Your application"
participant Store as "core/Storage"
participant Col as "core/Collection"
participant Idx as "VectorIndex"
App->>Store : Initialize storage (path)
App->>Col : Create collection (name, dim, metric, storage, useHNSW)
App->>Col : Upsert (vectors + metadata)
Col->>Store : Write to persistence
Col->>Idx : Update in-memory index
App->>Col : Search (query vector, filter, K)
Col->>Idx : Query return TopK
Col-->>App : Result (with ID/score/metadata)
App->>Store : Close storage

Command-Line Tool (CLI) Mode

GoVector provides powerful interactive and non-interactive command-line tools with abbreviated parameters.

  • Startup parameters and subcommands
  • serve: Start HTTP service, e.g., govector serve -p=18080 -d=govector.db
  • ls: List all collections in the database, e.g., govector ls demo.db
  • upsert: Write data, e.g., govector upsert demo.db -c=demo_col -j=[id:1]
  • search: Similarity search, e.g., govector search demo.db -c=demo_col -v=[0.1] -l=10
  • count: Count points, e.g., govector count demo.db -c=demo_col
  • delete: Delete data, e.g., govector delete demo.db -c=demo_col -i=[1]

Command-Line Tool (CLI) Mode

GoVector provides powerful interactive and non-interactive command-line tools with abbreviated parameters.

  • Startup parameters and subcommands
  • serve: Start HTTP service, e.g., govector serve -p=18080 -d=govector.db
  • ls: List all collections in the database, e.g., govector ls demo.db
  • upsert: Write data, e.g., govector upsert demo.db -c=demo_col -j='[{"id":"1","vector":[0.1]}]'
  • search: Similarity search, e.g., govector search demo.db -c=demo_col -v='[0.1]' -l=10
  • count: Count points, e.g., govector count demo.db -c=demo_col
  • delete: Delete data, e.g., govector delete demo.db -c=demo_col -i='["1"]'

Microservice Mode: Startup and Basic API Calls

Microservice mode provides Qdrant-compatible HTTP API interface, suitable for standalone deployment or integration with services in other languages.

  • Startup command and parameters
  • Port: -port, default 18080
  • Database path: -db, default govector.db
  • Basic API calls (refer to demo.sh)
  • Create collection: POST /collections
  • Write vectors: PUT /collections/{name}/points
  • Search: POST /collections/{name}/points/search
  • Delete: POST /collections/{name}/points/delete
  • List/info: GET /collections, GET /collections/{name}
sequenceDiagram
participant Client as "Client (curl)"
participant Bin as "cmd/govector/main.go"
participant API as "api/Server"
participant Col as "core/Collection"
participant Store as "core/Storage"
Client->>Bin : Start (port/database/index params)
Bin->>Store : Initialize storage
Bin->>Col : Create default collection (dim/metric/index)
Bin->>API : Register collection and start HTTP listening
Client->>API : POST /collections (create collection)
API->>Col : Create new collection
Client->>API : PUT /collections/{name}/points (batch write)
API->>Col : Upsert
Client->>API : POST /collections/{name}/points/search (query)
API->>Col : Search (filter + TopK)
Col-->>API : Return results
API-->>Client : JSON response

Data Model and Filtering Mechanism

  • PointStruct: Contains ID, vector, version number, Payload
  • ScoredPoint: Query result, contains ID, version, score, Payload
  • Filter/Condition: Supports must/must_not, condition types include exact, range, prefix, contains, regex
  • Matching rules: Hit only when all Must satisfied and all MustNot unsatisfied
flowchart TD
Start(["Enter filter matching"]) --> NilCheck{"Is Filter empty?"}
NilCheck --> |Yes| True["Return true (no filter)"]
NilCheck --> |No| MustAll["Iterate Must conditions"]
MustAll --> MustFail{"Any unsatisfied?"}
MustFail --> |Yes| False["Return false"]
MustFail --> |No| MustNotAll["Iterate MustNot conditions"]
MustNotAll --> MustNotFail{"Any satisfied?"}
MustNotFail --> |Yes| False
MustNotFail --> |No| True

Dependency Analysis

  • External Dependencies
  • bbolt: Local key-value storage
  • protobuf: Serialize points and metadata
  • hnsw: HNSW graph index implementation
  • Internal Modules
  • core: Storage, collection, index, models
  • api: HTTP server and routing
  • cmd/govector: Microservice entry
  • example/embedded: Embedded examples
graph LR
GOV["github.com/DotNetAge/govector"]
BBOLT["go.etcd.io/bbolt"]
PROTO["google.golang.org/protobuf"]
HNSW["github.com/coder/hnsw"]
GOV --> BBOLT
GOV --> PROTO
GOV --> HNSW

Performance and Best Practices

  • Choose appropriate index
  • Small scale/dev environment: Flat index, simple and stable
  • Production/large scale: HNSW index, sublinear search complexity
  • Dimension and metric
  • Ensure written vector dimension matches collection
  • Cosine/Euclidean/Dot perform differently in different scenarios
  • Write and consistency
  • Upsert persists first then updates in-memory index; attempts rollback on failure
  • Filter and query
  • Use Payload filter to reduce candidate set, improve query efficiency
  • Quantization
  • SQ8 quantization can be enabled to reduce disk usage, pay attention to accuracy trade-off

Troubleshooting Guide

  • Microservice startup error
  • Port occupied: Modify -port parameter
  • Insufficient database path permissions: Ensure directory is readable/writable
  • Invalid collection parameters: Check collection configuration parameters
  • Write failure
  • Vector dimension mismatch: Confirm collection dimension matches vector length
  • Storage closed: Ensure Close was not called prematurely
  • Query exception
  • Collection does not exist: Create collection first or confirm name is correct
  • Filter syntax error: Verify JSON structure and field names
  • Homebrew installation
  • Permission issue: Use sudo or correct directory permissions
  • Service fails to start: Check log path var/log/govector.log

Conclusion

Through this guide, you can complete GoVector installation and first run in 15 minutes, mastering core usage of both embedded and microservice modes. Recommend starting with embedded mode for local development and testing; production environments should use HNSW index with reasonable filter strategies, combined with quantization to balance performance and storage cost.

Appendix: Command and Example Paths