Crate velesdb_server

Expand description

§velesdb-server

HTTP/REST server that exposes a VelesDB database — vector, text, graph and VelesQL — to any language.

§Objective

velesdb-core is an embedded engine: it lives inside one Rust process. As soon as a second process — a Python service, a Node worker, an agent running on another machine — needs the same data, you need a network boundary. velesdb-server is that boundary: a single self-contained binary that wraps the engine in an Axum HTTP API, adds API keys, TLS, rate limiting, health probes and Prometheus metrics, and persists everything to a data directory (WAL + mmap) that survives restarts. No JVM, no sidecar, no external dependency.

The engine behind VelesDB — the explainable, local-first memory engine for AI agents. It fuses vector + graph + columnar under VelesQL; the why() recall trail returns the evidence path behind every answer.

§Use cases

A Python or TypeScript service needs vector search, and you do not want to embed a Rust library in every runtime you ship.
Several agents on a LAN share one memory store, authenticated with Bearer API keys over TLS.
A local RAG prototype needs a backend that survives a laptop reboot without setting up a database cluster.
A Kubernetes deployment needs liveness/readiness probes, /metrics, and a clean SIGTERM that flushes the write-ahead logs.
A knowledge graph is queried with Cypher-style MATCH and vector similarity in the same request.

§Prerequisites

Requirement	Minimum version	Note
Rust	1.90	Only to build or `cargo install`; the release archives ship a prebuilt binary. Workspace `rust-version`.
C toolchain	any	Needed when building from source: `rustls` uses the `ring` backend.
OS	Linux, macOS, Windows	Prebuilt binaries for Linux x86_64, macOS x86_64/aarch64, Windows x86_64.
HTTP client	any	`curl` is used in every example below.

§Installation

cargo install velesdb-server

Prebuilt archives (.tar.gz, .deb, .zip), Docker, and platform-specific notes: docs/guides/INSTALLATION.md. Container and orchestrator setup: docs/guides/SERVER_DEPLOYMENT.md.

Building from a clone of this repository:

cargo build --release -p velesdb-server

§First success in 60 seconds

# 1. Start the server and wait until it reports readiness
velesdb-server --port 8080 --data-dir ./velesdb_data &
until curl -sf http://localhost:8080/v1/ready > /dev/null; do sleep 1; done

# 2. Create a 4-dimensional collection
curl -sS -X POST http://localhost:8080/v1/collections \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart", "dimension": 4, "metric": "cosine"}'
echo

# 3. Insert three points
curl -sS -X POST http://localhost:8080/v1/collections/quickstart/points \
  -H "Content-Type: application/json" \
  -d '{"points": [
        {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "payload": {"title": "first"}},
        {"id": 2, "vector": [0.9, 0.4, 0.0, 0.0], "payload": {"title": "second"}},
        {"id": 3, "vector": [0.1, 0.9, 0.0, 0.0], "payload": {"title": "third"}}
      ]}'
echo

# 4. Search for the nearest two vectors
curl -sS -X POST http://localhost:8080/v1/collections/quickstart/search \
  -H "Content-Type: application/json" \
  -d '{"vector": [1.0, 0.0, 0.0, 0.0], "top_k": 2}'
echo

Expected output — three JSON lines, in this order:

{"message":"Collection created","name":"quickstart","type":"vector","warnings":["Collection dimension and metric are immutable after creation. If your embedding model changes, create a new collection and reindex data.","For first queries, start without strict filters/thresholds, then tighten progressively."]}
{"count":3,"message":"Points upserted"}
{"results":[{"id":"1","score":1.0,"payload":{"title":"first"}},{"id":"2","score":0.91381156,"payload":{"title":"second"}}]}

The code field is optional and omitted when no structured code applies. Use it for programmatic error handling (e.g., retry on VELES-006, display user hint on VELES-004). See ERROR_CODES.md for the full list.

§Operations

