GraphQL

This guide explains how to work with a GraphQL API, focusing specifically on the Graph Protocol. The protocol enables querying data directly from a blockchain, and our platform integrates a lightweight GraphQL client that supports querying this data. This tutorial will cover how to add a data source, configure it, write a query, execute the query, and work with time-travel queries.

1. Add Data Source

Begin by adding a GraphQL endpoint as a data source in your application. Navigate to the 'Data Sources' section under the 'Settings' menu and click on 'New Data Source'. Select 'GraphQL' from the dropdown list and enter your GraphQL endpoint URL. For example, we'll use the 'Inverse Governance Subgraph' for this guide, which indexes FiRM events and governance data.

2. Configure Data Source

After adding the data source, configure the authentication details. The platform supports both API Key-based and OAuth2 authentications. Provide the necessary authentication details depending on your server's setup. If your GraphQL server does not require authentication, you can skip this step. Test the connection to ensure the settings are correct.

3. Write a Query

Start writing your query in the built-in editor. Ensure your query follows the GraphQL syntax, which includes nested fields that correspond to the object structure in the server's schema. Here is a sample query:

query borrowEvents {
  borrows(
    first: $first,
    skip: $skip,
    orderBy: timestamp,
    orderDirection: desc
  ) {
    timestamp
    id
    account {
      id
    }
    emitter {
      id
    }
    market {
      id
    }
    transaction {
      id
    }
    amount
  }
}

This query is designed to fetch data from a table named 'borrows' with specific order and pagination. Fields within brackets, like { id }, represent sub-fields within a relational model. Once your query is set, hit the 'Run Query' button.

4. Time-travel Queries

Time-travel queries allow you to fetch data as it existed at a specific point in time. The Graph protocol supports querying the state of your entities for any arbitrary block in the past. This feature is particularly useful for analyzing historical data or debugging issues by examining the state of data at a specific moment.

{
  challenges(block: { number: 8000000-1000 }) {
    challenger
    outcome
    application {
      id
    }
  }
}

The above query returns Challenge entities and their associated Application entities as they existed after processing block number 8,000,000 and will iterate the query every 1000 blocks. This functionnality is handy when we don't need to retrieve the data for every single block but when needing timeseries for instance.

5. Execute the Query

Click on the 'Execute' button to run your query. The server will respond with a JSON object containing the requested data. If your query isn't properly structured or if the fields don't exist in the schema, you'll receive an error.

6. Post Query

Upon successful execution, the platform will automatically name your table and columns. If your query fetches data from multiple tables, these names will help you differentiate the data. You can then use the fetched data to produce visualizations.

7. Conclusion

GraphQL provides great flexibility and optimization in data exploration. Understanding how to write efficient queries, along with advanced techniques like time-travel queries, will help you make the most of your GraphQL implementation. Always ensure your queries' validity before executing them and consult the GraphQL implementation's documentation to understand its capabilities and features.

Note: This guide assumes you have knowledge of using GraphQL clients, The Graph Protocol, and the Ethereum blockchain. If you need to learn more about these technologies, refer to their respective documentation.