prometheus/Documentation/format/index.md

# Index Disk Format

The following describes the format of the `index` file found in each block directory.

```
┌────────────────────────────┬─────────────────────┐
│ magic(0xBAAAD700) <4 byte> │ version(1) <1 byte> │
├────────────────────────────┴─────────────────────┤
│ ┌──────────────────────────────────────────────┐ │
│ │                 Symbol Table                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │                    Series                    │ │
│ ├──────────────────────────────────────────────┤ │
│ │                 Label Index 1                │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      ...                     │ │
│ ├──────────────────────────────────────────────┤ │
│ │                 Label Index N                │ │
│ ├──────────────────────────────────────────────┤ │
│ │               Label Index Table              │ │
│ ├──────────────────────────────────────────────┤ │
│ │                   Postings 1                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      ...                     │ │
│ ├──────────────────────────────────────────────┤ │
│ │                   Postings N                 │ │
│ ├──────────────────────────────────────────────┤ │
│ │                 Postings Table               │ │
│ ├──────────────────────────────────────────────┤ │
│ │                      TOC                     │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```


### Symbol Table

The symbol table holds all strings encountered in our index. All other index sections just reference strings in the table as they are highly repetitive.

The section contains a sequence of the raw string data, each prefixed with the string's length.
Strings are referenced by pointing to the beginning of their length field. The strings are sorted in lexicographically ascending order.

```
┌─────────────────────────┬───────────────┐
│ count(symbols) <4 byte> │ len <4 byte>  │
├─────────────────────────┴───────────────┤
│ ┌─────────────────────┬───────────────┐ │
│ │ len(str_1) <varint> │ str_1 <bytes> │ │
│ ├─────────────────────┴───────────────┤ │
│ │                . . .                │ │
│ ├─────────────────────┬───────────────┤ │
│ │ len(str_n) <varint> │ str_1 <bytes> │ │
│ └─────────────────────┴───────────────┘ │
├─────────────────────────────────────────┤
│  CRC32 <4 byte>                         │
└─────────────────────────────────────────┘
```


### Series

The section contains a sequence of series that hold the label set of the series as well as the chunks within the block. The series are sorted lexicographically by their label sets.  
The file offset to the beginning of a series serves as the series' ID in all subsequent references. Thereby, a sorted list of series IDs implies a lexicographically sorted list of series label sets.

```
┌───────────────────────────────────────┐
│  count(series) <4 byte>               │
├───────────────────────────────────────┤
│ ┌───────────────────────────────────┐ │
│ │   series_1                        │ │
│ ├───────────────────────────────────┤ │
│ │                 . . .             │ │
│ ├───────────────────────────────────┤ │
│ │   series_n                        │ │
│ └───────────────────────────────────┘ │
└───────────────────────────────────────┘
```

Every series holds a list of label pairs and chunks. The label pairs reference the symbol table and the chunks an address in one of the block's chunk files.

```
┌─────────────────────────────────────────────────────────┐
│ len <varint>                                            │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────┬──────────────────────────────────┐ │
│ │                  │ ┌──────────────────────────┐     │ │
│ │                  │ │ ref(l_i.name) <varint>   │     │ │
│ │ #labels <varint> │ ├──────────────────────────┤ ... │ │
│ │                  │ │ ref(l_i.value) <varint>  │     │ │
│ │                  │ └──────────────────────────┘     │ │
│ ├──────────────────┼──────────────────────────────────┤ │
│ │                  │ ┌──────────────────────────┐     │ │
│ │                  │ │ c_i.mint <varint>        │     │ │
│ │                  │ ├──────────────────────────┤     │ │
│ │                  │ │ c_i.maxt <varint>        │     │ │
│ │ #chunks <varint> │ ├──────────────────────────┤ ... │ │
│ │                  │ │ ref(c_i.data) <varint>   │     │ │
│ │                  │ ├──────────────────────────┤     │ │
│ │                  │ │ crc32(c_i.data) <varint> │     │ │
│ │                  │ └──────────────────────────┘     │ │
│ └──────────────────┴──────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ CRC32 <4 byte>                                          │
└─────────────────────────────────────────────────────────┘
```

The CRC checksum is calculated over the series contents of the index concatenated with the data of its chunks (with encoding byte, without length).


### Label Index

The label index indexes holds lists of possible values for label names. A sequence of label index blocks follow on the series entries.

```
┌─────────────────────────────────────────────────────────┐
│ len <varint>                                            │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────┬──────────────────────────────────┐ │
│ │                  │ ┌──────────────────────────┐     │ │
│ │                  │ │ ref(value[0]) <4 byte>   │     │ │
│ │                  │ ├──────────────────────────┤     │ │
│ │  n = len(names)  │ │ ...                      │ ... │ │
│ │     <varint>     │ ├──────────────────────────┤     │ │
│ │                  │ │ ref(value[n]) <4 byte>   │     │ │
│ │                  │ └──────────────────────────┘     │ │
│ └──────────────────┴──────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ CRC32 <4 byte>                                          │
└─────────────────────────────────────────────────────────┘
```

The sequence of label index blocks is finalized by a lookup table pointing to the beginning of each label index block. It is simply a list of entries that are read into an in-memory hashmap when the index is loaded.

### Postings

Postings are postings lists that map label pairs to series they occur in.

```
┌─────────────────────────────────────────────────┐
│ len <varint>                                    │
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ ref(series[0]) <4 byte>                     │ │
│ ├─────────────────────────────────────────────┤ │
│ │ ...                                         │ │
│ ├─────────────────────────────────────────────┤ │
│ │ ref(series[n]) <4 byte>                     │ │
│ └─────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────┤
│ CRC32 <4 byte>                                  │
└─────────────────────────────────────────────────┘
```

### Offset Table


```
┌─────────────────────────┬───────────────┐
│ count(symbols) <4 byte> │ len <4 byte>  │
├─────────────────────────┴───────────────┤
│ ┌─────────────────────────────────────┐ │
│ │  n = len(strs) <varint>             │ │
│ ├─────────────────────────────────────┤ │
│ │  len(strs[0])                       │ │
│ ├─────────────────────────────────────┤ │
│ │  ...                                │ │
│ ├─────────────────────────────────────┤ │
│ │  strs[n]                            │ │
│ ├─────────────────────────────────────┤ │
│ │  offset <varint>                    │ │
│ └─────────────────────────────────────┘ │
│                  . . .                  │
├─────────────────────────────────────────┤
│  CRC32 <4 byte>                         │
└─────────────────────────────────────────┘
```



### TOC

The table of contents serves as an entry point to the entire index. It's size is fixed.

```
┌─────────────────────────────────────────────┐
│ ref(symbols) <8 byte>                       │
├─────────────────────────────────────────────┤
│ ref(series) <8 byte>                        │
├─────────────────────────────────────────────┤
│ ref(label indices) <8 byte>                 │
├─────────────────────────────────────────────┤
│ ref(label indices table) <8 byte>           │
├─────────────────────────────────────────────┤
│ ref(postings) <8 byte>                      │
├─────────────────────────────────────────────┤
│ ref(postings table) <8 byte>                │
└─────────────────────────────────────────────┘
```