> ## 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.

# Quickstart

> Make your first reads, writes, and subscriptions against BlockDB gRPC in a few minutes.

# Quickstart

BlockDB exposes only gRPC services. This quickstart drives them directly with `grpcurl` and JSON — no SDK required. gRPC reflection is enabled, so `grpcurl` discovers the schema itself.

## 0. Prerequisites

* A running BlockDB instance (default service address `localhost:19002`).
* [`grpcurl`](https://github.com/fullstorydev/grpcurl) installed.

Verify the connection and list the services:

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

You should see `blockdb.v1.TableReadService`, `blockdb.v1.BlockReadService`, and the other services.

## Step 1 — Write to a regular table

Use `TableWriteService/UpsertRows`. Every `Value` is a JSON object holding the one field you set (`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
```

A successful write returns a job ID:

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

<Note>
  Writes are asynchronous. The returned `jobId` does not mean the data is already committed.
</Note>

## Step 2 — Read a row

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

You get back a schema plus a positional array:

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

## Step 3 — Write to a Block State Table

For on-chain state, use `BlockWriteService/UpsertBlock` with a `block` anchor (the example table `token.token.eth` is a Block State table):

```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
```

## Step 4 — Read state at a block height

Anchor the read with `currentBlock`; BlockDB injects `height ≤ target 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
```

## Step 5 — Subscribe to block write events

`BlockSubscribeService/Subscribe` is a server-streaming call. It stays open and streams an event per block write:

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

Each event looks like:

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

## Next steps

* [API overview](/reference/api) — full reference with proto, JSON, and grpcurl for every method.
* [Read and write data](/guides/data-access) — the same operations through the `blockdb-py` SDK.
* [Write architecture](/architecture/batch-write) — batch writes and the asynchronous model.
* [High-concurrency compute with BlockX](/guides/blockx)


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