GraphQL API Builder

How to Build a GraphQL API

With API Builder, you can create your own GraphQL API in minutes. In ZettaBlock, there are two ways to build a GraphQL API:

  • Build with a new query,
  • Build with a saved query.

Option 1. Build with a new query

To create an API with a new query, you need to visit the Query Builder first. You can explore blockchain and other data via Database and Tables, and then write SQL to query the data. After the query is finished, click the “Create API” button in the upper right site to customize the API.
Note that turning a query with parameters into API is not supported yet (the update on this is coming soon).

Option 2. Build with a saved query

Additionally, you can select any saved query to create an API. Visit your workspace, enter API Builder, select a saved query in the query list, and click the “Select to Create” button. Now you can start configuring your API.

Configure API

API Transformation Code

API transformation code is the SQL query used to materialize and backfill a table in the database for the API.

Data Refresh Interval

Data Refresh Interval decides how often the data is refreshed. ZattaBlock provides several options, from 5 mins to 24 hrs. Also, you can choose "no fresh", which means that the underlying API table will never be updated. No refresh is used when the raw data used to create the API is rarely updated, such as system metadata.

In short, the shorter the refresh interval, the more real-time the API but it will consume more compute units.


Description is a field where you can give the API a brief description.

Incremental Data Refresh

This is an advanced option for users who want to further optimize the API cost and performance. With incremental data refresh, you can refresh only data that needs to be processed, either data that has changed or arrived fresh after the last time the API was refreshed. Incremental data refresh significantly decreases the API cost and processing time. For example, we use data_creation_date or the latest timestamp to refresh only data within the last 24 hours.
To enable incremental data refresh, you need to click the toggle, fill in the primary key and the Incremental SQL Code.


This option is not recommended for the dataset with more than 1 million records for now. The limit will be removed later on.

Set Primary Key

Primary key is a unique and not null key in the API table. There’s only one primary key in a table, which may consist of single or multiple fields. Incremental refresh will use this key to overwrite stale partitioned data.

Incremental SQL Code

Incremental SQL code is used to partially refresh the data, which could greatly reduce the cost by controlling how much data to scan and how to scan. The incremental SQL schema must be compatible with the API transformation SQL schema.

Index Fields (Optional)

This is also an advanced option for optimizing API query performance. Indexing makes fields faster to query by creating pointers to where the API data is stored within ZettaBlock virtual database. You can pre-index any field that may be used for querying the API later on.
You can also config the type for the index fields, ZattaBlock now supports these types:

  • Varchar
  • Boolean
  • Small Int
  • Integer
  • BigInt
  • Real
  • Double

Note that we will support the date and timestamp types in the future.

After all configurations, click "Create API" and your GraphQL API will be generated!

Quick demo

Here is a quick demo to walk you through how to build a GraphQL API for fetching the weekly ETH deposits on Beacon, refreshed in a daily basis with the incremental refresh enabled.