逻辑类型

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 表（链上相关逻辑类型的场景说明）
API 总览