Skip to main content

Introduction

This page will explain everything you need to know in order to use the hosted offering of The Graph. Let's first describe what The Graph is, and then explain how you can get started!

What The Graph Is#

The Graph is a decentralized protocol for indexing and querying data from blockchains, starting with Ethereum. It makes it possible to query data that is difficult to query directly.

For example, with the popular CryptoKitties dApp, it is relatively straightforward to ask the following questions:

How many CryptoKitties does a specific Ethereum account own? When was a particular CryptoKitty born?

This is because these read patterns are directly supported by the the balanceOf and getKitty methods exposed by the contract.

However, other questions are more difficult to answer:

Who are the owners of the CryptoKitties born between January and February of 2018?

To answer this question, you have to process all birth events and then call the ownerOf method for each CryptoKitty that has been born.

Even for this relatively simple question, it would take hours, or even days, for a decentralized application (dApp) running in a browser to get an answer. Indexing blockchain data is hard. Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data.

The Graph solves this today with a hosted service that indexes blockchain data. These indexes ("subgraphs") can then be queried with a standard GraphQL API. In the future, the hosted service will evolve into a fully decentralized protocol with the same capabilities. Both are backed by the open source implementation of Graph Node.

How The Graph Works#

The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database.

Once you have written a subgraph manifest, you use the Graph CLI to store the definition in IPFS and tell the hosted service to start indexing data for that subgraph.

This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions:

The flow follows these steps:

  1. A decentralized application adds data to Ethereum through a transaction on a smart contract.
  2. The smart contract emits one or more events while processing the transaction.
  3. Graph Node continually scans Ethereum for new blocks and the data for your subgraph they may contain.
  4. Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module that creates or updates the data entities that Graph Node stores in response to Ethereum events.
  5. The decentralized application queries the Graph Node for data indexed from the blockchain, using the node's GraphQL endpoint. The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The decentralized application displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats.

Next Steps#

In the following sections we will go into more detail on how to define subgraphs, how to deploy them, and how to query data from the indexes that Graph Node builds.

Before you start writing your own subgraph, you might want to have a look at the Graph Explorer and explore some of the subgraphs that have already been deployed. The page for each subgraph contains a playground that lets you query that subgraph's data with GraphQL.

While you are on the explorer, make sure you create an account by clicking on the Sign up with Github. You will need that later on when you want to deploy your first subgraph.