Section 5: Three Tables and a Version Number - Data Modeling

Executive Summary: The master holds three tables: a namespace mapping full pathnames to file metadata, a file → chunk list of 64-bit handles, and a chunk table mapping each handle to its version, replica locations, lease and reference count. The decision that matters is the split. The namespace, the chunk lists and the version numbers go through the operation log. Replica locations and leases are never persisted: the chunkserver has the final word on what it holds, and the master rebuilds that map from reports. On the chunkserver, a chunk is an ordinary Linux file named by its handle, carrying 4 KB of checksums and its own copy of the version. The whole metadata set is ~80 GB in RAM and a ~15 GB checkpoint on disk.

The interviewer points at FindChunks from Section 4. "Your master answers that in microseconds from memory. Show me what's in memory, and tell me which parts survive a reboot."

You: "Three tables and one rule. If the master is the only one who could know a fact, it goes to the log. If a chunkserver can tell the master again, it stays in memory. That rule shrinks the checkpoint to about 15 GB and removes a whole class of master-versus-disk disagreements."

The Three Tables

(1) Namespace. It's a lookup table from full pathname to file metadata, stored with prefix compression. There are no inodes, no per-directory list of children, and no hard or symbolic links (the paper's design). Every entry, files and directories alike, carries a read-write lock. Section 7 uses those locks to let two creates in one directory run concurrently while a snapshot of that directory waits. In this design the table is kept sorted, so list(dir) is a prefix range scan.

(2) File → chunk list. An ordered array of 64-bit chunk handles. Position i is chunk index i, which is why the client can turn a byte offset into an index without asking anyone (Section 4).

(3) Chunk table. The master assigns each chunk an immutable, globally unique 64-bit handle when it creates the chunk. The table maps that handle to everything else:

That's the 64 B per chunk in the numbers ledger. Section 3 already did the arithmetic: 32 GB of chunk table, 2 GB of namespace and 4 GB of chunk lists come to 38 GB raw and **80 GB** with hash-table and allocator overhead, inside a 256 GB machine. The persisted subset (namespace, chunk lists, handle and version) is a ~15 GB checkpoint.

Here are the running example's rows mid-hour, while chunk 42 is still being written and before Section 8's crash:

namespace   /crawl/2026-11-02/hour-09.rec  -> {owner: crawl, created, rw-lock}
chunk list  /crawl/2026-11-02/hour-09.rec  -> [ ..., [41] 0x7A3E, [42] 0x7A3F, [43] 0x7A40, ... ]
chunk table 0x7A3F -> version 1
                      replicas {cs-0412 (rack 12), cs-0788 (rack 27), cs-0153 (rack 05)}   # soft
                      primary cs-0412, lease expires grant + 60 s                         # soft
                      refcount 1                                                          # derived

Quick check before moving on: