Skip to content

NEW

Introducing SurrealDB Studio, the new official app of SurrealDB

1/4

TECHNICAL DEEP DIVE

What is SurrealDB?

One database for every model your AI agents need - documents, graphs, vectors, time-series, geospatial, and relational, in a single ACID transaction.

A deep dive into the architecture, storage engine, query language, and use cases that make SurrealDB a multi-model database built for modern applications and AI workloads.

Start free with SurrealDB Read the docs

01 | OVERVIEW

The short version

SurrealDB unifies documents, graphs, vectors, time-series, geospatial, and relational data in one engine - one query language (SurrealQL), one ACID transaction, one consistent snapshot.

Agent Memory adds persistent, structured agent memory and the distributed storage layer adds object-storage-backed compute-storage separation - together forming a single vertical stack from object storage to agent memory, with no glue code.

THE PROBLEM

The fragmented data stack

Building an enterprise AI agent today means stitching together five or six independent databases: a document store, a graph database, a vector index, a relational engine, a memory layer, and a message broker.

Each has its own consistency model, its own query language, and its own failure modes. When agents fail, it is rarely because the model is weak. It is because the data layer underneath cannot deliver consistent, complete context in a single operation.

THE SOLUTION

One database, one transaction

SurrealDB is the only data layer an enterprise agent needs. Your model, your data, one database.

It provides documents, graphs, vectors, time-series, geospatial, and relational structures as native primitives within a single engine, coordinated by a single query language (SurrealQL), and governed by a single ACID transaction boundary. Combined with Agent Memory for persistent Agent Memory and distributed storage backed by object storage, it forms one vertical stack from object storage to agent memory.

THE VERTICAL STACK

From object storage to agent memory

Agent Memory gives agents persistent memory. SurrealDB unifies every data model in one ACID transaction. The storage engine separates compute from storage on commodity object storage. No glue code. No middleware.

Applications

Agent Memory

Entity extraction

Knowledge graph

Temporal facts

Hybrid retrieval

Database

Documents

Graphs

Vectors

Time-series

Auth

APIs

Distributed write nodes

Node A

Node B

Node C

Object storage (S3 / S3-compatible)

The SurrealDB vertical stack: object storage, the multi-model engine, and Agent Memory in one path.

02 | SURREALQL

SurrealQL: one query, every model

The best way to understand SurrealQL is to see the payoff first. Consider a retrieval query for an AI agent that needs to find relevant knowledge base articles for a customer:

That single statement applies tenant isolation, temporal filtering, graph traversal through the customer's product relationships, and hybrid vector + full-text ranking. In a multi-system architecture, this would require four or five round-trips across independent databases with no transactional consistency between them. In SurrealQL, it is one query, one transaction, one consistent snapshot.

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;

Try SurrealQL in Studio

03 | SCOPE-FIRST RETRIEVAL

One query, one transaction

This works because SurrealQL treats every data model - documents, graphs, vectors, full-text, time-series, geospatial, relational - as composable operators within the same syntax. Here is how each one works individually.

Scope

Narrow the candidate set

Tenant isolation

tenant = $tenant

Temporal filter

updated_at > 30d ago

Graph traversal

→owns→product→…

Narrowed candidate set

Rank

Hybrid score ranking

Vector similarity

KNN · weight: 0.6

+

Full-text search

BM25 · weight: 0.4

Scope-first retrieval: narrow by tenant, time, and graph scope before ranking candidates by hybrid score.

04 | DATA MODELS

Composable by design

Graph relationships

Graph edges are native to the data model. Relationships are created with RELATE and traversed with arrow syntax. What makes SurrealDB's graph model distinct is that every edge is a full document - it can carry its own fields, metadata, embeddings, timestamps, and permissions.

Vector search

Vector similarity search is built into the query engine. You define an index on a field and query it with distance functions. The structured filter (category = 'tools') narrows the candidate set before the vector search runs - scope first, rank second.

RELATE customer:alice->purchased->product:widget_pro
    SET quantity = 2,
        date = time::now(),
        source = 'web',
        sentiment_embedding = $embedding;

SELECT ->purchased[WHERE date > time::now() - 30d]->product.name
    FROM customer:alice;

DEFINE INDEX product_embedding ON product
    FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;

SELECT id, name,
    vector::distance::knn() AS distance
    FROM product
    WHERE category = 'tools'
        AND embedding <|10,40|> $query_embedding
    ORDER BY distance;

Documents and record links

