SurrealDB overview: a multi-model database for modern applications

SurrealDB overview: what is unified data storage?#

SurrealDB is a multi-model database that stores documents, graphs, vectors, time-series, and relational data in one ACID-compliant engine, queryable in a single transaction. SurrealDB's own docs put it this way in October 2026: "One engine stores documents, graphs, vectors, text, time series, geospatial values and relational tables." So the product page sums it up as one database for every data model.

Most products hold more than one shape of data. For example, a catalogue is a set of documents, its suggestions are a graph, its search runs on vectors, and its billing is a table. So the usual answer is one store per shape, with sync jobs between them. As a result, each store needs its own setup, its own backups and its own pool of connections. Meanwhile, a change in one store can take seconds or minutes to reach the next, so the sync job becomes the most fragile part of the system.

Independent research names that cost. The M2 paper on arXiv, from Seoul National University in August 2025, calls this setup polyglot persistence. It says the coordinator between stores "suffers from high communication costs due to its physically disaggregated architecture," which is the sync tax in plain terms. A March 2026 arXiv paper on cross-model analytics states the other side. Multi-model databases hold several models in one system, "natively eliminating data movement overhead."

SurrealDB's what is SurrealDB page names seven models in one engine: document, graph, vector, full-text, time series, geospatial and relational. The models share one storage layer. So, per the docs, "a write that touches a record, its relations and its embeddings commits together," with no second store involved. In practice, that removes the sync job, since there is nothing left to copy between stores. In short, this SurrealDB overview is about one trade: fewer moving parts in exchange for betting on one engine.

What changed in SurrealDB 4?#

SurrealDB 4.0.0, released on 3 November 2026, replaces several query planners with one executor, runs PostgreSQL and MySQL SQL over the same tables and makes SurrealKV its one on-disk engine. For anyone who read an earlier SurrealDB overview, four changes bear on requests that mix data shapes. The 3.x line before it added DiskANN, a vector index for data too big for memory, and a first Postgres listener that still spoke SurrealQL.

• One executor. The 4.0 release notes say the old planners meant "the same query could give different answers depending on which one ran it." Now one executor compiles each statement.
• SQL over the same tables. PostgreSQL and MySQL clients connect over their own protocols and run a defined subset of SQL. SurrealQL, the native query language, reads the same records.
• One storage engine. SurrealKV, SurrealDB's own on-disk engine, now runs on a server, in an embedded SDK (a client library) and in the browser. The older RocksDB and IndexedDB engines are gone.
• Two new ways to scale. SurrealDS 1.0, on Enterprise Edition, keeps the data in object storage. SurrealDB Earth is a serverless option built on Cloudflare.

SurrealDB's own benchmarks page, read on 4 November 2026, reports that 4.x cut tail latency, the slowest one percent of requests, against 3.x, including on CRUD (create, read, update and delete) work. These are the vendor's figures on its own test rig, not an independent measurement. The page prints no full-table figure for this comparison, and its indexed figure is projected.

Upgrading has real limits. Version 4.0.0 was one day old on 4 November 2026, so your own test matters more than any launch claim. The 3.x to 4.0 upgrade guide says "Test the upgrade on a copy of the data first, because the upgrade described below is one-way." A 4.0 node refuses a 3.x datastore until you opt in with SURREAL_EXPERIMENTAL_UPGRADE_FROM_3X=true. So take and verify a surreal export before that first start.

The same guide adds a short list. Upgrade every SDK before the server, and leave room on the disk for a second copy of the data. On a datastore several nodes share, move every node to the latest 3.3 release first. Remove any SurrealML models on 3.x, because a datastore holding one does not start on 4.0. Afterwards, rebuild your vector indexes, both HNSW (a graph of nearby vectors) and DiskANN. The guide warns: "Some indexes give wrong results or answer more slowly until they are rebuilt." Also add ORDER BY wherever order matters, because rows without it can arrive in any order. The launch page promises "every 3.x record still readable." That holds only beside the one-way path and the indexes to rebuild.

How can you query multiple data models in one transaction?#

One query joins documents, traverses edges, searches vectors and scans events, all in one transaction. SurrealQL, the query language, "keeps the shape of SQL and adds the traversals, similarity functions and nested access the other models need," per SurrealDB's docs in October 2026.

First, the arrow is the graph part. For instance, ->likes->friend.name walks from a record along its likes edges and returns the names at the far end. Second, the vector part is the KNN (k nearest neighbours) operator, <|k,ef|>. It finds the k nearest embeddings through an HNSW index (a graph of nearby vectors) or a DiskANN one. Then both sit in one SELECT beside ordinary WHERE filters. So the graph walk, the vector match and the document fields come back on the same row.

The filter makes the mix cheaper. SurrealDB's similarity search guide, read on 4 November 2026, says the condition applies during the HNSW or DiskANN search. As a result, "the search does not spend its slots on records that would only be filtered out afterwards." So a filtered search returns up to k matching rows instead of fetching extra and throwing most away.

One engine has to carry every shape, so its speed matters. SurrealDB's own benchmarks page, read on 4 November 2026, reports mixed CRUD throughput for each major line. Those numbers come from the vendor's own benchmark, not from an independent lab.

One transaction still has an isolation level to choose. Per the 4.0 release notes, snapshot isolation is the default. It "lets two transactions each read something the other is about to change." Instead, BEGIN ISOLATION LEVEL SERIALIZABLE asks for the stronger guarantee, but only some engines give it. The notes say "The in-memory engine and SurrealDS offer the level, while SurrealKV refuses it outright." So a single SurrealKV server stays on snapshot isolation.

There is also a safe read-then-write. Per SurrealDB's SELECT reference, read on 4 November 2026, FOR UPDATE registers each selected record for conflict checks at commit, and its target is a record id such as account:one. A transaction then fails to commit if another one changed that record first. The same page says "The clause takes no lock," so plan for retries rather than waiting.

What deployment options does SurrealDB support?#

You can run SurrealDB embedded in your application, in a browser through WebAssembly, as a single server or as a distributed cluster, with the same queries in each. SurrealDB's deployment guide was read on 4 November 2026, and it says "The same SurrealQL, APIs, and client SDKs work across embedded devices, single-node servers, distributed clusters, and managed instances."

That matters for a mixed-shape product, because the query you prove on a laptop is the query you run in production. Embedded mode runs inside your process, so no network hop sits between app and data. In the browser, the same SurrealKV engine keeps its data in the Origin Private File System, a private storage area each site gets. For one server, surreal start --user root --pass secret surrealkv://data is the whole setup, and SurrealKV is the only on-disk engine. SurrealDB Earth adds a serverless route, where each database starts on its first query.

SurrealDB Earth is the Cloudflare route, for traffic that comes and goes. Its documentation, read on 4 November 2026, recommends it when a database sits idle for long periods or clients connect from many locations. SurrealDB's launch page reports a cold start of about 300 ms, its own figure rather than an independent test. While compute runs close to each client, "the data of an instance is kept in Cloudflare object storage in one location." So the distance to the data does not disappear. Our guide to what belongs at the edge shows how to count those trips for a route. Also, check the feature list. Change feeds, DiskANN indexes, JavaScript functions and outbound calls such as http::get() are "not available on Earth" yet, and the docs plan them for a future release.

The one SurrealDB deployment choice that changes behaviour is single node versus cluster. The guide lists Community Edition for a single node. Then, for a cluster you run yourself, it points to SurrealDS in SurrealDB Enterprise. For a managed one, it points to the Scale plan on SurrealDB Cloud. Also, the upgrade guide says TiKV, a distributed key-value store, now needs the separate surreal-tikv build. However, some features differ on a cluster, as the next section shows. In practice, start with one SurrealKV server and add a cluster only when one machine going down would stop the product. The guide says you can "change how the database runs without rewriting application code." Your queries stay the same, but your data still has to move. So plan that move as a migration.

