Query The Graph with Python and Subgrounds

Reading time: 2 min

Subgrounds is an intuitive Python library for querying subgraphs, built by Playgrounds. It allows you to directly connect subgraph data to a Python data environment, letting you use libraries like pandas to perform data analysis!

Subgrounds offers a simple Pythonic API for building GraphQL queries, automates tedious workflows such as pagination, and empowers advanced users through controlled schema transformations.

Subgrounds requires Python 3.10 or higher and is available on pypi.

pip install --upgrade subgrounds
# or
python -m pip install --upgrade subgrounds

Once installed, you can test out subgrounds with the following query. The following example grabs a subgraph for the Aave v2 protocol and queries the top 5 markets ordered by TVL (Total Value Locked), selects their name and their TVL (in USD) and returns the data as a pandas DataFrame.

from subgrounds import Subgrounds

sg = Subgrounds()

# Load the subgraph
aave_v2 = sg.load_subgraph(
    "https://api.thegraph.com/subgraphs/name/messari/aave-v2-ethereum")

# Construct the query
latest_markets = aave_v2.Query.markets(
    orderBy=aave_v2.Market.totalValueLockedUSD,
    orderDirection='desc',
    first=5,
)
# Return query to a dataframe
sg.query_df([
    latest_markets.name,
    latest_markets.totalValueLockedUSD,
])

Subgrounds is built and maintained by the Playgrounds team and can be accessed on the Playgrounds docs.

Since subgrounds has a large feature set to explore, here are some helpful starting places:

• Getting Started with Querying
  • A good first step for how to build queries with subgrounds.
• Building Synthetic Fields
  • A gentle introduction to defining synthetic fields that transform data defined from the schema.
• Concurrent Queries
  • Learn how to level up your queries by parallelizing them.
• Exporting Data to CSVs
  • A quick article on how to seemlessly save your data as CSVs for further analysis.