DEV Community: SurrealDB

Using SurrealDB to understand how Buffalo buffalo buffalo Buffalo buffalo

Dave MacLeod — Thu, 09 Jul 2026 13:54:06 +0000

Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

That's technically a valid English sentence, one of the ones that has its own Wikipedia article to explain just how it works. What makes it work is that the word buffalo is also a (rarely used) verb to mean to bully or to fool someone. Here's an example of the verb in practice:

"If nonfiction is where you do your best writing, or your best teaching of writing, don't be buffaloed into the idea that it's an inferior species."

The other thing that makes the sentence confusing is that the word buffalo can also be the plural of buffalo. Fortunately, you can also pluralise it with an s - which is what we will do in this post from here on.

With a bit of rewriting and notes in parentheses, the sentence makes a little more sense.

Buffaloes from Buffalo that buffaloes from Buffalo buffalo (trick) buffalo (trick) buffaloes from Buffalo.

If that still only makes just a bit of sense, don't worry - because we can demonstrate the situation using SurrealQL instead.

Buffaloes that buffalo Buffalo buffaloes

To start: if we have Buffalo buffalo, that means that there should also be non-Buffalo buffalo: buffalo that don't come from the city of Buffalo. Let's make 50 of each. Two following two CREATE statements will create them with a sequential ID starting from 1 and ending at 100.

CREATE |buffalo:1..=50| SET from = "Buffalo";
CREATE |buffalo:51..=100| SET from = "Somewhere else";

Now we need to get the buffaloes to interact with each other.

Since the original sentence is talking about how a buffalo can buffalo another buffalo, that must mean that this sometimes happens and sometimes does not. To demonstrate this, let's go through each buffalo, randomly choose a buffalo (with the rand::enum() function) that is not the buffalo in question (array::complement() will do that), and then use rand::bool() to give it a 50% chance of buffaloing that buffalo.

FOR $buffalo IN SELECT * FROM buffalo {
    // We could do this in a single line but let's go one step at a time
    LET $all_buffalo = SELECT VALUE id FROM buffalo;
    LET $except_this_one = $all_buffalo.complement([$buffalo.id]);
    LET $other_buffalo = rand::enum($except_this_one);
    // Now that we have another buffalo, we'll flip a coin
    // to see if it gets 'buffaloed'
    IF rand::bool() {
        RELATE $buffalo->buffaloes->$other_buffalo;
    };
};

With that set up, we can do a query to see which Buffalo buffaloes are buffaloing Buffalo buffaloes, and who they are. To do that, we can use a WHERE clause to ensure that the buffalo in question is from Buffalo, and that the path ->buffaloes->buffalo.from (the buffalo(es) that are getting buffaloed) contains the word "Buffalo".

SELECT 
    id, 
    from, 
    ->buffaloes->buffalo AS buffaloes
FROM buffalo 
WHERE 
    from = "Buffalo" 
AND 
    "Buffalo" IN ->buffaloes->buffalo.from;

Because half of the buffaloes are from Buffalo and half of these have buffaloed another buffalo, the output should show...about 25? Not quite, because some unlucky buffaloes have been buffaloed by more than one buffalo. We can demonstrate that by doing a reverse graph query on the buffaloes to see which ones they are being buffaloed by, followed by a filter to only retain the ones that have been buffaloed more than once.

(SELECT <-buffaloes<-buffalo AS buffaloed_by FROM buffalo)
    .filter(
        |$b| $b.buffaloed_by.len() > 1
    );

Buffaloing back

Now it's time for justice to be done. Because the original sentence can actually be read as a decree.

"No buffalo from Buffalo shall be buffaloed by a buffalo from Buffalo without the chance to buffalo back. Henceforth, any buffalo from Buffalo that Buffalo buffalo buffalo shall also buffalo a Buffalo buffalo."

Sounds fair.

To enact this decree, we will need to have every buffalo that is buffaloed by a buffalo from Buffalo now also buffalo another buffalo from Buffalo.

To start, we'll use much of the same query as above but turn it around. And this time we won't use rand::bool() because the buffalo from Buffalo in question that has been buffaloed now has a 100% chance of buffaloing another buffalo from Buffalo.

FOR $buffalo IN SELECT VALUE
    id
FROM buffalo 
WHERE 
    from = "Buffalo" 
AND 
    "Buffalo" IN <-buffaloes<-buffalo.from {
         LET $all_buffalo = SELECT VALUE id FROM buffalo;
         LET $except_this_one = $all_buffalo.complement([$buffalo.id]);
        LET $other_buffalo = rand::enum($except_this_one);
        RELATE $buffalo->buffaloes->$other_buffalo;
};

Visualising all the buffaloing

We can finish this off by visualising the data to see all of the buffaloing that is going on, whether actively (buffaloing a buffalo) or passively (being buffaloed by a buffalo). The following two queries will show who is buffaloing and who they are being buffaloed by, depending on whether they are from Buffalo or not.

SELECT 
    id, 
    buffaloes->buffalo AS buffaloes, 
    <-buffaloes<-buffalo AS buffaloed_by
FROM buffalo 
WHERE from = "Buffalo";

SELECT 
    id, 
    buffaloes->buffalo AS buffaloes,
    <-buffaloes<-buffalo AS buffaloed_by
FROM buffalo 
WHERE from != "Buffalo";

The raw output of these queries is easy enough to read, but it's tough to get a top-level idea of what is going on here.

[
    {
        buffaloed_by: [
            buffalo:76
        ],
        buffaloes: NONE,
        id: buffalo:3
    },
    {
        buffaloed_by: [
            buffalo:45,
            buffalo:18
        ],
        buffaloes: NONE,
        id: buffalo:4
    },
    {
        buffaloed_by: [],
        buffaloes: NONE,
        id: buffalo:5
    },
//...
]

This is where Surrealist's graph visualisation comes into play. To use it, just click on the "Combined" button next to the button used to run a query and change it to "Graph". As long as a query contains the id of each record, it will be able to visually show which records are connected to which other ones.

You can also click on "Stray edges" to display records that aren't connected, which is what we will do here.

The output will differ every time these queries are executed and every time this functionality is used to generate a visual output in Surrealist, but for the most part you will notice that there is a lot more going on between the buffaloes from Buffalo than those from somewhere else. That makes sense, because the second RELATE operation that we used was only for, and between, buffaloes from Buffalo.

The first query between buffaloes from Buffalo should look somewhat busy with connections between quite a few, and a number of stray edges floating around in the middle.

The second query is a bit less so, with fewer connections between these buffaloes and a lot more stray edges.

Learn more

Interested in learning more? Here are some more links and blog posts to get started.

And for another technically correct mind-bending sentence, check out the page on James while John had had had had had had had had had had had a better effect on the teacher.

Ready to try it?

Detecting connections as they form: An introduction to streaming graph pattern matching

Dave MacLeod — Thu, 09 Jul 2026 12:58:27 +0000

Detecting connections as they form: An introduction to streaming graph pattern matching

Originally published by Cyril Scetbon on 13 April, 2026

In my previous posts, I explored how SurrealDB blends document, graph, relational, and vector models into a single engine, and how you can combine it with Rig.rs to build LLM-native agents in Rust. I've written about SurrealDB more than once because I genuinely believe it's one of the most exciting databases out there right now — and the more I use it, the more I find myself reaching for it as the obvious foundation whenever I need something flexible, expressive, and Rust-native. Its graph capabilities — RELATE, record IDs, graph traversals — kept nagging at me with a question: what if you could continuously watch a graph as it grows and fire off actions the moment a meaningful pattern completes?

That question sent me down a rabbit hole. This post is the first in a series where I'll walk you through the concept, the configuration I'd want for such a tool, the actual implementation, and where things could go from there.

Let's start at the beginning. 🔍

🕸️ What is a labeled property graph?

If you've read my SurrealDB deep-dive, you already know that SurrealDB natively models data as a labeled property graph. But let's make it concrete for this series.

A labeled property graph has two building blocks:

Vertices — entities with a type and properties. Think person:clint_eastwood with a name field, or movie:unforgiven with a title and year.
Edges — directed, typed relationships between vertices. Think person:clint_eastwood -> acted_in -> movie:unforgiven.

Edges are first-class citizens: they have their own type (e.g., acted_in, directed) and can carry their own properties (e.g., the role a person played).

This model is perfect for representing the kind of messy, interconnected real-world data that relational tables struggle with — social networks, supply chains, knowledge graphs, movie databases.

If you want to get a feel for how expressive SurrealDB's query language gets when working with this kind of data, take a look at the idioms page in the docs. It's a compact showcase of what SurrealQL can do — and honestly, reading through it is a big part of what got me thinking about building this in the first place.

⚡ What is streaming graph pattern matching?

A graph pattern is a template describing a subgraph you care about. For example:

"Find any person who both acted in and directed the same movie."

In a static graph, you'd run a query once and get your results. But what if the graph is continuously growing? Edges arrive one by one as events stream in. You want to know the moment that pattern becomes complete — not minutes later, not after a full scan.

That's streaming graph pattern matching: detecting when a pattern is satisfied in real time, incrementally, as new edges are added.

The classic use cases are things like:

Fraud detection — flag the moment a money flow completes a suspicious cycle
Recommendation engines — create a "you might also like" edge the second two users share enough common favorites
Knowledge graph enrichment — derive new facts automatically as raw data arrives
Event correlation — detect that a sequence of system events matches a known failure signature

The challenge is doing this without re-scanning the entire graph every time a single edge lands.

🎬 A running example: the movie database

Throughout this series I'll use a movie dataset. It's a flat CSV file where each row is tagged with an Entity type:

Entity,tmdbId,movieId,name,Work,role
Person,190,,Clint Eastwood,,
Person,192,,Morgan Freeman,,
Movie,,33,Unforgiven,,
Join,190,33,,Acting,William Munny
Join,192,33,,Acting,Ned Logan
Join,190,33,,Directing,

A few things to note:

Person rows describe people.
Movie rows describe films.
Join rows describe relationships — acting roles, directing credits — linking people to movies.

This flat structure is typical of real-world export formats. The goal is to lift it into a proper graph and then continuously match patterns against it.

The pattern I want to detect: a person who both acted in and directed the same movie. Clint Eastwood fits. Morgan Freeman does not.

🗂️ Imagining the configuration

If I were to design a tool for this, I'd want the entire thing controlled by a single YAML configuration file. Two top-level sections: sources to describe how raw data becomes a graph, and patterns to express what I'm looking for in that graph. Let me walk through both in detail.

Sources — loading the graph

The sources section describes where your data comes from and how to turn each row into graph elements. Each source entry points to a file and defines a format block with two optional scripts: filter and load.

For the scripting language, I'd reach for VRL — Vector Remap Language — a safe, sandboxed expression language originally built for the Vector observability pipeline. It's expressive enough for real data wrangling, and it could be extended with a handful of custom functions to express graph operations directly.

Here's what a complete sources block would look like for the movie dataset:

sources:
  # --- Source 1: Load Person vertices ---
  - type: file
    path: $movie_file          # resolved at runtime via --variable movie_file=...
    format:
      filter: msg.Entity == "Person"   # only process rows where Entity is "Person"
      load: |
        .id = record_id!("person", [msg.tmdbId])   # build a typed record ID: person:190
        .name = msg.name
        + @                            # mark this object as a vertex to be created

  # --- Source 2: Load Movie vertices ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Movie"
      load: |
        .id = record_id!("movie", [msg.movieId])   # e.g. movie:33
        .title = msg.name
        + @

  # --- Source 3: Acting edges ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Join" && msg.Work == "Acting"
      load: |
        .id = record_id!("acted_in", [msg.tmdbId, msg.movieId, msg.role])
        .role = msg.role
        .person.id = record_id!("person", [msg.tmdbId])
        .movie.id  = record_id!("movie",  [msg.movieId])
        + @person->@->@movie    # create the edge; the root object becomes the edge record

  # --- Source 4: Directing edges ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Join" && msg.Work == "Directing"
      load: |
        .person.id = record_id!("person", [msg.tmdbId])
        .movie.id  = record_id!("movie",  [msg.movieId])
        + @person->directed->@movie    # anonymous edge — no edge record object

Let me unpack each key concept.

`filter` — Row-level gating

filter: msg.Entity == "Person"

This is a VRL boolean expression evaluated against each incoming row. If it returns false, the row is skipped entirely. The raw CSV row is available as msg. Multiple sources can read the same file with different filters — that's intentional. The file would be read once and fanned out to all matching sources in parallel.

`record_id!()` — Typed identifiers

.id = record_id!("person", [msg.tmdbId])
# Produces: person:190

