> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 在几分钟内直接通过 gRPC 完成 BlockDB 的读写与订阅。

# 快速开始

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

## 0. 前置条件

* 一个运行中的 BlockDB 实例（默认服务地址 `localhost:19002`）。
* 已安装 [`grpcurl`](https://github.com/fullstorydev/grpcurl)。

验证连接并列出服务：

```bash theme={null}
grpcurl -plaintext localhost:19002 list
```

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

## 第 1 步 — 写入普通表

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

```bash theme={null}
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：

```json theme={null}
{ "result": { "affectedRows": "1", "jobId": "..." } }
```

<Note>
  写入是异步的。返回的 `jobId` 不代表数据已提交。
</Note>

## 第 2 步 — 读取一行

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

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

```json theme={null}
{
  "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 表）：

```bash theme={null}
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 ≤ 目标高度`：

```bash theme={null}
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` 是一个服务端流式调用，保持打开并按每个区块写入推送事件：

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

每个事件形如：

```json theme={null}
{
  "tableId": "token.token.eth",
  "block": { "blockId": "0x...", "height": "18000001", "timestamp": "..." },
  "createdAt": "1720000000"
}
```

## 下一步

* [API 总览](/zh/reference/api) — 每个方法的完整参考（proto、JSON、grpcurl）。
* [读写数据](/zh/guides/data-access) — 通过 `blockdb-py` SDK 完成同样的操作。
* [写入架构](/zh/architecture/batch-write) — 批量写与异步模型。
* [配合 BlockX 高并发计算](/zh/guides/blockx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.