A cell is one entry of a b-tree: a key and its data. Every cell has the same shape, on leaf and interior pages and in tables and indexes alike: a 12-byte header, then the key and the data together. What the key and data hold is on the records and keys page.
Cell header
The struct CellHdr in the 2.8.17 source. Numbers are in the file’s
byte order. The key and data sizes are 24-bit numbers split into a low 16-bit part
and a high byte.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | u32 | Left child | The child page with the keys before this cell; 0 on a leaf page. |
| 4 | 2 | u16 | Key size, low | The key size in bytes, low 16 bits. |
| 6 | 2 | u16 | Next cell | The offset, from the start of the page, of the cell with the next key; 0 for the last. |
| 8 | 1 | u8 | Key size, high | The key size, high 8 bits. |
| 9 | 1 | u8 | Data size, high | The data size, high 8 bits. |
| 10 | 2 | u16 | Data size, low | The data size in bytes, low 16 bits. |
Key size = key size low + key size high × 65,536. Data size = data size low + data size high × 65,536.
Payload
After the header come the key and then the data, as one stream. If key + data is at
most 236 bytes (MX_LOCAL_PAYLOAD), all of it is in the cell. Otherwise
the first 236 bytes are in the cell, a 4-byte page number follows at cell offset 248,
and the rest of the stream is on that
overflow page and the ones it
chains to.
| Offset | Size | Description |
|---|---|---|
| 12 | key + data, rounded up to a multiple of 4 | the key, then the data, then padding to 4 bytes (when the payload fits) |
| 12 | 236 | the first 236 bytes of the key and data (when it does not) |
| 248 | 4 | the first overflow page (when it does not) |
Cell size
A cell takes 12 + (key + data, rounded up to a multiple of 4) bytes when the payload fits, or 12 + 236 + 4 = 252 bytes when it spills.
SQLite’s own 2.x file format document and a comment in the source give the local limit as 238 bytes. The macro that sets it gives (1,016 ÷ 4 − 16), rounded down to a multiple of 4, which is 236 for 1,024-byte pages, and the code is what counts. The explorer uses 236.
Example
The cell from the b-tree page
example, at offset 8 of a little-endian leaf page: rowid 1 of a table, with the
values 'hi', NULL and '42'. Built from the 2.8.17
layout.
00 00 00 00 04 00 00 00 00 00 0A 00
80 00 00 01 04 07 07 0A 68 69 00 34 32 00
00 0000 00 00 00: left child 0, a leaf.04 00: key size 4 (low bits).00 00: next cell 0, the last on the page.00,00: the high bytes of the key and data sizes.0A 00: data size 10.80 00 00 01: the key, rowid 1 (see rowid keys).04 07 07 0A 68 69 00 34 32 00: the data, a record of three values.00 00: padding, since 4 + 10 = 14 rounds up to 16. The cell takes 12 + 16 = 28 bytes.