This custom VRL function would build a SurrealDB-style record ID from a table name and a list of key components. If you pass multiple components, they're combined into a composite key. The result is a strongly typed identifier like person:190 or acted_in:[190, 33, "William Munny"]. This ensures that re-ingesting the same data is idempotent — the same row always produces the same ID.

`+ @` — Creating a vertex

.id = record_id!("person", [msg.tmdbId])
.name = msg.name
+ @          # "upsert me as a vertex"

The @ symbol refers to the current root object — the thing you've been building up with .field = value assignments. Prefixing it with + marks it for creation in the graph.

One important thing to be explicit about: nested objects are not pushed automatically. If your root object has a .person sub-object, doing + @ only persists the root — .person is ignored. To push a nested object as its own vertex, you have to say so explicitly with + @person. This keeps the behaviour predictable and avoids accidentally creating vertices you didn't intend.

You can also push multiple nested objects in the same script — + @movie, + @genre, and so on — each as a separate vertex, containing only its own fields.

`+ @from->edge->@to` — Creating an edge

.person.id = record_id!("person", [msg.tmdbId])
.movie.id  = record_id!("movie",  [msg.movieId])
+ @person->directed->@movie

This creates a directed edge between two vertices. The vertices themselves don't have to be created in the same source entry — they can come from a different one. What matters is that @person and @movie resolve to objects with a valid .id field at execution time.

Worth knowing: an edge can be written to the database even if the vertices it points to don't exist yet. The edge record is created regardless, but any pattern that tries to traverse it will come back empty until both endpoints are actually present. This is why source order doesn't have to be strict — edges landing before their vertices are harmless, they just won't produce matches until the graph is complete enough to satisfy the pattern.

If you want the edge itself to carry properties (like a role name), you use the root object as the edge record:

.id    = record_id!("acted_in", [msg.tmdbId, msg.movieId, msg.role])
.role  = msg.role
.person.id = record_id!("person", [msg.tmdbId])
.movie.id  = record_id!("movie",  [msg.movieId])
+ @person->@->@movie    # @ in the middle = "use the root object as the edge record"

Direction is explicit: -> means left-to-right, <- means right-to-left. You can chain them:

+ @movie<-acted_in<-@person->directed->@movie
# Two edges created from a single line

Patterns — Matching the graph

The patterns section is where things get interesting. Each pattern entry has a match field containing a small DSL that describes the subgraph you're looking for.

patterns:
  - match: |-
      /
        m:movie<-acted_in<-p:person->directed->m:movie
        + p->acted_and_directed->m
      / -> m as movieId, m.title as movie, p as personId, p.name as actor

Let me break this apart piece by piece.

Aliases and join conditions

m:movie<-acted_in<-p:person->directed->m:movie

m:movie means: match any vertex from the movie table and call it m.
p:person means: match any vertex from the person table and call it p.
The same alias used in multiple places means the same vertex. Here m appears on both sides — so the movie that p acted in must be the exact same movie that p directed. That's your join condition, expressed naturally.

This single-line form is just a convenience. You can spread the same pattern across multiple lines and the meaning is identical — each line describes one edge, and shared aliases still enforce the join. All three of these are equivalent:

p:person->acted_in->m:movie
p:person->directed->m:movie

m:movie<-acted_in<-p:person
m:movie<-directed<-p:person

m:movie<-acted_in<-p:person
p:person->directed->m:movie

Pick the direction that reads most naturally for the relationship you're describing. The engine doesn't care — it resolves the aliases and finds the join either way.

This is the heart of the pattern language. You describe structure; the engine figures out the join.

Actions — Deriving new edges

+ p->acted_and_directed->m

When the full pattern is satisfied, this line fires. It creates a new acted_and_directed edge between the matched p and m vertices.

Duplicate prevention is built into the ID scheme: the derived edge gets a composite record ID based on the two endpoint vertices — something like acted_and_directed:[person:190, movie:33]. That ID is always the same for the same pair, so re-triggering the match (say, because new edges arrived and the checker ran again) produces the exact same record rather than a second one. The operation is naturally idempotent.

Output projections

/ -> m as movieId, m.title as movie, p as personId, p.name as actor

After the closing /, you declare what gets emitted when a match is found. You can project full vertices (m as movieId) or individual fields (m.title as movie). Omit this section entirely and all matched aliases come back.

More pattern expressiveness

The DSL could support more than simple linear paths. A few things worth being able to express:

Multiple edge types — match either rated or disliked:

p:person->(rated, disliked)->m:movie

Wildcard edge — match any edge type between two vertices:

p1:person->?->p2:person

Edge filters — only match edges that satisfy a property condition:

p:person->directed[WHERE award = "Oscar"]->m:movie

Vertex filters — only match vertices satisfying a condition:

p:person[WHERE birth_date >= "2000-01-01"]->acted_in->m:movie

Multiple independent patterns in a single block — all must be satisfied for the action to fire:

/
  p:person->acted_in->m:movie
  p:person->directed->m:movie
  + p->acted_and_directed->m
/ -> m.title as movie, p.name as actor

🔄 What would it look like to run this?

At a high level, the tool would:

Read the configuration file and resolve any $variable placeholders passed on the command line.

Stream data from each source into the graph — filtering rows, transforming them into vertices and edges via the load scripts, and persisting everything to the database.

Watch the graph for pattern completions — as edges land, the tool continuously checks whether any of the declared patterns are now fully satisfied.

Fire actions and print results immediately — the moment a match is found, the + edges are created and the projected output is flushed to stdout right away, without waiting for ingestion to finish.

This last point matters: matches don't accumulate and print at the end. They appear as soon as they're found, interleaved with ongoing ingestion. If you're streaming a large dataset, you'd start seeing output long before the last row is processed.

For the movie example, as soon as both the acted_in and directed edges involving Clint Eastwood and Unforgiven are present, the pattern is satisfied and a line appears on stdout. Morgan Freeman only acted, so he never completes the pattern — no false match, no output for him.

The system is also tolerant of edges arriving out of order. If a directed edge lands before the corresponding acted_in edge exists yet, the check is retried automatically once the missing piece shows up. You don't have to pre-sort your data or reason about arrival order.

The key design intent is that you never have to write a query. You declare the shape of what you're looking for and let the tool figure out when it exists.

🧠 Why this configuration style?

A few deliberate design choices worth calling out:

One file per source, multiple sources per file. The same CSV can produce vertices, edges, and genre tags all at once — by duplicating the source entry with different filters. No preprocessing step required.
VRL for transformations. It's expressive enough to handle type coercions, array splits, conditional logic, and nested structures, while being safe and sandboxed. No need to invent yet another mini-language for data wrangling.
Aliases as join keys. Using the same alias name to enforce vertex identity across pattern lines is a small syntax choice that turns out to be remarkably readable. The pattern says what you mean.
Declarative actions. The + syntax for derived edges mirrors the + syntax in the load scripts. Once you understand one, you understand the other.
Idempotent by construction. Derived edges get a deterministic ID from their endpoints, so running the same match twice is harmless. No deduplication logic to write, no risk of polluting the graph with duplicate relationships.
Results stream, they don't batch. Output is flushed to stdout the moment a match is confirmed. You can pipe the output, process it downstream, or just watch it in a terminal — it behaves like any other streaming Unix tool.

👉 TL;DR

Streaming graph pattern matching is about detecting when a meaningful subgraph completes — incrementally, as edges arrive, without scanning the whole graph.

A YAML config maps raw data to graph elements via VRL, and a declarative DSL expresses the patterns you care about. When a pattern matches, derived edges are created automatically.

In the next post, I'll show you the actual implementation: the tech stack, how the pieces fit together under the hood, and what the database looks like once everything is loaded. Stay tuned. 🛠️

Introducing Scale: SurrealDB Cloud, built for high availability and scale

Mark Gyles — Thu, 02 Jul 2026 15:53:29 +0000

Author: Tobie Morgan Hitchcock

Today we're launching Scale, a new tier of SurrealDB Cloud built for the workloads you can't afford to have go down.

Our first tier, Start, was designed for building and shipping fast. Scale is designed for what happens next: production traffic, uptime commitments, and the kind of resilience your users never notice because there are always available nodes. It's the tier for teams running SurrealDB as the scalable context layer behind real applications and AI agents in production.

What you get with Scale

Scale is about one thing: keeping your database available and consistent under real-world conditions.

Highly-available, fault-tolerant clusters. Scale runs your database as a multi-node cluster designed to survive node and infrastructure failures without dropping writes or losing consistency. A single point of failure is no longer a single point of downtime.

Multiple availability-zone deployment. Your cluster is distributed across multiple availability zones, so even the loss of an entire zone doesn't take your database with it. Traffic keeps flowing while the cluster recovers in the background.

Horizontal scale. As demand grows, Scale grows with it. Add capacity by scaling out across nodes rather than being capped by the size of a single machine. Start with three nodes, and keep adding to scale your application or agent's needs.

See more information about SurrealDB Cloud Scale architecture here.

Built on SurrealDS

Scale is powered by SurrealDS, SurrealDB's distributed storage engine and the foundation that makes all of this possible.

SurrealDS is a new generation distributed storage architecture, rethought from first principles. Instead of coupling storage to compute on a single box or to a proprietary cloud tier, SurrealDS embeds consensus directly in SurrealDB nodes and separates the two layers cleanly. Here's what that architecture gives you.

Architecture overview

Compute and storage separation. Scale compute for QPS and storage for capacity independently, so you provision for the dimension that's actually under pressure.
No single leader. Each availability-zone node writes locally, writes scale horizontally, and transactions commit once a quorum acknowledges them.
Multi-write nodes. Every write node in the cluster can accept and coordinate transactions - there's no bottleneck routing all writes through one leader.
Reduced operational overhead. Consensus is embedded directly in SurrealDB nodes, eliminating external coordination services.
Fewer network dependencies. A single broadcast replaces multi-hop coordination, reducing latency.
Lower latency than leader-based replication. With no single leader and each AZ node writing locally, transactions avoid the extra round trips of traditional leader-based systems.

Future roadmap

Several SurrealDS capabilities are on the near-term roadmap and will land in the Scale tier as they ship:

Object-storage backed. Persist transactional data directly to commodity object storage - storage costs drop and capacity scales far beyond any single disk.
Cross-region replication. Data flows through object storage rather than between nodes, significantly reducing data-transfer costs while keeping regions in sync.
Instant recovery. A crashed node restores from object storage, with recovery time almost instant regardless of dataset size.
Instant branching. Clone a petabyte-scale database in seconds for development, testing, or experimentation.

Get started

If you're running SurrealDB in production, or getting ready to, Scale gives you the availability and fault-tolerance your workloads need, on the storage architecture no one else has.

Explore the tier in SurrealDB Cloud, and dig into the engine underneath at SurrealDS.

Bring SurrealDB to your Replit Agent

itsezc — Thu, 02 Jul 2026 15:23:55 +0000

Replit Agent turns a prompt into a working app. SurrealDB is the one database behind that app, covering documents, graph, vectors, and SQL in a single engine. The piece that connects them is the Model Context Protocol (MCP).

Every SurrealDB instance running 3.1 or later can expose a first-party MCP server: a typed tool surface that AI agents call to inspect your schema and run queries safely. Replit Agent supports any MCP server as a connector, and adds them with a single click. Put the two together and Replit can build directly from the data you already have in SurrealDB.

This is vibe coding for teams that already own their data. Instead of letting an agentic coding tool improvise a throwaway backend, you point Replit at SurrealDB and build on a database you already trust, with the agent reading your real schema as it goes.

This guide is a hands-on quickstart. By the end you will have SurrealDB 3.1 running with its MCP server enabled, connected to a Replit project, and you will have prompted Replit Agent to generate a real interface on top of your data.

What you'll need

You need a few things before you start, and none of them take more than a few minutes to set up.

You need SurrealDB 3.1.0 or later. You also need a way to reach your instance from the internet, because Replit's connectors talk to your MCP server over HTTP and the server needs a public URL. A SurrealDB Cloud instance gives you one out of the box; for a local instance you can use a tunnel, which we cover below. You need a Replit account. Finally, you need some data. Even a handful of records is enough to see the workflow end to end, and we create a small schema below so you have something to build against.

It is worth noting how this differs from Replit's built-in database. Replit Agent provisions a managed Postgres instance for the app it builds, which it owns. With SurrealDB over MCP, you own the database. Replit connects to a SurrealDB instance you already run, reads its schema as context, and can query or mutate it through a typed, permissioned tool surface. This is the right pattern when SurrealDB is your system of record and you want to build interfaces on top of it rather than spin up a new backend.

How SurrealDB, MCP, and Replit fit together

There are three moving parts to understand before the steps.

