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, 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 text and 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, and the sync job becomes the most fragile part of the system.

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 the docs say "a write that touches a record, its relations and its embeddings commits together." In practice, that removes the sync job, since there is nothing left to copy between stores. It also means every read in a transaction sees the same moment in time. In short, this SurrealDB overview is about one trade: fewer moving parts in exchange for betting on one engine.

What changed in SurrealDB 3.1, 3.2 and 3.3?#

SurrealDB 3.1 added an MCP server and DiskANN, 3.2 added ISO GQL, and 3.3 added a Postgres wire listener, streamed results and bitmap-combined indexes. For anyone who read an earlier SurrealDB overview, the core idea holds, and each minor release upgraded in place from the one before it.

• 3.1, released 14 May 2026. The 3.1 release notes add a first-party MCP server, the Model Context Protocol that lets AI agents call tools, with twelve typed tools. They also add DiskANN, a vector index for data too big for memory.

• 3.2, released 1 July 2026. The 3.2 release notes add ISO GQL, the standard graph query language, behind an experimental flag. They also enforce a typed id field at write time.

• 3.3, released 24 September 2026. The 3.3 release notes say it "lets any Postgres client query SurrealDB", streams results row by row, and combines indexes as bitmaps. It also adds SELECT ... FOR UPDATE, turns GQL on by default, and lets file buckets live in S3, Google Cloud Storage or Azure.

The 3.x line also cut tail latency, the slowest one percent of requests, in every workload class.

Upgrading has one sharp edge. The 3.2 to 3.3 upgrade guide says the first 3.3.0 node applies data migrations on its own. However, it also says "3.2 cannot read a datastore correctly once 3.3.0 has started against it." So take and verify a surreal export first.

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 operator, <|k,ef|>, which finds the k nearest embeddings through an HNSW or DiskANN index. 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.

SurrealDB 3.3 made the mix cheaper. Its release notes say that WHERE conditions covered by an index "become an allow-list before the HNSW or DiskANN search runs." So a filtered similarity search returns k matching rows instead of fetching extra and throwing most away.

Version 3.3 also added a safe read-then-write. Per SurrealDB's SELECT reference, FOR UPDATE registers each read record for conflict checks, so a transaction fails to commit if another one changed that record first. The same page notes that "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 in October 2026. It says "the same SurrealQL, APIs, and client SDKs work across embedded devices, single-node servers, distributed clusters, and managed instances."

For a SurrealDB deployment, the guide lists four storage choices:

• In memory (SurrealMX). The default since 3.0, suited to tests and to cache-like data, with optional snapshots.
• RocksDB. An on-disk key-value engine, and the guide's recommendation for production servers.
• SurrealKV. SurrealDB's own disk engine, still beta, aimed at embedded and local-first apps.
• IndexedDB. The browser's own storage, used by the WebAssembly build for offline web apps.

Embedded mode runs inside your process, so no network hop sits between app and data. Also, the guide lists embedded support in Rust, Go, JavaScript, TypeScript, WebAssembly, Python and .NET. For one server, surreal start rocksdb://path is the whole setup.

For high availability, the cluster mode runs on a distributed storage layer that handles replication and consensus. Self-hosted clusters on Kubernetes use SurrealDB Enterprise, which 3.3 now publishes as a public Docker Hub image that still needs a licence key. Per the 3.3 release notes, each node checks its licence every 30 minutes and keeps serving for 24 hours if the licence service is unreachable. Alternatively, SurrealDB's managed instances run clusters on the Scale plan, with a minimum of three compute units.

In practice, use the memory engine for tests and RocksDB for a first production server. Add a cluster only when one machine going down would stop the product. Because the queries stay the same, that move is a config change, not a rewrite. That is the deployment point of this SurrealDB overview.

When is SurrealDB the wrong tool for the job?#

SurrealDB is the wrong tool when your data is purely relational or your reporting tools need ANSI SQL, which its new Postgres listener still does not speak. In those cases a dedicated database serves you better, and saying so early saves a painful migration later.

First, take a purely relational workload. If your data is tables, joins and reports, with no graph walks or vector search, a mature SQL database is the better fit. Because it has decades of tuning, it also has more tooling and a wider hiring pool. Our guide to MySQL performance bottlenecks covers where a single-shape SQL database still shines.

Second, consider your reporting tools. SurrealDB's Postgres protocol docs are blunt: "ANSI SQL is not yet supported over the Postgres wire protocol." Instead, the listener accepts SurrealQL or GQL, not plain SQL. The same page lists catalogue emulation as not yet built, which some GUI clients need to connect. So if a BI tool must send standard SQL, keep a SQL copy for reporting.

Third, check real-time needs across a cluster. SurrealDB's LIVE SELECT reference is clear. Live queries are "only supported in single-node deployments." Therefore, a multi-node system that needs change streams should plan on a message queue for now. In short, when to use SurrealDB comes 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, analytics dashboards 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.

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. Since 3.3, a filter such as "only this tenant" applies before the vector search, so each tenant gets its own k results. Also, 3.3 stores graph edges in compact blocks, and its release notes say traversals over busy records "run substantially faster" as a result. The same notes put indexed full-text writes at 2.3 to 2.6 times faster.

Access control is the third. In 3.3, DEFINE ACCESS ... CONTEXT 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. Meanwhile, live queries push changes to a dashboard on a single node, so the screen updates without polling.

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 3.3. These official pages, in build order, cover the first working schema:

The six pages: What is SurrealDB, SELECT statement, LIVE SELECT statement, Similarity search guide, Postgres wire protocol, Upgrade from 3.2 to 3.3.

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, since 3.3 accepts Postgres clients, psql, the Postgres command-line shell, works as a quick console during the move.

What operational benefits does consolidation on one database bring?#

One database replaces 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. Today, 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. Since 3.1, metrics flow through one OpenTelemetry pipeline, the open standard for metrics, logs and traces, so one dashboard watches the whole data layer. Also, since 3.2 a /ready probe tells Kubernetes when a node can take traffic. Then 3.3 enforces --query-timeout on HTTP and RPC calls too, so a runaway query stops at the limit you set.

Speed matters too, because one engine must carry every workload. SurrealDB's benchmarks page, read in October 2026, reports the 2.x to 3.x gains below.

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 deployment docs show:

surreal start --user root --pass secret memory

Then run these statements in the surreal sql shell or any SurrealDB client:

-- 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 where this SurrealDB overview stops.

API types and architectures covers REST, GraphQL and RPC, the layers SurrealDB can now serve directly. 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 filtered vector search now helps. MySQL performance bottlenecks covers the relational baseline.

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 and the release notes are enough on their own to build and upgrade with.