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

# Introduction

> BlockDB is a logical database layer: it manages MySQL-protocol databases underneath and exposes regular tables, Block State/Event tables, and Time Tables with their own read/write APIs.

# Introduction

BlockDB is a **logical database layer**. It manages and operates **MySQL-protocol OLTP databases** underneath, and uses a two-layer table model to abstract data into programmable logical tables, each with its own read and write APIs. You never work with physical storage directly; you operate logical tables through semantic interfaces.

## A logical database layer

BlockDB is essentially a "logical database":

* **Underneath**: it manages and operates MySQL-protocol OLTP online databases.
* **Logical layer**: it defines logical tables, maps them to physical tables, hides storage details, and exposes a unified semantic interface.

You never write SQL to manage physical tables. BlockDB manages logical tables and their column and index definitions through a **metadata service (Meta)**, and materializes them onto the actual storage engine.

## Two-layer model, three logical table types

BlockDB organizes tables in two layers and offers three logical table types:

| Layer | Logical table type | Description |
| - | - | - |
| Regular table | Regular online table (Table) | Maps directly to one physical table; row-level semantic CRUD |
| Business abstraction | Block State Table / Block Event Table | On-chain semantic tables, backed by several cooperating physical tables |
| Business abstraction | Time Table | State series bucketed by physical time |

### Regular tables (Table)

A regular table maps 1:1 to a physical online table. Use it for non-on-chain business data, or for high-value data derived from on-chain processing. It offers row-level semantic read, write, and scan APIs.

### Business abstraction tables (Block State / Block Event / Time Table)

A business abstraction table **does not map directly to a single physical table**. When you create one, BlockDB automatically derives several cooperating physical tables (the shadow table mechanism) to maintain the latest values, historical snapshots, and processing progress:

| Logical table | Derived physical tables |
| - | - |
| Block State Table | main table, `_archive` (historical snapshots), `_height` (progress / consensus height), `_bundle` (block range hashes) |
| Block Event Table | main table, `_height`, `_bundle` (events are immutable and append-only, so no `_archive`) |
| Time Table | main table, `_archive` (history, bucketed by time) |

Different business abstraction table types expose different on-chain semantic APIs (see below).

## Read and write APIs per logical table

BlockDB defines dedicated interfaces for each logical table type (from `proto/blockdb/v1/`):

| Logical table | Read | Write | Subscribe / scan |
| - | - | - | - |
| Regular table (Table) | `GetRow` / `BatchGetRows` / `FilterRows` | `UpsertRows` / `DeleteRows` | `Scan` (streaming scan) |
| Block State Table | `GetState` (read state snapshot at a block) | `UpsertBlock` (atomic write per block) | `Subscribe` (block subscription) |
| Block Event Table | `GetEvent` (read events at a block) | `UpsertBlock` | `Subscribe` |
| Shared by abstraction tables | `GetConsensusHeight` / `GetBlockRows` | — | — |
| Time Table | `GetValue` (read by timestamp) | `UpsertTimeRows` | — |

There is also a **batch write** path for large datasets: `BatchWriteService` (`InitWriteJob` / `CommitWriteJob` / `CancelWriteJob`) performs large-scale asynchronous writes with object storage as the staging area. See [Write architecture](/architecture/batch-write) for the details.

## Metadata management

BlockDB manages the lifecycle and definitions of logical tables through the metadata service, which has three sub-services:

| Metadata service | Manages | Main methods |
| - | - | - |
| `TableMetaService` | Regular tables | `CreateTable` / `SaveTable` / `GetTable` / `DropTable` / `ListTable` |
| `BlockMetaService` | Block State / Event tables | `CreateBlockTable` / `SaveBlockTable` / `GetBlockTable` / `DropBlockTable` / `ListBlockTables` |
| `TimeMetaService` | Time tables | `CreateTimeTable` / `SaveTimeTable` / `GetTimeTable` / `DropTimeTable` / `ListTimeTables` |

Every logical table carries a **type** marker — `state`, `event`, or `time`. BlockDB uses it to decide whether the table is a regular table or a specific business abstraction table, and how it maps to physical storage. Block tables additionally carry on-chain semantic settings such as `chain_id` and a start height.

## Summary

* BlockDB is a **logical database layer** on top of MySQL-protocol databases.
* Its **two-layer model** provides three logical table types: regular tables, Block State/Event tables, and Time Tables.
* Each logical table type has **its own read and write APIs**, so you can pick the model that matches your data shape (row-level, block, or time).

Continue reading:

* [Data model](/concepts/data-model): Table / BlockTable / TimeTable and the shadow table mechanism.
* [Block State Table and Block Event Table](/concepts/block-tables): the two on-chain semantic table models.
* [Writes and event subscription](/concepts/write-subscribe): real-time writes, batch writes, and subscriptions.
* [API overview](/reference/api): the complete set of services and methods.
* [Architecture](/architecture/overview): components and implementation at the code level.


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