SurrealDB stores data as schemaless or schemafull documents. Record links replace foreign key joins with direct references that the engine resolves at query time, eliminating N+1 query patterns.

CREATE order SET
    customer = customer:alice,
    items = [product:widget_pro, product:gadget_x],
    total = 79.98;

-- Traverse record links inline, no JOIN needed
SELECT customer.name, items.name, total
    FROM order;

TEMPORAL AND SEARCH

Time-series, full-text, and real-time

Time-series and temporal queries

Native duration arithmetic, temporal aggregation functions, and point-in-time VERSION reads for time-travel queries without blocking writers.

Full-text search

BM25-scored full-text indexes with configurable analysers and the @@ match operator. Composes with every other model in the same query.

-- Aggregate sensor readings by hourly windows
SELECT
    time::floor(recorded_at, 1h) AS hour,
    math::mean(value) AS avg_temp,
    math::max(value) AS peak
    FROM reading
    WHERE sensor = sensor:temp_01
        AND recorded_at > time::now() - 7d
    GROUP BY hour
    ORDER BY hour DESC;

-- Time-travel: query the exact state 5 days ago
SELECT * FROM reading
    VERSION d'2026-03-20T00:00:00Z';

DEFINE ANALYZER english TOKENIZERS blank, class
    FILTERS lowercase, snowball(english);

DEFINE INDEX ft_content ON article
    FIELDS content
    FULLTEXT ANALYZER english BM25;

SELECT id, title,
    search::score(1) AS relevance
    FROM article
    WHERE content @1@ 'distributed consensus'
    ORDER BY relevance DESC;

Live queries, events, and more

Geospatial queries work on native GeoJSON types with built-in distance, bearing, and containment functions. LIVE SELECT provides real-time subscriptions over WebSockets. DEFINE EVENT triggers server-side logic on data changes, and changefeeds provide ordered, durable mutation streams per table.

Every one of these models composes with every other. A single SurrealQL statement can combine a graph traversal with a vector search, scope it by a full-text match, filter by a temporal range, restrict by geospatial proximity, aggregate relationally, and stream the results to a live subscriber.

05 | ARCHITECTURE

ACID transactions across every model

Every SurrealQL statement executes within an ACID transaction, regardless of which data models are involved. If a single query updates a document, creates a graph edge, writes a vector embedding, and persists an Agent Memory fact, either all of those operations commit or none do.

Every agent follows the same cycle: read context, reason over it, write the result. In multi-system architectures, reads and writes span databases with independent consistency models, so by the time the agent writes back, the data it read may have already changed. SurrealDB executes the entire loop within a single ACID transaction. The context the agent reads is the same consistent snapshot it writes against.

Single ACID transaction

Read

Docs + graphs

Vectors + memory

Consistent snapshot

Think

LLM reasoning

Tool selection

Model inference

Write

Update state

Persist memory

Atomic commit

Next cycle ↓

The read-think-write agent loop executing inside a single ACID transaction.

KV SUBSTRATE

One engine, one key-value substrate

At its lowest layer, SurrealDB stores all data - records, graph edges, index entries, metadata - as binary key-value pairs in a transactional KV store. The "models" are not separate engines. They are different query patterns and data structures layered on top of a single KV substrate.

A document is a KV entry with a * path separator. A graph edge pointer uses a ~ tag with an empty value - the key itself encodes the relationship. Index data entries use a + prefix.

Because every model shares the same sorted byte stream, there is no serialisation boundary between subsystems. When a query combines a graph traversal with a vector search, the query planner sees the entire operation and executes it against a single consistent snapshot. The KV store keeps keys in sorted binary order, so every "query by scope" becomes a tight prefix range scan. Graph traversals are not joins - they are prefix scans on contiguous slices of the sorted key space. When you write user:tobie->contributes->repo in SurrealQL, the engine jumps directly to the right byte range. A document lookup, a graph traversal, and an index scan all resolve to the same fundamental operation: scan a contiguous range of bytes.

Key structure for user:tobie

/

root

*

sep

00 00 00 01

NamespaceId

*

sep

00 00 00 02

DatabaseId

*

sep

user\0

table

*

type

\x03tobie\0

record ID

→

{name: "Tobie"}

Type tag determines the model

*

Document / relational record

Value = full document body

~

Graph edge pointer

Value = empty (key encodes the relationship)

+

Index data entries

B-tree, HNSW vector, full-text (BM25)

Documents, graph edges, and index entries all compile to keys in one sorted key-value substrate.

06 | QUERY ENGINE

