Data types

Field types define write formats and read results. Select types under Schema when creating a table. The primary key id uses a permitted string type and cannot be changed arbitrarily to a numeric field.

Strings and chain identifiers

Python types below describe common BlockDB SDK read representations. SQL types describe analytics-storage mappings; use the actual query result’s type information for a specific column.

Field type	Format and purpose	Python	SQL
`STRING`	Short string, up to 128 characters	`str`	`VARCHAR`
`TEXT`	Longer text, up to 16000 characters	`str`	`VARCHAR`
`HEXSTRING`	`0x` followed by an even number of hexadecimal digits, such as `0x1234`	`str`	`VARCHAR`
`ADDRESS`	EVM address: `0x` plus 40 hexadecimal digits	`str`	`VARCHAR`
`TOKENID`	Token identifier; EVM tokens usually use contract addresses	`str`	`VARCHAR`
`TXID`	Transaction hash: `0x` plus 64 hexadecimal digits	`str`	`VARCHAR`
`BLOCKID`	Block hash: `0x` plus 64 hexadecimal digits	`str`	`VARCHAR`
`HASH`	32-character hexadecimal record identifier, usually without `0x`	`str`	`VARCHAR`
`CHAINID`	Supported chain ID, such as `eth`	`str`	`VARCHAR`
`LOGO`	String value identifying a logo resource	`str`	`VARCHAR`

Use consistent lowercase addresses and hexadecimal identifiers. HASH has a different length from transaction and block hashes and is not interchangeable with them.

Numbers and booleans

Field type	Range or precision	Python	SQL
`INT`	Signed 64-bit integer: `-263` through `263 - 1`	`int`	`BIGINT`
`BLOCKHEIGHT`	Nonnegative integer up to `2**63 - 1`	`int`	`BIGINT`
`UINT256`	Integer from `0` through `2**256 - 1`	Decimal `str`	`VARBINARY`
`FLOAT`	64-bit floating point for approximate calculations	`float`	`DOUBLE`
`BOOLEAN`	`True` / `False`, or JSON `true` / `false`	`bool`	`BOOLEAN`

Large-integer precision

UINT256 reads return decimal strings. Convert to Python integers before computation:

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

Write integers outside the signed 64-bit range as decimal strings, for example:

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

Do not convert to float before writing an integer back, as that may lose precision. Similarly, do not pass large integers through JavaScript Number. UINT256 uses VARBINARY in SQL, while the query results page displays decimal strings. The display format does not determine the SQL type. For exact calculations, convert the values you read to Python int.

Dates and timestamps

Field type	Recommended format	Python SDK read	SQL
`DATE`	`YYYY-MM-DD`, such as `2026-09-09`	Date string	`DATE`
`TIMESTAMP`	RFC3339 with timezone, such as `2026-09-09T12:00:00Z`	Timestamp string	`TIMESTAMP`

Time Table interfaces accept strings and Python datetime values. Times without a timezone are treated as UTC. Prefer timezone-aware inputs to avoid confusing display timezone with data time. BlockDB’s block_timestamp field is an RFC3339 string, while timestamp in a Leafage block dictionary is Unix seconds. The similar names use different formats.

Structured fields

Field type	Format	Python	SQL representation
`JSON`	JSON-serializable object or array	`dict`, `list`, and other JSON values	`VARCHAR` containing JSON text
`LIST(T)`	List of elements of type `T`, such as `LIST(STRING)`	`list`	`VARCHAR` containing a JSON array
`DICT(K,V)`	Map with key type `K` and value type `V`, such as `DICT(STRING,INT)`	`dict`	`VARCHAR` containing a JSON object

After choosing LIST or DICT in the field editor, select the element or key/value types. Nested values must satisfy their own type requirements. In SQL, use JSON functions to parse these fields. Older data or metadata may also contain names such as OBJECT, DATASET, BIGINT, DOUBLE, or DECIMAL. These are not new-field types in the current selector. Follow the Schema when reading existing tables, and use the types above for new tables. Missing values are usually Python None or JSON null, distinct from an empty string, 0, or False. Primary keys cannot be null. Time Table batch writes require non-null id, time_at, and value fields.

Overview

Quickstart

Guides

Reference

Strings and chain identifiers

Numbers and booleans

Large-integer precision

Dates and timestamps

Structured fields

​Strings and chain identifiers

​Numbers and booleans

​Large-integer precision

​Dates and timestamps

​Structured fields

Strings and chain identifiers

Numbers and booleans

Large-integer precision

Dates and timestamps

Structured fields