SurrealDB 3.1 exposes a typed tool surface for AI agents. Rather than handing an agent a raw SQL console, the MCP server presents twelve defined tools: query, select, create, insert, upsert, update, delete, relate, info, list, use, and run. Each tool carries annotations (read_only_hint, destructive_hint, idempotent_hint) so an MCP client like Replit knows which operations are safe and which mutate data. The server also publishes self-describing schema resources at URIs like surrealdb://schema/ns/{ns}/db/{db}/table/{table}, so the agent discovers your tables and fields instead of guessing.

You can run that MCP server two ways. Locally, surreal mcp runs as a stdio subcommand, which suits IDE integrations on your own machine. For a remote client like Replit, the server is exposed over HTTP at /mcp, sitting behind SurrealDB's existing authentication middleware. We use the HTTP path here, because Replit needs to reach your server over the network.

Replit Agent treats MCP servers as connectors. Replit ships a curated list of MCP servers that install in one click, and lets you add any other server, including your SurrealDB instance, from the Integrations pane. All MCP traffic passes through Replit's security scanner, which inspects tool definitions and planned executions and blocks anything it judges unsafe before it runs. Once your SurrealDB endpoint is connected, the agent pulls your live schema and data into context while it builds.

Step 1: Install or upgrade to SurrealDB 3.1

If you are already on a 3.1.x release you can skip ahead. Otherwise, pick whichever install path matches your setup. Each pins to a specific version; drop the --version flag to always get the newest stable.

macOS (Homebrew), then upgrade in place:

surreal upgrade --version 3.1.5

Linux and macOS install script, which auto-detects your architecture:

curl -sSf https://install.surrealdb.com | sh -s -- --version 3.1.5

Windows (PowerShell), then upgrade in place:

surreal upgrade --version 3.1.5

Docker, to pull and run the exact image:

docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:v3.1.5 start

The surreal upgrade command can swap any existing install, whether Homebrew, install script, or manual binary, to the version you specify. Patch releases on the 3.1 line are drop-in upgrades.

If you are on SurrealDB Cloud, you can upgrade your instance in place from the Surrealist app, and you already have a public HTTPS endpoint, which makes the networking in Step 4 considerably simpler.

Verify your version:

surreal version

Step 2: Start your instance and create some data

For a local run, start a server with authentication enabled. The MCP HTTP endpoint sits behind the same auth middleware as the rest of SurrealDB, so credentials matter here.

surreal start \
  --user root --pass pass \
  rocksdb://mydata.db

This starts SurrealDB on http://localhost:8000 with a persistent RocksDB store and a root user. In production you would scope down to a namespace and database user rather than root, which we cover under permissions later.

Now give Replit something to build against. Use the CLI's surreal sql command to open a session, or use Surrealist, the visual query tool, and define a small schema. We model a simple product catalog with reviews, which is enough to show off SurrealDB's record links.

-- Pick a namespace and database to work in
USE NS shop DB catalog;

-- A products table
DEFINE TABLE product SCHEMAFULL;
DEFINE FIELD name        ON product TYPE string;
DEFINE FIELD price       ON product TYPE number;
DEFINE FIELD in_stock    ON product TYPE bool DEFAULT true;
DEFINE FIELD created_at  ON product TYPE datetime DEFAULT time::now();

-- A reviews table that links back to a product
DEFINE TABLE review SCHEMAFULL;
DEFINE FIELD product ON review TYPE record<product> REFERENCE;
DEFINE FIELD rating  ON review TYPE int ASSERT $value IN 0..=5;
DEFINE FIELD body    ON review TYPE string;

-- Seed a few records
CREATE product SET name = "Aeropress", price = 39.95;
CREATE product SET name = "Gooseneck Kettle", price = 64.00;
CREATE product SET name = "Burr Grinder", price = 129.00, in_stock = false;

A SCHEMAFULL table means SurrealDB enforces the field definitions, which is what you want when an AI agent is going to read and write the table. The schema becomes the contract the agent builds against. Because SurrealDB publishes that schema as an MCP resource, Replit reads these field types directly rather than inferring them from sample rows.

Step 3: Enable the MCP server over HTTP

In 3.1, the MCP HTTP surface is served at /mcp on the same port as the rest of the HTTP API, behind authentication. A handful of environment variables let you tune its limits. The defaults are sensible, but it is worth knowing they exist:

SURREAL_HTTP_MAX_MCP_BODY_SIZE: maximum request body size (default 4 MiB)
SURREAL_MCP_QUERY_TIMEOUT_SECS: per-query timeout (default 60 s)
SURREAL_MCP_MAX_RESULT_BYTES: maximum result payload (default 256 KiB)
SURREAL_MCP_RUN_MAX_ARGS: maximum arguments to the run tool (default 64)
SURREAL_MCP_PARAMS_MAX_KEYS: maximum bound parameters per call (default 256)

For example, to allow larger result payloads while keeping a tight query timeout:

SURREAL_MCP_MAX_RESULT_BYTES=1048576 \
SURREAL_MCP_QUERY_TIMEOUT_SECS=30 \
surreal start --user root --pass pass rocksdb://mydata.db

For PowerShell users on Windows:

$env:SURREAL_MCP_MAX_RESULT_BYTES = "1048576"
$env:SURREAL_MCP_QUERY_TIMEOUT_SECS = "30"
surreal start --user root --pass pass rocksdb://mydata.db

If instead you want to wire SurrealDB into a local IDE rather than Replit, run the stdio variant, surreal mcp, and point your editor's MCP client at that subcommand. For Replit, stick with the HTTP endpoint.

A good sanity check before involving Replit is to confirm the /mcp route is reachable and that requests without valid credentials are rejected, which tells you the auth middleware is doing its job.

Step 4: Make your instance reachable

Replit runs in the cloud, so it needs a public URL for your MCP endpoint. You have two clean options.

Option 1: SurrealDB Cloud. If your data lives in a SurrealDB Cloud instance, you already have a public HTTPS endpoint with managed TLS and authentication. Your MCP URL is simply that instance's address with the /mcp path appended. This is the lowest-friction path and the one we recommend for anything beyond local experimentation.

Option 2: A tunnel to a local instance. For local development, expose http://localhost:8000 through a tunneling service that gives you a temporary public HTTPS URL, such as ngrok or Cloudflare Tunnel. Your MCP URL is then https://<tunnel-host>/mcp. This works well for trying things out, but treat the URL as ephemeral and never point it at production data.

Either way, you end up with a single value to hand to Replit: an HTTPS URL ending in /mcp, plus the credentials needed to authenticate against it.

Security note: The MCP endpoint inherits SurrealDB's authentication and permissions. Before you expose anything, create a dedicated database user scoped to just the namespace and database you want Replit to touch, rather than handing over root. SurrealDB enforces record-level and field-level permissions on every query the agent runs, so a properly scoped user cannot read or write beyond what you have granted, even if the agent asks it to.

Connect SurrealDB to Replit

Now switch over to Replit. Because MCP is a standard, you add SurrealDB the same way you would any custom server.

Open your app in the Project Editor and open the Integrations pane (or go to replit.com/integrations).
Choose Add new integration, then add a custom MCP server.
Server URL: paste your MCP endpoint, for example https://your-instance.surrealdb.cloud/mcp or your tunnel URL ending in /mcp.
Authentication: Replit supports OAuth dynamic client registration where a server offers it, or custom headers for static tokens. For a SurrealDB instance, use a custom header with key Authorization and value Bearer <token> for your scoped database user. Reserve no-auth endpoints for a throwaway local demo, never for real data.
Authorize the connection. Replit's security scanner inspects the server's tools, and the connection persists across your apps once approved.

Build an app on your SurrealDB data with Replit

With the connector live, Replit Agent calls SurrealDB's tools to discover your schema and read your records, then generates UI that is wired to that data.

Start by pulling your data into context with a prompt like this:

Using my SurrealDB connector, list the tables in the shop/catalog database and show me the fields on the product table.

This prompts Replit to call the list and info tools and read the schema resource, then report back what it found. Behind the scenes, use selects the shop namespace and catalog database, and the schema resource at surrealdb://schema/ns/shop/db/catalog/table/product tells Replit that product has name, price, in_stock, and created_at with their exact types.

Once it understands your schema, ask it to build:

Build a product catalog page that shows every product from SurrealDB as a card with its name, price, and stock status. Add a filter to show only in-stock items.

Replit reads your live products via the select tool, scaffolds a front end, and binds the components to the real fields. Because the agent knows in_stock is a boolean from the schema, the filter it builds is correct on the first pass rather than a guess.

You can go further and let it traverse relationships, which uses SurrealDB's graph capabilities:

Add a detail view for each product that lists its reviews, the rating and body, pulled from the review table that links to the product.

Here SurrealDB's record links do the heavy lifting. A SurrealQL query like SELECT *, <~review.{ rating, body } AS reviews FROM product fetches each product together with its reviews in one round trip. The <~ operator walks incoming record references the same way graph queries do, and Replit issues exactly that through the query tool.

When you ask Replit to write data, such as adding a form to submit a new review, the agent reaches for the create or insert tool. Because those tools carry the non-read-only annotations, Replit knows they mutate state and can surface a confirmation before anything is written. Your SurrealDB permissions remain the backstop: if the connected user lacks CREATE permission on review, the write fails at the database regardless of what the agent attempts.

SurrealDB MCP tools reference

Knowing what each tool does tells you exactly what you can ask Replit to do with your data.

query: run arbitrary SurrealQL. The most powerful tool, and the one behind any complex read or graph traversal.
select: read records from a table, optionally filtered.
create and insert: add new records, with insert geared toward bulk.
upsert: create or update depending on whether the record exists.
update: modify existing records.
delete: remove records, which is a destructive operation.
relate: create graph edges between records, SurrealDB's relational strength.
info: describe the structure of a namespace, database, or table.
list: enumerate available namespaces, databases, or tables.
use: select the namespace and database to operate within.
run: invoke a defined function on the server.

The read-only tools (select, info, list) are safe to let an agent call freely. The mutating tools (create, insert, upsert, update, delete, relate) are the ones the hint annotations flag, and the ones your database permissions should govern most tightly.

Production considerations for SurrealDB with Replit

A few things are worth getting right before you let real users near a SurrealDB-backed Replit app.

Scope the connected user tightly. Create a database-level user with only the permissions the app needs. SurrealDB's permission model is enforced on every query, including record-level and field-level SELECT, CREATE, UPDATE, and DELETE permissions, so the agent is constrained by the database, not just by good behavior.

Use the limits. The MCP environment variables exist to keep a chatty agent from overwhelming your instance. Set a sensible SURREAL_MCP_QUERY_TIMEOUT_SECS and SURREAL_MCP_MAX_RESULT_BYTES for your workload.

Prefer Cloud or a stable endpoint over a dev tunnel. Tunnels work for trying this out, but they are ephemeral. For anything persistent, a SurrealDB Cloud instance, or your own properly secured deployment, is the right home.

Keep your token out of shared links. A Replit install link with an Authorization header baked in carries a real credential. Generate it for your own use and rotate the token if it leaks.

Where this leaves you

You now have a SurrealDB instance whose schema and data are first-class context for Replit Agent, exposed through a typed, permissioned, observable MCP surface. The same connection that lets Replit build a catalog page would let it scaffold an admin dashboard, a customer-facing storefront, or an internal tool, all reading from and writing to the one database you control.

That is the shape of the SurrealDB and Replit workflow: SurrealDB is the system of record and the source of truth for structure, and Replit is the interface layer that builds on top of it. MCP is the standard that makes the two speak the same language, with no bespoke integration to maintain on either side. It is what turns vibe coding and agentic coding from a demo trick into a workflow you can run against your own data.

From here, a few good next steps are to define a SurrealDB function and invoke it from Replit via the run tool, so business logic lives in the database where the agent can reuse it; to model a richer graph with RELATE and ask Replit to build views that traverse it; and to move from a dev tunnel to a Cloud instance and tighten your user permissions for a real deployment.

What's new in Surrealist 3.9

Matthew McFadden — Tue, 23 Jun 2026 17:10:31 +0000

We're excited to announce the release of Surrealist 3.9! This version introduces a complete design overhaul, a new datasets browser and data manager, an improved record inspector, and much more. Let's dive into what's new 🎉

Highlights

Complete design overhaul

Surrealist 3.9 introduces the most significant visual refresh since Surrealist 2.0. From the new sidebar and topbar to the fully revamped light theme, the entire interface has been redesigned to feel fresher, cleaner, more consistent, and easier to navigate.

Namespace and database selection has been unified into a single selection menu, making it faster to switch context without the need to navigate separate menus. Additionally, the new search input makes it easy to find what you need, even in large deployments.

Connection and instance settings have also been completely redesigned, and the overview page now includes search for both connections and organisations. These changes make it easier to find what you are looking for no matter how many instances you manage.