When is SurrealDB the wrong tool for the job?#

SurrealDB is the wrong tool when your data is purely relational, or when your reporting tools generate SQL that its PostgreSQL and MySQL dialects refuse. In those cases a dedicated database serves you better, and saying so early saves a painful migration later.

First, take a workload where one shape dominates. If your data is mostly tables with some JSON and some embeddings, PostgreSQL already covers a lot. The PostgreSQL 18 JSON docs, read on 30 October 2026, cover GIN indexes. That is the inverted index Postgres uses for jsonb, its binary JSON column. These "can be used to efficiently search for keys or key/value pairs occurring within a large number of jsonb documents," a document store inside SQL. The pgvector README, read the same day, adds vectors under the line "Store your vectors with the rest of your data." As a result, one Postgres can hold tables, documents and vectors, with a far larger tooling and hiring pool. Our guide to MySQL performance bottlenecks covers where a single-shape SQL database still shines.

Second, consider heavy analytics and reporting. From 4.0, PostgreSQL clients and object-relational mappers (ORMs) run a defined subset of SQL, so the limit is what that subset refuses. SurrealDB's Postgres protocol docs, read on 4 November 2026, are blunt. "Recursive common table expressions and FULL OUTER JOIN are refused," they say. They also refuse INTERSECT ALL, EXCEPT ALL and UPDATE ... FROM, and CREATE FUNCTION fails to parse. Meanwhile, the 4.0 release notes say "Joins, subqueries and window functions give the answers PostgreSQL and MySQL would." So if a business intelligence (BI) tool must send its own SQL, run what it generates before you commit. If it gets refused, keep a SQL copy for reporting. The same 2025 Seoul National University paper left SurrealDB out of its tests, "omitted due to limited support for join operations." However, that paper predates 4.0, so it tells you nothing about the new dialects either way.

Third, check real-time needs across a cluster. SurrealDB's LIVE SELECT reference, read on 4 November 2026, says that in Community "a live query only receives changes made on the node that holds its subscription." Live queries that receive changes from every node are part of Enterprise Edition. Therefore, a system that needs change streams across nodes should plan on Enterprise or a message queue. In short, this SurrealDB overview and when to use SurrealDB come down to one test: does one request need several data shapes at once?

What real-world patterns benefit from multi-model queries?#

SurrealDB unifies embeddings, documents, events and links in AI search and access control patterns. The common thread is one request that needs more than one shape of data at the same instant.

Take an AI-powered CRM, a customer relationship management system. Here, customers are documents with an embedding for similarity search. Accounts link through graph edges for partners and parent firms. Each email or call is a timestamped event. So one query can find customers like a target, walk their partner edges and count recent events, all from one snapshot. With four stores, that same request makes four calls and joins them in app code.

AI retrieval is the second pattern. SurrealDB's docs list vector similarity for meaning, full-text BM25 scoring for wording, graph traversal for connection, and hybrid search that fuses text and vector results. A filter such as "only this tenant" applies during the vector search, so each tenant gets its own k results.

SurrealDB's own launch page for version 4, read on 4 November 2026, reports the vector side of that request. A 1% filtered vector search went from 27 ms to 1.1 ms. It is the vendor's own measurement, not an independent test.

Access control is the third pattern. DEFINE ACCESS ... CONTEXT, added in 3.3, computes a value once at sign-in and exposes it as $session.data, per the 3.3 release notes. Then a row rule such as WHERE org IN $session.data no longer runs a subquery for every row, so the permission check rides along with the same query.

How do you start migrating from separate databases to SurrealDB?#

Start with what SurrealDB is, then the SELECT and LIVE SELECT references, then the similarity search guide, and read the upgrade guide before moving a datastore to 4.0. These official pages, in build order, cover the first working schema:

