Key concepts at a glance
A short tour of the structures and rules KDBS is built on, with a link to the full page for each.
In this article
KDBS uses its own names for several structures, because they are not the standard ones. This page gives each core concept in two or three sentences and links to its full page. Read it once before the concept pages; it gives you the vocabulary they use.
The trust ladder
Four structures can lead a query to a row. They differ in how far the engine is allowed to believe them, not in speed.
| Structure | Authority | Cost on each write | Can be dropped | If an entry is wrong |
|---|---|---|---|---|
| Primary-key B+ tree | Always authoritative | Maintained on every write | Never | Corruption |
| Secondary index | Authoritative, covers every row | One append | Whole index (DROP INDEX) | The statement fails |
| Cabin | Authoritative for the values it has observed | Probe and append, observed values only | One value at a time | The value is un-observed; queries scan |
| Waystone trail | Never authoritative (advisory) | None | Whole store | A miss; the authoritative path runs |
Correctness never depends on the bottom three. Delete every Cabin and trail and every query returns the same rows, only slower. This is why the engine can learn from the workload without risk to results.
Row identity: the Keystone
Every row carries a 64-bit identity word called the Keystone. Its id part is the row’s primary key: an integer from 1 to 2⁴⁸ − 1. An INSERT either supplies the key or leaves it out and the engine issues one. A committed key is never reissued, even after DELETE, unless an explicit PURGE frees it, and the primary key cannot be updated.
See Row identity and primary keys.
Tables and B+ tree storage
Every table is stored as a clustered B+ tree on the primary key, in 8 KiB pages. Every row in a table has the same fixed length, so an UPDATE never moves a row. A variable-width value takes one fixed-size cell (64 bytes by default) and longer values spill into a separate store. Creating the older HEAP storage form is refused.
See Tables and storage.
Statements compile to a fixed plan
Each statement is compiled when it is parsed into a step chain: an ordered list of lookups, probes and scans that runs in the order you wrote it. There is no plan search. The statement’s shape gets a pattern_id, and a pattern_id names one plan forever, whatever the table sizes. You can list the shapes the database has seen with SHOW PATTERNS.
See Statements and execution plans.
Transactions and MVCC
KDBS keeps older versions of rows (multi-version concurrency control, MVCC), so readers see a consistent snapshot without blocking writers. The default isolation level is READ COMMITTED; REPEATABLE READ is available per session or per transaction. When two transactions write the same row, the second one is refused with a retryable TXN_CONFLICT, and the client rolls back and retries.
See Transactions and isolation.
Write-ahead log and durability classes
Each instance has one write-ahead log (WAL): changes are logged before the data pages are written. Each transaction picks a durability class: strict (the reply waits for the commit record to reach the device), group (the same guarantee, with device syncs shared by concurrent commits) or relaxed (the reply does not wait, with a bounded loss window). Recovery runs when the database is mounted.
See Durability and the write-ahead log.
Assertions
An assertion declares an upper bound per group of rows, on COUNT(*) or SUM(column). The engine checks it before it admits each write, against a running total, so the check costs the same whatever the group size. A write that would break the bound is refused with ASSERTION_VIOLATION.
See Assertions and CREATE ASSERTION.
Foreign keys
A column declared REFERENCES <parent_table> must name an existing row of the parent table by primary key. The engine checks this when the child row is written, and it refuses a parent DELETE while live children reference it. A violation is refused with FK_VIOLATION.
See Foreign keys.
Secondary indexes
A secondary index covers every row of a table, on one or more columns, and can be covering. It serves the searches that a trail may never replace. UNIQUE indexes are refused: an index speeds up reads and never makes a write fail.
See Secondary indexes and CREATE INDEX.
Cabins
A Cabin is a lookup store on one column of one table that tracks only the values queries have actually asked for. For a value it has observed, it is complete, so an empty answer is a real “no rows”. Dropping an observed value only sends queries for it back to a scan. Cabin entries live in memory and are rebuilt by traffic after a restart.
See Cabins and CREATE CABIN.
Waystone trails
When the same query with the same arguments runs again, the engine records a trail: the rows the previous run touched and where it found them. A later run may use a trail in place of a key lookup, but never in place of a search, because a trail cannot show that a newer row is missing. Every entry is checked before use, and a miss falls back to the normal path.
See Waystone trails.
Physical optimizer
Besides choosing how a statement runs, KDBS decides which lookup structures should exist. The built half, the Cabin controller, creates, extends, repairs and drops Cabins from workload statistics within a page budget; it is off by default (cabin_optimizer = off), and SHOW CABIN_OPTIMIZER shows each decision. The other half, relayout, only reports in SHOW RELAYOUT and moves no data.
See Physical optimizer.
Thread-per-core execution
The server runs one scheduler loop (reactor) per configured core. Every statement runs to completion on the core its session is on, and a session may move to a less busy core between transactions. All cores share one buffer pool and one write-ahead log.
See Thread-per-core execution.