Create your first Blockchain GraphQL query

In the previous article, we have argued why you should GraphQL over Rest for blockchain data APIs. In this article, we will talk about some basic concepts of GraphQL in the context of Bitquery and show steps to create a simple GraphQL query.

GraphQL Query

If you have never seen a GraphQL query, the following image shows an example.

example of graphQL example

The left side is the query, and the right side showing the result.

As you can see, query and result look similar because, in GraphQL, your query actually specifies what exact data you are looking for.

  1. We start with a special “root” object.
  2. We selected the data hierarchy based on the schema to get the desired result.

GraphQL Types

GraphQL types area basically data objects that contain one or multiple fields. For example, in the image above. 

  • bitcoin is a type with the blocks field.

GraphQL Type System

GraphQL is a strongly typed language. Type System defines various data types that can be used in a GraphQL application. The type system helps to define the GraphQL schema. All the queries validated and executed against that schema.

What is GraphQL schema?

GraphQL server uses a schema to describe the shape of your data graph. This schema defines a hierarchy of data types with fields. 

GraphQL schema is a contract between the client and the server, which specifies exactly which queries and mutations are available for clients to execute against your data graph.

How does GraphQL Schema will help to use Bitquery?

GraphQL schema is a documentation of our APIs.

With GraphQL schema, you can search for types available in the APIs, different fields of those types, and their data format.

searching types in schema

GraphQL Playground

GraphQL playground is where you will spend most of your time when integrating which Bitquery

The playground allows you to create and run your queries and see the results. Besides, it also has an embedded Bitquery GraphQL schema.

bitquery graphQL schema

Creating Queries

Now, let’s create a simple GraphQL query using the Bitquery GraphQL playground.

Note: Our GraphQL queries support more than 20 blockchains such as Ethereum, Zcash, Cardano, etc. Therefore you can query any blockchain using our APIs.

Getting the latest bitcoin blocks

So let’s say we want to create a query to get the latest Bitcoin blocks details. So, let’s see step by step process of creating this query.

  • First, we need to search the schema for the Bitcoin type. 
searching schema
  • Once found, click on Bitcoin type to see the fields available. As you can see, we found the blocks field. 
blocks schema
  • So, for now, our query looks like below. As you can see, it’s showing a red underline, indicating there is some error. As we mentioned above, GraphQL is a strongly types language; therefore, you see this validation error.
Initial query
  • As you can see in the above image, blocks is also a type that contains multiple fields. We also need to mention what blocks fields we want in our query. Let’s say we want only to see the block height, so let’s mention that.
first full query
  • But before we run this query, let’s limit the results first. 

Note: You can see the available query option in the blocks schema.

adding limit parameter
  • Now, when you run this query, you will get the following result. 
initial results
  • But we want the latest bitcoin blocks, not the oldest. So we need to sort them based on the height.
limiting results
  • Now, rerun the query, you will get the following results.
results
  • If we want to get more details about these blocks, we just need to add it to the query. You can check blocks schema, to know what block fields you can query. 
sorting results
  • Once you are done with your query, you can use them programmatically in your applications. Our GraphQL endpoint is — graphql.bitquery.io. Unlike Rest, where every APIs have different endpoints, in GraphQL, all the APIs use the same endpoints.

Using examples to create queries

If you want to see more examples of GraphQL queries, you can check our blockchain explorer. On our explorer, every widget is created using GraphQL queries. You can just click on the GraphQL button on the bottom right corner to see the query.

You can also modify these queries to get the desired results. 

explorer widgets with GraphQL queries

Wrapping Up

Using GraphQL, you can write expressive queries to get the exact data you want. You can leverage the schema to understand what kind of data you can get using our APIs.

In the next article, we will talk about how to use arguments in your GraphQL queries.

If you have any questions or need help with queries, just hop on our Telegram channel. Also, let us know if you are looking for blockchain data APIs.

You might also be interested in:

About Bitquery

Bitquery is a set of software tools that parse, index, access, search, and use information across blockchain networks in a unified way. Our products are:

  • Digital Assets API provides index information related to all major cryptocurrencies, coins, and tokens.
  • DEX API provides real-time deposits and transactions, trades, and other related data on different DEX protocols like Uniswap, Kyber Network, Airswap, Matching Network, etc.

If you have any questions about our products, ask them on our Telegram channel or email us at hello@bitquery.io. Also, subscribe to our newsletter below, we will keep you updated with the latest in the cryptocurrency world.