Skip to content

Microservice Mode

This guide is for users who want to run GoVector in "microservice mode", providing complete instructions from starting an independent HTTP API server, configuring parameters, to calling core APIs for collection management, point operations, search queries, etc.; also explains GoVector's Qdrant-compatible API features and advantages to help users migrate quickly. At the same time, it covers deployment best practices (including Docker and Kubernetes), load balancing and monitoring integration suggestions, and actual reusable example scripts.

Project Structure

  • Core library is in the core package, providing capabilities such as vector collection, index, storage, model definitions, etc.
  • API layer is in the api package, providing Qdrant-compatible HTTP REST interfaces.
  • Command-line entry is at cmd/govector, starts as an independent microservice.
  • Example script demo.sh demonstrates the complete insert, search and filter flow.
  • Makefile provides build, run, cleanup and release scripts.
graph TB
subgraph "Command-line Entry"
M["cmd/govector/main.go"]
end
subgraph "API Layer"
S["api/server.go"]
end
subgraph "Core Library"
C["core/collection.go"]
ST["core/storage.go"]
I["core/index.go"]
MD["core/models.go"]
PR["core/proto/point.proto"]
end
M --> S
S --> C
C --> ST
C --> I
ST --> PR
MD --> S
MD --> C

Core Components

  • Server and startup
  • Independent microservice controls port, database path and index type via command-line parameters.
  • On startup, loads or creates default collection and registers to HTTP server.
  • API layer
  • Provides Qdrant-compatible interfaces for collection management, point write, search, delete.
  • Built-in graceful shutdown and concurrency safety.
  • Core library
  • Collection: Collection abstraction, encapsulates index and persistence, supports Upsert/Search/Delete.
  • Storage: Local persistence based on bbolt, supports Protobuf serialization and optional quantization.
  • VectorIndex: Unified index interface, supports Flat/HNSW strategies.
  • Models and filtering: Payload, PointStruct, ScoredPoint, Filter/Condition, etc.

Architecture Overview

The diagram below shows the overall interaction in microservice mode: client calls through HTTP API, API layer parses requests and delegates to Collection to execute business logic, Collection completes persistence and retrieval through Storage and VectorIndex.

sequenceDiagram
participant Client as "Client"
participant API as "HTTP API Layer(api/server.go)"
participant Col as "Collection"]
participant Store as "Storage(Storage)"]
participant Idx as "Index(VectorIndex)"]
Client->>API : "PUT /collections/{name}/points"
API->>Col : "Upsert(points)"
Col->>Store : "UpsertPoints()"
Col->>Idx : "Upsert(points)"
Col-->>API : "Result"
API-->>Client : "Status code + JSON"
Client->>API : "POST /collections/{name}/points/search"
API->>Col : "Search(vector, filter, limit)"
Col->>Idx : "Search(...)"
Idx-->>Col : "TopK results"
Col-->>API : "ScoredPoint list"
API-->>Client : "JSON result"

Detailed Component Analysis

Server Startup and Configuration

  • Startup method
  • Supports direct command-line entry execution, or use Makefile run target.
  • Default listening port is 18080, database file path is local file.
  • Key parameters
  • -port: HTTP service listening port, default 18080.
  • -db: bbolt storage file path, default govector.db.
  • Initialization flow
  • Initialize Storage (bbolt).
  • Create/load default collection (name, dimension, metric, index type).
  • Register collection to API Server and start listening.
  • Supports graceful shutdown (signal handling and timeout).

API Endpoints and Data Model

  • Collection management
  • POST /collections: Create collection (supports specifying vector_size, distance, hnsw, parameters).
  • DELETE /collections/{name}: Delete collection.
  • GET /collections: List all collections.
  • GET /collections/{name}: Get collection information.
  • Point operations
  • PUT /collections/{name}/points: Batch Upsert.
  • POST /collections/{name}/points/search: Vector search (supports filter and limit).
  • POST /collections/{name}/points/delete: Delete by ID or filter conditions.
  • Data model
  • PointStruct: id, vector, payload, version.
  • ScoredPoint: id, version, score, payload.
  • Filter/Condition: supports must/must_not conditions, supports exact, range, prefix, contains, regex.

