> 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/vector_index/persistence_and_recovery.md).

# 持久化、恢复与压缩

HNSW 文件位于：

```
vindexes/<vector-index-id>.hnsw
```

它不是固定页面树，而是“固定头部 + 追加提交帧”的日志式文件。

## 文件头

头部固定为 4096 字节，格式版本为 1，魔数为 `LHW1`。前 84 字节编码：

| 偏移 | 大小 | 字段                  |
| -: | -: | ------------------- |
|  0 |  4 | 魔数                  |
|  4 |  2 | 版本                  |
|  6 |  2 | 头部大小                |
|  8 |  8 | 向量索引 ID             |
| 16 |  8 | 集合 ID               |
| 24 |  8 | 列 ID                |
| 32 |  8 | 维度                  |
| 40 |  1 | 距离度量                |
| 41 |  7 | 保留                  |
| 48 |  8 | `max_neighbors`     |
| 56 |  8 | `ef_construction`   |
| 64 |  8 | `ef_search_default` |
| 72 |  8 | `random_seed`       |
| 80 |  4 | 头部 CRC32            |

打开时，文件头描述符必须与 Catalog 推导出的描述符完全一致。

## 提交帧

每次图修改追加一个帧。帧前缀固定为 32 字节：

| 偏移 | 大小 | 字段        |
| -: | -: | --------- |
|  0 |  4 | 魔数 `HWC1` |
|  4 |  2 | 版本        |
|  6 |  2 | 保留        |
|  8 |  8 | 帧总大小      |
| 16 |  8 | 连续递增的帧序号  |
| 24 |  4 | 负载 CRC32  |
| 28 |  4 | 保留        |

负载保存提交后的图元数据，以及本次 upsert 的节点完整状态。节点包含向量、删除标记和各层邻居列表。单帧最大为 64 MiB。

## 提交顺序

`HnswStore::commit`：

1. 验证变更后的图约束；
2. 编码完整提交帧；
3. 在内存中准备待发布状态；
4. 记录文件原长度；
5. 追加帧；
6. `sync_data`；
7. 成功后才更新内存图。

追加或同步失败时会尝试把文件截断回原长度并再次同步。由此，运行时不会在帧尚未持久化时先发布新图。

## 打开与尾部恢复

打开文件时，从头到尾重放连续帧。完整前缀或完整帧尚未写完的尾部会被截断到最后一个完整帧边界并同步。

以下情况不会被当成普通尾部撕裂：

* 已完整出现但校验和错误的帧；
* 帧序号不连续；
* 非法节点、邻居或图元数据；
* 描述符与 Catalog 不一致。

这些情况返回结构化错误，再由 `VectorIndexEngine` 判断是否从集合数据重建。

## 内容一致性验证

HNSW 文件结构合法仍不代表内容是最新的。恢复时会把活动节点与集合中的非空向量记录核对，包括记录 ID、向量值和数量。不一致会报告 stale index 并触发重建。

## 压缩

删除产生墓碑，追加更新也使旧帧保留在文件中。checkpoint 在满足任一条件时压缩：

* 墓碑至少 1024 个，且达到物理节点数约四分之一；
* 文件至少 64 MiB，且达到估算紧凑大小的两倍。

压缩从当前集合数据在 `.compact` 文件中重建全新图，关闭旧后端后原子替换正式文件、同步目录并重新打开。统计会记录回收字节数和耗时。

压缩是向量索引文件的维护操作。它不能取代 WAL checkpoint，也不定义集合数据和其他索引的跨文件事务边界。


---

# 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/vector_index/persistence_and_recovery.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.