Field Paths#

FieldPaths are the main building blocks used to construct Subgrounds queries. A FieldPath represents a selection path through a GraphQL schema starting from the root Query entity (see The Query and Mutation types) all the way down to a scalar leaf.

FieldPath are created by simply selecting attributes starting from the subgraph object returned by the load_subgraph or load_api methods:

Click for Interactive Documentation

Clicking this button will enable editing and execution of the code-blocks on this page. Learn more here.

Loading a curve subgraph#
from subgrounds import Subgrounds
sg = Subgrounds()

curve = sg.load_subgraph(
    "https://api.thegraph.com/subgraphs/name/messari/curve-finance-ethereum")
Analyzing curve pool data via the curve.Query.pools FieldPath#
# `curve.Query.pools` is a field path
curve_pools = curve.Query.liquidityPools

# We can then query based on the routing of these objects
sg.query_df([
    curve_pools.inputTokens.name,
    curve_pools.outputToken.name,
])
This is the GraphQL that subgrounds produces#
query {
  liquidityPools {
    inputTokens {
      name
    }
    outputToken {
      name
    }
  }
}

Note

If you're having trouble understanding the naming and pathing of the FieldPath classes in subgrounds, we recommend:

  • Use the GraphiQL Interface:

    • Copy and paste the subgraph URL into your web browser to access the GraphiQL interface.

    • This tool allows you to build a GraphQL string via the graphical query builder, which can help you understand the structure of the subgraph.

  • Leverage IDE Language Support:

    • If you use an IDE with Jupyter Notebook support (i.e. VSCode), you can take advantage of the built-in language server to auto-complete the field paths as you work.

    • To use this method, import and load the subgraph in the first notebook cell, then use it in later cells to benefit from auto-completion suggestions based on the schema.

    • This feature is particularly easy to use in VSCode, as the included Python extension automatically enables this behavior.