> ## 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 建表时，每列需声明一个逻辑类型。BlockDB 根据类型校验数据格式、映射到底层存储，并在 SDK 中以对应 Python 类型返回。

## 字符类型（主键可用）

除 `HEXSTRING` 和 `TEXT` 外的所有字符类型均可作为表的主键。

| 类型 | 长度 | 格式 | Python 类型 | 说明 |
| - | - | - | - | - |
| `STRING` | 最大 128 字符 | 普通字符串 | `str` | 通用短字符串 |
| `HASH` | 16 字节（32 hex） | 无前缀 hex | `str` | 通用哈希值 |
| `ADDRESS` | 20 字节（40 hex） | `0x` 前缀 hex | `str` | EVM 地址 |
| `TOKENID` | 20 字节 | `0x` 前缀 hex | `str` | 代币 / NFT 的 token id |
| `TXID` | 32 字节（64 hex） | `0x` 前缀 hex | `str` | 交易哈希 |
| `BLOCKID` | 32 字节（64 hex） | `0x` 前缀 hex | `str` | 区块哈希 |
| `CHAINID` | 最大 32 字符 | 普通字符串 | `str` | 链标识 |
| `DATASET` | 最大 255 字符 | 普通字符串 | `str` | 数据集标识 |
| `LOGO` | 最大 255 字符 | 普通字符串 | `str` | Logo URL 或标识 |

## 字符类型（不可主键 / 不可索引）

| 类型 | 长度 | 格式 | Python 类型 | 说明 |
| - | - | - | - | - |
| `TEXT` | 最大 64 KB | 普通字符串 | `str` | 长文本，不支持实时索引 |
| `HEXSTRING` | 可变，最大约 16 MB | `0x` 前缀 hex | `str` | 可变长度十六进制数据 |

## 数值类型

| 类型 | 范围 | Python 类型 | 说明 |
| - | - | - | - |
| `INT` | 64-bit 有符号整数 | `int` | 通用整数 |
| `BLOCKHEIGHT` | 64-bit 有符号整数 | `int` | 区块高度，语义化 `INT` |
| `UINT256` | \[0, 2²⁵⁶-1] | `int`（API 中以**字符串**传入传出） | 256-bit 无符号大整数，避免 JSON 精度溢出 |
| `FLOAT` | 64-bit IEEE 754 双精度 | `float` | 浮点数 |

## 时间类型

| 类型 | 格式 | Python 类型 | 说明 |
| - | - | - | - |
| `TIMESTAMP` | RFC 3339：`"2026-06-17T10:30:45.123Z"` | `str` | 高精度时间戳 |
| `DATE` | `YYYY-MM-DD` | `str` | 日期 |

## 布尔类型

| 类型 | Python 类型 | 说明 |
| - | - | - |
| `BOOLEAN` | `bool` | 布尔值 |

## 复合类型（不可建索引）

| 类型 | 格式 / 约束 | Python 类型 | 说明 |
| - | - | - | - |
| `JSON` | 任意 JSON | `any`（`json.loads` 后即可使用） | JSON 对象或数组，不可建索引 |
| `LIST` | 必须指定 item 类型，只允许简单类型（不含 LIST / DICT）。例：`LIST(STRING)`、`LIST(TIMESTAMP)` | `list` | 同类型列表 |
| `DICT` | 必须指定 key 和 value 类型，key 限简单字符类型。例：`DICT(STRING,STRING)` | `dict` | 键值对 |

## 类型使用约束

* **主键**只能使用字符类型中的 `STRING`、`HASH`、`ADDRESS`、`TOKENID`、`TXID`、`BLOCKID`、`CHAINID`、`DATASET`、`LOGO`（即除 `HEXSTRING` 和 `TEXT` 外的所有字符类型）。
* **`TEXT`** 不支持实时索引。
* **`HEXSTRING`** 不可作为主键，也不可建索引。
* **`JSON`、`LIST`、`DICT`** 不可建索引。
* 所有字符类型在 SDK 中均以 `str` 表示；所有 hex 类型（`HASH`、`ADDRESS`、`TOKENID`、`TXID`、`BLOCKID`、`HEXSTRING`）在 API 边界为十六进制字符串，BlockDB 内部校验长度与格式后以定长 / 变长字节存储。

## 相关参考

* [Block State 与 Block Event 表](/zh/concepts/block-tables)（链上相关逻辑类型的场景说明）
* [API 总览](/zh/reference/api)


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