Specialised indexes, streaming execution

While the storage is unified KV, the indexing layer is purpose-built for each model: HNSW graphs for vector similarity, BM25-scored inverted indexes for full-text, B-tree derivatives for structured lookups, and the directional key structure itself for graph traversals.

SurrealDB 3.0 rearchitected the query engine around streaming execution, processing results without materialising full intermediate result sets - critical for graph traversals where intermediate sets can explode in size.

-- 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;

-- Streaming execution: graph traversal
-- feeds into vector ranking without
-- materialising the intermediate set
SELECT id, name,
    vector::distance::knn() AS dist
    FROM customer:acme->owns->product
    WHERE embedding <|10|> $query_vec
    ORDER BY dist
    LIMIT 5;

07 | STORAGE

Pluggable storage, unified interface

The KV substrate is pluggable. SurrealKV is a custom-built embedded engine using a Versioned Adaptive Radix Trie (VART) over an LSM-tree architecture - it provides O(m) lookup matched to SurrealDB's hierarchical key layout, with built-in MVCC for time-travel VERSION queries.

SurrealMX is in-memory with optional persistence via append-only logs and snapshots. The distributed storage layer is described below. Every backend exposes the same transactional interface - switch engines without changing a single query.

# SurrealKV - embedded, VART + LSM-tree, MVCC
surreal start surrealkv://production.db

# SurrealMX - in-memory, optional persistence
surreal start memory

# RocksDB - embedded, LSM-tree
surreal start rocksdb://production.db

# Same queries. Same transactions.
# Every backend.

DISTRIBUTED STORAGE

Compute-storage separation

For production-scale distributed deployments, the distributed storage layer separates compute from storage entirely. Transactional data is durably persisted in commodity object storage - Amazon S3 or any S3-compatible store. Compute nodes are stateless and elastic. This layer, and the consensus and recovery behaviour described below, is an Enterprise Edition capability; the community edition runs the embedded backends above.

Most distributed databases were designed around provisioned disks attached to compute nodes: scaling meant a bigger machine, and the storage tier was the machine. The generation that followed separated compute from storage but tied the storage layer to a proprietary cloud database service - Aurora, AlloyDB - solving the elasticity problem by coupling the data to a single vendor's platform.

SurrealDB takes the third path. Transactional data is placed directly in commodity object storage and the database runs as stateless, elastic compute on top, with no proprietary storage tier in between. Data can live in any S3-compatible store - a major cloud, a private cloud, or an on-premise environment - and the compute layer is portable across all of them.

Client

Load balancer layer

Request routed to SurrealDB write node, or SurrealDB read-proxy node

Availability Zone A

Highly-scalable read compute

SurrealDBread node

SurrealDBread node

SurrealDBread node

SurrealDBwrite node

Availability Zone B

Highly-scalable read compute

SurrealDBread node

SurrealDBread node

SurrealDBread node

SurrealDBwrite node

Availability Zone C

Highly-scalable read compute

SurrealDBread node

SurrealDBread node

SurrealDBread node

SurrealDBwrite node

Object storage (S3 / S3-compatible / durable cold tier)

The distributed storage layer separates stateless, elastic compute from durable object storage.

INDEPENDENT SCALING

Compute and storage scale separately. Add read replicas without adding storage, or grow datasets without adding compute.

SCALE TO ZERO

Compute nodes shut down when idle. Data remains safe in object storage. Recovery time is proportional to log delta, not dataset size.

BUILT-IN DURABILITY

S3-class storage offers 99.999999999% durability. No separate backup infrastructure or snapshot management needed.

INSTANT BRANCHING

Create petabyte-scale database branches in seconds via logical metadata references - Git-like workflows for data.

STORAGE ECONOMICS

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

CROSS-ZONE REPLICATION

Data flows through shared object storage rather than streaming between nodes, structurally reducing the cross-availability-zone traffic that dominates the network bill of a traditional distributed cluster.

QUORUM CONSENSUS

No single leader, no split brain

Distributed transactions are coordinated by quorum rather than by an elected leader. Each availability zone runs its own write node, so write throughput scales horizontally instead of funnelling through a single primary. A transaction commits once a quorum of zones acknowledges it.

This removes the leader as both a bottleneck and a failure mode, and avoids the additional round-trip that leader-based replication pays on every write - consensus happens at the writing node itself.

1 transaction → 1 quorum decision

Every transaction is encapsulated within a quorum consensus decision. Transaction consensus is performed at the writing node, allowing writes to horizontally scale across all write nodes in a cluster.

