实时订阅
当一个 Block 表有新块写入,BlockDB 会通过 Kafka 发布一个区块订阅事件。SDK 的Subscribe 负责消费这个事件流,把下游业务接在区块”心跳”上,构建”生产 → 事件 → 消费”的闭环。
基本用法
订阅一张 Block 表,逐块消费:listen() 是一个长驻生成器,每次 yield (table_id, block)。block 是 Block 数据单位(id / height / timestamp)。
多表订阅
订阅多张表时,事件按表分发,table_id 用来区分来源。同一张表重复传入会被去重:
指定起始游标
默认从最新开始订阅。用start_at 指定起始游标,从某个时间之后的事件开始消费:
start_at 接受 RFC3339 时间字符串(如 2026-08-17T00:00:00Z)或 epoch 秒(int)。
start_at 最远只能回看到当前时间往前 1 小时以内(服务端 subscribe.max_lookback,默认 1h)。早于这个时间会被服务端以 InvalidArgument 拒绝。断线重连与游标续传
Subscribe 内置重连机制,无需业务层写重试:
- 自动重连:流断开(服务端空闲收流、重启、rebalance 或报错)都会自动重连,指数退避(1s → 30s)。
- 游标续传:重连会带上最后事件的时间游标,服务端回放断流期间的事件。
- 回放窗口:服务端对旧游标有 1 小时回放窗口;SDK 会把游标夹到 30 分钟内,太老的游标会被丢弃、改从最新订阅(漏掉的块由上游按高度补洞)。
for ... in listen(): 消费即可,无需自己写 try/except 重试。
停止订阅
close() 可以从另一个线程叫停正在阻塞的 listen():
多表订阅若需要按高度对齐(保证所有依赖表在目标高度都已就绪),请用
Aligned,见多表区块高度对齐订阅。