> For the complete documentation index, see [llms.txt](https://litedb.gitbook.io/litedb-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://litedb.gitbook.io/litedb-docs/architecture_and_design/scalar_index/file_format.md).

# 标量索引文件格式

每个标量索引使用一个独立文件：

```
indexes/<index-id>.bti
```

文件由一个 4096 字节的存储头页和若干 4096 字节的节点页组成。页面 ID 从 `1` 开始，物理偏移可由固定页大小计算。

## 存储头

当前格式版本为 2，同时保留对旧版本 1 的读取兼容。

| 偏移 | 大小 | 字段        |
| -: | -: | --------- |
|  0 |  4 | 魔数 `LBI1` |
|  4 |  2 | 格式版本      |
|  6 |  2 | 头部大小      |
|  8 |  4 | 页面大小      |
| 12 |  1 | 键类型       |
| 13 |  1 | 标志        |
| 14 |  2 | 保留        |
| 16 |  8 | 索引 ID     |
| 24 |  8 | 键类型参数     |
| 32 |  8 | 根页 ID     |
| 40 |  8 | 下一个页面 ID  |
| 48 |  8 | 条目总数      |
| 56 |  4 | 头部 CRC32  |
| 64 |  8 | 空闲页链表头    |
| 72 |  8 | 空闲页数量     |

根页 ID 为 `0` 表示空树。标志位 `HasKeyParameter` 表示键类型附带参数，例如变长类型的模式信息。

版本 2 校验头部 CRC；版本 1 按旧规则读取。

## 节点页头

每个 B+ 树节点页有 48 字节公共头：

| 偏移 | 大小 | 字段        |
| -: | -: | --------- |
|  0 |  4 | 魔数 `BTP1` |
|  4 |  2 | 页面格式版本    |
|  6 |  2 | 页头大小      |
|  8 |  4 | 页面大小      |
| 12 |  1 | 页面类型      |
| 13 |  1 | 保留        |
| 14 |  2 | 条目数量      |
| 16 |  8 | 页面 ID     |
| 24 |  8 | 第一链接字段    |
| 32 |  8 | 第二链接字段    |
| 40 |  2 | 空闲区起点     |
| 42 |  2 | 空闲区终点     |
| 44 |  4 | 页面 CRC32  |

链接字段按页面类型解释：

* 叶子页：前驱叶子、后继叶子；
* 内部页：第一个子页、保留零值。

版本 2 页面使用 CRC32；旧版本 1 要求校验字段为零。

## 槽目录与变长条目

页头之后是槽目录，每个槽占 4 字节。实际条目从页面尾部向前打包，槽中记录条目的位置和长度：

```
页头 | 槽 0 | 槽 1 | ... | 空闲空间 | ...变长条目 1 | 变长条目 0
```

这种布局允许不同长度的字符串键共享固定大小页面。编码器在写页前计算条目能否容纳，树的分裂逻辑据此决定拆分页。

叶子条目编码标量键和 `RecordId`。内部条目编码分隔用的完整键和右侧子页 ID。

## 空闲页

删除释放的页面不会立即缩短文件，而是编码为空闲页记录并串成单链表。空闲页使用魔数 `BRF1`，记录：

* 格式版本；
* 当前页面 ID；
* 下一个空闲页 ID；
* CRC32。

新页面分配优先复用空闲链表头；没有空闲页时才使用 `next_page_id` 扩展文件。

打开文件时，`BTreePageStore` 会检查空闲链表：

* 页面 ID 是否在有效范围内；
* 是否存在环；
* 实际节点数是否与头部计数一致；
* 每个空闲页记录是否通过格式和校验和验证。

## 校验边界

打开和读页时会验证魔数、版本、页面大小、索引 ID、键类型、页面 ID、槽边界和校验和等信息。格式错误以结构化索引错误返回，而不是继续使用可疑数据。

`sync_data` 和 `sync_all` 可把索引文件的修改推进到底层文件系统，但调用它们只说明这个文件的持久化状态。集合数据、多个索引和 Catalog 之间的提交顺序由 WAL 与事务协议定义。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://litedb.gitbook.io/litedb-docs/architecture_and_design/scalar_index/file_format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.