A database engine needs deterministic memory management, predictable latency, and safe concurrency. Rust's ownership model delivers all three without a garbage collector - no GC pauses during query execution, no unpredictable latency spikes under load, no memory overhead from a managed runtime.

ENGINEERING DEEP DIVE

What is SurrealDB?

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

Fair instinct, but architecturally wrong here. SurrealDB is not a wrapper over separate engines - it is one engine where every model shares a single KV substrate, a single query planner, and a single transaction coordinator. There are no seams between subsystems, no serialisation boundaries, no index coordination overhead. The cost of adding a graph traversal to a vector query is additive, not multiplicative. A purpose-built, single-model database will beat SurrealDB at its own specialty in isolation. But in production, your agent doesn't need "just vector search." It needs vector search scoped by a graph traversal, filtered by tenant and time, ranked by a hybrid score, and committed atomically alongside a memory update. The specialised system is fast at step one - the other four steps require separate systems, network round-trips, and glue code that add more latency and failure modes than the per-model difference saves.

Q: Why would I use SurrealDB over Postgres?

If your workload is purely relational, Postgres is excellent. The question gets interesting when you start adding pgvector for embeddings, recursive CTEs for graph traversal, Elasticsearch for full-text, Redis for real-time subscriptions, and a separate auth service - each with its own consistency model and failure modes. SurrealDB collapses that into one engine. The same query that would require four round-trips across independent systems is a single SurrealQL statement in a single ACID transaction. There are structural differences too: record links replace foreign key joins, graph edges are full documents, row-level permissions and live queries are built in, and SurrealDS scales compute and storage independently on object storage - a cost model coupled architectures cannot match.

Q: Is SurrealDB a fork or wrapper?

Neither. SurrealDB is built from scratch in Rust - the query engine, storage engines, transaction coordinator, permission system, and real-time subscription layer were all designed and implemented from the ground up. When you run a query combining graph traversal with vector similarity and structured filters, it executes natively inside SurrealDB's own query planner. There is no Postgres underneath, no Neo4j, no Pinecone.

Q: Is SurrealDB production-ready?

SurrealDB 3.0 is generally available and used in production by organisations including Nvidia, Samsung, Tencent, Verizon, Walmart, and ING across finance, healthcare, gaming, and defence. SurrealDB Cloud provides fully managed deployment with enterprise support, SLAs, and SOC 2 / ISO 27001 compliance.

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 building Read the docs

IN SHORT

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.

Spectron adds persistent, structured agent memory and SurrealDS 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 Spectron for persistent agent memory and SurrealDS for 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

Spectron 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

Spectron

Memory

Entity extraction

Knowledge graph

Temporal facts

Hybrid retrieval

SurrealDB

Context

Documents

Graphs

Vectors

Time-series

Auth

APIs

Storage

Quorum consensus

Compute-storage sep.

Scale to zero

Object storage (S3 / GCS / Azure Blob)

The SurrealDB vertical stack: object storage, the multi-model engine, and Spectron agent memory in one path.

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 - vec_dist) * 0.6 + ft_score * 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 the Surrealist sandbox →

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.

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.

ACID TRANSACTIONS

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 a Spectron 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.

ARCHITECTURE

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.

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;

STORAGE BACKENDS

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. SurrealDS is the distributed storage layer, 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.

SURREALDS

Compute-storage separation

For production-scale distributed deployments, SurrealDS separates compute from storage entirely. Transactional data is durably persisted in commodity object storage - Amazon S3, Google Cloud Storage, or Azure Blob Storage. Compute nodes are stateless and elastic.

Client

Load balancer layer

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

Availability Zone A

Highly-scalable read compute

SurrealDBread node

SurrealDBwrite node

Availability Zone B

Highly-scalable read compute

SurrealDBread node

SurrealDBwrite node

Availability Zone C

Highly-scalable read compute

SurrealDBread node

SurrealDBwrite node

Object storage (S3 / GCS / AFS / durable cold tier)

SurrealDS 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.

SPECTRON

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.

Spectron eliminates this. It is a persistent, structured memory engine built on SurrealDB. When a conversation is ingested, Spectron autonomously extracts entities, builds knowledge graph connections, tracks temporal facts with bi-temporal validity, and indexes everything for hybrid retrieval. All of this commits atomically in the same ACID transaction as the application data it relates to.

Working memory

Active context window for the current conversation and in-flight reasoning.

Semantic memory

Entities, properties, and relationships stored as a knowledge graph with vector embeddings.

Episodic memory

Structured records of past interactions, graph-linked and searchable by vector similarity.

Procedural memory

Learned patterns and decision heuristics informed by traces of past actions and outcomes.

Preference memory

Accumulated user preferences, interaction feedback, and behavioural patterns.

Because Spectron 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. Spectron inherits the full security model (row-level permissions, namespace isolation) and the full storage stack (SurrealDS, 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;

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

Surrealism: 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/platform/surrealdb/extensibility.

DEFINE MODULE mod::sentiment
    AS f"plugins:/sentiment.surli";

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 SurrealDS cluster. 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.

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	Spectron (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	Surrealism (sandboxed WASM)

SUMMARY

The full picture

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

FREQUENTLY ASKED QUESTIONS