BQL · TachyonDB

✅ What is live today

Authoritative source: TachyonDB PROTOCOL.md. Two builds speak the same wire: tachyon8 (ARM64) and tachyond (x64). Page put/get tests are green on Snapdragon.

🔷 BQL is binary, not interpreted

Unlike SQL or JSON query languages that rely on text parsing, tokenization, and AST generation, BQL encodes operations as binary bytecodes. Common commands occupy just 1 byte (0x00–0xFE). There is no runtime lexical analysis — the byte stream is executed directly via a 256‑entry jump table.

// SQL (text): dozens of bytes, needs parsing
"SELECT name FROM players WHERE health > 50"

// BQL: push value, set field, compare, scan — raw bytes
PUSH_I32 50 · FIELD health · GT · ALL · GET name · END
// No lexer. No keyword table. Opcode → handler.

Why it matters: cycles spent on string comparisons, keyword recognition, and grammar validation disappear. BQL opcodes map directly to native handlers (jmp [op_table + rax*8] on the hot path).

🔌 Wire protocol (TYDB)

1. On connect, server sends one length‑prefixed handshake frame: u32le length (= 12) + payload u32le magic='TYDB' (0x42445954), u8 version=1, u8 pad[3], u32le features=0.
2. Every subsequent message is a frame: u32le length + payload.
3. Client request payload = raw BQL bytecode (no text wrapper).
4. Server response payload: u32le status · u32le row_count · repeated ChannelData cells [u8 type][u32le len][len bytes].

Little‑endian throughout. Single‑threaded server; many concurrent clients via select().

Status codes

Index / buckets

Default branch width = 24 → 16,777,216 buckets. Bucket entry = 4‑byte arena offset → 64 MiB table (offsets address a 4 GiB arena; collision chains live in the arena). Integer keys use the low 24 bits; other keys fold with FNV‑1a to 24 bits.

📖 1‑byte opcode map — TachyonDB (authoritative)

Every opcode triggers a precompiled handler. Dispatch is a 256‑entry jump table — no string switch.

// Intent: GET field where value > 50, then END
// SQL text:  "SELECT name FROM players WHERE health > 50"  → ~40+ bytes of ASCII
// BQL bytes: PUSH_I32 + FIELD + GT + ALL/GET pattern + END → a handful of bytes
// Exact length depends on field/type encoding — the win is zero parsing + tiny wire.

🔌 Extended 16‑bit opcodes (after 0xFE)

Rare / admin operations stay off the hot 1‑byte path. Prefix with OP_EXT (0xFE), then a little‑endian 16‑bit code.

// FLUSH snapshot — 3 bytes
[0xFE] [0x05] [0x00]   // OP_EXT + 0x0005 little-endian

// JOIN — 3 bytes + args
[0xFE] [0x01] [0x00]   // OP_EXT + 0x0001

Tradeoff: keeping rare ops in the 16‑bit escape leaves the common case lean without capping future commands.

📄 Pages — URLChannel / BML bodies

Page bodies are stored as DATA_BYTE_ARRAY (type 8) keyed by a UTF‑8 path. Internal type id for page records is 0xFE (not a wire ChannelData code).

Typical sequence (after handshake + AUTH)

1. PAGE_PUT path + body → status 0
2. PAGE_GET same path → status 0, cell type=8, bytes identical
3. Missing path → status 4 (NOT_FOUND), no cell
4. EXT FLUSH then restart → same PAGE_GET still returns the body (snapshot)

Empty bodies (body_len=0) are valid. Tested sizes include 0, 100, 16348, 16349, 70000, and 1 MiB. Bodies larger than max_page (config default 16 MiB; clamped 64 KiB..64 MiB) return status 13 (TOO_LARGE). Per‑connection I/O buffers start at 8 KiB and grow on demand. Frames prefer one TCP segment (TCP_NODELAY).

📦 ChannelData — type packing on the wire

Aligned with channels7 defines.h. On the Tachyon wire:

• Bits 0–4 = type code 0..31 (do not remap)
• Bits 5–7 = memory kind (HEAP / STACK / GPU / CLOUD / REGISTRY / PAGE)

Bits:  7     6     5     4     3     2     1     0
      +-----+-----+-----+-----+-----+-----+-----+-----+
      |   memory kind   |        type code 0..31      |
      +-----+-----+-----+-----+-----+-----+-----+-----+

BML / page bodies use DATA_BYTE_ARRAY (8) keyed by path. Zero string conversion on the hot path — the type byte selects the handler.

📏 Compactness vs SQL strings

SQL sends human‑readable keywords as ASCII/UTF‑8. BQL replaces each keyword with a 1‑byte opcode. Result: much smaller wire payloads and zero parsing cost on the server.

Qualitative wins that matter in practice: smaller frames on constrained links, predictable latency (no planner surprises), and no SQL‑injection surface because there is no SQL string to inject into.

📊 Measured — Tachyon PAGE vs SQLite BLOB (Snapdragon)

Real numbers only · 25 September 2026 · DESKTOP-2QI0DQ0 · Snapdragon 7c Gen 2 @ 2.55 GHz · Windows on ARM · native ARM64 tachyon8 + benches (not x64 emulation).

Wire / server only Cont, URLChannel, and the Display sit above these numbers — do not quote this table as end‑to‑end Cont throughput.

Fair page/BLOB store comparison: Tachyon = persistent TCP loopback + BQL PAGE_* on 127.0.0.1:7447. SQLite = in‑process library (file WAL or :memory:) — no socket. This is not a SQL‑parse contest and not the same IPC.

n=2000 (1 MiB: n=200); 50 warm‑up ops discarded; SQLite 3.42.0, journal_mode=WAL, synchronous=NORMAL.

Earlier Linux‑native loopback baseline (different CPU): PAGE_GET 4 KiB ≈ 5307 ops/s, p50 0.059 ms — Snapdragon 7c Gen 2 is slower as expected. Full raw log kept with the publish tree.

⚙️ Execution: 256‑entry jump table

The BQL VM uses a static array of handlers. Fetching an opcode becomes a single indexed jump. On x64/ARM64 assembler builds this is literally jmp [op_table + rax*8]. The table fits in a few KB and stays L1‑friendly.

typedef void (*bql_handler)(VMState*);
static const bql_handler dispatch[256] = {
    [0x00] = op_nop,
    [0x01] = op_get,
    [0x02] = op_put,
    [0x03] = op_all,
    [0x33] = op_page_put,
    [0x34] = op_page_get,
    [0xFE] = op_ext,
    // ...
};

while (!vm_halt) {
    uint8_t opcode = *vm->ip++;
    dispatch[opcode](vm);
}

Not interpreted in the text sense: there is no lexer, no grammar walk, no keyword strcmp. It is threaded binary code with a fixed opcode → handler map.

⚖️ Honest assessment — strengths & realities

🚀 Recommended next capabilities

Priority order for Cont / URLChannel / TachyonDB hardening. Each item earns its bit cost — frequency packing still rules.

🎯 Design philosophy

BQL embraces that machines speak binary, not English. One‑byte opcodes for the common case, 16‑bit EXT for the rare case, ChannelData packed so type selection is a branch — not a string compare.

• Compactness: 1 byte instead of keywords like “WHERE”.
• Zero‑cost abstraction: no parser, no grammar, no lexer — direct execution.
• Honest limits: AUTH, journal, and tooling called out above — not papered over.
• Same wire everywhere: ARM64 tachyon8 and x64 tachyond; page tests prove the contract.