> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BlockDB 是什么

> BlockDB 是一个逻辑数据库层：底层管理 MySQL 协议数据库，上层提供普通表、Block State/Event 表与 Time 表三类逻辑表及各自的读写 API。

# BlockDB 是什么

BlockDB 是一个**逻辑数据库层**。它底层管理和操作 **MySQL 协议的 OLTP 物理数据库**，上层通过两层表模型，把数据抽象为可编程的逻辑表，并为不同类型的逻辑表提供各自的读写 API。用户不与物理存储直接打交道，而是通过语义化接口操作逻辑表。

## 逻辑数据库层

BlockDB 的本质是一层"逻辑数据库"：

* **底层**：管理和操作 MySQL 协议的 OLTP 物理在线数据库。
* **逻辑层**：定义逻辑表、组织映射到物理表、屏蔽存储细节，向上提供统一的语义化接口。

用户无需直接书写 SQL 管理物理表。BlockDB 通过\*\*元数据服务（Meta）\*\*管理逻辑表及其列、索引定义，并将逻辑表落到实际的存储引擎上。

## 两层模型与三类逻辑表

BlockDB 用两层模型组织表，共提供三类逻辑表：

| 层 | 逻辑表类型 | 说明 |
| - | - | - |
| 普通表 | 普通在线表（Table） | 直接对应一张物理表，行级语义化 CRUD |
| 业务抽象表 | Block State 表 / Block Event 表 | 链上语义表，底层由多张协作物理表支撑 |
| 业务抽象表 | Time 表 | 按物理时间分桶的状态序列 |

### 普通表（Table）

普通表直接映射到一张物理在线表（1:1），用于存储非链上的业务数据，或链上数据处理后的高价值数据，提供行级、语义化的读写与扫描 API。

### 业务抽象表（Block State / Block Event / Time 表）

业务抽象表**本身不直接对应一张物理表**。创建时，BlockDB 会在底层自动派生多张协作的物理表（影子表机制），用于维护最新值、历史快照与处理进度：

| 逻辑表 | 派生的物理表 |
| - | - |
| Block State 表 | 主表、`_archive`（历史快照）、`_height`（处理进度 / 共识高度）、`_bundle`（区块区间哈希） |
| Block Event 表 | 主表、`_height`、`_bundle`（事件不可变只追加，不维护 `_archive`） |
| Time 表 | 主表、`_archive`（历史，按时间分桶） |

不同类型的业务抽象表，提供不同的链上语义 API（见下节）。

## 各类逻辑表的读写 API

BlockDB 针对不同类型的逻辑表，定义了各自的访问接口（来自 `proto/blockdb/v1/`）：

| 逻辑表 | 读 | 写 | 订阅 / 扫描 |
| - | - | - | - |
| 普通表（Table） | `GetRow` / `BatchGetRows` / `FilterRows` | `UpsertRows` / `DeleteRows` | `Scan`（流式扫描） |
| Block State 表 | `GetState`（按区块时刻读状态快照） | `UpsertBlock`（按区块原子写） | `Subscribe`（区块订阅） |
| Block Event 表 | `GetEvent`（按区块时刻读事件） | `UpsertBlock` | `Subscribe` |
| 业务抽象表通用 | `GetConsensusHeight` / `GetBlockRows` | — | — |
| Time 表 | `GetValue`（按时间戳读） | `UpsertTimeRows` | — |

此外，还有面向大批量数据的**批量写入**能力：通过 `BatchWriteService`（`InitWriteJob` / `CommitWriteJob` / `CancelWriteJob`）以 S3 中转实现大规模异步写入。具体架构与提交流程详见[大批量写](/zh/architecture/batch-write)。

## 元数据管理

BlockDB 通过元数据服务（Meta）管理逻辑表的生命周期与定义，包含三个子服务：

| 元数据服务 | 管理对象 | 主要方法 |
| - | - | - |
| `TableMetaService` | 普通表 | `CreateTable` / `SaveTable` / `GetTable` / `DropTable` / `ListTable` |
| `BlockMetaService` | Block State / Event 表 | `CreateBlockTable` / `SaveBlockTable` / `GetBlockTable` / `DropBlockTable` / `ListBlockTables` |
| `TimeMetaService` | Time 表 | `CreateTimeTable` / `SaveTimeTable` / `GetTimeTable` / `DropTimeTable` / `ListTimeTables` |

每个逻辑表都带有\*\*类型（type）\*\*标记——`state` / `event` / `time`。BlockDB 据此判断它是一张普通表还是某种业务抽象表，以及如何映射到物理存储。Block 表还带有 `chain_id` 与起始高度等链上语义配置。

## 小结

* BlockDB 是一个**逻辑数据库层**，管理 MySQL 协议数据库。
* 通过**两层模型**提供三类逻辑表：普通表、Block State / Event 表、Time 表。
* 每类逻辑表都有**各自的读写 API**，让用户按数据形态（行级 / 区块 / 时间）选择最合适的模型。

继续阅读：

* [数据模型](/zh/concepts/data-model)：Table / BlockTable / TimeTable 与影子表机制。
* [Block State 与 Block Event 表](/zh/concepts/block-tables)：两种链上语义表模型。
* [写入与事件订阅](/zh/concepts/write-subscribe)：实时写 / 批量写与订阅。
* [API 总览](/zh/reference/api)：完整服务与方法。
* [架构介绍](/zh/architecture/overview)：代码层面的组件与实现。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.