---
title: "How one SurrealQL query scans 10 billion rows a second"
description: "SurrealDB Earth splits one query into morsels, runs them on about 1,000 Workers reading R2, and merges one snapshot-consistent answer."
url: https://surrealdb.com/blog/how-one-surrealql-query-scans-10-billion-rows-a-second
date: 2026-11-17
authors: "Tobie Morgan Hitchcock"
---

# How one SurrealQL query scans 10 billion rows a second

![How one SurrealQL query scans 10 billion rows a second](https://cdn.surrealdb.com/sa6rpoogao26n8zxx5ra7sv1.auto)

SurrealDB Earth reaches more than 10 billion rows a second by splitting one SurrealQL query into many small pieces of work, running them on around 1,000 Cloudflare Workers at the same time, and merging the results into one answer that reads the whole database at a single moment. This post explains each step of that path. Earth launched on 3 November 2026, alongside SurrealDB 4.

## What is Earth built from?

Earth runs SurrealDB's own code on four building blocks of Cloudflare's platform:

| Cloudflare building block | What it is | What Earth uses it for |
| :-- | :-- | :-- |
| Worker | A short-lived, stateless function that runs in its own isolate, a lightweight sandbox | Leaves, which read data during a scan |
| Durable Object | A single-threaded object with a fixed identity and its own small storage | The executor, the sequencer and the openers, which hold state that needs one strict order |
| R2 | Cloudflare's object storage, similar to Amazon S3 | Runs, the immutable files that hold the database's data |
| Colo cache | The cache in each Cloudflare data centre ("colo" is short for colocation facility) | Keeping recently read parts of runs close to the leaves |

A Durable Object and an R2 object are unrelated despite the shared word. A Durable Object is a running program with state, and an R2 object is a stored file.

Everything else in this post is SurrealDB: the query engine, the roles below, the way a scan is cut into pieces, and the checks that make the result correct.

## What happens when one query fans out?

A single executor receives the query, runs the SurrealDB engine, and decides whether the scan is too large for one isolate. If it is, the executor cuts the scan into **morsels**, which are key ranges of the table, and sends them down a tree of openers to stateless leaves. The film on the [SurrealDB Earth page](https://surrealdb.com/earth) titled "One query. Thousands of compute units. One answer." shows this fan-out, and the scan in it read about 50 billion rows.

```mermaid
flowchart LR
  C[Client] --> E[Executor Durable Object]
  E --> N[Opener Durable Objects]
  N --> L[Leaf Workers, around 1,000 at once]
  L --> R[(Runs in R2)]
  S[Sequencer Durable Object] -. snapshot and tail .-> E
  L -- verified streams --> N
  N --> E
  E --> C
```

Each role does one job:

| Role | Runs as | Job |
| :-- | :-- | :-- |
| Executor | Durable Object | Runs the engine, holds the transaction, pins the snapshot, plans the scan and merges the results |
| Sequencer | Durable Object | Gives every commit its place in one order, and holds recent small commits until they are written to R2 |
| Opener | Durable Object | Passes a group of morsels to leaves and streams their answers back |
| Leaf | Worker | Reads one morsel from R2 and streams back rows or partial results |
| Run | R2 object | Immutable, sorted data that leaves read directly |

The sequencer holds recent commits in its Durable Object's own storage, which Cloudflare builds on SQLite. That storage is only a short-term holding area for commits before they are written to R2 as runs. The SurrealDB engine runs every query, and the data that a scan reads comes from the runs in R2.

## How is the snapshot chosen?

The scan reads at the snapshot of the open transaction, and a reader lease keeps that snapshot available throughout the scan. Before it serves a fresh read, the executor asks the sequencer for its latest position and waits until it has applied every commit up to that position.

The executor then fixes a snapshot position and builds each morsel request from three things:

1. The key range of the morsel.
2. The run list at that position, which is every run whose first position is at or below it.
3. The tail, which is the commits accepted after the last write to R2 and up to the snapshot, limited to the morsel's key range.

Because every leaf receives the same position, the same run list and its part of the same tail, each leaf sees the database exactly as it was at one moment. Commits that arrive after the snapshot are invisible to every morsel. The tail travels with the request, so a leaf never has to call back to the executor for it.

The sequencer keeps a history floor that only rises, and it never lets the floor pass the oldest snapshot that an unexpired lease holds. A scan therefore reads the same runs from start to finish, even while compaction and new commits continue.

## What do the leaves do?

Each leaf is a Worker that runs in its own isolate. Earth deploys the same leaf code under many script names so that calls spread over many isolates. In the measurements below, 1,024 calls landed on 1,016 to 1,024 separate isolates.

A leaf receives a morsel request on `POST /morsel`, an internal endpoint of Earth's leaf code. It reads its key range from R2 through the colo cache, merges the tail in by position, and streams the results back with running counts of rows and bytes. An aggregate such as a count returns as a partial result, and the executor adds the partial results together.

## How wide does the tree get?

An executor cannot manage a thousand connections at once, so openers sit between it and the leaves. A few limits keep each part of the tree to a size that one object can manage:

- Each node passes work to at most 32 children.
- By default, the executor sends work through 6 openers.
- A read keeps at most 64 R2 requests in progress at once.

To reach more leaves, the tree adds levels instead of making any one node wider. In the measurements below, 16 openers each fed 8 nodes, and each of those fed 8 leaves, which gives 1,024 leaves at once. Each leaf takes its next morsel when it finishes one, so a scan can have many more morsels than there are leaves.

## How do results merge into one answer?

Morsels cover separate key ranges in ascending order, and together they cover the whole scan range. Verified rows can therefore be released in key order without a sort. Counts add up correctly because every key falls in exactly one morsel and is counted once, from a verified stream.

The executor verifies every morsel before it releases a row. The stream must have consecutive sequence numbers starting from zero, running row and byte counts that match what arrived, and a final frame whose totals equal the rows, bytes and frames received. A stream that is missing, incomplete or inconsistent, or an opener that stops answering, fails the check, and the morsel runs again through another opener.

A morsel gets up to 3 attempts, and each attempt may take up to 8,000 ms. A morsel that never verifies fails the whole scan, so Earth never returns a partial answer.

Slow leaves are hedged. Once every morsel has started, a morsel whose leaf is slower than a threshold is also given to an idle leaf, and the first verified answer wins. In the measurements below, hedging reduced the median time for a count over 10 million rows with 1,024 leaves from 751 ms to 537 ms.

## Why does the scan scale with the number of leaves?

Durable Objects hold the state that has to stay in one order. The sequencer gives every commit its place in one order, and the executor holds sessions, the transaction and the dispatch logic. Openers are a pool of Durable Objects that limits how many connections the executor manages.

R2 holds all the data that has been written into runs. Runs never change, so neither the executor's cache nor the colo cache ever needs invalidating, and every leaf reads the same bytes without coordinating with any other. Leaves hold no data and no state, so any of them can stop in the middle of a scan, and the verifier turns that into a retry.

No node owns a part of the data, so adding more leaves needs no data to move. That is why scan throughput grows with the number of leaves while the data stays in object storage.

## What do the measurements show?

The figures below come from a round of measurements in October, during the run-up to Earth's launch, on a development deployment. The table had 10 million rows of 100-byte values.

| Leaves | Query | Median wall time | Rows per second |
| :-- | :-- | :-- | :-- |
| 64 | 1 in 10,000 rows selected | 4,228 ms | 2.4 million |
| 256 | 1 in 10,000 rows selected | 1,775 ms | 5.7 million |
| 1,024 | 1 in 10,000 rows selected | 849 ms | 12.4 million |
| 1,024, hedged | count | 537 ms | 29.1 million |

The scan rate grows with the number of leaves, while the slowest leaves (the 99th percentile) stay near 350 ms. Past 1,024 leaves, throughput on this small table falls, because each morsel shrinks to a few milliseconds of work.

The figure of more than 10 billion rows a second comes from the launch deployment on a far larger table, which is the size of scan that the tree and morsels were designed for.

## Where is the limit, and what comes next?

The executor is the next limit. Each morsel costs about 4 ms of the executor's single thread, which caps a scan of small morsels at about 200 to 280 morsels a second. Planning also takes time, because the executor reads run indexes to decide where morsel boundaries go. The next step is to move planning and the carrying of results from the executor into the node levels of the tree, so that the executor does less work for each morsel.

We are also working on these improvements to Earth:

- **Faster cold starts.** A cold start currently takes about 300ms, and we are working to bring that down.
- **Database branching.** Branching is coming to Earth, where R2 does much of the work.

The [SurrealDB Earth documentation](https://surrealdb.com/docs/manage/instances/earth) covers how to deploy an instance and how usage is measured, and the [SurrealDB 4 release notes](https://surrealdb.com/releases) list everything that shipped on 3 November 2026.

[Start free on Earth](https://surrealdb.com/earth)
