Skip to main content
Concept
Each Helix Cloud cluster runs one writer and two readers behind a routing gateway. The writer commits every write, the readers serve reads, and object storage holds the data. Shared-plan databases share a regional cluster; a dedicated cluster serves only your databases. Helix Cloud is a fundamentally different architecture and database compared to the open-source v1 version of HelixDB. That version used LMDB, which was limited to sequential writes and could only handle a relatively small amount of data. Helix Cloud uses a new LSM-based storage engine backed by object storage that can handle concurrent writes to the writer node and allows for virtually unlimited data storage.

Gateway

The gateway is the entry point for all client traffic. It authenticates each request’s API key, applies the request rate limit on shared plans, and routes writes to the writer and reads to a reader. A read goes to the writer only when it sets X-Helix-Require-Writer: true. Each cluster runs several gateway replicas.

Writer

A single writer process handles all mutations. The writer supports concurrent write transactions through MVCC (multi-version concurrency control), allowing multiple writes to execute in parallel without blocking each other. Serializing the commit path through one process keeps the consistency model simple. The writer batches mutations for throughput and persists them durably to object storage before acknowledging. A read sent to the writer with X-Helix-Require-Writer: true sees every committed write immediately, with no snapshot refresh delay.

Readers

The two readers serve every other read. Each keeps its own memory and SSD cache, filled from object storage, and sees a new write once it refreshes to a snapshot that contains it. See read-after-write. The reader count is fixed; it does not grow with load. The gateway retries transient reader failures, but with no reader available a read fails with 503 backend_unavailable rather than moving to the writer; retry with backoff. Contact founders@helix-db.com if you need more read capacity.

Writer failover

Helix elects the writer through a lease. If the writer fails, Helix promotes a healthy reader and fences the old writer so it cannot commit after the new one takes over. Meanwhile:
  • Writes wait up to 90 seconds for the new writer. If none is ready, the gateway returns 503 failover_wait_unavailable without sending the write; retry after its Retry-After.
  • A write already sent when the writer changed returns 503 write_outcome_unknown. It may have committed, so reconcile before resubmitting; see Timed-out writes.
  • Reads continue on the readers.
If Helix detects more than one possible writer, it stops routing writes until it has fenced them; reads continue.

Object storage

Object storage is the durable system of record. All graph data, vector indexes, text index artifacts, and metadata persist here. No data lives exclusively on local disk. This means the system can recover from a full cache loss by reading from object storage, and storage capacity is effectively unbounded.

Cache hierarchy

Each process (writer and readers) caches the data it reads:
  • In-memory cache. Fastest access. Holds the hottest storage blocks and vector search state. Bounded by available RAM.
  • SSD cache. Larger capacity, lower cost per byte. Holds warm storage blocks and object storage files. Reads from SSD are significantly faster than reads from object storage.
Text search uses these same caches; there is no separate text-search cache. On cold start, caches warm as queries run. To warm them before traffic arrives, send reads with X-Helix-Warm: true.

Read path

  1. The gateway sends the read to a reader, or to the writer when it sets X-Helix-Require-Writer: true.
  2. The process resolves a consistent snapshot from object storage metadata.
  3. Data is read from the in-memory cache, SSD cache, or object storage (in that order).
  4. The query executes against the snapshot and returns results.
Cache misses transparently fall through to object storage. The same query produces the same result regardless of cache state; caching affects latency, not correctness.

Write path

  1. A write request arrives at the gateway and is routed to the writer.
  2. The writer executes the mutation within a serializable transaction. Multiple write transactions execute concurrently via MVCC; conflicts are resolved at commit time.
  3. The mutation is batched and persisted durably to object storage.
  4. Once durable, the write is acknowledged to the client.
  5. Readers observe the new data on their next snapshot refresh.

Next steps

Data Model

Nodes, edges, properties, and the labeled multigraph model.

Indexing

Secondary, vector, and text indexes over the property graph.

Reading data

Select and traverse graph data with the SDKs.

Guarantees

Consistency, durability, and isolation under this architecture.