Everything an operator configures — API keys and their rotation, TLS, the graceful-shutdown sequence and its WAL flush guarantee, the /health and /ready probes — lives in Server security, which is the canonical reference and covers each of them in more depth than a README should.

Docker, Kubernetes manifests, rate limiting, CORS and the startup update check are in Deployment.

The short version:

Concern	Set	Default
API keys	`VELESDB_API_KEYS`, or `api_keys` in `velesdb.toml`	none — the server runs in local dev mode and accepts every request
TLS	`VELESDB_TLS_CERT` / `VELESDB_TLS_KEY`, or `--tls-cert` / `--tls-key`	off (plain HTTP)
Data directory	`VELESDB_DATA_DIR`	`./data`
Bind address	`VELESDB_HOST` / `VELESDB_PORT`	`127.0.0.1:8080`
Config file	`VELESDB_CONFIG` or `--config`	`./velesdb.toml` if present

Configuration priority, highest first: CLI flags > environment variables > velesdb.toml > built-in defaults. Every section of the file is optional; declare only what you override.

Distance metrics accepted by the API (cosine, euclidean, dot — aliases dotproduct, inner, ip —, hamming, jaccard) are listed with their use cases in the REST tour; measured latency figures live in the benchmarks, pinned to promise-contract.json.

§Examples

REST tour — every endpoint family with runnable curl recipes: collections, quantization, points, search modes, sparse and hybrid search, VelesQL, graph, MATCH, indexes, errors.
Deployment — Docker, Kubernetes probes, rate limiting, CORS, update check.
Server security — API keys, key rotation, TLS, graceful shutdown, health endpoints.
Getting started — the wider VelesDB tour, engine included.

§API / commands

Surface	Where
HTTP endpoint specification	docs/reference/api-reference.md
Machine-readable schema	docs/openapi.yaml, docs/openapi.json
Swagger UI	`http://localhost:8080/swagger-ui` — requires a build with `--features swagger-ui`
Rust items (`routes::api_routes`, `config`, `auth`, `tls`)	docs.rs/velesdb-server
CLI flags	`velesdb-server --help`
Error codes	docs/reference/ERROR_CODES.md

Routes are served under two prefixes: /v1/… is canonical, and the unversioned /… form is kept for backward compatibility — its responses carry deprecation: true and x-api-deprecated: Use /v1/ prefix.

§Known limits

One process per data directory. The engine takes an exclusive OS-level lock on <data_dir>/velesdb.lock. There is no built-in clustering, replication, or sharding: scale vertically, or shard at the application level. See CONCURRENCY_LOCKING.md.
Authentication is a flat list of API keys. No users, no roles, no per-collection scoping. Keys are read at startup, so rotation requires a restart (both old and new key can be active during the transition).
Rate limiting is per process and in memory. Replicas do not share a budget; put a shared limiter in front if you need a global one.
CORS is permissive by default (allowed_origins = ["*"]); the server warns about it at startup. Restrict [cors] before exposing a browser-facing deployment.
Swagger UI is opt-in at build time (--features swagger-ui); the released default build does not serve /swagger-ui or /api-docs/openapi.json.
The /v1 prefix is added by the binary. Embedding velesdb_server::routes::api_routes() in your own Axum application gives you the unversioned routes; nest them yourself if you want the versioned form.
Engine-level limits (query length caps, GROUP BY ceilings, scan caps) are listed in docs/reference/KNOWN_LIMITATIONS.md.

§Compatibility

Environment	Status	Note
Linux x86_64 (glibc)	Supported	`.tar.gz` and `.deb` release artifacts
macOS aarch64 (Apple Silicon)	Supported	`.tar.gz` release artifact
macOS x86_64 (Intel)	Supported	`.tar.gz` release artifact
Windows x86_64 (MSVC)	Supported	Portable `.zip`; no signed MSI installer yet
Docker	Supported	Repository `Dockerfile`: `rust:1.97-bookworm` builder, `debian:bookworm-slim` runtime, non-root user, port 8080
Rust toolchain	1.90 or later	Workspace MSRV, for `cargo install` and source builds
`velesdb-core`	5.0.0	Same workspace version; non-optional dependency with `openapi` + `persistence` enabled
HTTP clients	Any	Plain JSON over HTTP/1.1, described by an OpenAPI 3.0 document

