This guide serves to help you start using a publicly available instance of TezGraph. You can also consider hosting your own instance. The instructions for hosting your own instance can be found under the "Self-Hosting" section.
Also, in this guide, you will access TezGraph through a web user interface. It makes GraphQL calls behind the scene. For your actual usage, you might need to make GraphQL queries/subscription calls using an existing GraphQL library for your favourite programming language or even make calls directly using HTTP.
Public TezGraph Links
It is not necessary to set up TezGraph locally. You can use our public TezGraph servers linked here.
What is GraphQL, and why should I care?
GraphQL is a standard query language to access data remotely. An ecosystem of client and server libraries, best practices and knowledge bases make it easy to adopt, especially on the client-side.
Using GraphQL, you can:
- Query historical data with filtering, sorting and pagination (as made available by the GraphQL server developer)
- Subscribe to changes
- Get related data in the same query
- Only get the data that you need
- Discover the API using GraphQL Schema
- Use the existing tooling/libraries in the GraphQL ecosystem
- Write clients that keep working after new features are added to the GraphQL server (less versioning)
- Write clients that are faster and more responsive as they make fewer calls to the servers
- Have better scalability
What is TezGraph
TezGraph is a GraphQL interface to Tezos data. It connects to a Tezos node to enable real-time subscriptions and to a historical database of indexed Tezos data (updated by Nomadic Labs' Tezos Indexer).
To use TezGraph effectively, familiarity with Tezos concepts (like baking, endorsing, block, implicit and originated addresses, contracts, operations, transactions, bigmaps, metadata, etc.) is assumed.
connection (operations query), we have an
edges sub-selection. Edges consist of two queryable fields,
node field is a sub-selection in which we request the operation fields of interest.
Your First Tezgraph Query
Let's assume you want to check out the 3 latest operations performed by a specific account. You can head to one of the public TezGraph links or use the user interface below to issue the following query.
You can learn about the
accounts query in greater detail under the "Accounts" section.
Let's have a closer look at the query:
query: This signifies that a query is about to begin. Another value that can go here is
subscription. TezGraph gives you a read-only view of the blockchain, so there is no
accounts: This is the root query we are using.
- TezGraph also provides:
version, which can be used to query information about TezGraph's version and release. All of the available queries can be found under the DOCS tab on the right side of the playground (https://mainnet.tezgraph.tez.ie/graphql) or here.
The account query accepts arguments. Here we ask for the
account with the address
tz1MBidfvWhJ64MuJapKExcP5SV4HQWyiJwS. In TezGraph queries, precisely one of the
last arguments are required, as it limits the number of rows you can query in each GraphQL call. If more data is needed, you can use the pagination arguments to get the following pages or rows. That is, by passing the
cursor values you get from your response to
That is, by using the
cursor values provided by the Tezgraph results for the arguments
after. This is the standard of relay pagination, a common practice in the GraphQL ecosystem, further explored below.
operations: One of the benefits of GraphQL is that you can query related data in the same query. Here, for each
account returned by the query, we ask for the first 3 of the operations it has initiated (it's their source), in reverse chronological order.
edges: This is part of the relay pagination standard. The query returns a relay
connection which has the following information:
page_info: Tells you if there are previous and next pages and the cursor to use to query those pages. Further explained in the "Pagination" section.
edges: Contains an array of objects, each containing one row of the information you requested inside the
nodefield and a
cursorfield of type
The whole boilerplate around relay pagination might seem overkill at first, but it becomes second nature after a few queries.
This concludes the quick start example on Tezgraph queries. Details on paginating Tezgraph results are documented here. For more information on queries, please refer to their dedicated documentation.
More details and examples on Tezgraph queries:
Advanced Tezgraph Query with Pagination
The previous example returned 3 operations. In this advanced query example, we will now add in the
block field to reveal which block these operations were performed on. Adding the following to the query, after the
Here, because each operation is related to only one block, the
block field is simple to query.
For performance reasons, we limit the complexity and depth of queries that TezGraph accepts. If you are not satisfied with the limits, you can contact us about your use-cases or alternatively choose to self-host TezGraph with more relaxed limits for your usage.
In this advanced query example, we will also add in pagination fields (
cursor) and arguments (
after) to the query. Tezgraph uses the Relay Cursor Connections Specification for pagination, if you are unfamiliar with this, it is recommended that you read the pagination documentation.
operations sub-query, just above
edges, we have added the following lines:
We have also added the
cursor field right inside the
Now you will see that the query has no previous page, but it will have a next page.
To query the next page, we have to use
after argument in the
operations sub-query and pass the
page_info.end_cursor value to it:
Your First Tezgraph Subscription
GraphQL queries allow you to get historical data. In some other technologies (namely REST services), if you need to stay informed of new changes, you need to make repeated calls to the service backend. If these queries are too much separated in time, the user can be using stale data for a while, but if you repeat queries too frequently, a lot of network and server resources will be wasted to serve these repeated queries. Enter GraphQL subscriptions.
In this example, we subscribe to entire new blocks and also get reveals which can be filtered too.
This allows clients to make sure they have not missed any updates as they can easily keep track of the last seen block level on their side. For example, if a connection is dropped, it is easy for the client to reconnect and get all the updates from the last seen block using
More details and examples on Tezgraph subscriptions can be found here.
- You can learn more about GraphQL by checking out the official GraphQL website.
- You can learn more about pagination in Tezgraph queries.
- You can further explore the Tezgraph queries.
- You can explore the TezGraph schema by checking out the DOCS button in GraphiQL interfaces embedded in this page. You may also explore the DOCS on our Tezgraph GraphQL playground here and here.
- You can connect your software to TezGraph by leveraging any of the client libraries written for at least 23 different languages. A starting point is here.