New datasets browser and data manager

Working with imports and exports of your database and trying out new features with official SurrealDB demo datasets has never been easier! Surrealist 3.9 introduces a data manager and dedicated datasets browser to make managing bulk data in your database faster and more intuitive.

Additionally, it is now easier than ever to discover, browse, and apply official SurrealDB datasets to your database or Sandbox instance so that you can learn about and try new SurrealDB features in an interactive manner without needing to scroll through docs.

Improved record inspector

The record inspector has been significantly enhanced to give you a deeper view of your data. The new References and Live tabs make it easier to explore record relationships and monitor real-time changes, while the new actions menu gives you more control over how you interact with individual records.

These improvements make the record inspector a more capable tool for day-to-day data exploration whether you are tracing graph relationships, inspecting linked records, or watching live query results update in real time.

Full changelog

Improved designer view to use ALTER statements in 3.x instances
Overhauled Surrealist design
- Improved brand icons
- Redesigned light theme
- Redesigned sidebar and topbar
- Added a toggle sidebar button to the topbar
- Moved settings button to a menu item in the topbar when logged out and account menu when logged in
- Unified the namespace and database selectors into a single selection menu
- Completely redesigned connection and instance settings
- Implemented new search functionality for connections and organisations on the overview page
- Revamped and re-enabled API Docs view
Implemented a new datasets browser and data manager (#1224)
Improved the record inspector with new references and live tabs, and new actions
Implemented VIM mode setting (#106)
Implemented the ability to toggle tables in the designer (#372)
Implemented default namespace and database functionality for 3.x instances
Implemented namespace and database comment editor
Added namespace and database comments to selection menu and database settings page
Added search inputs to the namespace and database selection lists
Added designer view LOD settings for zoom-based table simplification (#1222)
Added pagination to the newsletter drawer
Fixed title bar overlapping drawers on Windows and Linux
Fixed authentication redirect on session expiry
Fixed Windows install art not showing for new installations
Fixed Surrealist mini not allowing datasets other than surreal-deal-store
Fixed an error where imports always showed success, even when they failed
Fixed 2.x sample data datasets being applied to 3.x databases
Fixed explorer returning no rows when sorting on empty columns (#1194)
Fixed interface and designer zoom not applying on all platforms (#1188)
Clean up stale graph connections after deleting edge tables (#1147)
Fixed an issue where clicking a table in designer view would cause a crash (#1238)
Fixed an issue causing large conection urls to cause UI overflow in connection cards (#1225)
Fixed broken documentation links (#1217)
Fixed passing URLs through desktop launcher (#1179)
Fixed Designer exports including lower LOD levels
Fixed designer not showing links for complex ids (#1063)
Fixed UUID records not resolving correctly in graph (#974)
Fixed clipboard writes failing in some browsers (#994)
Fixed GraphQL view authentication (#1101)

We hope you enjoy these new features and improvements! As always, we appreciate your feedback and suggestions for future releases. Join the SurrealDB Discord to engage with the community and receive support.

Get started for free today at app.surrealdb.com

SurrealDB is now available on the Nebius AI Cloud Marketplace

Mark Gyles — Thu, 18 Jun 2026 15:33:29 +0000

Author: Tobie Morgan Hitchcock

We're excited to announce that SurrealDB is now officially available on the Nebius AI Cloud Marketplace.

This launch reflects our commitment to meeting developers and AI teams where they build, and deepens our partnership with Nebius to make SurrealDB easier to adopt, deploy, and scale on one of the fastest-growing AI cloud platforms in the world.

Why Nebius?

Nebius is a full-stack AI cloud built for the demands of modern AI workloads. Powered by the latest GPU and high-performance networking infrastructure, with managed platform, serverless AI, and storage built for the entire AI lifecycle, Nebius gives teams the infrastructure to train, tune, and serve models at scale.

As an NVIDIA Reference Platform Cloud Partner with infrastructure across Europe and the US, Nebius pairs bare-metal performance with the operational simplicity and cost efficiency that AI teams need to move from experiment to production. It's a natural home for SurrealDB - giving you a unified data layer right alongside the compute powering your AI and agentic applications.

Why SurrealDB?

SurrealDB combines document, graph, and relational capabilities in one unified database - designed for agent memory, context layers, modern applications, real-time systems, and AI-powered workloads.With flexible schema, SurrealQL, and built-in real-time features, SurrealDB enables you to build semantic and context layers powered by knowledge graphs for agent memory and multi-agentic workflows.

SurrealDB simplifies your technology stack, reduces Total Cost of Ownership and operational complexity, and allows you to ship products and features in days rather than weeks.

Get started

SurrealDB is available now on the Nebius AI Cloud Marketplace. We can't wait to see what you build, join our Discord community and let us know how you get on!

SurrealDB 3.x by the numbers

Mark Gyles — Fri, 29 May 2026 19:20:49 +0000

Author: Tobie Morgan Hitchcock

One engine, multi-workloads, full durability.

You can explore the full results, methodology, and per-database breakdowns at surrealdb.com/benchmarks.

Why we ran these

Database benchmarks are notoriously easy to game, and difficult to get right. Different hardware, different durability settings, different client libraries, a workload that happens to suit one engine's indexing strategy - any of those will tilt the numbers. So we did three things:

Ran every database on the same hardware - an AMD Ryzen Threadripper 9970X (32C/64T), 128 GiB DDR5, NVMe storage, Ubuntu 24.04.
Used the same open-source harness - crud-bench - with each workload translated into each engine's native query language so no database is penalised for an unfamiliar dialect.
Configured every engine for production-grade durability - fsync on, snapshot isolation, no in-memory shortcuts (except where explicitly noted for embedded comparisons).

We also went out of our way to give every database a fair shot. Rather than running each engine on its out-of-the-box defaults, we used optimised configurations across the board - the same kind of tuning a production team would apply before going live. That meant raising connection and worker pool limits to match the 128-client load, sizing buffer pools, page caches, and shared memory to take advantage of the available 128 GiB of RAM, enabling parallel query execution and prepared-statement caching where supported, setting WAL and checkpoint intervals to values recommended by each project's own performance guides, and turning on the indexes and storage engines (InnoDB, WiredTiger, RocksDB-backed stores, etc.) that each database's documentation recommends for OLTP workloads. The goal was to make sure no engine was held back by a conservative default - if a database underperforms here, it isn't because we left it on its laptop-friendly starter config.

Workloads run with 128 clients issuing 48 concurrent queries each, against datasets of a single table with 5 - 15 million rows of mixed-type records (strings, integers, floats, UUIDs, datetimes, booleans, large text fields, geospatial data, and nested objects and arrays).

About last time

We owe a word on durability. The previous round of benchmark results ran with fsync disabled for every engine - leaving each database's writes in the OS page cache rather than flushed to disk. Every database in the comparison ran with the same setting, so nothing was being "fudged" relative to the other engines, but we didn't make the setting explicit, and the headline numbers ended up describing a workload that most production deployments would not likely run.

This round is different. Every database in these benchmarks runs with full disk durability enabled - fsync on, WAL flushed on every commit, no buffered writes hiding behind the page cache. The configuration files for each engine are checked into the crud-bench repository so anyone can audit them. The numbers above are what each engine sustains when every committed transaction is on disk before the client gets an acknowledgement. That's slower than the cache-friendly numbers you'll find in some marketing posts, ours included, but it's the only honest way to compare databases that are going to outlive a power outage.

How far SurrealDB has come

The biggest story is internal. Across three major releases, we've fundamentally rebuilt the query, parser, and storage layers:

Between SurrealDB 2.x and 3.x alone:

31% faster mean CRUD throughput
58% faster batch operations
11,894% faster non-indexed full-table scans
136% faster indexed queries
Tail latency improvements of 27% (CRUD), 32% (batches), 59% (indexed), and 99% (scans)

The scan number is not a typo. The SurrealDB 3.x query planner and storage engine eliminates the per-row decoding overhead that dominated earlier versions, which is why a workload that used to take minutes now completes in seconds.

How we compare to other databases

SurrealDB is a durable, transactional, multi-model database, so the comparisons that matter most are against the primary databases people actually evaluate it against - Postgres for relational, MongoDB for document, Neo4j for graph. Here's how the same workload looks across those three categories, run on the same hardware with each engine on a tuned production-grade configuration.

vs. PostgreSQL (and MySQL)

CRUD throughput (ops/s) and bulk-read metrics:

SurrealDB is faster than Postgres on every write operation - roughly 1.5× faster creates, 1.3× faster updates, and 1.8× faster deletes - while Postgres still edges ahead on raw single-record reads. Against MySQL the gap widens dramatically: SurrealDB is 5 - 7× faster on writes.

Averaged across creates, updates, and deletes, SurrealDB delivers ~1.5× the write throughput of Postgres - the headline number the benchmarks page leads the Relational category with - and beats Postgres by ~1.5× on full-table counts. Postgres' query planner is 30 years old and still ahead on indexed predicate filtering; we're not pretending otherwise, and we're working on closing that gap in 3.1.

vs. MongoDB (and ArangoDB)

CRUD throughput (ops/s) and bulk-read metrics:

This is the closest race. MongoDB still leads on single-record writes, while SurrealDB is ~1.3× faster on reads - and the picture flips on heavier workloads. On predicate filter scans against unindexed tables - the headline figure the benchmarks page uses for the Document category - SurrealDB is roughly 2.7× faster than MongoDB, with consistently lower mean and p99 latency. Against ArangoDB's document engine, SurrealDB is between 100× and 150× faster on writes.

vs. Neo4j (and ArangoDB)

CRUD throughput (ops/s) and bulk-read metrics:

SurrealDB outperforms Neo4j across every CRUD operation - roughly 2 - 3.5× faster on writes and 1.5× faster on reads - while running the same graph traversals through the same engine that handles documents and tables.

The gap on filtered scans is even more dramatic. Across indexed predicate filter queries - the headline metric the benchmarks page uses for the Graph category - SurrealDB is roughly 35× faster than Neo4j. No separate database, no separate query language, no separate operational story.

Reference point: Redis and KeyDB

For raw key-value throughput, we also ran SurrealDB's in-memory engine (with append-only persistence) against Redis and KeyDB:

That's roughly 3× faster than Redis on writes, updates, and deletes, while offering durable, snapshot-isolated transactions and a full query language Redis doesn't have. Redis still wins on large 1,000-record batch operations and edges ahead on single-record reads.

Embedded mode (vs. SQLite)

SurrealDB's embedded engine runs the same SurrealQL on the same disk format as the server.

Against SQLite, SurrealDB is roughly 85× faster on creates, 110× faster on updates, and 75× faster on deletes, with single-record reads in the same ballpark. On predicate filter scans against unindexed tables it's around 6.5× faster than SQLite, and on indexed filter scans, around 3× faster.

The full breakdowns - including p50, p95, and p99 latencies, batch sizes from 100 to 1,000 rows, indexed and non-indexed predicate filters, and full-text search - are on the benchmarks page.

Closing the remaining gaps

The numbers above are an honest snapshot, not a finish line. There are still workloads where Redis, MongoDB, and Postgres beat us - large batch operations vs. Redis, single-record writes vs. Mongo, indexed predicate filtering vs. Postgres - and we know exactly where each gap comes from. Closing those gaps is the central focus of the SurrealDB 3.1 cycle.

What we're actively working on:

Batch path rewrites to bring 100-row and 1,000-row batched ops closer to Redis throughput, including better client-side pipelining and a leaner server-side batch executor.
A smarter query planner with cost-based optimisation, predicate pushdown into the storage engine, and richer index selectivity statistics - the work that gets us to parity with Postgres on indexed filter scans.
Storage layer improvements for the document workload - more compact in-place updates, sharper write amplification, and tighter integration between the key encoding and the document path resolver - which is where Mongo currently has the edge on single-record writes.
Vector and graph traversal optimisations as those workloads land in the benchmark suite, so the multi-model story holds up at the same rigour as CRUD.

The goal isn't "fastest at one thing." It's to be fastest, or competitive, across every workload that matters, while keeping the one property no specialist engine can match: a single query language - SurrealQL - that handles relational, document, graph, key-value, time-series, vector, and full-text search data in the same database, with the same transactional guarantees, on the same disk format - and the same engine, whether you're running it embedded inside an application, on a single server, at the edge close to your users, or distributed across hundreds of nodes for horizontal scale. We don't think you should have to choose between Postgres, Mongo, Neo4j, and Redis - or between a database that runs on a developer laptop and one that runs across a global fleet. We think a single database should run all four shapes of workload at production speed, anywhere it needs to live, and the SurrealDB 3.x numbers above are the strongest evidence yet that it can.

Why this matters for AI agents

There's a reason we keep pushing on this combination of data models, and it's not historical accident. Agent memory is multi-model by nature. A useful AI agent needs structured facts about the world (relational), semi-structured context and tool outputs (document), entity and event relationships (graph), embeddings for semantic recall (vector), keyword and BM25 retrieval over its corpus (full-text search), episodic and temporal context (time-series), and fast session and cache state (key-value) - and it needs all of that in a single transactionally consistent store, because the moment those shapes live in separate databases, you've built a glue-code problem that breaks every time the schema changes or the model is updated.

Agents also need that memory close to where they run. An agent reasoning inside a browser, a phone, an in-vehicle system, or a per-tenant edge worker can't afford a round trip to a central database for every retrieval. The fact that SurrealDB runs as an embedded engine on the same disk format as the distributed server - with the same query language and the same transactional guarantees - is what makes it usable as the memory layer for agents that move fluidly between local, edge, and centralised deployments. Faster CRUD, faster scans, and faster indexed lookups aren't just abstract benchmark wins; they're how many tools an agent can call, how much context it can recall per turn, and how many concurrent agents a single host can support. That's the workload SurrealDB 3.x is built for, and it's the workload the next round of benchmarks - covering vector search, graph traversal, and full-text retrieval - will measure head-on.

What's next

We intend to expand the benchmarks to also cover CockroachDB, TiDB, MongoDB, and Aerospike for distributed comparisons, which we'll publish in a future round. We also plan to expand the workload set to include graph traversals vector search, and full-text search, two areas where the single-engine, multi-model design of SurrealDB shows its biggest advantages.

Until then: the harness is open source, the results are reproducible, and we'd love for you to run them on your own hardware and tell us what you find.

See the full benchmarks.

SurrealDB 3.1: stability, DiskANN, and a new release process

Mark Gyles — Thu, 28 May 2026 08:43:39 +0000

Author: Tobie Morgan Hitchcock

Three months after 3.0 went GA, we're excited to announce that SurrealDB 3.1 is now available. This is the first minor release in the 3.x series. It builds on the foundations we shipped in 3.0 with a focus on stability, a second approximate-nearest-neighbour index in DiskANN, and a substantial round of security hardening. Alongside the release, we're also rolling out a change to how we develop and ship SurrealDB.

The full list of changes is in the 3.1 release notes. Below are the highlights.

What's new in 3.1

DiskANN approximate-nearest neighbour index

SurrealDB now ships DiskANN as a second ANN index type, sitting alongside HNSW. DiskANN trades a different set of memory and recall characteristics and is well suited to larger-than-memory vector workloads, which has been a recurring request from teams building production agent and search systems on SurrealDB.

The introduction of DiskANN also drove an end-to-end overhaul of the ANN warm-lookup path. Both HNSW and DiskANN benefit from this work, with measurable improvements to warm-cache latency on the existing HNSW index for free.

You can pick the index type at definition time with the new DEFINE INDEX ... DISKANN syntax. See the release notes for the full set of options.

GraphQL: aliases, cursor pagination, and multi-model filtering

SurrealDB v3.1 brings a significant upgrade to the GraphQL surface, making it more expressive, more predictable, and easier to integrate with modern GraphQL clients.

The generated schema now follows Apollo conventions by default, with singular fetch, plural list queries, and createX / updateX / deleteX mutations, so you always know what to expect without consulting per-database config. Fields and tables can now carry GRAPHQL_ALIAS and GRAPHQL_DEPRECATED clauses directly in their definitions, letting you decouple your SurrealQL identifiers from the names your API consumers see:

Schema

DEFINE FIELD first_name ON person TYPE string
  GRAPHQL_ALIAS "firstName";

DEFINE FIELD legacy_score ON player TYPE int
  GRAPHQL_DEPRECATED "Use `rank` instead";

Cursor pagination arrives in this release too. Each table now gets a <plural>Connection query returning edges, pageInfo, and a lazily-evaluated totalCount, so you only pay for the count when you ask for it. Offset pagination via limit and start remains fully supported alongside it.

On the multi-model side, GraphQL queries can now reach across SurrealDB's full data model. Full-text search, vector similarity, and time-series aggregation are all directly queryable through the GraphQL API, unlocking AI-native and analytics-heavy workloads without touching SurrealQL.

This release also closes a range of reported issues: stale schema caches after DDL changes, invalid filter identifiers on nested array fields, missing id range and in filters, and count()-based predicates in WHERE clauses, all resolved and covered by integration tests.

Improved in-memory performance

SurrealDB's in-memory backend now uses a datastore based on optimistic lock coupling. This improves performance by allowing readers to acquire lock-free access, only retrying at the end if a modification has occurred in the meantime. This allows readers to proceed without blocking writers, and vice versa.

Stability and correctness

The bulk of the 3.1 work is bug fixes and stabilisation of the 3.0 line. This continues the stream of fixes that shipped in v3.0.1 through v3.0.5, with a substantial number of additional issues addressed across the query engine, indexing, and storage layers. If you upgraded from 2.x to 3.0 and hit any rough edges, there's a strong chance the relevant fix is in 3.1.

Security hardening

3.1 closes a batch of previously reported security vulnerabilities, alongside a set of previously undiscovered issues that we found internally. The undiscovered ones come from an increased investment in LLM-assisted security review, in line with broader industry practice. Mozilla wrote a good summary of this approach recently. The combined result is a notably larger security section in this release than in previous ones.

The full security section is itemised in the release notes.

Enterprise: audit logging and slow-query pipeline

Customers on the Enterprise tier get two new operational tools in 3.1:

A structured audit log capturing authentication events, schema changes, and other actions of interest to compliance and security teams.
A slow-query pipeline that surfaces queries exceeding a configurable threshold, complete with their plan and execution metadata, to help diagnose performance issues in production.

Both have been on Enterprise customer wishlists for a while, and we're pleased to have them shipping in 3.1.

Other quality of life additions

Among the many changes mentioned in the 3.1 release notes, some of the changes that you won't want to miss are:

A built-in MCP server for AI tools and IDEs,Unified OpenTelemetry metrics and logging pipeline,
Unified OpenTelemetry metrics and logging pipeline,W3C trace propagation across HTTP and WebSocket,
W3C trace propagation across HTTP and WebSocket,Full ALTER coverage for every DEFINE statement,
Full ALTER coverage for every DEFINE statement,
And continued executor and index improvements beyond the in-memory engine.

A new release process

3.1 is also the first release we've shipped under a new development workflow, and we want to be transparent about what's changed and why.

For most of SurrealDB's history, we've developed in public on the main surrealdb/surrealdb repository. When a security vulnerability needed addressing, we'd cut a temporary private fork, fix the issue there, cut a release, patch the SurrealDB Cloud fleet, and then make the release public. The intent was good. Development happened where the community could see it, and security fixes were embargoed only as long as they needed to be. In practice, though, this added real overhead to every security response. Cutting a fresh private fork for each issue, keeping it in sync with main, and merging the fix back when going public all took time we'd rather have spent on the fix itself.

Starting with 3.1, we've moved all development to a private repository. The public surrealdb/surrealdb repo remains the source of truth for releases, issues, and the source code that users read. Day-to-day commits now happen privately.

The cadence looks like this:

We develop and tag releases in the private repository.
When a release is ready, we announce it publicly and ship binaries and Docker images on the usual schedule.
Roughly 1 week after each release, we sync the private repository back to the public surrealdb/surrealdb repo.

The week between release and public sync gives us a private window to triage any issues or vulnerabilities reported against the new version before the corresponding commits become visible. We can ship a fix and roll it out across SurrealDB Cloud before the underlying issue is public. This is the same model used by most database and infrastructure projects at comparable scale, and it lets us close security issues as quickly as they're reported.

A few practical notes:

Issues, PRs, and discussions stay on the public repo. Keep filing them on surrealdb/surrealdb. We watch and respond to them daily.
Security reports. Use the GitHub Security Advisory flow on the public repo, or email security@surrealdb.com. Both reach us privately, and are the right route for anything you don't want disclosed publicly.
Community PRs. We're still very keen for community contributions. They get reviewed against the public repo as before, and brought into the private tree as part of the normal cycle.

We don't expect this to be visible to most users in day-to-day use. If you follow commit-by-commit development on the public repo, the experience will change: you'll see batched updates around each release rather than a continuous stream. We think the security benefit is worth that tradeoff, and we plan to keep working this way for the foreseeable future.

Try it

SurrealDB 3.1 is available now. Head to the install page to grab it for your platform.

If you're running on SurrealDB Cloud, instances are being rolled to 3.1 as part of our standard release cycle. No action needed.

Read the full release notes for the complete list of changes, and come say hello on Discord if you hit anything along the way.

Kreuzberg & SurrealDB: from unstructured documents to hybrid retrieval

Mark Gyles — Tue, 12 May 2026 12:35:55 +0000

Author: Ignacio Paz

We’re excited to share a new partner integration: kreuzberg-surrealdb, a connector that bridges the Kreuzberg document intelligence framework directly into SurrealDB. This integration was created by the Kreuzberg team and we are excited to have this functionality available now in SurrealDB.

Kreuzberg extracts, chunks, and generates embeddings from 88+ document formats, while SurrealDB provides a multi-model database for AI applications, combining documents, graphs, vectors, and full-text search in a single system.

Together, they make it easy to build document search and RAG pipelines.

What the integration does

kreuzberg-surrealdb handles the full ingestion workflow:

Automatic schema setup
Content deduplication using SHA-256 hashing
Storage and indexing in SurrealDB
Documents ready for search immediately after ingest

The integration supports two modes:

DocumentConnector:indexes full documents for BM25 keyword search.
DocumentPipeline:chunks documents, generates embeddings, and enables semantic and hybrid search using HNSW vector indexes and Reciprocal Rank Fusion.

Why it matters

Building document search systems often requires combining multiple tools for extraction, chunking, embeddings, and storage.

With kreuzberg-surrealdb, the entire workflow runs through a single integration—no schema boilerplate, no duplicate ingestion, and built-in support for keyword, semantic, and hybrid search.

Get started

See how to get started in SurrealDB Docs: Kreuzberg Integration, and check out our example of How to build a knowledge graph for AI with SurrealDB and Kreuzberg.

Schema migrations in SurrealDB: A local dev workflow

Mark Gyles — Fri, 08 May 2026 12:42:16 +0000

Author: Chiru Boggavarapu

This post walks through a proper migration workflow for local development using SurrealKit, an official tool from the SurrealDB team that handles schema sync, rollouts, seeding, and testing.

If you've spent any time working with SurrealDB, you know that with great flexibility comes the responsibility of managing your schema carefully. You're iterating quickly, adding tables, refining field definitions, and removing what you no longer need, and before long your local database can drift out of sync with what your code expects.

What is SurrealKit?

SurrealKit is a CLI tool that manages your SurrealDB schema through .surql files. You define your schema as files, and SurrealKit keeps your database in sync with them.

It has two main modes:

Sync: a fast, declarative approach for local and dev environments. Your files are the source of truth. Add something and it gets created, change it and it gets updated, remove it and it gets deleted.
Rollout: a more controlled migration path for shared or production databases, with planning, staged execution, and rollback support.

For local dev, you'll mostly live in sync. Rollouts come into play when you're pushing to shared environments.

Getting Started

Cargo is the Rust package manager. It downloads a Rust package's dependencies, compiles the packages, and makes distributable packages.

Install via Cargo

cargo install surrealkit

Or grab a prebuilt binary from the GitHub releases page if you don't want to compile it.

Initialise a project

surrealkit init

This creates a /database directory with the scaffolding you need. SurrealKit connects to your database using environment variables, so add these to your .env:

.env

SURREALDB_HOST=localhost:8000
SURREALDB_NAME=myapp
SURREALDB_NAMESPACE=development
SURREALDB_USER=root
SURREALDB_PASSWORD=secret

It supports both DATABASE_HOST and PUBLIC_DATABASE_HOST variants, which is handy if you're working in a SvelteKit or similar setup where env vars are split by visibility.

The Local Dev Workflow

Writing Your Schema

Schema files live in database/schema/. Each file is a .surql file with your table definitions, indexes, access rules — whatever you'd normally write in SurrealQL.

The structure is entirely up to you. You might have one file per table, or group related things together. Either way, SurrealKit tracks what's in those files and reconciles it with what's actually in your database.

Syncing Changes

When you've made a change and want to apply it:

surrealkit sync

That's it. SurrealKit diffs your schema files against the current database state and applies what's changed. If you deleted a table definition from your files, it removes it from the database too. Everything stays in sync.

For active development sessions, watch mode is where you'll spend most of your time:

surrealkit sync --watch

This watches your database/schema/ directory and resyncs automatically whenever you save a file. It handles deletions too — if you remove a definition, it gets cleaned up. No manual intervention needed.

Moving to Shared Environments

The sync approach is great for local databases you own completely. But the moment you're working against a shared or staging database, you need more control. That's what rollouts are for.

Baseline First

Before your first rollout on an existing database:

surrealkit rollout baseline

This records the current state so SurrealKit knows what it's working from.

Plan → Start → Complete

When you're ready to ship a schema change:

surrealkit rollout plan --name add_user_indexes

This generates a TOML manifest in database/rollouts/ describing exactly what will change. You can review it, commit it, get it reviewed. Treat it like a pull request for your schema.

When you're ready to apply, you'll reference the manifest by its full filename. SurrealKit names these with a timestamp prefix: 20260302153045 translates to 2nd March 2026 at 15:30:45. This is the time the plan was generated, and it's there so rollouts always have a guaranteed sort order. If two people generate a plan on the same day, the timestamps keep them distinct and sequential. You'll see the full name in your database/rollouts/ directory after running plan.

When you're ready to apply:

surrealkit rollout start 20260302153045__add_user_indexes

This runs the non-destructive part of the migration. Once your application is deployed and you're confident everything is working:

surrealkit rollout complete 20260302153045__add_user_indexes

This finishes the migration, including any cleanup of legacy objects.

If something goes wrong mid-rollout:

surrealkit rollout rollback 20260302153045__add_user_indexes

You can also validate a manifest without touching the database:

surrealkit rollout lint 20260302153045__add_user_indexes

And check what state a rollout is in:

surrealkit rollout status

SurrealKit tracks rollout state in the database itself, so it's always resumable.

Seeding

SurrealKit has a built-in seeding system for populating your local database with test data:

surrealkit seed

Seed files live alongside your schema in the /database directory. Useful for onboarding new team members quickly — they clone the repo, init SurrealKit, run sync and seed, and they're good to go.

Testing

One of the more interesting features is the declarative testing framework. You write TOML test suites in database/tests/suites/ and run them with:

surrealkit test

Each suite runs in an isolated ephemeral namespace, so tests can't interfere with each other or your actual data. You can test SQL assertions, permission rules, schema metadata, and even HTTP API endpoints.

A simple example, checking that a guest can't create an order:

name = "security_smoke"

[[cases]]
name = "guest_cannot_create_order"
kind = "sql_expect"
actor = "guest"
sql = "CREATE order CONTENT { total: 10 };"
allow = false
error_contains = "permission"

You can also test permission matrices across a whole table at once, which is handy for verifying your access rules haven't regressed after a schema change.

For CI, add --json-out to get machine-readable output:

surrealkit test --json-out database/tests/report.json

The command exits non-zero on any failure, so it integrates cleanly with GitHub Actions and other CI/CD systems seamlessly.

Putting It Together

Here's what a typical day looks like with this setup:

Pull the latest changes
Run surrealkit sync to update your local DB
Edit schema files in database/schema/
Use surrealkit sync --watch while you work
When you're done, run surrealkit test to make sure nothing broke
Commit your schema files alongside your code

For production changes, swap step 4 for surrealkit rollout plan and follow the plan → start → complete flow.

Would love to hear how you get on with SurrealKit. Jump into Discord and let us know how it goes or if you need a hand along the way.

New SurrealDB docs search using hybrid search and HNSW/BM25 reranking

Mark Gyles — Fri, 01 May 2026 15:32:31 +0000

Author: Dave MacLeod

Trying to produce relevant search results is one of the hardest things to get right when building an app. Searching can be done in a lot of ways: basic text search, full-text search, vector search, and often even graph and geospatial.

This post introduces an example that includes two of these models: full-text and vector search together. These two tend to involve quite a bit of SurrealQL code, because:

To use full-text search, you first have to define how you want text to be split up and modified. Do you want it to be case-sensitive? Split by whitespace, or some other way? Modified to root forms based on the language of the text? (And so on...)
To use vector search, you have to generate embeddings for pieces of text and know how to query them.

What makes this example special is that it is the search function you use every time you type some text into the "Search the docs" part of the SurrealDB documentation! This functionality was recently implemented, and because it's open source we are able to show you the ins and outs of how it was done.

How Doc Search Is Implemented

The README in the /search section of the docs repo goes into a good amount of detail.

In addition, you can see the mechanics of the search itself inside this search.ts file in another section.

The entire implementation is done using SurrealDB, along with Bun to deploy the website and an OpenAI API key. You can go to this part of the page to deploy it locally and test it out.

Here is what the final result looks like:

Since the README file already goes into detail about how to do the deployment yourself, in this post we will instead take a closer look at the SurrealQL statements themselves to see how they work and how they might help you do something similar in your own tools and apps.

The role SurrealDB Plays

As the README mentions, the search functionality uses hybrid search:

Hybrid search for the SurrealDB documentation. Combines BM25 full-text search with OpenAI vector embeddings, fused via Reciprocal Rank Fusion (RRF) inside SurrealDB.

Hybrid search allows you to combine full-text search with vector search, giving you the best of both worlds.

Vector search is useful because it is capable of going beyond the outward appearance of words to get to their semantic meaning. For example, the term lead in the following paragraph is used to mean two different things. We can recognize that as humans, and LLM models are also able to do the same, returning the output as an embedding (a large array of numbers representing semantic space).

The project lead frowned and took a hard look at the results. They were clear as day. There was far too much lead content in the water. That's why the town had gotten sick!

However, full-text search is useful too because it excels at slicing and modifying text into tokens. To show what that looks like, here's what the full-text analyzer looks like that is used in the docs search.

DEFINE ANALYZER OVERWRITE simple
    TOKENIZERS blank, class, camel, punct
    FILTERS snowball(english);

The easiest way to understand what all the tokenizers and filters do in an analyzer is by putting a string into the search::analyze() function, which returns an array. To avoid showing a huge array in this blog post, we'll call .join(' ') on the output to join them back into a single string.

search::analyze(
    "simple", 
    "The project lead frowned and took a hard look at the results. They were clear as day. There was far too much lead content in the water. That's how the town had gotten sick!")
.join(' ');

As the output shows, using this analyzer will allow you to match on terms like "FroWNinG" which will turn into "frown" before being compared against a search string.

"the project lead frown and took a hard look at the result . they were clear as day . there was far too much lead content in the water . that ' s how the town had gotten sick !"

So if vector search and full-text search each have their advantages, how can you combine the two? It would be nice if you could somehow plug them into a function that does this.

And it turns out that SurrealDB has exactly that! It is called search::rrf() and was added during the 3.0 beta period. Here is what it looks like in practice.

-- ── Reciprocal Rank Fusion ──
-- Combines the four ranked lists into a single ranking.
-- RRF scores each result as: sum(1 / (k + rank_in_list))
-- across all lists the result appears in.
--   arg 1: array of ranked lists to fuse
--   arg 2: k=60 (smoothing constant, standard RRF default)
--   arg 3: limit=80 (max candidates to consider)
LET $fused = search::rrf(
    [$page_ft, $page_vs, $section_ft, $section_vs], 
    60, 
    80
);

As you can probably guess, it is fusing the results of previous queries for full-text search on pages and sections ($page_ft, $section_ft) together with vector searches on pages and sections ($page_vs, $section_vs).

Full-text searches are done using the @@ operator (the "matches" operator). This operator works as long as you have a index on a field that uses a FULLTEXT ANALYZER:

DEFINE INDEX OVERWRITE page_ft_title       ON page FIELDS title       FULLTEXT ANALYZER simple BM25;
DEFINE INDEX OVERWRITE page_ft_breadcrumb  ON page FIELDS breadcrumb  FULLTEXT ANALYZER simple BM25;
DEFINE INDEX OVERWRITE page_ft_description ON page FIELDS description FULLTEXT ANALYZER simple BM25;
DEFINE INDEX OVERWRITE page_ft_content     ON page FIELDS content     FULLTEXT ANALYZER simple BM25;
DEFINE INDEX OVERWRITE page_ft_path        ON page FIELDS path        FULLTEXT ANALYZER simple BM25;

In between these two @ operators you can insert a number to access the search::score() for each field. This will make sense once you take a look at these two queries. Each of them is querying multiple fields, each of which will return a score thanks to BM25 defined in the field. To know which field is which, you put a reference number in between the @ operators like @0@ and @2@. They can then be added together or multiplied or whatever logic you would like to use.

LET $page_ft =
        SELECT
            id,
            "page" AS kind,
            path AS url,
            path AS page_path,
            collection,
            title,
            breadcrumb,
            description,
            content,
            (
                (search::score(0) * 15)
                + (search::score(1) * 25)
                + (search::score(2) * 10)
                + (search::score(3) * 8)
                + (search::score(4) * 3)
            ) AS ft_score
        FROM page
        WHERE
            path @0@ $query
            OR title @1@ $query
            OR breadcrumb @2@ $query
            OR description @3@ $query
            OR content @4@ $query
        ORDER BY ft_score DESC
        LIMIT 30;

LET $section_ft = 
        SELECT
            id,
            "section" AS kind,
            string::concat(page.path, "#", anchor) AS url,
            page.path AS page_path,
            page.collection AS collection,
            title,
            breadcrumb,
            content,
            (
                (search::score(0) * 25)
                + (search::score(1) * 10)
                + (search::score(2) * 3)
            ) AS ft_score
        FROM section
        WHERE
            title @0@ $query
            OR breadcrumb @1@ $query
            OR content @2@ $query
        ORDER BY ft_score DESC
        LIMIT 30;

The vector search query also uses its own index. Note that you don't specifically need an index to use vector search, as you can go with a brute force function such as vector::similarity::cosine() instead. However, an HNSW index instead can speed up the process dramatically if you don't mind sacrificing a bit of precision. Here the index is defined with a dimension of 1536 to match the length of the array returned by OpenAI's text-embedding-3-small model.

-- HNSW index for approximate nearest-neighbour vector search.
-- Dimension 1536 matches OpenAI text-embedding-3-small output.
-- Cosine distance is the standard metric for normalised text embeddings.
DEFINE INDEX OVERWRITE page_embedding_hnsw ON page FIELDS embedding
    HNSW DIMENSION 1536 DIST COSINE;

Having an HNSW index also lets you use the <||> operator (the KNN, or K-nearest neighbour) operator when performing the query. The comments above the code explain what each of the two numbers mean. Here, the |30,100| syntax means to return 30 neighbours among up to 100 candidates.

-- ── Page vector search ──
-- Finds the 30 pages whose embeddings are closest to the
-- query embedding. The <|30,100|> syntax means: return 30
-- neighbours, exploring up to 100 candidates in the HNSW
-- graph (higher = more accurate but slower).
LET $page_vs = 
    SELECT
        id,
        "page" AS kind,
        path AS url,
        path AS page_path,
        collection,
        title,
        breadcrumb,
        description,
        content,
        vector::distance::knn() AS distance
    FROM page
    WHERE embedding <|30,100|> $qvec
    ORDER BY distance ASC
    LIMIT 30;

-- ── Section vector search ──
-- Same as page vector search but for H2 sections.
-- Pulls the parent page's path and collection via the
-- record link (page.path, page.collection).
LET $section_vs =
    SELECT
        id,
        "section" AS kind,
        string::concat(page.path, "#", anchor) AS url,
        page.path AS page_path,
        page.collection AS collection,
        title,
        breadcrumb,
        content,
        vector::distance::knn() AS distance
    FROM section
    WHERE embedding <|30,100|> $qvec
    ORDER BY distance ASC
    LIMIT 30;

So that is how the magic happens. Well, part of it. Be sure to check out the rest of the code which shows what happens after the SurrealDB query returns. For example, as the database is unaware of which collections it is searching through, some modifications are made on the SDK side to give SDK docs less precedence compared to more core docs. This is something that you could perhaps do on the database side if you wanted (starting with DEFINE TABLE sdk_page instead of DEFINE TABLE page for example) but that will always depend on your own case.

// ──────────────────────────────────────────────────────────
// Post-retrieval boosting
//
// After RRF fusion, we apply multiplicative boosts to adjust
// rankings based on signals the database query can't capture:
// title similarity, content type (page vs section), source
// collection, and comparison-query detection.
// ──────────────────────────────────────────────────────────

/**
 * Non-SDK doc collections get a small ranking boost because
 * generic queries like "authentication" should prefer the
 * core concept page over an SDK API reference page that
 * happens to mention auth as one of many methods.
 */
const CORE_COLLECTIONS = new Set([
    "doc-surrealdb",
    "doc-surrealql",
    "doc-tutorials",
    "doc-cloud",
    "doc-surrealist",
    "doc-surrealml",
    "doc-surrealkv",
    "doc-integrations",
]);

Simplifying the Example

Since you might not have the head space at the moment to play around with the existing code demonstrated in this blog post, let's finish up with the same pattern as above in a very simplified form. This will let you copy and paste the example into the online Surrealist UI to give it a try yourself.

The content below holds all the same features: a full-text analyzer, a full-text and vector index, a full-text and vector query, and a final query that combines the two into hybrid search results. However, it has all been simplified to a single field for text content and embeddings, and a single document table that is being searched on. In addition, the embeddings have been cut down to an array of just ten numbers in length. An array that small is very imprecise, but just long enough to serve for our simple example.

-- Define an analyzer
DEFINE ANALYZER OVERWRITE simple TOKENIZERS blank, class, camel, punct FILTERS SNOWBALL(en);

-- Attach it to an index
DEFINE INDEX OVERWRITE ft ON document FIELDS content FULLTEXT ANALYZER simple BM25(1.2, 0.75);

-- Create a vector index too
DEFINE INDEX OVERWRITE page_embedding_hnsw ON document FIELDS embedding HNSW DIMENSION 10 DIST COSINE;

-- Add some sample data
{
    CREATE document:one SET content =   "Elves and halflings and witches and such", embedding = [-0.0019, -0.0142, 0.0080, -0.0664, 0.0173, 0.0109, 0.0066, 0.0045, 0.0204, 0.0087];
    CREATE document:two SET content =   "Is that a wizard?",                        embedding = [0.0010, -0.0051, 0.0207, -0.0787, -0.0061, 0.0127, -0.0172, -0.0097, 0.0077, -0.0120];
    CREATE document:three SET content = "Databases are used to store information",  embedding = [-0.0317, -0.0112, 0.0118, -0.0348, 0.0061, 0.0114, 0.0310, 0.0117, 0.0034, 0.0195];
    NONE
};

-- A sample query and its embedding
LET $witch_text = "witches";
LET $witch_embed = [-0.0200, -0.0059, -0.0081, -0.0475, 0.0020, 0.0295, -0.0183, 0.0170, 0.0048, 0.0286];

-- Get the full-text score
LET $fts_score =
        SELECT
            id,
            content,
            search::score(0) AS ft_score
        FROM document
        WHERE
            content @0@ $witch_text;

-- Get the vector score
LET $vector_score = 
    SELECT
        id,
        content,
        vector::distance::knn() AS distance
    FROM document
    WHERE embedding <|30,100|> $witch_embed
    ORDER BY distance ASC;

-- Combine the results as a hybrid score
search::rrf([$fts_score, $vector_score], 60, 80);

We can see in the output that while only one document had a match on the word "witches" (and thus a value for ft_score), the vector search portion has been able to conclude that the sentence about wizards is semantically a bit closer than the one about databases. This would be a lot more accurate of course if the embedding were longer than 10 elements, but even at this length we can still see its potential.

[
    {
        "content": "Elves and halflings and witches and such",
        "distance": 0.2789615948854415,
        "ft_score": 0.4782197177410126,
        "id": "document:one",
        "rrf_score": 0.024691358024691357
    },
    {
        "content": "Is that a wizard?",
        "distance": 0.385041442417419,
        "id": "document:two",
        "rrf_score": 0.012195121951219513
    },
    {
        "content": "Databases are used to store information",
        "distance": 0.3876749269204385,
        "id": "document:three",
        "rrf_score": 0.012048192771084338
    }
]

Hopefully the simplified example has made it easy to follow the logic we use in our own doc search and has given you some ideas for how to implement patterns yourself. Have any questions or comments about hybrid search? Feel free to Create a free SurrealDB Cloud instance today to get started, and drop by our Discord community to discuss anything on your mind with the SurrealDB community and staff.

How to get near-perfect, deterministic accuracy from your AI agents

Mark Gyles — Thu, 23 Apr 2026 22:23:21 +0000

Author: Matthew Penaroza

I have spent a lot of time working on large-scale agent architectures with some of the largest organizations in the world, and the single most common mistake I see teams make is assuming their accuracy problems are model problems. They almost never are. Your agent is typically not struggling because the LLM is weak. It is struggling because your retrieval layer is feeding it bad context. Fix your retrieval, and accuracy jumps. Make your retrieval learn from its own results, and accuracy becomes deterministic. Here is what that looks like in practice.

TL;DR - Agent accuracy problems are almost always retrieval problems, not model problems. At scale, vector search alone is not enough. You need structured filters, graph traversal, temporal constraints, and vector similarity composed in a single atomic query to get to ~90–95% accuracy. To close the remaining gap to ~99%+, you need reasoning graphs and retrieval graphs: structured graph edges that capture the agent's logic and retrieval patterns, feeding back into the pipeline so the system learns which approaches produce correct outcomes. Both require a multi-model database with ACID transactions across every data model, which is exactly what we designed SurrealDB to be.

The problem: why agent accuracy hits a ceiling

Every agent follows the same loop: retrieve context, reason over it, act. The quality of the action is bounded by the quality of the context. I have seen perfectly capable models produce terrible outputs because the context they were given was noisy, and I have seen mid-tier models produce excellent outputs because the context was precise. The model matters less than most teams think.

At small scale, none of this is a problem. If you have a few thousand documents, vector search returns good results, everything fits in a single database, and accuracy looks great. The problems emerge when data grows into the millions or billions of records. Suddenly more candidates look semantically similar, top-k selection becomes unstable, unrelated chunks bleed into the context window, and your agent starts hallucinating. The RAG survey literature (Gao et al., 2023) documents these failure modes extensively. Vector similarity is a useful ranking signal. It is not a control plane.

What makes it worse is the typical production stack. Most teams are running Postgres for state, Neo4j for relationships, Pinecone for vectors, MongoDB for documents, sometimes Elasticsearch and a memory layer on top. Five or six independent systems, each with its own consistency model. When the graph database is 200ms behind the relational store, or the vector index has not ingested a document that was just written, your agent is reasoning over a version of reality that does not exist. It does not know the data is stale. It just makes a worse decision. And in multi-step workflows, each bad retrieval compounds into the next.

So the question worth asking is not "which model should we use?" It is: how do you guarantee that the context reaching the model is valid, complete, current, and precise, even at scale? In my experience, the answer has two layers. The first gets you to roughly 90–95%. The second closes the gap to 99%+.

The accuracy staircase

Each layer compounds on the last. Skip any step and accuracy hits a ceiling.

Getting to ~90–95%: scope-first retrieval

The idea is straightforward: instead of running similarity search against everything and cleaning up the results, you constrain the candidate set before ranking. Define what counts as a valid result first. Rank inside that scope second.

Think about what a single agent retrieval step actually needs, and what goes wrong without each layer.

Structured filters narrow by type, permissions, and tenancy. Without them, I have watched a support agent retrieve internal engineering postmortems and serve them verbatim to a customer, because the postmortem was semantically similar to the customer's question. The vector search was technically correct. The result was a data leak.

Temporal constraints ensure the data is current. Without them, an agent recommending products will happily surface items that were discontinued months ago, because the old product description is still the closest embedding match. The customer clicks through to a dead link. Trust erodes.

Graph traversal follows real relationships: this customer owns this product, which has this known issue, which maps to this knowledge base article. Without it, your agent retrieves articles about similar-sounding problems on entirely different products. The answer reads plausibly but is wrong in the specifics, which is the worst kind of hallucination because it is hard to catch.

Only after all of that scoping should vector similarity and full-text search run, ranking the remaining candidates by relevance. By this point, the candidate pool is already valid. Similarity is just picking the best among the valid.

The problem is you cannot compose these operations across a fragmented stack. In a multi-database architecture, each is an independent query against an independent system. The application layer stitches the results together and hopes the data was consistent across all of them. It never fully is. You need a database that handles all of this natively, in a single query, against a single consistent snapshot. That is why we built SurrealDB the way we did: structured filters, temporal constraints, graph traversal, vector similarity, full-text search, and business rule enforcement all compose in one SurrealQL transaction.

Here is what that looks like. One query, every scoping layer, against one consistent snapshot:

SELECT
    id,
    title,
    vector::distance::knn() AS vec_dist,
    search::score(1) AS ft_score,
    (1 - vector::distance::knn()) * 0.65 + search::score(1) * 0.35 AS blend_score,
    search::highlight('<em>', '</em>', 1) AS content_snippet
FROM knowledge_base
WHERE type = 'support'
    AND tenant = $tenant
    AND $agent_principal INSIDE allowed_principals
    AND updated_at > time::now() - 30d
    AND id IN $customer->owns->product->has_issue->knowledge_base
    AND content_embedding <|100,40|> $query_embedding
    AND content @1@ $query_text
ORDER BY blend_score DESC
LIMIT 10;

That single statement does what would take four or five round-trips across a fragmented stack: permission checks, temporal filtering, graph traversal through the customer's actual product relationships, and hybrid vector + full-text ranking. One query. One transaction. One consistent snapshot. The line that does the most work is the graph traversal: $customer->owns->product->has_issue->knowledge_base. That is not a join. It is a native graph traversal across edges, and it means the agent only sees knowledge base articles connected to the specific products this customer actually owns. Everything else is excluded before similarity even runs.

Two reasons fragmented stacks kill accuracy

Microsoft's GraphRAG work (Edge et al., 2024) demonstrated the same principle at the retrieval level: combining graph structure with similarity search significantly outperforms vector-only approaches. The CoALA framework (Sumers et al., 2024) describes it architecturally: agent memory must be consistent and accessible within a single reasoning cycle. A multi-model database that handles all data models under one transaction boundary is the simplest way I know to actually do both.

This gets you to roughly 90–95% accuracy on large corpora. The consistency gaps are gone. The retrieval noise is way down. For many use cases, this is enough.

But for agents that need to operate autonomously, make consequential decisions, or run in production without human oversight, the last 5–10% is where the difference between "mostly works" and "deterministic" lives. Closing that gap requires a different kind of mechanism.

Getting to ~99%+: reasoning graphs and retrieval graphs

Scope-first retrieval fixes the shape of the funnel. Reasoning and retrieval graphs fix the funnel itself. They are the mechanism that turns a static retrieval pipeline into one that learns from its own results, and in my experience they are the single biggest differentiator between agents that are "pretty good" and agents that are genuinely deterministic.

Every time an agent runs a retrieval pipeline and makes a decision, two graph structures get written in the same transaction as the action: a reasoning graph (the agent's decision and the evaluated edges for each piece of evidence it considered) and a retrieval graph (the operational details of how context was retrieved).

I want to be specific about what these are. They are not log entries. They are not analytics events. They are graph edges stored in the same database as the data they describe, connecting the agent, the action, the customer, and the evidence records the agent evaluated. Written atomically with the agent's action and fully traversable with the same query language you use for everything else. ACID-guaranteed edges in the same graph your agent operates on. This is exactly why SurrealDB is a graph-native multi-model database: the reasoning and retrieval graphs have to be part of the same graph as the documents, the relationships, the vector embeddings, and the agent state, all under one transaction boundary. If they are not, the causal link between "what was retrieved," "how the agent reasoned about it," and "what it decided" breaks.

The reasoning graph is a set of edges radiating from the agent. A decided edge connects the agent to the action, carrying confidence and the eventual outcome. But the reasoning itself is not a field on that edge. Each step of the agent's logic is its own evaluated edge connecting the agent directly to the evidence it considered: agent->evaluated->kb:4821 with a verdict (used or rejected), the reason, and how much it moved the agent's confidence. The reasoning is not a string or an array. It is a set of traversable edges connecting the agent to every piece of evidence it touched. The retrieval graph is a retrieved_via edge from the action back to the customer, carrying which scope filters were applied, the graph path traversed, the candidate count before and after scoping, whether the top result was relevant, and the retrieval latency.

Anatomy of the Reasoning and Retrieval Graphs

Every reasoning step and every retrieval detail is a graph edge. Traversable, not buried in strings.

The reason the reasoning has to be a graph, not a field, is that the pipeline planner needs to traverse individual evaluation steps across thousands of runs. If kb:2201 gets rejected in 94% of firmware queries, the planner can only discover that by traversing evaluated edges, not by parsing strings in a log. In SurrealQL, this is what the actual transaction looks like. The action is a node. The reasoning and retrieval are edges, created with RELATE, connecting the agent to each piece of evidence and the action back to the customer:

BEGIN;

CREATE support_action:escalate_7291 CONTENT {
  action: 'escalate_to_engineering',
  customer: customer:acme,
  ticket: ticket:9913,
  created_at: time::now()
};

RELATE agent:support_tier2->decided->support_action:escalate_7291 CONTENT {
  confidence: 0.94,
  created_at: time::now()
};

RELATE agent:support_tier2->evaluated->kb:4821 CONTENT {
  action: support_action:escalate_7291,
  step: 1, verdict: 'used',
  reason: 'Identical symptoms on same SKU',
  confidence_delta: 0.3
};

RELATE agent:support_tier2->evaluated->kb:2201 CONTENT {
  action: support_action:escalate_7291,
  step: 2, verdict: 'rejected',
  reason: 'Wrong product line',
  confidence_delta: 0
};

RELATE agent:support_tier2->evaluated->kb:5540 CONTENT {
  action: support_action:escalate_7291,
  step: 3, verdict: 'rejected',
  reason: 'Issue resolved, no longer active',
  confidence_delta: 0
};

RELATE support_action:escalate_7291->retrieved_via->customer:acme CONTENT {
  scope_filters: { type: 'support', tenant: 'acme', max_age: '30d' },
  graph_path: 'customer:acme->owns->product:x100->has_issue->kb',
  candidates_before: 2847331,
  candidates_after: 14,
  top_result_relevant: true,
  latency_ms: 8.2,
  created_at: time::now()
};

COMMIT;

The decision logic is not buried in strings. Every reasoning step is an edge in the graph. The decided edge connects the agent to the action. Each evaluated edge connects the agent to a specific piece of evidence it considered, carrying the verdict, the reason, and the confidence delta. The retrieved_via edge connects the action back to the customer with the retrieval metadata. The evaluated edges are not magic. Your agent framework already evaluates candidates and produces a decision. The RELATE statements just persist what the agent already computed. The only design requirement is that your agent emits structured evaluations per candidate rather than a single monolithic response.

That graph structure gives you something most teams have never had: you can replay any agent run, traverse the exact reasoning it followed, and identify exactly where and why it went wrong. But the real value is what happens when the reasoning and retrieval graphs feed back into the system. And they feed back in two different ways, serving two different purposes.

The pipeline planner traverses the reasoning and retrieval graphs to decide what context the agent sees. This is structural optimization. The planner can start from kb:2201 and traverse all evaluated edges pointing at it across every run. If it discovers that kb:2201 gets rejected 94% of the time for firmware queries, it deprioritizes or excludes it from the candidate set for that query type. It can walk agent:support_tier2->evaluated->* to see every piece of evidence this agent has ever considered, grouped by action, filtered by verdict. It learns which retrieval patterns, graph paths, and scope filters correlate with correct outcomes and tightens the funnel accordingly.

The LLM itself receives relevant past reasoning edges as context to guide how it thinks about the candidates it receives. This is behavioral optimization. When the agent retrieves context for a firmware issue on product:x100, the system can also pull in past evaluated edges for queries in the same product category: "Last time an agent evaluated a firmware issue on this product line, it used kb:4821 (identical symptoms, same SKU) and rejected kb:2201 (wrong product line). That decision was correct." The agent is not just getting better candidates. It is getting guidance on how to reason about those candidates, grounded in what actually worked before.

Those two mechanisms work on different layers. The pipeline planner tightens the funnel so fewer, better candidates reach the agent. The past reasoning edges sharpen how the agent evaluates whatever reaches it. Together, they compress errors from both directions. This is different from a context graph, which stores world facts (this customer owns this product). The reasoning and retrieval graphs extend the context graph with behavioral facts: how agents reasoned, what worked, what did not. The pipeline planner and the LLM both walk all three layers.

The graph feedback loop

This is the critical shift. The reasoning and retrieval graphs turn retrieval from a static pipeline into a feedback loop. The funnel does not just narrow the data. It narrows itself. Every agent run produces decided, evaluated, and retrieval edges. Those edges inform the next pipeline plan. The scoping gets tighter. The graph paths get more precise. And because both graphs are written in the same transaction as the action, you have a causally consistent, traversable record of every decision the agent ever made, every piece of evidence it considered, and the retrieval path that produced it.

Let me walk through what this looks like concretely. On the first run for a given query type, the retrieval funnel starts with 2.8 million candidates and narrows to 14. The agent evaluates the top candidates, creating an evaluated edge for each one with a verdict and reason. It makes a decision. The decision turns out to be correct. The decided edge, the evaluated edges, and the retrieval edges all persist in the graph.

On the next similar query, both mechanisms kick in. The pipeline planner traverses past retrieval and reasoning edges. It knows the successful graph path. It knows which filter combination produced a good reduction ratio. It knows kb:2201 was rejected last time for being the wrong product line, so it excludes it from the candidate set entirely. The funnel goes from 2.8 million to 9 instead of 14. Meanwhile, the agent receives past evaluated edges as context alongside the candidates: "For similar firmware queries, kb:4821 was used because it described identical symptoms on the same SKU. kb:5540 was rejected because the issue was already resolved." The agent is not just seeing better candidates. It is seeing how a previous agent successfully reasoned about similar candidates.

After a hundred similar queries, the graph contains a rich web of evaluated edges for that query type. The planner can see, across all runs, which evidence records consistently get used versus rejected, which rejection reasons recur, and which evaluation patterns correlate with correct outcomes. The LLM, on every new run, gets the distilled reasoning patterns from the most relevant past decisions. The funnel is no longer exploring. The reasoning is no longer starting from scratch. Both layers are applying learned patterns. And the patterns are not summaries or statistics computed offline. They are live graph topology that gets traversed on every run.

This is what "deterministic" means in practice. Not that the LLM produces identical tokens every time. It means that given the same type of query, the system follows the same learned retrieval pattern, produces the same quality of context, and arrives at the same caliber of decision. The variability gets squeezed out of the data layer, which is where it was causing problems in the first place. The model can still be creative where creativity helps. But the retrieval is locked down.

The full retrieval funnel

Putting it all together, here is the complete pipeline from raw candidates to agent context, with graphs feeding back into pipeline planning.

After the agent acts, the decided, evaluated, and retrieval edges are written back, feeding into the next cycle of pipeline planning. The funnel self-tightens with every run.

Why the graphs break in a fragmented stack

There is one more thing worth making concrete, because it is easy to nod along with "you need one database" without feeling why.

Say your reasoning and retrieval edges write to Postgres, your vector embeddings live in Pinecone, and your graph relationships are in Neo4j. The pipeline planner needs to query: "for this query type, which graph paths and filter combinations correlated with correct decisions in the last 200 runs?" That query needs to join reasoning edges and retrieval edges in Postgres with graph topology in Neo4j and vector metadata in Pinecone. What transaction boundary covers all three systems? There is not one. So the planner is reading behavioral data that may or may not reflect what actually happened, referencing graph paths that may have changed since the edges were written, and correlating against outcomes that landed in a different system at a different time. The feedback loop is broken before it starts. You are building a learning system on top of eventually consistent quicksand.

That is why this architecture needs a multi-model graph database. Not because fewer databases is aesthetically nicer, but because the reasoning and retrieval edges need to live in the same graph as the entities they reference. The feedback loop is a graph traversal: walk from an agent through its decided edges, through its evaluated edges to each piece of evidence, follow the retrieval edges, compare outcomes. That only works when the reasoning and retrieval edges, the documents, the graph relationships, the vector embeddings, and the agent state all live in the same engine with the same transactional guarantees. SurrealDB handles all of this natively. This is the exact problem we designed it to solve.

Supporting research

Cognitive Architectures for Language Agents (CoALA) — Sumers, Yao, Narasimhan, Griffiths · 2024. Formalizes agent memory into episodic, semantic, and procedural types coordinated through a single decision loop. Reasoning and retrieval graphs map directly to CoALA's episodic memory: structured records of past actions that inform future decisions. The framework makes clear that scattering memory types across separate systems works against reliable agent behavior.

From Local to Global: A Graph RAG Approach — Edge, Trinh, Larson, Truitt (Microsoft Research) · 2024. Demonstrated that combining knowledge graphs with retrieval-augmented generation significantly outperforms vector-only retrieval for complex queries requiring multi-hop reasoning and structured context.

Retrieval-Augmented Generation: A Survey — Gao, Xiong, Gao et al. · 2023. Identifies consistent failure modes in RAG at scale: top-k instability, chunk blending, precision degradation. Recommends constraining the candidate set before similarity search using structural filters and graph traversal.

Graph Retrieval-Augmented Generation: A Survey — Peng, Zhu, Liu et al. · 2024. First comprehensive overview of GraphRAG, formalizing how graph-based indexing, retrieval, and generation improve accuracy and context-awareness over similarity-only approaches.

Conclusion

Near-perfect agent accuracy comes from two things working together. A retrieval pipeline that scopes candidates using structural filters, temporal constraints, graph traversal, and business rules before similarity ranking, all within a single ACID transaction. That gets you to roughly 90–95% on large corpora by eliminating the consistency gaps and retrieval noise that cause most agent failures.

And reasoning and retrieval graphs stored as edges in the same transaction as the agent's action, feeding back into the pipeline so the funnel tightens with every run. That is what closes the gap to 99%+.

Neither works if your data models are split across separate systems. The scope query cannot compose and the feedback loop breaks unless everything shares one transaction boundary. That is why we built SurrealDB.

On the first run, 2.8 million candidates narrowed to 14. A few hundred runs later, it narrows to 9, then 6, each time more precise, each time learning from the last. That is what deterministic accuracy looks like in practice: agents that do not just perform well on average, but get better with every decision they make.

References

Sumers, T.R., Yao, S., Narasimhan, K., & Griffiths, T.L. (2024). Cognitive Architectures for Language Agents. Transactions on Machine Learning Research.
Edge, D., Trinh, H., Larson, J., & Truitt, S. (2024). From Local to Global: A Graph RAG Approach to Query-Focused Summarization. arXiv:2404.16130.
Gao, Y., Xiong, Y., Gao, X., et al. (2023). Retrieval-Augmented Generation for Large Language Models: A Survey. arXiv:2312.10997.
Peng, B., Zhu, Y., Liu, Y., et al. (2024). Graph Retrieval-Augmented Generation: A Survey. arXiv:2408.08921.

DEV Community: SurrealDB

Using SurrealDB to understand how Buffalo buffalo buffalo Buffalo buffalo

Buffaloes that buffalo Buffalo buffaloes

Buffaloing back

Visualising all the buffaloing

Learn more

Ready to try it?

Detecting connections as they form: An introduction to streaming graph pattern matching

Detecting connections as they form: An introduction to streaming graph pattern matching

🕸️ What is a labeled property graph?

⚡ What is streaming graph pattern matching?

🎬 A running example: the movie database

🗂️ Imagining the configuration

Sources — loading the graph

filter — Row-level gating

record_id!() — Typed identifiers

+ @ — Creating a vertex

+ @from->edge->@to — Creating an edge

Patterns — Matching the graph

Aliases and join conditions

Actions — Deriving new edges

Output projections

More pattern expressiveness

🔄 What would it look like to run this?

🧠 Why this configuration style?

👉 TL;DR

Introducing Scale: SurrealDB Cloud, built for high availability and scale

What you get with Scale

Built on SurrealDS

Architecture overview

Future roadmap

Get started

Bring SurrealDB to your Replit Agent

What you'll need

How SurrealDB, MCP, and Replit fit together

Step 1: Install or upgrade to SurrealDB 3.1

Step 2: Start your instance and create some data

Step 3: Enable the MCP server over HTTP

Step 4: Make your instance reachable

Connect SurrealDB to Replit

Build an app on your SurrealDB data with Replit

SurrealDB MCP tools reference

Production considerations for SurrealDB with Replit

Where this leaves you

What's new in Surrealist 3.9

Highlights

Complete design overhaul

New datasets browser and data manager

Improved record inspector

Full changelog

SurrealDB is now available on the Nebius AI Cloud Marketplace

Why Nebius?

Why SurrealDB?

Get started

SurrealDB 3.x by the numbers

One engine, multi-workloads, full durability.

Why we ran these

About last time

How far SurrealDB has come

How we compare to other databases

vs. PostgreSQL (and MySQL)

vs. MongoDB (and ArangoDB)

vs. Neo4j (and ArangoDB)

Reference point: Redis and KeyDB

Embedded mode (vs. SQLite)

Closing the remaining gaps

Why this matters for AI agents

What's next

SurrealDB 3.1: stability, DiskANN, and a new release process

What's new in 3.1

DiskANN approximate-nearest neighbour index

GraphQL: aliases, cursor pagination, and multi-model filtering

Improved in-memory performance

Stability and correctness

Security hardening

Enterprise: audit logging and slow-query pipeline

Other quality of life additions

A new release process

Try it

Kreuzberg & SurrealDB: from unstructured documents to hybrid retrieval

`filter` — Row-level gating

`record_id!()` — Typed identifiers

`+ @` — Creating a vertex

`+ @from->edge->@to` — Creating an edge