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

# Block State表和Block Event表

> 深入理解 Chaintable 的两大核心逻辑表模型及其区块链语义扩展

***

Chaintable Block 表不仅仅是存储数据，它还通过 **BlockDB 抽象层** 赋予了每个物理表“理解区块链”的能力。在传统数据库中，你需要自己维护区块高度、处理数据覆盖与回退；而在 Chaintable 中，平台将链上数据抽象为两种核心逻辑模型：**Block State 表** 与 **Block Event 表**。

***

## 1. 模型定义与选型指南

### Block State 表：单行状态模型

如果你关注的是链上实体的**当前最新状态或最新结果**，请使用 Block State 表。

* **设计哲学**：以唯一实体（如“地址”、“合约”）为主键，每次写入都会覆盖上一次的状态，但 BlockDB 会在底层保留历史快照。
* **典型场景**：
  * 用户的原始代币余额（Balances）
  * 智能合约的当前状态变量（State Variables）
  * NFT 的当前持有人（Current Owners）
* **系统内置字段**：除了业务主键外，BlockDB 会自动隐式维护 `block_id` `block_height`和 `block_timestamp`，用以支持状态的历史版本回溯。

### Block Event 表：事实记录模型

如果你关注的是链上发生的**历史流水或事件痕迹**，请使用 Block Event 表。

* **设计哲学**：数据是只读且追加（Append-only）的，每一行代表一个确定发生过的链上事实，不可被修改。
* **典型场景**：
  * 代币转账流水（Transfer Logs）
  * 智能合约的事件抛出（Event Emitted）
  * 交易所的每笔撮合记录（Swap Trades）
* **系统内置字段**：每行数据, BlockDB会自动隐式维护 `block_id`、`block_height` 和 `block_timestamp`列。

***

## 2. Block 抽象表的三大核心特性

无论你选择哪种表，BlockDB 抽象层都为其注入了以下企业级的链上数据管理能力：

### 1. 区块语义的建模与原生读写 API

* **区块粒度原子性（Atomic Write）**：写入 API 保证以“区块”为最小单元进行提交。一个区块内的加工数据要么全部写入成功，要么全部失败，绝对不会出现“半个区块”的脏数据。
* **历史高度回溯（Time-travel Query）**：读取 API 原生支持 `AS OF BLOCK <height>` 语义。即使 State 表里存的是最新余额，你也可以一行代码查询其在任意历史区块高度下的历史余额。

### 2. 实时事件订阅 API（下游联动）

* 当你使用 Notebook 任务或者BlockX计算引擎，向一张 Block 表执行区块数据写入时，BlockDB 会自动捕获变更，并产生标准化的 **Table Block Events**。
* 这一机制使得下游的其他任务可以通过事件订阅，**实时、增量地**处理上游表在每个区块高度产出的数据，极其优雅地构建多级级联的事件驱动数据管道（Data Pipeline）。

### 3. 零感知的自动分叉处理（Auto-Reorg Management）

* 区块链的分叉（Reorg）是链上数据处理的最大痛点。当底层链发生分叉、需要回滚 N 个区块时，Chaintable 会自动捕获这一事件。
* **自动撤销机制**：BlockDB 会基于隐式维护的区块列，自动撤销分叉block\_id的数据写入行，删除block event表的相关事件，保证block state表的状态最终一致。

***

## 总结与开发建议

| 比较维度      | Block State 表   | Block Event 表      |
| :-------- | :-------------- | :----------------- |
| **数据形态**  | 状态快照（最新结果）      | 流水日志（历史事实）         |
| **查询关注点** | “某个地址现在的资产是多少？” | “过去 24 小时发生了哪些转账？” |

在链上数据生产场景中，使用 Block 表及其高级 API，开发效率和数据质量会远高于自己基于普通关系型数据库或 ClickHouse 搭建流程。**在 Chaintable 平台中，链上数据应该始终选择创建 Block 表来进行管理。**