快速开始

BlockDB 只暴露 gRPC 服务。本快速开始直接用 grpcurl 与 JSON 驱动这些服务，无需 SDK。gRPC reflection 已开启，因此 grpcurl 会自动发现 schema。

0. 前置条件

一个运行中的 BlockDB 实例（默认服务地址 localhost:19002）。
已安装 grpcurl。

验证连接并列出服务：

grpcurl -plaintext localhost:19002 list

你应该看到 blockdb.v1.TableReadService、blockdb.v1.BlockReadService 等服务。

第 1 步 — 写入普通表

使用 TableWriteService/UpsertRows。每个 Value 都是只包含你想设置那个字段的 JSON 对象（stringValue、intValue、doubleValue、boolValue）。

grpcurl -plaintext -d '{
  "tableId": "demo.event_log",
  "rows": [
    {
      "fields": {
        "id":    { "stringValue": "evt_001" },
        "name":  { "stringValue": "login" },
        "value": { "intValue": "1" }
      }
    }
  ]
}' localhost:19002 blockdb.v1.TableWriteService/UpsertRows

写入成功返回一个任务 ID：

{ "result": { "affectedRows": "1", "jobId": "..." } }

写入是异步的。返回的 jobId 不代表数据已提交。

第 2 步 — 读取一行

grpcurl -plaintext -d '{
  "tableId": "demo.event_log",
  "rowId":   { "stringValue": "evt_001" }
}' localhost:19002 blockdb.v1.TableReadService/GetRow

你会得到一个 schema 加一个位置数组：

{
  "result": {
    "columns": [ { "name": "id", "logicalType": "STRING" }, { "name": "value", "logicalType": "INT" } ],
    "rows": [ { "values": [ { "stringValue": "evt_001" }, { "intValue": "1" } ] } ]
  }
}

第 3 步 — 写入 Block State 表

链上状态用 BlockWriteService/UpsertBlock 加 block 锚点写入（示例表 token.token.eth 是一张 Block State 表）：

grpcurl -plaintext -d '{
  "tableId": "token.token.eth",
  "block": {
    "blockId": "0x0c76b9c84c58c1d77cd4d6bd70c3cf27d7b7ae151a26c00403191f3be18114a0",
    "height":  "18000000",
    "timestamp": "2024-06-08T00:00:00Z"
  },
  "rows": [
    { "fields": { "id": { "stringValue": "acct_1" }, "balance": { "intValue": "1000" } } },
    { "fields": { "id": { "stringValue": "acct_2" }, "balance": { "intValue": "2000" } } }
  ]
}' localhost:19002 blockdb.v1.BlockWriteService/UpsertBlock

第 4 步 — 按区块高度读取状态

用 currentBlock 锚定读取；BlockDB 注入 height ≤ 目标高度：

grpcurl -plaintext -d '{
  "tableId": "token.token.eth",
  "stateId": { "stringValue": "acct_1" },
  "currentBlock": {
    "blockId": "0x0c76...",
    "height":  "18000000",
    "timestamp": "2024-06-08T00:00:00Z"
  }
}' localhost:19002 blockdb.v1.BlockReadService/GetState

第 5 步 — 订阅区块写入事件

BlockSubscribeService/Subscribe 是一个服务端流式调用，保持打开并按每个区块写入推送事件：

grpcurl -plaintext -d '{"tableIds": ["token.token.eth"]}' \
  localhost:19002 blockdb.v1.BlockSubscribeService/Subscribe

每个事件形如：

{
  "tableId": "token.token.eth",
  "block": { "blockId": "0x...", "height": "18000001", "timestamp": "..." },
  "createdAt": "1720000000"
}

下一步

API 总览 — 每个方法的完整参考（proto、JSON、grpcurl）。
读写数据 — 通过 blockdb-py SDK 完成同样的操作。
写入架构 — 批量写与异步模型。
配合 BlockX 高并发计算

开始使用

核心概念

架构介绍

使用指南

参考

快速开始

快速开始

0. 前置条件

第 1 步 — 写入普通表

第 2 步 — 读取一行

第 3 步 — 写入 Block State 表

第 4 步 — 按区块高度读取状态

第 5 步 — 订阅区块写入事件

下一步

​快速开始

​0. 前置条件

​第 1 步 — 写入普通表

​第 2 步 — 读取一行

​第 3 步 — 写入 Block State 表

​第 4 步 — 按区块高度读取状态

​第 5 步 — 订阅区块写入事件

​下一步

快速开始

0. 前置条件

第 1 步 — 写入普通表

第 2 步 — 读取一行

第 3 步 — 写入 Block State 表

第 4 步 — 按区块高度读取状态

第 5 步 — 订阅区块写入事件

下一步