https://github.com/0xPlaygrounds/subgrounds
An intuitive Python library for interfacing with subgraphs and GraphQL
https://github.com/0xPlaygrounds/subgrounds
analytics blockchain data decentralized graph graphql pandas python subgraphs substreams
Last synced: 9 months ago
JSON representation
An intuitive Python library for interfacing with subgraphs and GraphQL
- Host: GitHub
- URL: https://github.com/0xPlaygrounds/subgrounds
- Owner: 0xPlaygrounds
- License: apache-2.0
- Created: 2023-01-06T20:59:21.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-20T14:28:14.000Z (over 1 year ago)
- Last Synced: 2025-04-21T04:54:08.711Z (9 months ago)
- Topics: analytics, blockchain, data, decentralized, graph, graphql, pandas, python, subgraphs, substreams
- Language: Python
- Homepage: http://docs.playgrounds.network
- Size: 1.75 MB
- Stars: 63
- Watchers: 2
- Forks: 11
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-subgraphs - Subgrounds
README
# Subgrounds
[](https://pypi.org/project/subgrounds/)
[](https://pypi.org/project/subgrounds/)
[](https://github.com/ambv/black)
[](https://github.com/0xPlaygrounds/subgrounds/actions/workflows/main.yml)
[](https://discord.gg/gMSSh5bjvk)
[](https://twitter.com/Playgrounds0x)
[](https://colab.research.google.com/github/0xPlaygrounds/subgrounds/blob/main/examples/notebook.ipynb)
[](https://codespaces.new/0xPlaygrounds/subgrounds-template?quickstart=1)
An intuitive Python library for interfacing with subgraphs and GraphQL.
## Features
- **Simple**: Leverage a Pythonic API to easily build queries and transformations without the need for raw GraphQL manipulation.
- **Automated**: Automatically handle pagination and schema introspection for effortless data retrieval.
- **Powerful**: Create sophisticated queries using the `SyntheticFields` transformation system.
## Resources
- [**Docs**](http://docs.playgrounds.network/): User guide and API documentation
- [**Snippets**](https://github.com/0xPlaygrounds/subgrounds/tree/main/examples): A list of examples showcasing Subgrounds integration with Dash and Plotly
- [**Examples**](http://docs.playgrounds.network/subgrounds/examples/): An ever growing list of projects created by our community members and team
- [**Videos**](https://docs.playgrounds.network/subgrounds/videos/): Video workshops on Subgrounds
## Installation
> Subgrounds **requires** atleast Python 3.10+
Subgrounds is available on PyPi. To install it, run the following:
`pip install subgrounds`.
Subgrounds also comes bundled with extra modules that may require extra libraries. You can get all functionality of `subgrounds` via the following:
`pip install subgrounds[all]`.
## Simple example
```python
>>> from subgrounds import Subgrounds
>>> sg = Subgrounds()
>>> # Load
>>> aave_v3 = sg.load_subgraph("https://api.thegraph.com/subgraphs/name/messari/aave-v3-ethereum")
>>> # Construct the query
>>> largest_markets = aave_v3.Query.markets(
... orderBy=aave_v3.Market.totalValueLockedUSD,
... orderDirection='desc',
... first=5,
... )
>>> # Return query to a dataframe
>>> sg.query_df([
... largest_markets.name,
... largest_markets.totalValueLockedUSD,
... ])
markets_name markets_totalValueLockedUSD
0 Aave Ethereum wstETH 1.915090e+09
1 Aave Ethereum WETH 1.047417e+09
2 Aave Ethereum WBTC 6.049655e+08
3 Aave Ethereum USDC 4.482461e+08
4 Aave Ethereum USDT 4.280103e+08
```
## About Us
Playgrounds Analytics is a data solutions company providing data infrastructures and services for data teams, analysts, and engineers. Check us out [here](https://playgrounds.network/) to learn more!
## Acknowledgments
This software project would not be possible without the support of The Graph Foundation. You can learn more about The Graph and its mission [here](https://thegraph.com/).