Collection and Storage

  • Collection
  • Unified encapsulation of Upsert/Search/Delete, internally maintains read-write lock.
  • Supports Flat/HNSW index switching, automatically loads persisted data.
  • Storage
  • Based on bbolt, one bucket per collection; metadata saved in special bucket.
  • Uses Protobuf to serialize point data; supports optional SQ8 quantization.
  • Provides Upsert/Load/List/Delete and other operations.
  • Index interface
  • VectorIndex abstracts Upsert/Search/Delete/Count/Filter capabilities, convenient for replacing implementations.

Qdrant Compatibility and Advantages

  • Compatibility points
  • REST API paths and semantics are similar to Qdrant, convenient for migration.
  • Payload filtering supports multiple matching types, covering common query scenarios.
  • Advantages
  • Single-machine high performance: HNSW provides approximate nearest neighbor search, low latency, high throughput.
  • Local persistence: bbolt + Protobuf, no external dependencies.
  • Optional quantization: SQ8 reduces disk usage, suitable for large-scale data.
  • Dual mode: Can be used embedded or deployed as microservice independently.

Dependency Analysis

  • External dependencies
  • bbolt: Local key-value database.
  • protobuf: Serialization models.
  • hnsw: HNSW index implementation.
  • Internal modules
  • api depends on core's Collection/Storage/Index.
  • core's Collection depends on Storage and VectorIndex.
  • Storage depends on Protobuf and bbolt.
graph LR
A["api/server.go"] --> B["core/collection.go"]
B --> C["core/storage.go"]
B --> D["core/index.go"]
C --> E["core/proto/point.proto"]
F["cmd/govector/main.go"] --> A

Performance and Capacity Planning

  • Index selection
  • Small scale/development environment: Flat index can meet requirements, fast startup, low memory usage.
  • Production environment: Recommend enabling HNSW to get lower query latency and higher throughput.
  • Vector dimension and count
  • Higher dimensions and larger data volume result in higher memory and disk usage; can combine with SQ8 quantization to reduce storage.
  • I/O and persistence
  • Upsert order persists to disk first then updates in-memory index, ensuring consistency; recommend reasonable disk and backup planning.
  • Concurrency and locking
  • Collection internally uses read-write lock protection, Upsert/Search/Delete are respectively locked to avoid race conditions.

Troubleshooting Guide

  • Startup failure
  • Check port occupancy and permissions; confirm -db file path exists and is writable.
  • Check startup log output to locate errors during Storage initialization or collection creation phases.
  • API returns 404/400/500
  • 404: Collection does not exist; please create collection first or check name.
  • 400: Request body format incorrect or fields missing; check JSON structure and required fields.
  • 500: Internal error; check server logs, focus on Upsert/Search/Delete error messages.
  • Graceful shutdown
  • Service will attempt graceful shutdown after receiving interrupt signal; if timeout, logs will prompt; can appropriately extend timeout.

Conclusion

GoVector's microservice mode provides Qdrant-compatible REST API, with advantages of single-machine high performance, local persistence and optional quantization. You can quickly start an independent service via command-line parameters and implement collection management, point write, search and delete through standard API. With reasonable index selection and capacity planning, it can run stably in production environments.

Appendix: API Reference and Deployment Practices

Startup and Basic Configuration

  • Using command-line parameters
  • -p / -port: HTTP listening port (default 18080)
  • -d / -db: bbolt database file path (default govector.db)
  • Using Makefile
  • make run: One-click start service with default configuration.
  • make build: Compile and generate binary to bin/.

API Call Examples (REST)

The following examples are based on the call flow in demo.sh, demonstrating typical usage of collection management, point write, search without filter and search with filter. Adjust port and collection name according to your actual environment.

  • Create collection
  • Method and path: POST /collections
  • Request body fields: name, vector_size, distance, hnsw, parameters
  • Success response: Returns collection configuration and parameters
  • List collections
  • Method and path: GET /collections
  • Success response: Collection list (name, dimension, distance metric, point count)
  • Get collection details
  • Method and path: GET /collections/{name}
  • Success response: Collection basic information
  • Delete collection
  • Method and path: DELETE /collections/{name}
  • Success response: Operation completion flag
  • Write points
  • Method and path: PUT /collections/{name}/points
  • Request body fields: points (array, containing id, vector, payload)
  • Success response: Operation completion flag
  • Search
  • Method and path: POST /collections/{name}/points/search