Then move one workload, not the whole estate. For example, pick the query that today calls the most stores, model its records, edges and embeddings, and write it as one SurrealQL query. After that, run the old path and the new one on the same test data and compare the rows. Once they match, move the next query. Because each port is one small step, a mistake shows up early and stays small. Also, an existing Postgres or MySQL client can point at the same tables during the move. However, those connections run SQL only. The Postgres docs say "SurrealQL is not available over this protocol from 4.0," so SurrealQL still goes over HTTP, a remote procedure call (RPC) or an SDK.

What operational benefits does consolidation on one database bring?#

One database can replace four: less to run, simpler backup, one observability plane. Each store you remove takes its setup, alerts, backup plan and runbook with it.

Backups are the clearest win. As an illustration, with four stores, a restore means four snapshots taken at four slightly different times, then repair work to make them agree. However, with one engine, one snapshot holds documents, edges and vectors from the same commit. So you restore one backup and rehearse one restore plan.

Connections shrink the same way. In short, one pool replaces four, one set of credentials replaces four, and one firewall rule replaces four. The 3.1 release notes say observability "is now a single OpenTelemetry pipeline," the open standard for metrics, logs and traces, so one dashboard can watch the whole data layer.

The trade is that one engine now carries every workload, so a slow release hurts every shape at once. SurrealDB's own benchmarks page, read on 4 November 2026, reports the 3.x to 4.x gains below. They are the vendor's benchmark, so treat them as a claim to test on your own data.

How does a multi-model query in SurrealDB replace separate single-model queries?#

One short script starts an in-memory server, creates two records with embeddings, relates them with an edge and runs a graph and vector query together. First, start a local server with the in-memory engine, as the install page shows:

surreal start --user root --pass secret memory

We ran this script on SurrealDB 4.0.0 on 4 November 2026. In a second terminal, open the surreal sql shell with the connection flags the install page prints, but change http:// to ws://, because a live query needs a WebSocket connection. Over HTTP the LIVE SELECT fails with "Unable to perform the realtime query". Keep each statement on a single line, because piped input is read line by line:

-- 1. A vector index on the customer embeddings
DEFINE INDEX hnsw_customer ON customer FIELDS embedding HNSW DIMENSION 4;

-- 2. Two customers, each a document with an embedding
CREATE customer:alice SET name = 'Alice Corp', embedding = [0.1, 0.2, 0.3, 0.4];
CREATE customer:bob SET name = 'Bob Ltd', embedding = [0.2, 0.1, 0.4, 0.3];

-- 3. A graph edge between them
RELATE customer:alice->partner_of->customer:bob;

-- 4. The nearest customers to a query vector, with each one's partners
LET $query = [0.15, 0.25, 0.35, 0.45];
SELECT name, ->partner_of->customer.name AS partners, vector::distance::knn() AS distance FROM customer WHERE embedding <|2,40|> $query ORDER BY distance;

-- 5. Push every later change to this client
LIVE SELECT * FROM customer;

The first statement builds the HNSW index, a graph of nearby vectors that answers "what is close to this?" quickly. Then the two CREATE lines store two documents. Next, RELATE adds an edge record called partner_of, which can carry its own fields. So the SELECT is the multi-model part: the KNN operator picks the two nearest customers, the arrow walks their partner edges, and vector::distance::knn() returns the distance the search already computed. Finally, LIVE SELECT opens a live query, so new or changed customers stream to the client.

With separate stores, the same answer takes a vector query, a document fetch and a graph lookup, joined in app code. Each call can fail or return data from a different moment. Instead, one statement here reads one snapshot.

What are your next steps for building with SurrealDB?#

Explore API design, system architecture choices and database tuning strategies. Each of these guides picks up a part of the mixed-shape question where this SurrealDB overview stops.

Microservices vs monolith weighs one store per service against a shared one, the same trade at the architecture level. Why RAG fails in production covers the retrieval side, where vectors meet documents in one request. API types and architectures covers the layer that sends those requests.

If you want help designing a first SurrealDB schema, our build and launch team works on new systems. If a SurrealDB app is already live and slowing down, scale and optimise covers query and schema tuning.

Still, you may need neither. The SurrealDB documentation is enough on its own to build with.