Storage format

Conventions

• Every integer is little-endian. u8, u16, u32, u64 are unsigned, i8 to i64, i128 and i256 are two's complement, f32 and f64 are IEEE 754.
• var_uint is unsigned LEB128: seven bits per byte, low bits first, the high bit set when another byte follows, at most 10 bytes, and the tenth byte is 00 or 01 so that the value fits a u64, and a writer emits the shortest form.
• A length or a count in metadata is a var_uint. Offsets and counts inside column data are fixed width, so a reader can index them without a scan.
• A name is a var_uint length followed by UTF-8 bytes.
• The checksum everywhere is CRC32C: polynomial 0x1EDC6F41, reflected, initial value and final xor 0xFFFFFFFF. The check value is crc32c("123456789") = 0xE3069283. Where one file records the checksum of another file that ends in a checksum, it records that file's trailer value, because the CRC of a file over its own CRC is always the constant 0x48674BC7.
• Every file, object and record starts with a 4-byte magic and a 1-byte version. A reader that meets a version it does not know refuses the file. A file is exactly one envelope and bytes after the trailer are an error, except in the S3 bundle, whose files follow its envelope by design.
• Every length, count and offset is checked against the bytes held and against the limits before a reader allocates or indexes.
• A time value is a UTC instant. A time zone in a type is a display attribute, so a change of the zone touches metadata and no stored byte.

The envelope Work in progress

Every file that is not a stream of records uses one envelope. A stream, such as a write-ahead log segment, uses it once at the head and its records follow the envelope's checksum.

An optional field's tag carries the must-understand bit in bit 0. A reader skips an entry with an even tag it does not know and refuses a file with an odd tag it does not know. Tags 0 and 1 are invalid. Each format assigns its own tags, and a field whose absence would change the meaning of the data gets an odd tag.

The codec block

Compressed bytes always sit behind this 20-byte header: every stream of a column block, a compressed write-ahead log insert record, and a compressed envelope body. The header names the chain that produced the payload, so a reader needs no other source for it.

Stages run in order on encode and in reverse on decode. A general compressor (lz4 or zstd) is the last stage and there is at most one; none is always the only stage; the payload of each stage is:

When a general compressor follows a stage whose output length the header does not record (rle, double_delta, gorilla), its payload starts with u32 intermediate_len, the length of the bytes it decodes to; after delta, which keeps the length, that length is raw_len. The width parameter of double_delta and gorilla lets a later reader level add 4-byte lanes; a level-1 reader refuses any value but 8.

A reader that meets an id it does not know refuses that stream with an unsupported-codec error. A new codec therefore costs an older reader one stream of one column in one granule, never the part.

The type descriptor

A column type is written in the ClickHouse binary type encoding: one id byte, the type's parameters, and the descriptors of its children for a composite. The ids are ClickHouse's own, so a type read from a ClickHouse Native export decodes with the same code. The table lists the ids the beta writer emits.

The prefix F0 followed by a var_uint extension id marks a muscles extension. Extension 1 wraps a ClickHouse AggregateFunction descriptor and says that the cells hold muscles aggregate states. No other extension is defined.

A reader that meets any other ClickHouse id, among them Variant, Dynamic, JSON, Nested and QBit, reports an unsupported type for that column, skips its bytes by the stream lengths, and reads the rest of the part. A later revision of this page defines their layouts; adding one adds an id and bumps no version.

Time types and their ranges: Date as u16 days ends on 2149-06-06 and DateTime as u32 seconds on 2106-02-07; Date32 and DateTime64 reach far past both. For Iceberg interchange, DateTime64(6) maps to timestamp, DateTime64(6, 'UTC') to timestamptz, and Date and Date32 to date.

The column encoding Work in progress

A column block holds n rows of one column as a list of streams, and each stream is its own codec block. A compression transform therefore sees exactly the bytes it expects: the values of a UInt64 column are a stream of 8n bytes with nothing in front of them. The same block appears in write-ahead log insert records, in the granules of a column file, in the dictionary file and in the primary index.

The compact form is for small log inserts, where a 20-byte codec header per stream would outweigh the values; a part never uses it. Stream kinds: 0 validity, 1 values, 2 offsets, 3 data, 4 indexes. A reader refuses a kind from 5 to 127 and may skip one from 128 to 255. The streams of a type come in a fixed order, depth first, and every count follows from a stream's raw_len, so there is no count field:

