Architecture

Overview

hlquery is written in C++20 and uses RocksDB as the storage engine for persistence, compaction, and crash recovery. The architecture is split into:

• Request handling (API layer)
• Search execution (keyword, vector, and hybrid pipelines)
• Durable storage (RocksDB with WAL and compaction) This separation keeps query latency low while preserving durability and operational safety.

System Architecture

The system is modular, consisting of a core engine, storage layer (RocksDB), search engine, API layer, and client libraries. Each component is optimized for its specific role. The architecture prioritizes performance, reliability, and simplicity in equal measure.

graph TB
    Client[Client Applications] -->|HTTP/REST| API[API Layer]
    API --> Search[Search Engine]
    API --> Storage[RocksDB Storage Engine]
    Search --> Index[Inverted Index<br/>BM25+ Ranking]
    Search --> Vector[Vector Search<br/>Exact scan today]
    Storage --> MemTable[MemTable<br/>In-Memory Buffer]
    Storage --> SSTable[SSTables<br/>Disk Storage]
    Storage --> WAL[Write-Ahead Log<br/>Durability]
    Storage --> Cache[Block Cache<br/>Read Optimization]
    Search --> Hybrid[Hybrid Search<br/>Weighted Blending]
    Hybrid --> Results[Search Results]

Component Responsibilities

• Client Applications: Use REST or client libraries to send search, indexing, and management requests.
• API Layer: Validates inputs, enforces auth, and translates requests into internal search/storage operations. This is also where consistent error handling and response shaping live.
• Search Engine:
  • Inverted Index + BM25+: Fast lexical matching for exact and near-exact keyword retrieval.
  • Vector Search: Semantic similarity search for embeddings from any model. Current execution is exact scan over candidate vectors, not ANN indexing.
  • Hybrid Blending: Combines lexical and semantic scores to balance precision and recall.
• RocksDB Storage Engine:
  • MemTable: In-memory staging area for fast writes.
  • WAL: Guarantees durability on crash before data is fully compacted.
  • SSTables: Sorted on-disk segments optimized for reads and compaction.
  • Block Cache: Reduces disk I/O by caching hot data.

Data and Query Flow

1. Indexing path: Documents arrive at the API layer, are validated, then written to RocksDB (WAL + MemTable), and indexed for both lexical and vector search.
2. Query path: A search request is parsed, then dispatched to the keyword engine, vector engine, or both (hybrid). Results are scored, blended, and returned with metadata.
3. Durability path: Writes are buffered in MemTable, logged to the WAL, and eventually flushed into SSTables through RocksDB compaction.

This split ensures writes are safe and durable without forcing search queries to wait on disk-level operations.

Performance Characteristics

Baseline Performance

• 128-256MB - Baseline memory
• <5ms - P50 Latency (hardware/data dependent)
• 10k+ - Queries/sec (hardware/data dependent)
• 90+ - Days uptime (target; verify in your environment)

The baseline assumes a moderate schema with typical text fields and a single vector field. The most important driver of latency is cache locality: hot indexes in memory perform significantly faster than cold, disk-backed reads.

Performance Numbers

Performance depends on hardware, dataset shape, cache locality, vector dimensionality, filters, and request mix. Treat any benchmark as workload-specific rather than a general guarantee.

Use Benchmark and your own traffic profile to measure:

Area	What to measure
Document writes	Batch size, WAL pressure, compaction behavior, and indexing cost.
Lexical search	P50/P95/P99 latency with representative query terms and filters.
Vector search	Candidate count, vector dimensionality, filter selectivity, and exact-scan cost.
Hybrid search	Lexical/vector blend cost plus result merging.
Collection operations	Schema creation, collection metadata loading, and distributed discovery.

Scaling depends primarily on index size vs. memory, write patterns, filter selectivity, and vector dimensionality. Validate scale with your own data and queries.

Scaling depends most on:

• Index size vs. memory: Keeping frequently accessed index segments in memory preserves low latency.
• Write patterns: Batch inserts reduce write amplification and compaction overhead.
• Vector dimensionality: Higher-dimensional vectors cost more CPU and memory per query.

Operational Notes

• Graceful shutdown and WAL sync are built in.
• JSON metrics and health endpoints provide basic observability.
• Authentication can be enabled or disabled per config.

Operational behavior is best validated under your own workload and deployment constraints.