Data types

When you create a BlockDB table, every column declares a logical type. BlockDB validates the data format against the type, maps it to the underlying storage, and returns it as the corresponding Python type in the SDK.

Character types (usable as primary key)

Every character type except HEXSTRING and TEXT can be used as a table’s primary key.

Type	Length	Format	Python type	Description
`STRING`	Up to 128 chars	Plain string	`str`	General-purpose short string
`HASH`	16 bytes (32 hex)	Hex, no prefix	`str`	Generic hash value
`ADDRESS`	20 bytes (40 hex)	Hex with `0x` prefix	`str`	EVM address
`TOKENID`	20 bytes	Hex with `0x` prefix	`str`	Token / NFT token id
`TXID`	32 bytes (64 hex)	Hex with `0x` prefix	`str`	Transaction hash
`BLOCKID`	32 bytes (64 hex)	Hex with `0x` prefix	`str`	Block hash
`CHAINID`	Up to 32 chars	Plain string	`str`	Chain identifier
`DATASET`	Up to 255 chars	Plain string	`str`	Dataset identifier
`LOGO`	Up to 255 chars	Plain string	`str`	Logo URL or identifier

Character types (not usable as primary key or index)

Type	Length	Format	Python type	Description
`TEXT`	Up to 64 KB	Plain string	`str`	Long text; does not support real-time indexing
`HEXSTRING`	Variable, up to ~16 MB	Hex with `0x` prefix	`str`	Variable-length hexadecimal data

Numeric types

Type	Range	Python type	Description
`INT`	64-bit signed integer	`int`	General-purpose integer
`BLOCKHEIGHT`	64-bit signed integer	`int`	Block height; a semantic `INT`
`UINT256`	[0, 2²⁵⁶-1]	`int` (passed as a string at the API boundary)	256-bit unsigned big integer; avoids JSON precision loss
`FLOAT`	64-bit IEEE 754 double	`float`	Floating-point number

Time types

Type	Format	Python type	Description
`TIMESTAMP`	RFC 3339: `"2026-06-17T10:30:45.123Z"`	`str`	High-precision timestamp
`DATE`	`YYYY-MM-DD`	`str`	Date

Boolean type

Type	Python type	Description
`BOOLEAN`	`bool`	Boolean value

Composite types (not indexable)

Type	Format / constraints	Python type	Description
`JSON`	Any JSON	`any` (usable after `json.loads`)	JSON object or array; not indexable
`LIST`	Item type required, simple types only (no LIST / DICT). Examples: `LIST(STRING)`, `LIST(TIMESTAMP)`	`list`	Homogeneous list
`DICT`	Key and value types required; keys limited to simple character types. Example: `DICT(STRING,STRING)`	`dict`	Key-value pairs

Type usage constraints

Primary keys may only use the character types STRING, HASH, ADDRESS, TOKENID, TXID, BLOCKID, CHAINID, DATASET, and LOGO (that is, every character type except HEXSTRING and TEXT).
TEXT does not support real-time indexing.
HEXSTRING cannot be a primary key and cannot be indexed.
JSON, LIST, and DICT cannot be indexed.
All character types are represented as str in the SDK. All hex types (HASH, ADDRESS, TOKENID, TXID, BLOCKID, HEXSTRING) are hexadecimal strings at the API boundary; BlockDB validates their length and format and stores them as fixed-length or variable-length bytes.

Block State Table and Block Event Table (scenarios for the blockchain-specific logical types)
API overview

Getting started

Core concepts

Architecture

Guides

Reference

Data types

Data types

Character types (usable as primary key)

Character types (not usable as primary key or index)

Numeric types

Time types

Boolean type

Composite types (not indexable)

Type usage constraints

​Data types

​Character types (usable as primary key)

​Character types (not usable as primary key or index)

​Numeric types

​Time types

​Boolean type

​Composite types (not indexable)

​Type usage constraints

​Related topics

Data types

Character types (usable as primary key)

Character types (not usable as primary key or index)

Numeric types

Time types

Boolean type

Composite types (not indexable)

Type usage constraints

Related topics