Values of the fixed-width types: integers two's complement; Date days since 1970-01-01 as u16, Date32 as i32; DateTime seconds since the epoch as u32; DateTime64(P) ticks of 10−P seconds as i64; a decimal as its scaled integer; IPv4 as the address value in a u32; IPv6 and UUID as the 16 bytes in the order their text form prints them; Bool as 0 or 1. There is no padding or alignment inside a stream.

Every stream has a path: the top level is empty, a tuple element is its ordinal, a map's key and value are key and value, an array's child is elem, and a nullable's child or a dictionary's element adds nothing. A LowCardinality nested in a composite has its own dictionary file, col-<id>.<path>.dict: Map(LowCardinality(String), LowCardinality(String)) in column 7 has col-7.key.dict and col-7.value.dict. The names col-<id>.<path>.bin are reserved for a later layout that stores one stream in its own file, so that a reader can fetch a map's keys or a null map alone. The beta writes every stream of a column into one file, and a reader ignores a stream file it does not expect.

Identities Work in progress

• A table has a 128-bit table_uuid, a UUID version 7 assigned at CREATE TABLE and kept across renames. Its lowercase 32-digit hex is the table's directory name.
• A column has a column_id u32, assigned from 1 when it is created and never reused by the table; the schema record carries the next id to hand out. Files, blocks and manifests name columns by id, so a rename touches no data file.
• A part has a 128-bit part_uuid, a UUID version 7 assigned when the writer opens it. Every file of the part carries it, so a file from another part fails the check even when the row counts agree.
• A row is (part_uuid, position), with the position a u64 below the part's row count. A part holds at most 2³⁶ rows and 2²⁶ granules, the most its marks, primary index and deletion vector can hold within their limits, and a merge that would pass either is not planned. Parts never change, so the pair holds until a merge rewrites the part, and the merge journal names the inputs. No row id is stored in the data.
• Every file and replication object names its writer, as a text such as muscles 0.1.0-beta.1, and a min_reader u16. Level 1 is this page. A writer raises the level only in a release that changes what existing bytes mean; an addition takes a new id or field instead, so a raised level is rare, and a file that exceeds a level-1 limit carries the level that allows it. A merged part carries the highest level among its inputs and the writer. A reader whose level is below min_reader refuses the file; a reader that knows a writer's defect can skip what that writer got wrong.

Write-ahead log Work in progress

Each table has its own log directory, <wal_dir>/<table_uuid>/, of append-only segments named wal-<seq>.wal with a 16-digit zero-padded sequence, so lexicographic order is segment order. A segment starts with the envelope, magic MWAL, version 1, with this body.

Record framing

Records follow the envelope's checksum, each in one frame.

A write is acknowledged after the frame is on disk and synced. On replay, an incomplete frame at the end of the last segment, or a frame with a bad checksum that no later frame's synced stamp covers, is a torn tail: the reader truncates there. A bad frame at offset p is corruption when a later intact frame carries synced > p, because a completed sync covered it; a reader reports it and does not skip it. A last segment whose envelope is incomplete or fails its checksum holds no acknowledged record and is read as empty; the same in an earlier segment is corruption. The directory is synced after a segment is created, renamed or deleted. A kind from 0 to 127 must be understood, and a reader refuses a segment with one it does not know. A kind from 128 to 255 may be skipped.

Insert record, kind 1

Below 4096 bytes the columns section is stored raw and its blocks use compact streams; from 4096 bytes on, flags bit 0 is set and the section is one LZ4 codec block whose raw bytes hold every stream as a codec block under none; a table setting selects ZSTD instead. Optional field 2 (may be skipped) is the 16-byte insert token that lets a client retry a batch. Optional field 5 (must be understood) is present when one statement spans frames: statement_uuid (16 bytes), seq u32, last u8; replay applies such a statement only when its last frame is present.

Checkpoint, kind 2

Optional field 3 is a Kafka position, partition i32 and offset i64, the point from which ingest resumes. Its tag is odd: a reader that resumes ingest must understand it.

Schema record, kind 3

The record is the whole table definition. A later record with a higher epoch replaces an earlier one, so a reader keeps the one with the highest schema_epoch.

