Storage model

Every table is split into tablets. Each tablet has one owner that orders its commits, writes them to a local write-ahead log (WAL), and acknowledges a write only once it is durable. The table's physical layout — row-oriented, columnar, or both — is chosen per table with STORAGE PROFILE.

Commit and durability

• One owner serializes each tablet's commits. Each commit carries the owner epoch, a commit sequence and a hybrid logical timestamp.
• Records go to a local WAL that is segmented and checksummed. Concurrent commits are written together in groups, behind one persistence barrier per group (group commit).
• A write is acknowledged only after its WAL group is durable, and committed changes are published to consumers through PSI only after that.
• Each database runtime has a set of WAL shards. Every tablet maps to one shard by a stable hash.

On restart, a tablet replays its WAL suffix on top of its last checkpoint and repairs a torn tail record if the process stopped mid-write. The operator view of this is on Durability and recovery.

Storage profiles

STORAGE PROFILE is a table trailer that expands into the table's physical projections:

The expansion applies to each kind of state the table keeps: its current rows (UPSERT and VERSIONED tables) and its retained history (APPEND and VERSIONED tables).

CREATE TABLE token_metadata (
  chain_id UINT16 NOT NULL,
  token STRING NOT NULL,
  symbol STRING NULL ENCODING LOW_CARDINALITY,
  decimals UINT8 NULL,
  PRIMARY KEY (chain_id, token)
)
MODE UPSERT
SHARD BY (token) SHARDS 4
STORAGE PROFILE ROW;

Column encodings and codecs

Each column may declare how its values are encoded and compressed in column blocks:

<column> <type> … [ENCODING PLAIN | LOW_CARDINALITY]
                  [COMPRESSION NONE | LZ4 | ZSTD | CODEC(<stage>[(<int>, …)], …)]

• ENCODING LOW_CARDINALITY stores repeated values through a dictionary.
• CODEC(…) is a chain of stages applied in order. The stages are NONE, Delta, DoubleDelta, GCD, T64, Gorilla, FPC, LZ4, LZ4HC and ZSTD, where ZSTD(<level>) takes a level. A chain is checked against the column type.
• COMPRESSION NONE | LZ4 | ZSTD is the one-stage shorthand of CODEC.

CREATE TABLE transfers (
  chain_id UINT16 NOT NULL CODEC(Delta(2), ZSTD(1)),
  token STRING NOT NULL ENCODING LOW_CARDINALITY,
  sender STRING NOT NULL CODEC(ZSTD(1)),
  recipient STRING NOT NULL CODEC(ZSTD(1)),
  amount UINT256 NOT NULL CODEC(ZSTD(1)),
  transferred_at DATETIME64(3, 'UTC') NOT NULL CODEC(DoubleDelta, ZSTD(1)),
  _index UINT128 NOT NULL CODEC(ZSTD(1)),
  INDEX transfers_ts (transferred_at) USING MINMAX SCOPE HISTORY GRANULE 8192
)
MODE APPEND
SHARD BY (token) SHARDS AUTO
PARTITION BY MONTH(transferred_at)
ORDER BY (chain_id, token, _index)
STORAGE PROFILE COLUMNAR;

system.table_column_codecs lists the codec chain of every column and whether it was declared explicitly.

Policy bindings

Every table is bound to policies, one per role: placement, storage, retention, compaction, projection storage and residency, and index storage and residency. Named policies attach with … POLICY <name> on a table or an index, and system.table_policy_bindings lists the bindings. Retention policies expire rows by age, and storage policies tier data between local devices and object storage.

Related

• Durability and recovery
• Storage operations
• Indexes
• CREATE TABLE