Cellular Compute Substrate

WASMComputeExecution

Stable On by default · production-ready

What it is

The cellular compute substrate is how AetheriusDB executes ordinary queries. Eligible queries run as WASM compute cells — this is the primary, production execution path for lowerable plans (Scan → Filter → Project → Limit). It is on by default and entirely transparent: you write normal SQL, and the engine routes it through a cell automatically.

Compute is allocated per connection. A lightweight worker spins up when a client connects and is reclaimed when it disconnects, so compute capacity scales with how many clients you have, not with how much data you store. With no clients connected, there is nothing running.

This is distinct from invoking a deployed cell by name. The substrate is the automatic path the engine takes for you and it is live today; the per-row CELL(...) invocation syntax is a planned surface the parser does not accept yet.

Why it matters

Co-locating compute with storage normally means client query spikes fight ingest and compaction for the same resources, and idle connections still hold memory. The substrate addresses all three:

• Compute scales with connections — workers are allocated per connection and reclaimed on disconnect; idle connections cost almost nothing.
• Reads only what can match — before a cell runs, the engine narrows to the rows that could satisfy the query, so the cell processes survivors rather than the whole table.
• Correct-or-fall-back — any query shape the cell path doesn’t support is served by the standard planner with identical results. There is never a correctness difference.
• Hard isolation — a cell that exceeds its budget fails cleanly without affecting the engine.
• Zero idle footprint — with no clients connected, the live-cell count returns to zero.

sequenceDiagram
  autonumber
  participant App as Client
  participant DB as Engine
  participant Cell as Compute cell

  App->>DB: connect
  DB->>Cell: allocate worker for this connection
  App->>DB: SELECT SUM(price) WHERE id >= 2
  DB->>DB: narrow to matching rows
  DB->>Cell: run against those rows
  Cell-->>App: result
  Note over App,Cell: idle → HIBERNATED → COLD
  App->>DB: disconnect
  DB->>Cell: reclaim worker

How you use it

You don’t — that’s the point. There is nothing to enable and nothing to call. Eligible queries route through the cell path automatically; everything else falls back. Today the substrate serves two families of query shape:

-- 1) Single-table aggregates route to a cell:
--    COUNT(*), and SUM / MIN / MAX over an integer or float column,
--    with optional comparison predicates.
SELECT SUM(price) FROM trades WHERE id >= 2;
SELECT MAX(price) FROM trades WHERE price >= 20.0;

-- 2) Two-table equi-joins on an indexed integer key run as an
--    ordered merge: INNER / LEFT / FULL, SELECT *, and a post-join
--    WHERE are all supported.
SELECT o.id, c.name
FROM orders o JOIN customers c ON o.id = c.id
WHERE o.total > 40;

-- See what's live right now (empty when no clients are connected):
SELECT cell_id, conn_id, state, lifecycle FROM system.compute_cells;

A query that doesn’t fit — multi-column join keys, nullable join keys, transactions — is handed to the standard planner with no client-visible difference. You can grow into the cell path simply by giving a join key a single-column index.

String projections (opt-in)

Opt-in Implemented · off by default — enable with AETHER_WASM_STRING

Alongside the numeric shapes above, the compiled path can also run an ASCII UPPER() / LOWER() projection over a text column. Unlike the automatic shapes, this one is off by default — start the server with the AETHER_WASM_STRING environment variable set to turn it on.

-- With AETHER_WASM_STRING enabled, a bare UPPER()/LOWER() projection
-- over a text column runs on the compiled path.
SELECT UPPER(name)  FROM customers;
SELECT LOWER(email) FROM customers;

Two things to know before you switch it on:

• ASCII only. The compiled string path folds case letter-by-letter over A–Z / a–z. For plain-ASCII text the result is identical to the ordinary UPPER / LOWER; for accented or non-Latin characters it is not — which is exactly why it stays opt-in.
• Bare projection only. It applies to a plain SELECT UPPER(col) FROM t. Add an ORDER BY, a WHERE, or more columns and the query runs on the standard path instead, with the normal fully-Unicode result.

Keep it off for non-ASCII text

Because the case fold is ASCII-only, enabling this flag changes the result of UPPER / LOWER on non-ASCII text. If any text column you query holds accented or non-Latin characters, leave AETHER_WASM_STRING unset.

Lifecycle & idleness

A connection can hold a worker for minutes between queries, so cells move through idleness tiers and reclaim resources while idle.

Tier	Meaning
HOT	Recently active; resident and answers immediately.
HIBERNATED	Idle a while; the instance is parked to shrink footprint, reactivated on the next query.
COLD	Long idle; the cell is released, its session metadata restorable on reconnect.

A connection can also hint how its cell behaves on disconnect:

Hint	Behavior
Ephemeral	Dissolve on disconnect (the default).
Sticky	Survive a short reconnect grace window for the same client.
Dedicated	Never auto-dissolve.

Observability

Three SQL views expose the live state:

View	What it shows
system.compute_cells	Per-cell live rows: id, connection, state, lifecycle, timing. Empty at idle.
system.compute_workers	Per-worker fleet introspection.
system.cell_lifecycle_policy	Per-client lifecycle overrides (Ephemeral / Sticky / Dedicated).

Notes & caveats

Index the join key

Give a join key a single-column index whose order matches storage order, and a two-table equi-join on it runs as an ordered merge automatically. Without it, the join still runs correctly — just on the standard hash-join path.

Multi-node distribution is separate

The in-process path on this page runs anywhere AetheriusDB runs. Distributing cells across multiple nodes is a separate, multi-node capability — see Compute Push — and carries its own availability badge.

WASM Compute Cells →

The cell programming model, and what runs today vs. what's planned.

Logic Registry & Deploy →

Deploy, version, and roll back the cells the substrate runs.

Configuration & Availability →

Tunables and what's on by default.

Query Data →

The SQL surface and how queries execute.