Glossary

This page defines the terms used across the KDBS documentation. Several names follow a stone metaphor: a keystone holds a structure up, a waystone guides a traveler without being the road, and a cabin is a place someone has actually been. The engine’s own sources call the product “KDS”.

A

Access shape. One kind of access to a table, recorded as (kind, table, columns), such as a FilterScan of passengers on name. Values are never recorded. Read them with SHOW ACCESS. See Inspect the workload.

Advisory structure. A structure that can only speed a query up. Deleting it may cost performance but can never change a result. Waystone trails, access statistics and the relayout report are advisory.

ANALYZE. A prefix that runs a SELECT and reports what each step did: access kind, rows examined, pages read. See ANALYZE.

Assertion. A declared upper bound on COUNT(*) or SUM(column) for every group of rows in a table. The engine checks it before admitting each write. See Assertions.

Autocommit. The default mode: each statement outside BEGIN ... COMMIT is its own transaction. See Transactions and isolation.

B

Backup. A directory holding a copy of the data file, the log from the backup’s start to its stop, and a manifest. A base backup (path B) is copied by the server; a snapshot backup (path D) comes from a filesystem snapshot. See Back up and restore.

Borrow. A scoped right to a page or row: a lock, held for a transaction and waitable, or a latch, held for a short critical section. See Transactions and isolation.

Bound Cabin. The pinned, fully covering, logged Cabin that backs an assertion. It is outside the Cabin optimizer’s control. See Cabins.

Buffer pool. The in-memory page cache shared by all cores, sized by buffer_pool_frames in 8 KiB frames. See Server configuration.

C

Cabin. A store for one (table, column) that knows, for each value queries have observed, which rows hold it. It can answer “no rows” for an observed value without reading the table. Its contents live in memory and are rebuilt by traffic after a restart. See Cabins.

Cabin optimizer. A background controller that can create, extend, heal and drop Cabins for columns declared CABIN AUTO. Off by default. View it with SHOW CABIN_OPTIMIZER. See Physical optimizer.

Catalog view. A system relation under sys., such as sys.tables or sys.patterns, readable with SELECT. ORDER BY, joins and aggregates over a view are refused. See SHOW and DESCRIBE.

Checkpoint. The periodic write of dirty pages to the data file, every checkpoint_interval_ms. See Durability and the write-ahead log.

Core (reactor). One pinned thread that runs sessions. An instance runs cores of them. A statement runs on its session’s core from start to end. See Thread-per-core execution.

D

Decay score. The engine’s one time-weighting: a score that halves every decay_half_life seconds without use, computed when read. The relayout report and the Cabin optimizer use it.

Delete mark. What DELETE does to a row: it marks the row deleted and keeps its bytes for older snapshots. The row’s key stays used until PURGE frees it. See DELETE.

Durability class. When COMMIT returns: strict, group (default) or relaxed. Set per server, per session or per transaction. See Choose a durability class.

E

Epoch (page). A per-page counter that changes when the page’s rows are moved. Trail entries and Cabin hints record it, and a mismatch means the stored location is no longer trusted.

F

fetch_id. The id of a query pattern with its select list left out. ANALYZE prints it, and SHOW PATTERNS lists patterns by it.

Foreign key. A column declared REFERENCES <parent>, checked against the parent’s primary key on every write. Only RESTRICT behavior exists. See Foreign keys.

G

Group commit. The group durability class: commits that arrive together share one log sync. wal_mean_group_batch in SHOW META shows commits per sync.

I

Issued key. A primary key the engine assigns when an INSERT omits it. Issued keys ascend in the order they are issued. See Row identity and primary keys.

K

Keystone. The 64-bit word at the start of every row that holds its identity: a 48-bit id, 8 flag bits and 8 reserved bits. The id is the row’s primary key. See Row identity and primary keys.

KWP/1. The KDS Wire Protocol: length-prefixed binary frames with a handshake, optional SCRAM authentication, parse/bind/execute, and per-transaction durability. The default port speaks it. See Connect with the CLI.

L

Lineage. The id of a volume’s log history (wal_lineage in SHOW META). Every restore that opens takes a new one, so archived segments from different histories never collide.

LSN. Log sequence number: a byte position in the write-ahead log. A point-in-time restore takes an LSN as its target.

N

Namespace. A name that groups related tables, such as bookings.tickets. It does not scope names, transactions or storage; a table name is unique in the whole instance. See CREATE NAMESPACE, DROP NAMESPACE.

P

Pattern. The shape of a query with its values left out, identified by pattern_id. The engine registers patterns from traffic; they cannot be declared. See Waystone trails.

Physical optimizer. The part of the engine that watches access shapes and plans physical changes. Its relayout half runs in shadow mode and moves nothing. See Physical optimizer.

Point-in-time recovery. A restore that replays the WAL archive past a backup’s stop, up to a target LSN or to latest. See Back up and restore.

Poisoned transaction. An explicit transaction in which a statement failed. It accepts only ROLLBACK and a few session commands until rolled back. See Errors and refusals.

PURGE. The statement that removes deleted rows in a primary-key range and frees their keys for reuse. See PURGE.

R

Read view. The snapshot a statement or transaction reads from: per statement under READ COMMITTED, per transaction under REPEATABLE READ. See Transactions and isolation.

Relayout. A physical move the optimizer could plan, such as compacting or clustering a table. SHOW RELAYOUT reports candidates. Not built yet: no relayout is ever carried out.

Retryable. The retryable=1 flag on an error. Only TXN_CONFLICT carries it. See Errors and refusals.

S

Secondary index. An index on non-key columns of a table, with up to 4 key columns and 8 covered columns. Its entries hold primary keys. It speeds reads and cannot fail a write. See Secondary indexes.

Shadow mode. The default physical_optimizer setting: the planner computes its report when asked and changes nothing.

Step chain. The compiled form of a statement: an ordered list of steps run in the order the query is written. “The query is the plan.” See Statements and execution plans.

Superblock. Page 0 of the data file. It records the format version, inline_cell_width, the core count and the WAL anchors.

T

Trail. The recorded path of one pattern run: the rows a previous run touched and where they were. A trail can replace a lookup, never a search, and every entry is checked before use. See Waystone trails.

Transaction lifetime ceiling. The maximum age of an explicit transaction, txn_lifetime_ceiling_ms (default 60 s). Older transactions are rolled back by the server.

W

WAL (write-ahead log). The log every commit is written to before the data pages. One WAL stream serves the whole instance. See Durability and the write-ahead log.

WAL archive. A copy of every sealed log segment, kept by archive_dir or archive_command, used for point-in-time recovery. See Back up and restore.

Waystone. The advisory store of trails, reached through sys.patterns. It can be dropped whole without changing any result. See Waystone trails.