---
title: Query The Graph with Python and Subgrounds
sidebarTitle: Python (Subgrounds)
---

Subgrounds is an intuitive Python library for querying Subgraphs, built by [Playgrounds](https://playgrounds.network/). It allows you to directly connect Subgraph data to a Python data environment, letting you use libraries like [pandas](https://pandas.pydata.org/) 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.

## Getting Started

Subgrounds requires Python 3.10 or higher and is available on [pypi](https://pypi.org/project/subgrounds/).

```bash
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](https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.DataFrame.html#pandas.DataFrame).

```python
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,
])
```

## Documentation

Subgrounds is built and maintained by the [Playgrounds](https://playgrounds.network/) team and can be accessed on the [Playgrounds docs](https://docs.playgrounds.network/subgrounds).

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

- [Getting Started with Querying](https://docs.playgrounds.network/subgrounds/getting_started/basics/)
  - A good first step for how to build queries with subgrounds.
- [Building Synthetic Fields](https://docs.playgrounds.network/subgrounds/getting_started/synthetic_fields/)
  - A gentle introduction to defining synthetic fields that transform data defined from the schema.
- [Concurrent Queries](https://docs.playgrounds.network/subgrounds/getting_started/async/)
  - Learn how to level up your queries by parallelizing them.
- [Exporting Data to CSVs](https://docs.playgrounds.network/subgrounds/faq/exporting/)
  - A quick article on how to seamlessly save your data as CSVs for further analysis.