§Troubleshooting

Symptom	Cause	Fix
`curl: (7) Failed to connect to localhost port 8080`	The server is not running, or it bound another address — the startup log prints `Bind address: <host>:<port>`.	Start it, or set `--host` / `--port`. `127.0.0.1` is the default and is not reachable from another machine.
`{"error":"[VELES-002] Collection 'x' not found","code":"VELES-002"}`	Wrong collection name, or the server was started on a different `--data-dir` (a missing directory is created empty).	`curl http://localhost:8080/v1/collections` to list what this instance actually holds.
`{"error":"Vector dimension mismatch for collection 'demo': expected 4, got 2. …","code":"VELES-004"}`	The query vector does not match the collection dimension; dimension and metric are immutable after creation.	Use the embedding model the collection was built with, or create a new collection and reindex.
`401` with `{"error":"Unauthorized","message":"missing Authorization header"}`	API keys are configured, so every route except the health/readiness probes requires a key.	Add `-H "Authorization: Bearer <key>"`. `/metrics` needs it too.
`429 Too Many Requests`	The per-IP limiter (100 req/s by default) is saturated; the response carries `retry-after`.	Back off, raise `--rate-limit`, or pass `--rate-limit 0` to disable it.
The process exits at startup with `tls_cert is set but tls_key is missing`	TLS needs both files; a half-configured pair is refused rather than silently downgraded to HTTP.	Provide `--tls-cert` and `--tls-key` together, and check both paths exist.

§License

VelesDB Core License 1.0 — see LICENSE.

velesdb-server v5.0.0 · Last updated: 2026-08-10 · Applies to: velesdb-core 5.0.0 · Report a docs error

§Crate-level notes

VelesDB Server - REST API library for the VelesDB vector database.

This module provides the HTTP handlers and types for the VelesDB REST API.

§OpenAPI Documentation

The API is documented using OpenAPI 3.0. Access the interactive documentation at:

Swagger UI: GET /swagger-ui
OpenAPI JSON: GET /api-docs/openapi.json

Re-exports§

pub use onboarding::OnboardingMetrics;

Modules§

auth: API key authentication middleware.
config: Server configuration module.
explain: EXPLAIN query handler and plan building logic.
match_query: MATCH query handler for REST API (EPIC-045 US-007).
onboarding: Lightweight counters for first-hour troubleshooting diagnostics.
query: VelesQL query execution handlers.
rate_limit: Global per-IP rate limiting middleware backed by tower-governor.
routes: Route definitions for the VelesDB REST API.
search: Search handlers for vector similarity, text, and hybrid search.
serde_id: Serde helpers for serializing u64 IDs as JSON strings.
tls: TLS configuration and server support via rustls.

Structs§

