Skip to content

TECHNICAL DEEP DIVE

What is SurrealDB?

Architecture. One key-value substrate, one query planner, one transaction coordinator.
Every model. Documents, graphs, vectors, time-series, geospatial and relational, in one ACID transaction.
Storage. Compute apart from storage, 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

Idle compute shuts down and the data stays in object storage. Recovery is proportional to the log delta, not the dataset.

DURABILITY

Built-in durability

S3-class storage carries eleven nines of durability, so the database needs no backup tier of its own.

BRANCHING

Instant branching

A petabyte-scale branch in seconds, as a logical reference over shared storage. Git-like workflows for 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.

SurrealDB

The context and memory layer for AI agents

Database. Graphs, vectors, documents and relational data in one engine, in a single ACID transaction.
Agent Memory. Connects and retrieves context wherever your data lives, every fact carrying its source.
Cloud. Fully managed, in the cloud provider and region you choose.

Explore with AI

Copyright © 2026 SurrealDB Ltd. Registered in England and Wales. Company no. 13615201

Registered address: 3rd Floor 1 Ashley Road, Altrincham, Cheshire, WA14 2DT, United Kingdom

Trading address: Huckletree Oxford Circus, 213 Oxford Street, London, W1D 2LG, United Kingdom