A col_flags bit a reader does not know refuses the record. When older segments are deleted, the newest schema record is carried forward into the oldest kept segment, so a log always starts with its schema. The initial default is the value a row written before the column existed reads; the default expression is what an insert that omits the column computes. Where a part's descriptor differs from the schema's, the part's descriptor says what the bytes are and a reader casts the values to the schema's type. The optional fields with even-numbered tags carry what a reader of the data does not need: tag 2 the TTL expression, tag 4 the skip-index declarations, tag 6 the Kafka source, tag 8 the table settings. A ClickHouse Field is the value encoding ClickHouse uses for aggregate function parameters: a tag byte (00 NULL, 01 var_uint, 02 zigzag var_int, 07 f64, 0C string as var_uint length and bytes), then the value.

Delete record, kind 4

Dedup record, kind 5

kind u8 = 5, flags u8, var_uint count, then 16-byte insert tokens that the table still remembers after older segments were deleted.

Parts Work in progress

A part is an immutable directory under <parts_dir>/<table_uuid>/, named <table_uuid>-<seq>.part when a memtable flush wrote it and <table_uuid>-m<seq>.part when a merge did. The writer builds it under a .tmp name, syncs every file and the directory, and publishes it with one atomic rename. A directory whose name ends in .tmp is not a part.

A file in a part directory that this table does not name is ignored. The column data is always authoritative: a damaged or missing index costs a reader speed and never a wrong row.

The manifest

The envelope's magic is MUS1 and the version is 1. The body:

Column flags: bit 0 the column holds at least one NULL, bit 1 dictionary files follow; bits 2 to 7 are reserved, and a reader refuses the manifest when one is set. The per-column section takes even tags: 2 null_count u64, 4 raw_bytes u64 (the sum of the column's raw stream lengths), 8 the initial default as a ClickHouse Field. The manifest's own optional fields: 3 a Kafka position (partition i32, offset i64), 4 the list of sidecar files with their checksums, 6 the value-sorted flag of a collapsing merge key.

Zone maps

Every column has a zone map: the least and greatest non-NULL value in the part, so a WHERE can skip the part before it reads anything. The bytes start with kind u8 and bound_flags u8, then the minimum and the maximum unless bit 3 is set. A kind or a flag bit a reader does not know means there is no zone map and the column is scanned.

• Kind 1, fixed width: each bound at the column's lane width. The order is the type's own, so a reader compares UInt64 values unsigned and Int64 values signed and never compares the bytes. Floats compare numerically, with −0 equal to +0; as in Parquet, a writer stores a zero minimum as −0 and a zero maximum as +0. NaN is left out of the bounds, and bit 2 says the column holds a NaN, so a predicate that could match NaN does not prune.
• Kind 2, prefix, for strings: each bound as a var_uint length and up to 64 bytes, ordered as unsigned bytes. A minimum that was cut is a prefix of the true minimum and still a lower bound; bit 0 says it was cut. A maximum that was cut would not be an upper bound, so the writer increments the last byte of the prefix that is not FF and drops the bytes after it; when every byte is FF there is no upper bound and bit 1 says so. Bit 4 says the maximum was cut: it is an upper bound and not the true maximum, so a reader never answers max from it.
• Bit 3 says there are no bounds, because every row is NULL or NaN.

Marks and the primary index

A column file is split into granules: runs of up to granule_rows rows, each a column block of its own. Each column has a marks file, magic MMRK version 1, so a reader fetches the marks of the columns it needs and no others:

The primary index, magic MPIX version 1, holds what every column shares: where each granule starts, and the sort key of its first row.

A granule's row count is the difference of adjacent row_index values, and the last granule's against row_count. The stored length in the marks lets a reader fetch one granule from S3 with one range request. The key blocks are typed by the sort key's descriptors, so a 128-bit, decimal or string key needs nothing special.

Column files

A column file starts with a 32-byte header: the magic MCOL, version u8 = 1, flags u8 = 0, reserved u16 = 0, part_uuid, column_id u32, reserved u32 = 0. Then the granule blocks follow back to back, each a column block whose streams are codec blocks. The marks give the offset, the length and the checksum of each block; the manifest gives the length and checksum of the whole file.

A LowCardinality column also has col-<id>.dict: an envelope, magic MDCT version 1, whose body is part_uuid, column_id u32, dict_count u32, then one column block of the element type with dict_count rows. Every granule of the column stores indexes into it, and a nested LowCardinality has a file of its own, named by its stream path, with that path in the body. A column whose dictionary would pass the dictionary limit is written with an inline dictionary in every granule instead.

The deletion vector

DELETE never rewrites a published part. It writes rows.del next to it: an envelope, magic MDLV version 1, with the body below. A reader drops the masked rows from every scan; a later merge leaves them out and the new part has no vector.

Skip indexes

A skip index summarises blocks of granularity granules of one column so that a scan can skip a block before it reads it. Each is an envelope whose body starts with the same header, then one entry per block, then nothing else. A reader cross-checks part_uuid, row_count and granule_rows against the manifest and ignores the file on a mismatch.

• MSKI, minmax: per block flags u8 (bit 0 the block holds a NULL, bit 1 the bounds are unusable and the block always survives), then a zone map in the manifest's form.
• SSKI, set: per block flags u8 (bit 0 has NULL, bit 1 the set overflowed and the block always survives), u32 count, then the distinct values at lane width, or as var_uint length and bytes for strings.
• BSKI, bloom filter: after the header m_bits u32 (a multiple of 8), k u8, seed u64; per block flags u8 (bit 0 has NULL) and m_bits / 8 bytes. A value's hash h is the 64-bit wyhash with seed over its canonical bytes; with h1 = h mod 232 and h2 = (h >> 32) | 1, probe i of k tests bit (h1 + i × h2) mod m_bits, computed in 64-bit unsigned arithmetic.
• TBKI, text bloom filter: as BSKI with subtype u8 (0 n-gram, 1 token) and n u8 before m_bits; each token or n-gram of a cell is hashed as a string.

The map-key digest, the full-text index and the vector index are rebuilt from the column data by the server, so their bodies are not frozen by this page, and a reader ignores a sidecar version it does not know. The full-text index records its tokenizer: id 0 splits on ASCII punctuation and folds ASCII case; id 1 is ngram, whose spec holds min_gram u8 and max_gram u8, the lengths in code points of the terms it indexes. A query side that does not know the tokenizer id scans instead.

The S3 bundle

A part moved to the cold tier is one object: an envelope, magic MPBL version 1, whose body is part_uuid, table_uuid and a file table (var_uint count; per file a name, offset u64, length u64, crc32c u32), followed after the envelope's checksum by the files back to back, with offsets relative to the end of the envelope. The stub part.cold left in the part directory carries part_uuid, the object key relative to the configured prefix, the object length and a copy of the table, so a reader can fetch one granule with one ranged request.

Aggregate states Work in progress

A column of the aggregate-state type holds one state per row, as the result of a -State combinator, a rollup rung or an aggregating materialized view. Each cell is one record: an envelope with magic MAS1, version 1, body kind u8 then the kind's payload. A reader that copies parts can carry a state as opaque bytes; to finish or merge it, it needs the payload. A kind id is never redefined: a changed payload takes a new id.

A held value inside a payload is a tag u8 followed by the value: 0 nothing, 1 i64, 2 f64, 3 a string as var_uint length and bytes, 4 u64, 5 i128, 6 u128, 7 sixteen raw bytes (UUID, IPv6), 8 thirty-two raw bytes (256-bit integers and decimals).

Canonical bytes, for every hash in this format: a signed integer of any width, and a decimal as its scaled integer, as i64 little-endian with wyhash seed 1, or as its 16 or 32 raw bytes with seed 4 when it does not fit; an unsigned one as u64 with seed 2; a float as the f64 bit pattern with seed 3; a string, FixedString, UUID, IPv6 and the wide integers as their raw bytes with seed 4. Hashing the widened value keeps a sketch valid when a column is widened within its class, signed to wider signed, unsigned to wider unsigned, Float32 to Float64; a change of class, such as UInt32 to Int64, rebuilds the sketches. The hash is wyhash final version 4 as the Zig standard library implements it. Test vectors: wyhash(1, i64 1) = 0x736c1462d905b0f3, wyhash(2, u64 1) = 0x3816548725c03c86, wyhash(3, f64 1.5) = 0xc76a38da4e33d8ee, wyhash(4, "ann") = 0x2733844f6ddc4d99, wyhash(0, "") = 0x0409638ee2bde459.

The exact kinds carry a cap on what they hold: uniqExact 2²⁰ keys, groupArray 2²⁰ items, quantileExact and quantileExactInterpolated 2²⁰ values, groupBitmap 2²⁰ keys, entropy 2²⁰ keys, mannWhitneyUTest and kolmogorovSmirnovTest 2²⁰ samples per side, uniqUpTo its threshold and topK its k, so every state stays below the cell limit. A merge of two states can still pass a cap, and the rule is that no value is ever dropped: a part merge that would pass a cap leaves the inputs uncollapsed and reports it, and a query that needs the collapsed value fails with an error that names the aggregate. The sketch kinds, uniq, quantile and the moment and regression families, are bounded in size whatever the input and always merge.

Replication objects Work in progress

Three replication objects outlive a release and follow the same rules as the files above: the commit record in the Kafka topic, the shard manifest and the schema snapshot in S3, each of them an envelope.

• MRCL version 1, a commit record: kind u8 (1 part added, 2 part removed, 3 part masked, 4 generation barrier, 5 DDL set, 6 DDL drop, 7 DDL snapshot), the writer, min_reader u16, generation u64, emitter u64, shard_id u32, schema_epoch u64, then the kind's fields. A part kind carries table_uuid, part_uuid, block u64, content_id u64, row_count u64 and the part name, and the bundle key is parts/<name>-<content_id>.part; an added part also carries its insert tokens, and a masked part masked_rows u64. A DDL kind carries the object kind as a word, the name, the SHA-256 of the text, the text (empty when withheld) and, for a table, the body of its schema record, so a replica takes the table id, every column id and the next column id from the primary. A snapshot carries watermark i64, the SHA-256 and the object key. Optional field 3 is the Ed25519 signature over the body.
• MSHM version 3, the shard manifest: the writer, min_reader u16, watermark i64, generation u64, shard_id u32, key_fingerprint u64, u32 count, then per live part table_uuid, part_uuid, content_id u64, block u64, row_count u64 and the part name. The bundle key is parts/<name>-<content_id>.part, relative to the configured prefix.
• MSCM version 3, the schema snapshot: the writer, min_reader u16, watermark i64, generation u64, shard_id u32, schema_epoch u64, key_fingerprint u64, the topic name, u32 count, then per entry the object kind as a word, flags u8, created_epoch u64, the name, the text and, for a table, its schema record body, with the signature as optional field 3.

Directories, catalogs and markers

A data directory has two roots, set by MUSCLES_WAL_DIR and MUSCLES_PARTS_DIR. Under each, one directory per table carries the table's id in hex. A reader needs no catalog file to read the data: the table list is the directory list, the table name, the column names and types and the sort key are in the latest schema record of the table's log and in each part's manifest.

Which part directories are live follows from the markers. A directory with a part.tombstone or a part.deleting marker is not live. A part.cold stub means the column files are in the S3 bundle it names. A part.moved redirect names the disk the part was moved to. A part.replicated marker means the part was installed from another node. Each marker is an envelope with the magic in the parts table and part_uuid in its body; the tombstone, deleting and replicated markers carry nothing else.

The definitions of views, rollups, dictionaries, policies, recording rules and search indexes are envelope files that hold SQL text. A reader of the data does not need them.

Versioning and extension rules

• Every file, object and record starts with a magic and a version. The version changes only when the fixed body changes, and a reader refuses a version it does not know.
• Every file names its writer and a minimum reader level, and a reader below that level refuses the file.
• Every durable record carries a CRC32C: the envelope over the whole file, the log frame over its body and sync stamp, the marks over each granule block, the manifest over each column file, each marks file and the primary index.
• Reserved flag bits are 0 and a reader refuses a set one. A later version can therefore give a bit a must-understand meaning.
• An optional field with an even tag may be skipped and one with an odd tag must be understood. A new piece of information that a reader may ignore is an even field; one that changes the meaning of the data is an odd field.
• Column ids, table ids and part ids are stable: a rename, a dropped column or a merge never changes an existing id, and a dropped column's id is never reused.
• A new column type is a new ClickHouse id or a new extension id in the descriptor. An older reader reports an unsupported type for that column, skips its streams, and reads the others.
• A new codec is a new id in the block header. An older reader refuses that stream and reads the others.
• A new stream kind from 128 up may be skipped by an older reader; one below 128 is refused. The same rule holds for a new log record kind.
• A new sidecar is a new file in the part directory. A reader ignores files it does not know.
• A limit that a writer may raise is stored in the file it applies to, and a reader honours the stored value up to the format's own limit. A format limit changes only with the reader level, never with a version.
• All integers are little-endian, everywhere, including inside the ClickHouse type descriptor.

Limits a reader enforces

A reader checks each of these before it allocates or indexes, and refuses a file that passes one. They are fixed for reader level 1; the two writer settings, max_insert_raw_bytes and max_block_raw_bytes, are stored in the files and bounded by the raw stream limit.

Worked examples

The examples use one table, events, with two columns: id UInt32 (column id 1) and name Nullable(String) (column id 2), sorted by id. Three rows are inserted: (1, 'ann'), (2, NULL), (3, 'bob'). The table id is 0193b2f4-e5c0-7a1b-8c3d-4e5f60718293 and the writer is muscles 0.1.0-beta.1. Every checksum below is computed over the bytes shown, and a script that walks every structure on this page and recomputes every checksum is run before the page is published.

The log segment header

The segment starts with the envelope MWAL, version 1, flags 0, body length 67: sequence 1, floor 0, created_at, the table id, the writer, the reader level and the writer's insert limit, then the checksum, 81 bytes in all.

0000  4d 57 41 4c 01 00 43 00 00 00                    "MWAL", version 1, flags 0, body_len 67
000a  01 00 00 00 00 00 00 00                          segment_seq = 1
0012  00 00 00 00 00 00 00 00                          lsn_floor = 0
001a  00 40 ac c6 3d 28 74 18                          created_at
0022  01 93 b2 f4 e5 c0 7a 1b 8c 3d 4e 5f 60 71 82 93  table_uuid
0032  14 6d 75 73 63 6c 65 73 20 30 2e 31 2e 30 2d 62  writer: 20 bytes, "muscles 0.1.0-b
0042  65 74 61 2e 31                                   eta.1"
0047  01 00                                            min_reader = 1
0049  00 00 00 40                                      max_insert_raw_bytes = 1 GiB
004d  64 ff 58 77                                      crc32c = 0x7758ff64

A log insert record

The columns section is 61 bytes, below the compression threshold, so flags bit 0 is clear, the section is stored raw and its blocks use compact streams. The frame is 93 bytes, and its sync stamp says the 81 bytes of the header were synced before it was written.

0000  4d 00 00 00                                      len = 77
0004  01                                               kind = 1, insert
0005  00                                               flags = 0
0006  00 00 00 00 00 00 00 00                          first_lsn = 0
000e  03 00 00 00                                      row_count = 3
0012  02 00                                            column_count = 2
0014  01                                               column_id = 1
0015  01 03                                            descriptor: 1 byte, 03 = UInt32
0017  04                                               block flags = 4: compact streams
0018  01                                               stream_count = 1
0019  01 0c                                            stream kind 1 = values, length 12
001b  01 00 00 00 02 00 00 00 03 00 00 00              values 1, 2, 3
0027  02                                               column_id = 2
0028  02 23 15                                         descriptor: 2 bytes, 23 15 = Nullable(String)
002b  04                                               block flags = 4: compact streams, validity present
002c  03                                               stream_count = 3
002d  00 08                                            stream kind 0 = validity, length 8
002f  05 00 00 00 00 00 00 00                          bits 0 and 2 set: rows 0 and 2 hold a value
0037  02 10                                            stream kind 2 = offsets, length 16
0039  00 00 00 00 03 00 00 00 03 00 00 00 06 00 00 00  offsets 0, 3, 3, 6
0049  03 06                                            stream kind 3 = data, length 6
004b  61 6e 6e 62 6f 62                                data "ann" "bob"
0051  51 00 00 00 00 00 00 00                          synced = 81
0059  e4 6d 9a 36                                      crc32c over bytes 4 to 0x58 = 0x369a6de4

The column files of the flushed part

After the flush, the part has one granule. col-1.bin is 67 bytes: the 32-byte header, then a 35-byte column block with the same stream as the log record, as a codec block.

0000  4d 43 4f 4c 01 00 00 00                          "MCOL", version 1, flags 0, reserved
0008  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
0018  01 00 00 00                                      column_id = 1
001c  00 00 00 00                                      reserved
0020  00 01 01                                         column block: flags 0, 1 stream, kind values
0023  c6 01 01 00 00 00 00 00 00 00 00 00              codec block header, chain none
002f  0c 00 00 00 0c 00 00 00                          raw_len = 12, stored_len = 12
0037  01 00 00 00 02 00 00 00 03 00 00 00              values 1, 2, 3

col-2.bin is 127 bytes: the header, then the 95-byte block of the name column.

0000  4d 43 4f 4c 01 00 00 00                          "MCOL", version 1, flags 0, reserved
0008  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
0018  02 00 00 00                                      column_id = 2
001c  00 00 00 00                                      reserved
0020  00 03                                            column block: flags 0, 3 streams
0022  00                                               stream kind 0 = validity
0023  c6 01 01 00 00 00 00 00 00 00 00 00              codec block header, chain none
002f  08 00 00 00 08 00 00 00                          raw_len = 8, stored_len = 8
0037  05 00 00 00 00 00 00 00                          bits 0 and 2 set
003f  02                                               stream kind 2 = offsets
0040  c6 01 01 00 00 00 00 00 00 00 00 00              codec block header, chain none
004c  10 00 00 00 10 00 00 00                          raw_len = 16, stored_len = 16
0054  00 00 00 00 03 00 00 00 03 00 00 00 06 00 00 00  offsets 0, 3, 3, 6
0064  03                                               stream kind 3 = data
0065  c6 01 01 00 00 00 00 00 00 00 00 00              codec block header, chain none
0071  06 00 00 00 06 00 00 00                          raw_len = 6, stored_len = 6
0079  61 6e 6e 62 6f 62                                data "ann" "bob"

The marks and the primary index

col-1.mrk records the one granule of column 1: its block starts at byte 32 of the column file, is 35 bytes long, and has the checksum shown. col-2.mrk has the same shape with column id 2, length 95 and checksum 80 a9 1d b5; its trailer is 7d 5b 3f 94.

0000  4d 4d 52 4b 01 00 28 00 00 00                    "MMRK", version 1, flags 0, body_len 40
000a  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
001a  01 00 00 00                                      column_id = 1
001e  01 00 00 00                                      granule_count = 1
0022  20 00 00 00 00 00 00 00                          granule 0: offset 32
002a  23 00 00 00                                      length 35
002e  cd 63 bd fd                                      crc32c of the block = 0xfdbd63cd
0032  26 2b 40 20                                      crc32c = 0x20402b26

0000  4d 4d 52 4b 01 00 28 00 00 00                    "MMRK", version 1, flags 0, body_len 40
000a  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
001a  02 00 00 00                                      column_id = 2
001e  01 00 00 00                                      granule_count = 1
0022  20 00 00 00 00 00 00 00                          granule 0: offset 32
002a  5f 00 00 00                                      length 95
002e  80 a9 1d b5                                      crc32c of the block = 0xb51da980
0032  7d 5b 3f 94                                      crc32c = 0x943f5b7d

primary.idx says the granule starts at row 0 and that the sort key of that row is id = 1.

0000  4d 50 49 58 01 00 38 00 00 00                    "MPIX", version 1, flags 0, body_len 56
000a  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
001a  01 00 00 00                                      granule_count = 1
001e  00 00 00 00 00 00 00 00                          granule 0 starts at row 0
0026  01                                               key_count = 1
0027  00 01 01                                         column block: flags 0, 1 stream, kind values
002a  c6 01 01 00 00 00 00 00 00 00 00 00              codec block header, chain none
0036  04 00 00 00 04 00 00 00                          raw_len = 4, stored_len = 4
003e  01 00 00 00                                      first key of granule 0 = 1
0042  41 2b e8 44                                      crc32c = 0x44e82b41

The part manifest

The manifest is 303 bytes. The part id is 0193b301-6f3e-7b2c-9d4e-5f6071829304; the log coverage is sequence numbers 0 to 2, stored plus one. The checksums it holds for the marks files and the primary index are those files' trailers; the checksums for the column files cover every byte of them.

0000  4d 55 53 31 01 00 21 01 00 00                    "MUS1", version 1, flags 0, body_len 289
000a  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
001a  01 93 b2 f4 e5 c0 7a 1b 8c 3d 4e 5f 60 71 82 93  table_uuid
002a  14 6d 75 73 63 6c 65 73 20 30 2e 31 2e 30 2d 62  writer: 20 bytes, "muscles 0.1.0-b
003a  65 74 61 2e 31                                   eta.1"
003f  01 00                                            min_reader = 1
0041  03 00 00 00 00 00 00 00                          row_count = 3
0049  00 20 00 00                                      granule_rows = 8192
004d  01 00 00 00                                      granule_count = 1
0051  01 00 00 00 00 00 00 00                          block = 1
0059  60 4e 7d 2b 3f 9e 1a 5c                          content_id
0061  01 00 00 00 00 00 00 00                          first_lsn = 0 + 1
0069  03 00 00 00 00 00 00 00                          last_lsn = 2 + 1
0071  01 00 00 00 00 00 00 00                          schema_epoch = 1
0079  00 0a 47 02 3e 28 74 18                          written_at
0081  00 00 00 02                                      max_block_raw_bytes = 32 MiB
0085  06 65 76 65 6e 74 73                             table name "events"
008c  01                                               sort key: 1 entry
008d  01 00 00 00 00 00 00 01 03                       column_id 1, ascending, NULLs last, no expression, UInt32
0096  46 00 00 00 00 00 00 00 41 2b e8 44              primary.idx: 70 bytes, checksum 0x44e82b41
00a2  02                                               column_count = 2
00a3  01 00 00 00                                      column_id = 1
00a7  02 69 64                                         name "id"
00aa  01 03                                            descriptor UInt32
00ac  00                                               col_flags = 0
00ad  43 00 00 00 00 00 00 00 67 1e f0 67              col-1.bin: 67 bytes, crc32c 0x67f01e67
00b9  36 00 00 00 00 00 00 00 26 2b 40 20              col-1.mrk: 54 bytes, checksum 0x20402b26
00c5  0a 01 00 01 00 00 00 03 00 00 00                 zone map, 10 bytes: kind 1, flags 0, min 1, max 3
00d0  14 02 08 00 00 00 00 00 00 00 00                 section, 20 bytes: tag 2 null_count = 0,
00db  04 08 0c 00 00 00 00 00 00 00                    tag 4 raw_bytes = 12
00e5  02 00 00 00                                      column_id = 2
00e9  04 6e 61 6d 65                                   name "name"
00ee  02 23 15                                         descriptor Nullable(String)
00f1  01                                               col_flags: bit 0, the column holds a NULL
00f2  7f 00 00 00 00 00 00 00 bf 4b f3 ec              col-2.bin: 127 bytes, crc32c 0xecf34bbf
00fe  36 00 00 00 00 00 00 00 7d 5b 3f 94              col-2.mrk: 54 bytes, checksum 0x943f5b7d
010a  0a 02 00 03 61 6e 6e 03 62 6f 62                 zone map, 10 bytes: kind 2, flags 0, min "ann", max "bob"
0115  14 02 08 01 00 00 00 00 00 00 00                 section, 20 bytes: tag 2 null_count = 1,
0120  04 08 1e 00 00 00 00 00 00 00                    tag 4 raw_bytes = 30
012a  00                                               replaces_count = 0
012b  d5 75 6c ab                                      crc32c = 0xab6c75d5

A deletion vector and an aggregate state

A DELETE of the row with the NULL name writes rows.del in the bitmap form with bit 1 set, 63 bytes:

0000  4d 44 4c 56 01 00 31 00 00 00                    "MDLV", version 1, flags 0, body_len 49
000a  01 93 b3 01 6f 3e 7b 2c 9d 4e 5f 60 71 82 93 04  part_uuid
001a  01 00 00 00 00 00 00 00                          generation = 1
0022  03 00 00 00 00 00 00 00                          row_count = 3
002a  01 00 00 00 00 00 00 00                          deleted_count = 1
0032  00                                               form 0 = bitmap
0033  02 00 00 00 00 00 00 00                          word 0: bit 1 set, row 1 is deleted
003b  04 77 3f 7e                                      crc32c = 0x7e3f7704

The state of avg(id) over the three rows, as a rollup stores it, is a 64-byte record: the integer sum 6 as 32 bytes, the float sum 0.0, and the count 3.

0000  4d 41 53 31 01 00 32 00 00 00                    "MAS1", version 1, flags 0, body_len 50
000a  02                                               kind 2 = avg
000b  01                                               lane 1 = integer
000c  06 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  sum_int = 6 as i256
001c  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
002c  00 00 00 00 00 00 00 00                          sum_float = 0.0
0034  03 00 00 00 00 00 00 00                          count = 3
003c  77 ed 2b 34                                      crc32c = 0x342bed77