blockdb-py

Import public interfaces from blockdb. Use writes and subscriptions in Chaintable Notebooks; Functions can use permitted read interfaces. See the source for the full implementation.

Normal Tables

`NormalTable(table_id)`

table_id is the full table ID. Returns a Normal Table object.

Method	Parameters	Return value
`get(row_id)`	Primary key	Record dictionary, or `None` if missing
`get_many(row_ids)`	Primary-key list	Records in input order, with `None` for missing entries
`filter_rows(filters='', order_by='', limit=0, offset=0)`	SQL condition, sort order, limit, and offset	Record list
`scan(sql)`	Complete supported SQL statement	List of all results
`scan_iter(sql)`	Same as `scan()`	Iterator yielding individual rows
`write(rows, condition=None)`	Record list and optional update condition	`True` when the request is accepted
`batch_write(rows, condition=None)`	Batch records and optional update condition	`True` after asynchronous job submission
`delete(row_ids)`	Primary keys to delete	`True` when the request is accepted

from blockdb import NormalTable

notes = NormalTable('demo.asset_notes')
print(notes.get('usdc'))
print(notes.filter_rows("symbol = 'USDC'", limit=5))
print(notes.scan("SELECT id, symbol FROM `demo.asset_notes` WHERE id = 'usdc'"))

First create the example table, then write its records. filter_rows() conditions omit the WHERE keyword; use limit to restrict the number of rows. In scan(), quote the full table ID with backticks. The SDK does not fill in FROM from the table object. This is the BlockDB scan interface, whose supported SQL differs from the analytics engine.

Conditional writes

from blockdb import NormalTable, IF_LARGER

NormalTable('demo.asset_notes').write(
    [{'id': 'usdc', 'symbol': 'USDC', 'amount': 2000000}],
    condition=('amount', IF_LARGER),
)

condition is (column_name, mode). IF_LARGER updates an existing record only when the new value is larger; IF_SMALLER updates only when it is smaller. Missing records are still inserted. The condition column cannot be the primary key, and all rows in a batch share one condition. Every row in batch_write() needs the same field set. Success does not guarantee an immediately visible write. To check batch-write status, see Inspect asynchronous write jobs.

Block Event and Block State Tables

`EventTable(table_id, block_id=None)` / `StateTable(table_id, block_id=None)`

table_id identifies the table; block_id sets the read position. Event tables read by event ID, while state tables read a business ID’s state at that block. Without block_id, state tables read the object’s latest stored state, while event tables read the record at the highest block height for that event ID, without a consensus-height limit. When you specify a block, the server checks that the table’s consensus height covers it.

Method	Parameters	Return value
`get(row_id)`	Event or state ID	Record dictionary or `None`
`get_many(row_ids)`	ID list	Records corresponding to the inputs
`get_block_rows(block)`	`Block` object or object containing block information	Records written in that block
`get_consensus_height()`	None	Integer table consensus height
`write(rows, block_id)`	Result rows and block ID	`True` when accepted
`batch_write(rows, bundle_id)`	Rows with block fields and a block-bundle number	`True` after asynchronous job submission

from blockdb import StateTable

reserves = StateTable('demo.pool_reserves.eth')
print(reserves.get('0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc'))

This example reads the latest state from the table built in Track liquidity pool reserves. Reading state at a specified block requires the table’s consensus height to cover that block; see How tables work. For per-block write(), the server fills in block fields. Every row in batch_write() must include block_id, block_height, and block_timestamp. A bundle number is not a block height.

Time Tables

`TimeTable(table_id, time_at=None)`

time_at sets the read time; omit it for the latest value. It accepts RFC3339 strings or Python datetime values. Times without a timezone are interpreted as UTC.

Method	Parameters	Return value
`get(row_id)`	Business ID	Record containing `id`, `time_at`, and `value`, or `None`
`get_many(row_ids)`	ID list	Records in input order, with `None` for missing entries
`write(rows, time_at)`	`{id, value}` records and a shared timestamp	`True` when accepted
`batch_write(rows)`	Rows each containing `id`, `time_at`, and `value`	`True` after asynchronous job submission

from blockdb import TimeTable

price = TimeTable('price.price.eth').get(
    '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
)
print(price)

write() uses its timestamp argument, ignoring any row-level time_at. Use batch_write() for multiple timestamps, with each row containing only the three fixed fields. The server groups time points into buckets and keeps the latest point in each bucket. Resolution changes with data age; see How tables work.

Blocks and subscriptions

Interface	Parameters and return value
`Block(id, height, timestamp)`	Block ID, integer height, and timestamp; returns a block object
`Subscribe(tables=None, start_at=None)`	Table objects or IDs, with an optional event-time cursor
`sub.listen()`	Continuously yields `(table_id, Block)`
`sub.close()`	Stops the subscription; callable from another thread
`Aligned(sub, loose_align=None, strict_align=None)`	Subscription, trigger tables, and consensus dependency tables
`aligned.listen()`	Yields `Block` when the tables meet height requirements

start_at is a subscription event-time cursor accepting an RFC3339 string or Unix seconds, not a historical block height. Reconnection does not guarantee recovery of arbitrarily old events; combine subscriptions with backfills. loose_align requires at least one trigger table. strict_align requires dependency consensus to reach the block being processed. See Subscribe to block events for a runnable example.

Filter expressions and types

from blockdb import Column, filter

operator = filter(
    (Column('contract_id') == '0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc')
    & (Column('name') == 'Sync')
)

Column and filter() build filters for Pipeline sources. Combine expressions with parenthesized & and |. Do not pass these expressions to filter_rows(), which expects a SQL condition string. LogicalType provides type names, and restore_value(logical_type, raw) restores Python values according to metadata. For example, restore_value('UINT256', '1500000') retains a decimal string; use int() for computation. See Data types.

Overview

Quickstart

Guides

Reference

Normal Tables

`NormalTable(table_id)`

Conditional writes

Block Event and Block State Tables

`EventTable(table_id, block_id=None)` / `StateTable(table_id, block_id=None)`

Time Tables

`TimeTable(table_id, time_at=None)`

Blocks and subscriptions

Filter expressions and types

​Normal Tables

​NormalTable(table_id)

​Conditional writes

​Block Event and Block State Tables

​EventTable(table_id, block_id=None) / StateTable(table_id, block_id=None)

​Time Tables

​TimeTable(table_id, time_at=None)

​Blocks and subscriptions

​Filter expressions and types

Normal Tables

`NormalTable(table_id)`

Conditional writes

Block Event and Block State Tables

`EventTable(table_id, block_id=None)` / `StateTable(table_id, block_id=None)`

Time Tables

`TimeTable(table_id, time_at=None)`

Blocks and subscriptions

Filter expressions and types