​

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:

​

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: 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/): 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 for the details.

​

Metadata management

BlockDB manages the lifecycle and definitions of logical tables through the metadata service, which has three sub-services: 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: Table / BlockTable / TimeTable and the shadow table mechanism.
• Block State Table and Block Event Table: the two on-chain semantic table models.
• Writes and event subscription: real-time writes, batch writes, and subscriptions.
• API overview: the complete set of services and methods.
• Architecture: components and implementation at the code level.