data/<block-ulid>/index
Index
The index file is how PromQL finds series without scanning data. It is a
sequence of sections terminated by a table of contents: readers seek to the
end first, read the TOC, and jump from there. Three structures do the real work:
- The symbol table deduplicates every label name and value string; all later sections refer to strings by their sorted position in it.
- The series section stores each series' labels (as symbol refs) and its
chunk metadata (time range + chunk reference). Entries are 16-byte aligned, and a series'
ID is
offset / 16, an address masquerading as an ID. - Postings lists invert the index: for each label pair, the sorted list of series IDs that carry it. PromQL matchers intersect these lists.
Open the interactive byte explorer →
Field notes & invariants
- Series are sorted lexicographically by label set, and IDs are
offset/16, so a sorted list of series IDs is also a sorted list of label sets. That's what makes postings intersection cheap. - To evaluate
up{job="prometheus"}, Prometheus intersects the postings for__name__="up"andjob="prometheus"— walk both lists below and check the intersection yourself. - Sections that begin with
lenput the CRC-32C right afterlenbytes; the checksum covers exactly those bytes. - Arbitrary zero padding may appear between sections; readers skip zero bytes after a section's stated length.
- Chunk metadata is delta-encoded: first chunk stores
mintraw, thenmaxt−mint; later chunks store deltas against the previous chunk. Chunk refs must strictly increase across the file. - The label index sections and the label offset table are legacy: still written for compatibility, but marked "no longer used" in the spec.
- The postings offset table stores raw name/value strings (not symbol refs) and is partially kept in memory when a block is opened.
- Accuracy note: the spec diagram header says
version(1), but blocks written by modern Prometheus use index format v2 (v1 is the legacy Prometheus 2.0 layout, still readable). - A TOC entry of 0 means the section is absent and lookups must return empty results.