Quorum transaction

(majority commit)

Quorum consensus

Storage enginedata storage

Storage enginedata storage

Storage enginedata storage

Each availability zone runs its own write node; transactions commit on quorum acknowledgement.

RESILIENCE

Node failure and recovery

When a compute node fails there is no state to rebuild from its peers. A replacement node restores from object storage and replays the transaction log from the last durable point.

Recovery time is therefore a function of the log delta since that point, not of the size of the dataset - a hundred-gigabyte database and a hundred-terabyte database recover in the same time from the same log position.

Client

Load balancer layer

Request routed to SurrealDB write node, or SurrealDB read-proxy node

Availability Zone A

Write queries are handled by write nodes

SurrealDBread proxy node

SurrealDBwrite node

Availability Zone B

Node B acknowledges writes.
Persistence succeeds, quorum fulfilled.

SurrealDBwrite node

Availability Zone C

Node C fails to acknowledge writes.
Persistence fails, but quorum fulfilled.

SurrealDBwrite node

LSM tree layers are retrieved from object storage so the query requests ranges which are not in the local storage cache

LSM tree layers are synced to object storage after range compaction

Transaction log written asynchronously to object storage

After the transaction log syncs from object storage, the node syncs the latest writes from a SurrealDB write node, and forms part of the quorum

On node recovery, data is restored from object storage, and the transaction log on object storage is tailed for the latest writes

Object storage (S3 / S3-compatible / durable cold tier)

Behaviour:

Quorum commit: transaction is committed once a quorum acknowledges the writes.

Durable log: committed writes are safe via a replicated write-ahead-log, with asynchronous durability to object storage for fast node recovery and secondary-region disaster recovery.

Catch-up: failed node restarts and replays transaction log from object storage (for reduced cost) and from cross-availability zone (for recent transactions).

Node crash: a new node catches up with the cluster, regardless of the existing local state, using transaction-log replay before joining the quorum.

Outcome:

Transaction commit succeeds with quorum majority

Client receives transaction success confirmation

SurrealDB write node in Availability Zone C catches up with cluster after restart

No split-brain / consistent ordering

Significant reduction in cross-availability zone traffic

A replacement node restores from object storage and replays the transaction log.

08 | AGENT MEMORY

Persistent agent memory

Most memory solutions for AI agents are middleware layers that sit above a fragmented data stack. They abstract over the seams between your vector database, your document store, and your graph engine - but the seams are still there. Memory writes go to one system, application data to another, and there is no transactional guarantee that the two are consistent. When an agent retrieves a memory that references data which has since changed, it reasons over a stale view of the world.

Agent Memory eliminates this. It is a persistent, structured memory engine built on SurrealDB. When a conversation is ingested, Agent Memory autonomously extracts entities, builds knowledge graph connections, tracks temporal facts with tri-temporal validity, and indexes everything for hybrid retrieval. Because memory and application data share one substrate, each write lands in the same transactional store the rest of your data lives in - no second system to keep in step, and no cross-database consistency gap.

Episodic

The raw conversational record - sessions and turns as authored, in order. The source of truth every extracted category cites back to.

Identity

Durable facts about who the principal is: name, role, employer, long-lived attributes. Long retention, low decay.

Knowledge

What the principal has learnt or shared - project facts, observations, references. Decays without reinforcement.

Context

What is happening right now: active topics, recent intents, the working set for the current conversation. Replaced rapidly.

Instructions

Behavioural rather than factual memory - how the principal wants to be served. Applied at prompt-assembly time, not at retrieval.

Uncertainty

Explicit "not known yet" rows, raised when confidence falls below the floor or provenance conflicts. Gaps stay visible instead of being papered over.

Because Agent Memory runs on SurrealDB, it composes naturally with every other data model. A single SurrealQL statement can traverse a user's purchase history through graph edges, filter reviewed products by semantic similarity, and retrieve only currently valid preferences via temporal constraints - all in one query, one transaction.

Multiple agents can read and write to the same memory surface with full ACID guarantees - coordination happens through shared context rather than message passing. Agent Memory inherits the full security model (row-level permissions, namespace isolation) and the full storage stack (distributed storage, scale-to-zero, branching). Between conversations, it continues working in the background: discovering connections, consolidating knowledge, resolving ambiguities, and inferring implicit relationships.

LET $user = user:jaime;
LET $query_vec = fn::embed(
    "What products does this user like?"
);

SELECT
    ->purchased->product
        AS purchase_history,
    ->reviewed->product[
        WHERE vector::similarity::cosine(
            embedding, $query_vec
        ) > 0.8
    ] AS relevant_products,
    ->preferences[
        WHERE valid_at <= time::now()
    ] AS current_preferences
    FROM ONLY $user;

09 | CAPABILITIES

Beyond the core models

Geospatial queries

Native GeoJSON support with built-in distance, bearing, area, and containment functions. No PostGIS extension. Geospatial composes with everything else - find stores within 5km and traverse their inventory graph in one statement.

SELECT name,
    geo::distance(location, $user_location)
        AS dist,
    ->stocks->product[
        WHERE category = 'electronics'
    ] AS inventory
    FROM store
    WHERE geo::distance(
        location, $user_location
    ) < 5000
    ORDER BY dist;

Plugins: the extension system

A WebAssembly-based extension system. Write an extension in Rust, compile it to a .surli module, load it into a running database. Your functions become callable from SurrealQL, sandboxed in WASM, participating in ACID transactions. See surrealdb.com/surrealdb/extensions.

DEFINE MODULE mod::sentiment
    FROM f"modules:/sentiment.surli"
    UNSIGNED;

UPDATE article SET
    sentiment = mod::sentiment::analyze(
        content
    ),
    keywords = mod::sentiment::extract(
        content
    )
WHERE created_at > time::now() - 1h;

DEFINE API: custom endpoints in the database

DEFINE API creates custom HTTP endpoints directly inside SurrealDB - no external framework, no routing layer. The endpoint inherits ACID transactions, row-level permissions, and multi-model query capabilities. For agent-facing APIs and internal tools, this eliminates the entire API routing layer.

DEFINE API "/agent/context"
    FOR post
        PERMISSIONS
            WHERE $auth.role = "agent"
        THEN {
            LET $results = SELECT *
                FROM knowledge
                WHERE vector::similarity::cosine(
                    embedding,
                    $request.body.embedding
                ) > 0.8;

            RETURN {
                status: 200,
                body: $results,
            }
        };

Single binary, runs everywhere

SurrealDB compiles to a single binary. It runs in the browser via WebAssembly, embedded in edge devices, as a serverless function, as a single-node server, or as a distributed cluster on object storage. The query engine, data model, and application code are identical across all environments - a prototype built embedded in a browser can move to a distributed cluster in production without rewriting a single query.

10 | COMPARISON

How SurrealDB compares

How SurrealDB compares to single-purpose databases. Reflects publicly documented capabilities as of June 2026.
Feature	Postgres	Neo4j	Pinecone / Weaviate	SurrealDB
Data models	Relational + extensions	Graph + native vector index	Vector-first	Documents, graphs, vectors, time-series, geospatial, relational
Graph support	Recursive CTEs	Native (Cypher)	None	Native (arrow syntax, edges as documents)
Vector search	pgvector extension	Native vector index	Native ANN (specialised)	Native, composable with filters + graphs
Transactions	ACID, single model	ACID, graph	Tunable / eventual	ACID across every model
Agent Memory	External middleware	External middleware	External middleware	Agent Memory (built on SurrealDB, ACID-consistent)
Storage	Coupled compute + storage	Coupled, cache-dependent	Managed service	Object-storage-backed, compute-storage separation
Extensibility	C extensions, PL/pgSQL	Java / APOC plugins	Limited	WebAssembly extensions (sandboxed)

11 | SUMMARY

The full picture

The distributed storage layer is backed by S3-class object storage with quorum consensus, compute-storage separation, and scale-to-zero. SurrealDB provides the unified data layer: documents, graphs, vectors, time-series, geospatial, and relational structures as native primitives in one ACID transaction. Agent Memory provides persistent, structured agent memory that commits atomically alongside application data.

12 | FREQUENTLY ASKED QUESTIONS

Frequently asked questions

If SurrealDB does everything, doesn't that mean it's bad at everything?

Why would I use SurrealDB over Postgres?

Is SurrealDB a fork or wrapper?

Why Rust?

Is SurrealDB production-ready?

What is quorum consensus?

Which object storage providers are supported?

How does scale-to-zero work?

How does instant branching work?

GET STARTED

Start building with SurrealDB

Object storage to agent memory. A single stack, a single transaction, one query language.

Samsung

NVIDIA

Apple

Verizon

Tencent

SOC 2 Type 2

GDPR

Cyber Essentials Plus

ISO 27001

Start free with SurrealDB Talk to our team