数据类型

字段类型规定写入格式和读取结果。创建表时在 Schema 中选择类型；主键 id 使用允许的字符串类型，不能任意改为数值字段。

字符串和链上标识

下表的 Python 类型指 BlockDB SDK 读取值的常见表示，SQL 类型指分析存储中的对应类型。具体查询列仍以查询结果的类型信息为准。

字段类型	格式与用途	Python	SQL
`STRING`	普通短字符串，最长 128 个字符	`str`	`VARCHAR`
`TEXT`	较长文本，最长 16000 个字符	`str`	`VARCHAR`
`HEXSTRING`	`0x` 加偶数位十六进制字符，如 `0x1234`	`str`	`VARCHAR`
`ADDRESS`	EVM 地址，`0x` 加 40 位十六进制字符	`str`	`VARCHAR`
`TOKENID`	代币标识；EVM 代币通常使用合约地址	`str`	`VARCHAR`
`TXID`	交易哈希，`0x` 加 64 位十六进制字符	`str`	`VARCHAR`
`BLOCKID`	区块哈希，`0x` 加 64 位十六进制字符	`str`	`VARCHAR`
`HASH`	32 位十六进制记录标识，通常不含 `0x`	`str`	`VARCHAR`
`CHAINID`	平台支持的链 ID，例如 `eth`	`str`	`VARCHAR`
`LOGO`	Logo 资源的字符串值	`str`	`VARCHAR`

地址和十六进制标识使用统一的小写形式。HASH 与交易或区块哈希的长度不同，不能互换。

数值和布尔值

字段类型	范围或精度	Python	SQL
`INT`	有符号 64 位整数：`-263` 至 `263 - 1`	`int`	`BIGINT`
`BLOCKHEIGHT`	非负整数，最大 `2**63 - 1`	`int`	`BIGINT`
`UINT256`	`0` 至 `2**256 - 1` 的整数	十进制 `str`	`VARCHAR`
`FLOAT`	64 位浮点数，适合近似计算	`float`	`DOUBLE`
`BOOLEAN`	`True` / `False`，JSON 为 `true` / `false`	`bool`	`BOOLEAN`

大整数精度

UINT256 读取结果为十进制字符串，计算时先转为 Python 整数：

raw_amount = int('1500000')
amount_usdc = raw_amount / 10 ** 6

写入超出有符号 64 位范围的整数时使用十进制字符串，例如：

row = {
    'id': '0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc',
    'reserve_usdc': '10126490434274',
    'reserve_weth': '4043982044925209426729',
}

不要先转成 float 再写回整数，否则可能丢失精度。JavaScript 中同样不要通过 Number 传递大整数。 SQL 中若要计算字符串形式的数值，应显式转换并确认目标数值类型容纳得下。DOUBLE 适合近似统计，不能完整保存任意 UINT256；十进制类型的精度也可能小于 256 位整数所需精度。

日期和时间

字段类型	建议格式	Python SDK 读取	SQL
`DATE`	`YYYY-MM-DD`，例如 `2026-09-09`	日期字符串	`DATE`
`TIMESTAMP`	带时区的 RFC3339，例如 `2026-09-09T12:00:00Z`	时间字符串	`TIMESTAMP`

SDK 的时间表接口接受时间字符串和 Python datetime，无时区时间按 UTC 解释。统一使用带时区的输入，避免页面显示时区与数据时间混淆。 BlockDB.Block.timestamp 是 RFC3339 字符串；Leafage 返回的区块字典 timestamp 是 Unix 秒数。两者名称相近，但格式不同。

结构化字段

字段类型	格式	Python	SQL 表示
`JSON`	可序列化为 JSON 的对象或数组	`dict`、`list` 等	JSON 文本，按查询需要解析
`LIST(T)`	元素类型为 `T` 的列表，例如 `LIST(STRING)`	`list`	对应元素类型的 `ARRAY`
`DICT(K,V)`	键和值类型分别为 `K`、`V`，例如 `DICT(STRING,INT)`	`dict`	对应键值类型的 `MAP`

在字段编辑器选择 LIST 或 DICT 后，还需选择元素或键值类型。复杂类型内部的值也必须满足各自类型要求。旧数据或元数据中还可能出现 OBJECT、DATASET、BIGINT、DOUBLE 或 DECIMAL 等名称；它们不属于当前字段选择器提供的新建类型。阅读已有表时以其 Schema 为准，新建表优先使用上面的类型。缺失值通常表示为 Python None 或 JSON null，与空字符串、0 和 False 不同。主键不能为空；时间表的批量写入要求 id、time_at、value 三个字段均非空。

概览

快速开始

使用指南

参考

字符串和链上标识

数值和布尔值

大整数精度

日期和时间

结构化字段

​字符串和链上标识

​数值和布尔值

​大整数精度

​日期和时间

​结构化字段

字符串和链上标识

数值和布尔值

大整数精度

日期和时间

结构化字段