NEW

SurrealDB 4 is here, introducing SurrealDB Earth and SurrealDS!

Learn more

TECHNICAL DEEP DIVE

What is SurrealDB?

Architecture. One key-value substrate, one query planner and one transaction coordinator beneath every model.
Every model. Documents, graphs, vectors, time-series, geospatial and relational, in one ACID transaction.
Storage. Compute scales apart from storage, with the data held on commodity object storage.

SURREALQL

One query, every model. Filters, a graph walk and hybrid ranking in one statement, on one snapshot.

SURREALQL

Hybrid query in one statement

One statement: tenant and time filters, a graph walk, and hybrid vector and full-text ranking. One transaction, one snapshot.

Try SurrealQL in Studio
SELECT id, title,
vector::distance::knn() AS vec_dist,
search::score(1) AS ft_score,
(1 - vector::distance::knn()) * 0.6
+ search::score(1) * 0.4
AS blend_score
FROM knowledge_base
WHERE tenant = $tenant
AND updated_at > time::now() - 30d
AND id IN $customer->owns->product
->has_issue->knowledge_base
AND content_embedding <|50,20|>
$query_embedding
AND content @1@ $query_text
ORDER BY blend_score DESC
LIMIT 10;
QUERY ENGINE

Indexes built for each model

HNSW for vectors, BM25 for full-text, B-trees for lookups and the key layout itself for graph traversal. Execution streams, so a traversal feeds a vector ranking with nothing materialised between them.

-- HNSW graph for vector similarity
DEFINE INDEX product_vec ON product
FIELDS embedding
HNSW DIMENSION 1536 DIST COSINE;

-- BM25 inverted index for full-text
DEFINE INDEX article_ft ON article
FIELDS content
FULLTEXT ANALYZER english BM25;

-- B-tree for structured lookups
DEFINE INDEX user_email ON user
FIELDS email UNIQUE;

-- A traversal feeds a vector ranking
-- as one stream
SELECT id, name,
vector::distance::knn() AS dist
FROM customer:acme->owns->product
WHERE embedding <|10|> $query_vec
ORDER BY dist
LIMIT 5;
GRAPH

Relationships are records

An edge is a full document with its own fields and permissions. Arrow syntax walks it in either direction, filtering as it goes.

-- An edge with its own fields
RELATE customer:acme->owns->product:p42
SET since = time::now(),
seat_count = 120;

-- Walk it, filtering the edge
SELECT ->owns[WHERE seat_count > 50]->product.name
FROM customer:acme;

-- Two hops, bounded depth
SELECT ->owns->product->has_issue->knowledge_base
FROM customer:acme;
LIVE QUERIES

A result set that keeps arriving

Add LIVE to a SELECT and every matching change streams to the client as it commits. DIFF sends only the change; KILL ends the stream.

-- The query you already wrote, as a stream
LIVE SELECT * FROM knowledge_base
WHERE tenant = $tenant;

-- Only the change, not the whole record
LIVE SELECT DIFF FROM task
WHERE status != "closed";

-- The client receives each commit:
-- { action: "UPDATE", result: { id: task:9f2, ... } }

-- Stop receiving updates
KILL $live_id;

DATA MODELS

Composable by design. Every model is a native primitive, and any statement can combine them: a graph walk scoped by a full-text match, ranked by vector distance and streamed live.

CAPABILITIES

Beyond the core models. Geospatial, WebAssembly extensions, custom endpoints and a single binary that runs anywhere.

ARCHITECTURE

One engine, from the transaction to the disk. Every model shares one transaction, one sorted key space and one pluggable storage layer.

Transactions

ACID across every model

A document update, a new edge, an embedding and a memory fact commit whole or not at all. An agent's read-think-write loop runs inside one transaction.

Single ACID transaction

  1. 01 Read

    • Docs + graphs
    • Vectors + memory
    • Consistent snapshot
  2. 02 Think

    • LLM reasoning
    • Tool selection
    • Model inference
  3. 03 Write

    • Update state
    • Persist memory
    • Atomic commit

Next cycle

The read-think-write loop, inside a single ACID transaction.
Key space

One engine, one key-value substrate

Records, edges and index entries are sorted keys in one transactional store. A lookup, a traversal and an index scan are all one scan of contiguous bytes.

One engine

Everything becomes an ordered key

  1. * Documents

  2. ~ Graph edges

  3. + Index entries

  1. Namespace

    01

  2. Database

    02

  3. Table

    user

  4. Type

    *

  5. Record id

    tobie

One sorted key space

Lookup · traversal · search

Documents, edges and index entries compile to keys in one sorted key space.

Compute apart from storage. SurrealKV embedded, SurrealMX in memory, or stateless compute over object storage. Every backend answers the same query. The distributed layer ships in SurrealDB Enterprise and SurrealDB Cloud; the community edition runs the embedded engines.

SCALING

Independent scaling

Compute and storage scale apart. Add replicas without adding storage, or grow the dataset without adding compute.

IDLE

Scale to zero

On SurrealDB Earth, idle compute shuts down and the data stays in object storage. Recovery follows the log delta, not the dataset.

DURABILITY

Built-in durability

With the default two-zone policy, a write is acknowledged only after it is stored on disks in both zones, and object storage, built for eleven nines of durability, holds the long-term copy.

BRANCHING

Instant branching, coming soon

A petabyte-scale branch in seconds, as a logical reference over shared storage, will bring Git-like workflows to data.

COST

Storage economics

Object storage costs a fraction of provisioned disk, and the dataset can exceed the local capacity of any instance.

REPLICATION

Cross-zone replication

Data flows through shared object storage rather than between nodes, so cross-zone traffic falls away.

WRITES

Quorum writes

Each availability zone runs its own write node. A transaction commits once a quorum of zones acknowledges it, with no elected leader.

RECOVERY

Recovery from the log

A replacement node restores from object storage and replays the transaction log. Recovery time follows the log delta, not the dataset.

Your questions,answered

It is one engine, so the models share a key-value substrate, a query planner and a transaction coordinator. Adding a graph traversal to a vector query costs one more step, in the same plan, against the same snapshot. A single-model database wins its own discipline in isolation. Production queries are rarely in isolation: they scope, traverse, rank and commit at once, and the round trips between separate systems cost more than the per-model difference saves.

THE PLATFORM

Everything an application and its agents know. Five surfaces, one engine.

IN PRODUCTION

Trusted at scale. Samsung, Nvidia, Verizon, Tencent, and Walmart run on SurrealDB.

14,000+

Developers building on SurrealDB Cloud

4M+

Developers building on SurrealDB worldwide

FROM THE TEAMS

SurrealDB gives us a foundation where we can unify semantic search, knowledge graphs, and AI-driven decision making without stitching together multiple systems. Collapsing responsibility into SurrealDB has become our default engineering posture.
Justin Foley

VP of Engineering, Later

GET STARTED

Start building with SurrealDB. Object storage to agent memory: one stack, one transaction, one query language.