> ## 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.

# 数据类型

> 数据表字段的格式、数值精度，以及 Python SDK 与 SQL 中的类型对应。

字段类型规定写入格式和读取结果。创建表时在 **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 位整数：`-2**63` 至 `2**63 - 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 整数：

```python theme={null}
raw_amount = int('1500000')
amount_usdc = raw_amount / 10 ** 6
```

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

```python theme={null}
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` 三个字段均非空。