---
title: "Technical deep-dive | SurrealDB"
description: "Technical breakdown of SurrealDB's architecture, storage engine, query language, and use cases for modern apps and AI workloads."
url: https://surrealdb.com/surrealdb/deep-dive
---

TECHNICAL DEEP DIVE

# What is SurrealDB?

[Start free with SurrealDB](https://studio.surrealdb.com/current/instances/deploy) [Read the docs](https://surrealdb.com/docs/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.

1. ![Babcock](https://surrealdb.com/assets/static/babcock.lo4rnVg1.svg)
2. ![ING](https://surrealdb.com/assets/static/ing.X3I6S3_V.svg)
3. ![British Airways](https://surrealdb.com/assets/static/british-airways.KEsZiwV-.svg)
4. ![Nvidia](https://surrealdb.com/assets/static/nvidia.DaIEuMil.svg)
5. ![Apple](https://surrealdb.com/assets/static/apple.D5pq4flY.svg)
6. ![SpaceX](https://surrealdb.com/assets/static/spacex.CQJEk-IL.svg)
7. ![Samsung](https://surrealdb.com/assets/static/samsung.CH-vQgnb.svg)
8. ![adidas](https://surrealdb.com/assets/static/adidas.DdTC5qhk.svg)
9. ![Tencent](https://surrealdb.com/assets/static/tencent.paQmLxyy.svg)
10. ![Alibaba](https://surrealdb.com/assets/static/alibaba.B16idgfM.svg)
11. ![PolyAI](https://surrealdb.com/assets/static/poly-ai.c3w_fAg6.svg)
12. ![Later](https://surrealdb.com/assets/static/later.Ds736jFO.svg)
13. ![Verizon](https://surrealdb.com/assets/static/verizon.BI7CajdX.svg)
14. ![Liberty Mutual](https://surrealdb.com/assets/static/liberty-mutual.B7qOU1pd.svg)
15. ![Walmart](https://surrealdb.com/assets/static/walmart.BjDg_Sr8.svg)
16. ![Carrier](https://surrealdb.com/assets/static/carrier.D21gC6NX.svg)
17. ![Saks Fifth Avenue](https://surrealdb.com/assets/static/saks-fifth-avenue.COIDpLSb.svg)
18. ![San Francisco Compute Company](https://surrealdb.com/assets/static/sfcc.B7jlImq4.svg)
19. ![Shield AI](https://surrealdb.com/assets/static/shield-ai.pINZ0KJr.svg)
20. ![Wix](https://surrealdb.com/assets/static/wix.DvHhmoBi.svg)

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](https://studio.surrealdb.com/)

Copy

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

Copy

```
-- HNSW graph for vector similarityDEFINE INDEX product_vec ON product    FIELDS embedding    HNSW DIMENSION 1536 DIST COSINE;-- BM25 inverted index for full-textDEFINE INDEX article_ft ON article    FIELDS content    FULLTEXT ANALYZER english BM25;-- B-tree for structured lookupsDEFINE INDEX user_email ON user    FIELDS email UNIQUE;-- A traversal feeds a vector ranking-- as one streamSELECT 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.

Copy

```
-- An edge with its own fieldsRELATE customer:acme->owns->product:p42    SET since = time::now(),        seat_count = 120;-- Walk it, filtering the edgeSELECT ->owns[WHERE seat_count > 50]->product.name    FROM customer:acme;-- Two hops, bounded depthSELECT ->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.

Copy

```
-- The query you already wrote, as a streamLIVE SELECT * FROM knowledge_base    WHERE tenant = $tenant;-- Only the change, not the whole recordLIVE SELECT DIFF FROM task    WHERE status != "closed";-- The client receives each commit:-- { action: "UPDATE", result: { id: task:9f2, ... } }-- Stop receiving updatesKILL $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.

### [Documents](https://surrealdb.com/docs/surrealql/datamodel)

Schemaless or schemafull records. Record links replace foreign-key joins with references the engine resolves at query time.

Read the docs

### [Graphs](https://surrealdb.com/docs/surrealql/statements/relate)

Edges made with RELATE and walked with arrow syntax. Every edge is a full document with its own fields and permissions.

Read the docs

### [Vectors](https://surrealdb.com/docs/surrealdb/reference-guide/vector-search)

HNSW indexes queried with distance functions. A structured filter narrows the candidates before the search runs.

Read the docs

### [Time-series](https://surrealdb.com/docs/surrealql/datamodel/datetimes)

Native duration arithmetic, temporal aggregation and point-in-time VERSION reads without blocking writers, on a versioned storage engine (experimental).

Read the docs

### [Full-text search](https://surrealdb.com/docs/surrealdb/reference-guide/full-text-search)

BM25-scored indexes with configurable analysers and the @@ match operator, composed with every other model.

Read the docs

### [Live queries](https://surrealdb.com/docs/surrealql/statements/live)

LIVE SELECT streams changes over WebSockets. DEFINE EVENT runs logic on writes. Changefeeds keep an ordered log per table.

Read the docs

CAPABILITIES

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

### [Geospatial](https://surrealdb.com/docs/surrealql/datamodel/geometries)

Native GeoJSON types with distance, bearing, area and containment functions, composed with the graph in one statement.

Read more

### [Extensions](https://surrealdb.com/surrealdb/extensions)

WebAssembly modules written in Rust, loaded into a running database and callable from SurrealQL inside the transaction.

Read more

### [DEFINE API](https://surrealdb.com/docs/surrealql/statements/define/api)

HTTP endpoints defined inside the database, with its transactions, permissions and every model behind them.

Read more

### [Single binary](https://surrealdb.com/surrealdb/install)

The same engine in the browser as WebAssembly, embedded at the edge, as a server or as a cluster on object storage.

Read more

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

If SurrealDB does everything, is it good at anything?

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.

Why SurrealDB over Postgres?

Is SurrealDB a fork or a wrapper?

Why Rust?

Is SurrealDB production-ready?

Which object storage providers are supported?

How does scale-to-zero work?

THE PLATFORM

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

Database

Document, graph, vector, time-series and relational in one engine.

![Five data models as dotted tiles: documents, graph, vector, time-series and relational](https://surrealdb.com/assets/static/platform-database.DUdumYDz.avif)

Read more

[Database](https://surrealdb.com/surrealdb)

Agent Memory

What an agent learns, with its source and its time, in the same engine.

![A timeline of remembered facts, each with its source](https://surrealdb.com/assets/static/platform-agent-memory.Cvv8D5Wl.avif)

Read more

[Agent Memory](https://surrealdb.com/agent-memory)

Cloud

Managed clusters in the regions you choose, scaled on demand.

![Clusters in three regions on a world map, each running or scaling](https://surrealdb.com/assets/static/platform-cloud.--QZnaVi.avif)

Read more

[Cloud](https://surrealdb.com/cloud)

Studio

Query, explore and design the schema from the browser.

![A SurrealQL query in Studio and the schema graph under it](https://surrealdb.com/assets/static/platform-studio.7ykBFNLq.avif)

Read more

[Studio](https://surrealdb.com/studio)

MCP

Every model that speaks MCP reaches the database and the memory directly.

![Three models connected through MCP to the database and Agent Memory](https://surrealdb.com/assets/static/platform-mcp.D_oH0_wm.avif)

Read more

[MCP](https://surrealdb.com/mcp)

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.

[Get started](https://studio.surrealdb.com/current/instances/deploy) [Talk to our team](https://surrealdb.com/contact/sales)

```json
{"@context":"https://schema.org","@type":"Organization","@id":"https://surrealdb.com/#organization","name":"SurrealDB","url":"https://surrealdb.com","logo":"https://surrealdb.com/assets/static/logo.BG7_TG2b.svg","description":"SurrealDB is the context and memory layer for AI agents. A multi-model database for documents, graphs, vectors, and time-series.","foundingDate":"2022","legalName":"SurrealDB Ltd","identifier":{"@type":"PropertyValue","propertyID":"GB-COH","value":"13615201"},"address":{"@type":"PostalAddress","streetAddress":"3rd Floor, 1 Ashley Road","addressLocality":"Altrincham","addressRegion":"Cheshire","postalCode":"WA14 2DT","addressCountry":"GB"},"contactPoint":[{"@type":"ContactPoint","contactType":"customer support","email":"support@surrealdb.com","url":"https://surrealdb.com/contact","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"sales","email":"info@surrealdb.com","url":"https://surrealdb.com/contact","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"security","email":"security@surrealdb.com","url":"https://surrealdb.com/.well-known/security.txt","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"legal","email":"legal@surrealdb.com","url":"https://surrealdb.com/legal","availableLanguage":"English"}],"hasCertification":[{"@type":"Certification","name":"SOC 2 Type 2"},{"@type":"Certification","name":"GDPR"},{"@type":"Certification","name":"Cyber Essentials Plus"},{"@type":"Certification","name":"ISO 27001"}],"owns":[{"@type":"SoftwareApplication","name":"SurrealDB","url":"https://surrealdb.com/surrealdb"},{"@type":"SoftwareApplication","name":"Agent Memory","url":"https://surrealdb.com/agent-memory"}],"knowsAbout":["multi-model databases","document databases","graph databases","vector search","time-series databases","SurrealQL","Agent Memory","real-time databases","embedded databases","context layer","graph ontology","distributed database","knowledge graphs","distributed transaction protocols","highly-scalable databases"],"sameAs":["https://www.wikidata.org/wiki/Q124316308","https://github.com/surrealdb/surrealdb","https://twitter.com/surrealdb","https://www.youtube.com/@surrealdb","https://www.linkedin.com/company/surrealdb","https://discord.gg/surrealdb","https://www.reddit.com/r/surrealdb","https://www.instagram.com/surrealdb","https://medium.com/surrealdb","https://dev.to/surrealdb"]}
```

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://surrealdb.com"},{"@type":"ListItem","position":2,"name":"SurrealDB","item":"https://surrealdb.com/surrealdb"},{"@type":"ListItem","position":3,"name":"Deep dive","item":"https://surrealdb.com/surrealdb/deep-dive"}]}
```

```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"What is SurrealDB? An engineering deep dive","description":"Technical breakdown of SurrealDB's architecture, storage engine, query language, and use cases for modern apps and AI workloads.","about":"SurrealDB architecture, storage engine, and SurrealQL","mainEntityOfPage":"https://surrealdb.com/surrealdb/deep-dive","author":{"@type":"Organization","name":"SurrealDB","url":"https://surrealdb.com"},"publisher":{"@type":"Organization","name":"SurrealDB","url":"https://surrealdb.com"}}
```

```json
{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"If SurrealDB does everything, is it good at anything?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Why SurrealDB over Postgres?","acceptedAnswer":{"@type":"Answer","text":"For a purely relational workload Postgres is excellent. The comparison changes once pgvector, recursive CTEs, Elasticsearch, Redis and an auth service join it, each with its own consistency model. SurrealDB is one engine for all of it: record links in place of foreign-key joins, edges as full documents, row-level permissions and live queries built in, and compute scaled apart from storage."}},{"@type":"Question","name":"Is SurrealDB a fork or a wrapper?","acceptedAnswer":{"@type":"Answer","text":"Neither. The query engine, storage engines, transaction coordinator, permission system and real-time layer are written from scratch in Rust. A query that combines graph traversal, vector similarity and structured filters runs in SurrealDB's own planner."}},{"@type":"Question","name":"Why Rust?","acceptedAnswer":{"@type":"Answer","text":"A database wants deterministic memory, predictable latency and safe concurrency. Rust's ownership model gives all three without a garbage collector, so there are no collection pauses during a query and no managed runtime between the engine and the machine."}},{"@type":"Question","name":"Is SurrealDB production-ready?","acceptedAnswer":{"@type":"Answer","text":"The 3.x line is generally available and shipping patch releases, and runs in production at organisations including Nvidia, Samsung, Tencent, Verizon, Walmart and ING. SurrealDB Cloud adds managed deployment, enterprise support, SLAs and SOC 2 / ISO 27001 compliance."}},{"@type":"Question","name":"Which object storage providers are supported?","acceptedAnswer":{"@type":"Answer","text":"Amazon S3 and any S3-compatible store; the endpoint is configurable, so self-hosted and third-party providers work too. The data stays in commodity object storage, portable rather than tied to a proprietary storage tier."}},{"@type":"Question","name":"How does scale-to-zero work?","acceptedAnswer":{"@type":"Answer","text":"Compute is stateless, so when nothing is running the compute nodes shut down and the data persists in object storage. On demand a new node restores from storage and replays the recent transaction log. Cold-start time follows the size of that log, not of the dataset."}}]}
```