Building GraphQL Queries on Bitquery: First Query to Aggregates

Every Bitquery query has the same shape: a root for the chain or the Trading family, a cube for the kind of fact, a where filter, an orderBy, a limit, and a selection of fields or metrics. Learn that shape once and it carries across every chain and cube. This section takes you from a first query to aggregates and history in four steps: query principles and filters, datasets that decide how far back you reach, metrics that turn rows into numbers, and the schema reference for field names. Everything runs in the Bitquery IDE on a free account.

Read in this order

Step	Guide	What you get
1	Query principles	The root, cube, filter and selection structure
2	Query filters, date and time filters, relative time	Narrowing rows by address, token, amount and time
3	Dataset options, realtime, archive, combined	How far back a query can reach and how fresh it is
4	Metrics overview, count, sum, uniq, quantile, conditional metrics	Aggregates, conditions and statistics
5	Sorting, limits, indexed fields, optimizing queries	Fast, well-formed queries
6	EVM schema reference	Exact field names per cube

The data coverage and retention page answers "how far back does the data go" per cube and chain, and the capabilities section covers joins, calculations, JSON filters and subscriptions.

A first query

The five most recent transfers on Ethereum: one root, one cube, an order and a limit.

{
  EVM(network: eth) {
    Transfers(limit: { count: 5 }, orderBy: { descending: Block_Time }) {
      Block {
        Time
      }
      Transfer {
        Amount
        Currency {
          Symbol
        }
        Sender
        Receiver
      }
    }
  }
}

From here, add a where to pick one token or one wallet, replace the field list with count and sum(of: Transfer_Amount) to aggregate, add dataset: archive to the root to reach history, or change query to subscription to stream new transfers.

The four groups in this section

• Capabilities (20 pages): filters, time windows, sorting, limits, aggregates, calculations, joins, array and JSON filters, subscriptions, Postman. Open the capabilities hub.
• Dataset (8 pages): options, realtime, archive, combined, database selection, network selection, reorg handling, early access program.
• Metrics (11 pages): overview, alias, count, distinct, if, priceAsymmetry, selectWhere, statistics, sum, uniq, quantile.
• Schema reference (11 pages): blocks, miner rewards, uncles, balances, token holders, transfers, transactions, events, DEX trades, calls, arguments and returns.

Frequently Asked Questions

What does a Bitquery GraphQL query look like?

A root such as EVM(network: eth), Solana or Trading, then a cube such as Transfers or DEXTrades, then where, orderBy and limit arguments, then the fields or metrics you want back. The same shape works on every chain.

How do I query historical data?

Add dataset: archive or dataset: combined to the chain root. Without it a query uses the realtime window, which is short. The data coverage page lists how far back each cube reaches.

How do I count or sum instead of listing rows?

Replace fields with metrics: count, sum(of: ...), uniq(of: ...), quantile and others. Metrics accept an if condition and can be sorted with orderBy descendingByField on an alias.

Where do I find the exact field names?

In the schema reference pages for each EVM cube and in the builder-terms pages for EVM and Solana, or in the IDE, which autocompletes fields as you type.

Do I need an API key to try queries?

Not in the IDE: a free account runs every example. To call the API from code, create an access token at account.bitquery.io.

Related pages

• GraphQL query capabilities
• Understanding cubes
• How to generate an access token
• Data coverage and retention