Module section 

The section table: one general mechanism for carrying a graph structure in a rudb file.

spec/graph/03-the-file-format.md section 3.2 asks for one mechanism and three section kinds rather than three mechanisms. A section is an opaque payload with a kind, an identity, a generation stamp and a list of extents, and this module is the whole of what the format knows about one. What a key map or a forward link means lives in rudb-graph at rank 5, which is below the format on purpose: a key map that could see a page would be a key map that could only be tested through a file.

Three rules make the mechanism the last one the format needs.

A reader ignores a kind it does not know. That is what Section::kind being eight opaque bytes rather than an enum is for: a build that meets RUDBAJ1\0 before backward adjacency exists carries the entry through, does not read the payload, and answers the query without it. Section 3.1 guarantees the answer is the same either way, so ignoring is always available and no future section kind needs another format bump.

A section is a list of extents of at most MAX_EXTENT bytes, each independently checksummed and readable. Issue #745 is what this rule is for: a single buffer works until it does not, and an SF100 lineitem neighbour array is two gigabytes. Splitting is not an optimization here, it is the difference between a structure that exists at scale and one that does not.

Sections are written before the directory and committed by the two-generation header swap the format already performs. So a crash during a section build leaves unreferenced trailing bytes in the file and nothing else, and there is no new recovery path to write or to test.

Structs

Attachment

One section to be written into a file, handed to crate::attach.

Extent

Where one extent of a section’s payload lives.

Section

One entry in a table’s section table.

Constants

ADJACENCY

A backward adjacency list, per section 3.5.

DEGREES

A relationship’s degree distribution and certificates, per spec/stats/07-graph-statistics.md.

EXTENT_BYTES

Bytes one extent entry takes in an extent table.

FORWARD_LINK

A forward link column, per section 3.4.

GRAPH_KINDS

The kinds the graph document owns, which share its ten percent of the column bytes.

KEY_MAP

A key map, per section 3.3.

MAX_EXTENT

The largest one extent may be.

MAX_EXTENTS

The most extents one section may have.

SKETCHES

A column’s sketches, per spec/stats/03-the-file-format.md section 3.4.

STATISTICS_KINDS

The kinds the statistics document owns, which share its two percent.

SUMMARY

A column summary, per spec/stats/03-the-file-format.md section 3.3.

Functions

decode_extents

Decodes a whole extent table.

encode_extents

Encodes a whole extent table, checking that it describes a contiguous run of elements.

locate

Which extent holds a given logical element, by binary search over the table.