ActualStatsResponse: Actual execution statistics for EXPLAIN ANALYZE responses.
AggregationResponse: Response from VelesQL aggregation query execution.
ApiDoc: Public entry point for the full OpenAPI document. Merges in the prometheus-gated /metrics path when that feature is enabled.
AppState: Application state shared across handlers.
BatchSearchRequest: Request for batch vector search.
BatchSearchResponse: Response from batch search.
CollectionConfigResponse: Response with detailed collection configuration.
CollectionDiagnosticsResponse: Response with a collection’s health diagnostics.
CollectionResponse: Response with collection information.
CollectionStatsResponse: Response with collection statistics from ANALYZE.
ColumnStatsResponse: Per-column statistics in a collection stats response.
CreateCollectionRequest: Request to create a new collection.
CreateIndexRequest: Request to create a property index.
DegreeResponse: Response for node degree query.
EdgeCountResponse: Response for edge count query.
EnableStreamingRequest: Request body for the enable-streaming endpoint.
ErrorResponse: Error response.
ExplainCost: Estimated cost metrics for the query.
ExplainFeatures: Features detected in the query.
ExplainRequest: Request for query EXPLAIN.
ExplainResponse: Response from query EXPLAIN.
ExplainStep: A step in the query execution plan.
FusionRequest: Fusion configuration for hybrid dense+sparse search.
GraphSearchRequest: Request for graph embedding search.
GraphSearchResponse: Response for graph embedding search.
GuardRailsConfigRequest: Request to configure query guard-rails.
GuardRailsConfigResponse: Response with current guard-rails configuration.
HybridSearchRequest: Request for hybrid search (vector + text).
IdScoreResult: A single ID+score result from IDs-only search.
IndexResponse: Response with index information.
IndexStatsResponse: Per-index statistics in a collection stats response.
ListIndexesResponse: Response listing all indexes.
MultiQuerySearchRequest: Request for multi-query vector search with fusion.
NodeEdgeQueryParams: Query parameters for node-scoped edge queries.
NodeListResponse: Response containing all node IDs in the graph.
NodePayloadResponse: Response for a node payload retrieval.
NodeStatsResponse: Per-plan-node estimated execution statistics for EXPLAIN ANALYZE responses.
ParallelTraverseRequest: Request for parallel multi-source BFS traversal.
PointRequest: A point in an upsert request.
QueryErrorDetail: VelesQL query error detail.
QueryErrorResponse: VelesQL query error response.
QueryRequest: Request for VelesQL query execution.
QueryResponse: Response from VelesQL query execution.
QueryResponseMeta: Metadata section for VelesQL query responses.
ScrollPoint: A single point in a scroll response.
ScrollRequest: Request body for the scroll endpoint.
ScrollResponse: Response from the scroll endpoint.
SearchIdsResponse: Response from IDs-only search (no payload hydration).
SearchRequest: Request for vector search (dense, sparse, or hybrid).
SearchResponse: Response from vector search.
SearchResultResponse: A single search result.
StreamDoneEvent: SSE event: Traversal completed.
StreamInsertRequest: Request body for the streaming insert endpoint (single point).
StreamNodeEvent: SSE event: A node reached during traversal.
StreamStatsEvent: SSE event: Periodic statistics update.
StreamTraverseParams: Query parameters for streaming graph traversal.
TextSearchRequest: Request for BM25 text search.
TraversalResultItem: A single traversal result item.
TraversalStats: Statistics from traversal operation.
TraverseRequest: Request for graph traversal.
TraverseResponse: Response from graph traversal.
UnifiedQueryResponse: Unified response from /query endpoint.
UpsertNodePayloadRequest: Request to upsert a node payload.
UpsertPointsRequest: Request to upsert points.
VelesqlErrorDetail: Standardized VelesQL semantic/runtime error detail.
VelesqlErrorResponse: Standardized VelesQL semantic/runtime error response.

Enums§

QueryType: Query type for unified /query endpoint.
SparseVectorInput: Input format for sparse vectors, supporting two JSON representations:

Constants§

MAX_SPARSE_NNZ: Maximum non-zero entries (NNZ) allowed in a single sparse vector.
VELESQL_CONTRACT_VERSION: Canonical VelesQL contract version for REST responses.

Functions§

add_edge: Add an edge to a collection’s graph.
add_edges_batch: Add multiple edges to a collection’s graph in one batched operation.
aggregate: Execute an aggregation-only VelesQL query.
analyze_collection: Analyze a collection, computing and persisting statistics.
batch_search: Batch search for multiple vectors.
bulk_delete_points: Deletes multiple points by ID in a single request.
collection_diagnostics: Get health diagnostics for a collection (index readiness, point count).
collection_sanity: Run a quick sanity check for onboarding and troubleshooting.
compact_collection: Compacts the vector storage of a collection, rewriting active vectors into a contiguous layout and reclaiming disk space from deleted entries.
create_collection: Create a new collection.
create_index: Create a property index on a graph collection.
default_avg_weight: Default average weight for weighted fusion.
default_collection_type: Default collection type: vector.
default_dense_weight: Default dense weight for relative score fusion.
default_fusion_strategy: Default fusion strategy: RRF.
default_hit_weight: Default hit weight for weighted fusion.
default_index_type: Default index type: hash.
default_max_weight: Default max weight for weighted fusion.
default_metric: Default distance metric: cosine.
default_rrf_k: Default RRF k parameter.
default_sparse_weight: Default sparse weight for relative score fusion.
default_storage_mode: Default storage mode: full (no quantization).
default_top_k: Default number of results to return.
default_vector_weight: Default vector weight for hybrid search.
delete_collection: Delete a collection.
delete_index: Delete a property index.
delete_point: Delete a point by ID.
enable_streaming: Enable streaming ingestion on a collection.
explain: Explain a VelesQL query, optionally executing it with instrumentation.
flush_collection: Flush pending changes to disk.
get_collection: Get collection information.
get_collection_config: Get detailed collection configuration (HNSW params, storage mode, schema, etc.).
get_collection_stats: Get cached collection statistics (returns 404 if never analyzed).
get_edge_count: Get the total number of edges in the graph.
get_edges: Get edges from a collection’s graph filtered by label.
get_guardrails: Get current guard-rails configuration.
get_node_degree: Get the degree (in and out) of a specific node.
get_node_edges: Get edges for a specific node with direction filtering.
get_node_payload: Get the payload of a graph node.
get_point: Get a point by ID.
get_point_relations: List outgoing relation edges for a point.
graph_search: Search graph nodes by embedding similarity.
health_check: Liveness probe — always returns 200 OK.
health_metrics: Simple health metrics for lightweight monitoring.
hybrid_search: Hybrid search combining vector similarity and BM25 text search.
is_empty: Check if a collection is empty.
list_collections: List all collections.
list_indexes: List all indexes on a collection.
list_nodes: List all node IDs in the graph.
match_query: Execute a MATCH query on a collection.
mode_to_search_quality: Convert search mode string to crate::SearchQuality.
multi_query_search: Multi-query search with fusion strategies.
multi_query_search_ids: Multi-query fusion search returning only ids and scores (no payloads).
prometheus_metrics: Prometheus text format metrics response.
query: Execute a VelesQL query.
readiness_check: Readiness probe — returns 200 when the database is fully loaded, 503 otherwise.
rebuild_index: Rebuilds the HNSW index of a vector collection, reclaiming memory occupied by tombstoned entries and producing a fresh graph from the current vector storage.
relate_points: Create a relation edge between two points in a collection.
remove_edge: Remove an edge by ID.
reorder_for_locality: Reorders the HNSW adjacency lists and vector storage for cache locality so nodes traversed together during search sit close in memory (issue #377). No-op for collections with fewer than 1 000 vectors. Recall is preserved — only the physical layout changes.
scroll_points: Scroll through collection points with cursor-based pagination.
search: Search for similar vectors.
search_ids: Lightweight search returning only IDs and scores (no payload hydration).
set_point_ttl: Set (or refresh) the durable TTL of a point.
stream_insert: Stream-insert a single point via the bounded ingestion channel.
stream_traverse: Stream graph traversal results via SSE.
stream_upsert_points: Stream upsert points using NDJSON.
text_search: Search using BM25 full-text search.
traverse_graph: Traverse the graph using BFS or DFS from a source node.
traverse_parallel: Parallel multi-source BFS traversal.
unrelate_points: Remove a relation edge by ID.
update_guardrails: Update guard-rails configuration (partial update).
upsert_node_payload: Upsert a payload on a graph node.
upsert_points: Upsert points to a collection.
upsert_points_raw: Bulk upsert points via the binary wire format.
vacuum_collection: Vacuums the HNSW index of a vector collection, removing tombstoned entries and rebuilding the graph from current vectors.