Fieldpath#

subgrounds.subgraph.fieldpath.fieldpaths_of_object(subgraph, object_)#

Returns generator of FieldPath objects that selects all non-list fields of GraphQL Object of Interface object_.

Parameters:

  • schema -- _description_

  • object -- _description_

Yields:

_description_

class subgrounds.subgraph.fieldpath.FieldPath(subgraph: 'Subgraph', root_type: 'TypeRef.T', type_: 'TypeRef.T', path: 'list[tuple[dict[str, Any] | None, TypeMeta.FieldMeta]]')#
property _root: FieldMeta#

Returns the type information of the root field of the current FieldPath

Returns:

Type information of the root field of the current FieldPath

property _leaf: FieldMeta#

Returns the type information of the leaf field of the current FieldPath

Returns:

Type information of the leaf field of the current FieldPath

static _merge(fpaths)#

Returns a Selection tree containing all selection paths in fpaths. Note: Assumes that all fieldpaths in fpaths belong to the same subgraph

Parameters:

fpaths (list[subgrounds.subgraph.fieldpath.FieldPath]) -- _description_

Returns:

_description_

Return type:

list[subgrounds.query.Selection]

_name_path(use_aliases=False)#

Returns a list of strings correspoding to the names of all fields selected in the current FieldPath. If use_aliases is True, then if a field has an automatically generated alias, the alias will be returned.

Parameters:

use_aliases (bool) -- Flag indicating wether of not to use the fields' automatically generated alias (if present). Defaults to False.

Returns:

List of field names selected in the current FieldPath

Return type:

list[str]

_name(use_aliases=False)#

Generates the name of the current FieldPath using the names of the fields it selects. If use_aliases is True, then if a field has an automatically generated alias, the alias will be used.

Parameters:

use_aliases (bool) -- Flag indicating wether of not to use the fields' automatically generated alias (if present). Defaults to False.

Returns:

The generated name of the current FieldPath.

Return type:

str

_extract_data(data)#

Extract the data corresponding to the current FieldPath from the dictionary data.

Parameters:

data (dict[str, Any] | list[dict[str, Any]]) -- Data dictionary that contains the data corresponding to the current FieldPath.

Returns:

Data corresponding to the current FieldPath.

Return type:

Union[list[Any], Any]

_selection()#

Returns a selection or list of selections corresponding to the current FieldPath.

Returns:

_description_

Return type:

Selection | list[Selection]

_set_arguments(args, selection=[])#

Set the arguments to the leaf of the current FieldPath. The method returns the self.

Parameters:
Returns:

_description_

Return type:

subgrounds.subgraph.fieldpath.FieldPath | list[subgrounds.subgraph.fieldpath.FieldPath]

_select(name)#

Returns a new FieldPath corresponding to the FieldPath self extended with an additional selection on the field named name.

Parameters:

name (str) -- The name of the field to expand on the leaf of fpath

Raises:
Returns:

A new FieldPath containing fpath extended with the field named name

Return type:

FieldPath

_extend(ext)#

Extends the current FieldPath with the FieldPath ext. ext must start where the current FieldPath ends.

Parameters:

ext (FieldPath) -- The FieldPath representing the extension

Raises:
Returns:

A new FieldPath containing the initial current FieldPath

extended with ext

Return type:

FieldPath

class subgrounds.subgraph.fieldpath.SyntheticField(f: 'Callable', type_: 'TypeRef.T', deps: 'list[FieldPath | SyntheticField] | FieldPath | SyntheticField', default: 'Any' = None)#
classmethod constant(value)#

Returns a constant SyntheticField with value value. Useful for injecting additional static data to a schema or merging entities.

Parameters:

value (str | int | float | bool) -- The constant field's value

Returns:

The constant SyntheticField

Return type:

SyntheticField

Example:

>>> from subgrounds import Subgrounds, SyntheticField
>>> sg = Subgrounds()
>>> univ3 = sg.load_subgraph(
...     "https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3"
... )

# Create constant SyntheticFields
>>> univ3.Mint.tx_type = SyntheticField.constant('MINT')
>>> univ3.Burn.tx_type = SyntheticField.constant('BURN')

# Last 10 mints and burns
>>> mints = univ3.Query.mints(
...     first=10,
...     orderBy=univ3.Mint.timestamp,
...     orderDirection='desc'
... )
>>> burns = univ3.Query.burns(
...     first=10,
...     orderBy=univ3.Burn.timestamp,
...     orderDirection='desc'
... )

# Query mints and burns. Notice that we merge the two entity tables by
# setting `concat=True` and overwriting the column names (columns must
# match the `FieldPaths`)
>>> df = sg.query_df(
...     [
...         mints.transaction.id,
...         mints.timestamp,
...         mints.tx_type,
...         mints.origin,
...         mints.amountUSD,
...         burns.transaction.id,
...         burns.timestamp,
...         burns.tx_type,
...         burns.origin,
...         burns.amountUSD,
...     ],
...     columns=['tx_hash', 'timestamp', 'tx_type', 'origin', 'amount_USD'],
...     concat=True
..  )

# Sort the DataFrame (output is truncated)
>>> df.sort_values(by=['timestamp'], ascending=False)
 tx_hash   timestamp    tx_type  origin     amount_USD
0xcbe1...  1656016553    MINT  0x3435....  7.879784e+03
0xddda...  1656016284    MINT  0xc747....  5.110840e+04
0xa767...  1656016284    BURN  0xd40d....  2.804573e+05
0xc132...  1656015853    MINT  0xc747....  5.122569e+04
0x1444...  1656015773    MINT  0xd11a....  8.897983e+03
0x3315...  1656015693    MINT  0xb7dd....  0.000000e+00
0xcc71...  1656015278    BURN  0xa7c4....  1.254942e+06
0x7bbf...  1656015111    MINT  0xac56....  3.432075e+04
0xea21...  1656014785    BURN  0x0709....  2.059106e+04
0x3bd3...  1656014120    MINT  0x5099....  2.517578e+03
0x1ea5...  1656014018    BURN  0x5099....  0.000000e+00
0xb9d3...  1656013998    MINT  0x22df....  8.365750e+04
0xc5e3...  1656013946    BURN  0xac56....  3.363809e+04
0x7c73...  1656013913    MINT  0x4ce6....  4.837287e+04
0x95cf...  1656013728    BURN  0x4ce6....  5.110010e+04
0x76dd...  1656013599    MINT  0x234a....  5.363896e+03
0x47e5...  1656013580    BURN  0xaf0f....  0.000000e+00
0xe20e...  1656013455    BURN  0xaf0f....  0.000000e+00
0xac3e...  1656013237    BURN  0x665d....  2.254100e+05
0x01c3...  1656013034    BURN  0x0084....  0.000000e+00
classmethod datetime_of_timestamp(timestamp)#

Returns a SyntheticField that will transform the FieldPath timestamp into a human-readable ISO8601 string.

Parameters:

timestamp (subgrounds.subgraph.fieldpath.FieldPath | subgrounds.subgraph.fieldpath.SyntheticField) -- A FieldPath representing a Unix timestamp field.

Returns:

An ISO8601 datetime string SyntheticField.

Return type:

Self

Example:

>>> from subgrounds import Subgrounds, SyntheticField
>>> sg = Subgrounds()
>>> univ3 = sg.load_subgraph(
...     "https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3"
... )

# Create datetime SyntheticField
>>> univ3.Swap.datetime = SyntheticField.datetime_of_timestamp(
...     univ3.Swap.timestamp
... )

# Query 100 swaps
>>> sg.query_df([
...     univ3.Query.swaps.timestamp,
...     univ3.Query.swaps.datetime,
... ])
    swaps_timestamp       swaps_datetime
0        1625105710  2021-06-30 22:15:10
1        1629253724  2021-08-17 22:28:44
2        1647333277  2022-03-15 04:34:37
3        1630801974  2021-09-04 20:32:54
4        1653240241  2022-05-22 13:24:01
..              ...                  ...
95       1646128326  2022-03-01 04:52:06
96       1646128326  2022-03-01 04:52:06
97       1626416555  2021-07-16 02:22:35
98       1626416555  2021-07-16 02:22:35
99       1625837291  2021-07-09 09:28:11
classmethod map(dict, type_, fpath, default=None)#

Returns a SyntheticField that will map the values of fpath using the key value pairs in dict. If a value is not in the dictionary, then default will be used instead.

Parameters:
Returns:

A map SyntheticField

Return type:

Self

Example:

>>> from subgrounds import Subgrounds, SyntheticField
>>> sg = Subgrounds()
>>> univ3 = sg.load_subgraph(
...     'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3'
... )

# Hand-crafted mapping of pool addresses to symbol
>>> pooladdr_symbol_map = {
...     '0x5777d92f208679db4b9778590fa3cab3ac9e2168': 'DAI/USDC-001',
...     '0x6c6bc977e13df9b0de53b251522280bb72383700': 'DAI/USDC-005',
...     '0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8': 'USDC/ETH-030',
...     '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640': 'USDC/ETH-005',
... }

# Create map SyntheticField using our dictionary with 'UNKNOWN' as the
# default value
>>> univ3.Pool.symbol = SyntheticField.map(
...     pooladdr_symbol_map,
...     SyntheticField.STRING,
...     univ3.Pool.id,
...     'UNKNOWN'
... )

# Query top 10 pools by TVL
>>> pools = univ3.Query.pools(
...     first=10,
...     orderBy=univ3.Pool.totalValueLockedUSD,
...     orderDirection='desc'
... )
>>> sg.query_df([
...     pools.id,
...     pools.symbol
... ])
                                     pools_id  pools_symbol
0  0xa850478adaace4c08fc61de44d8cf3b64f359bec       UNKNOWN
1  0x5777d92f208679db4b9778590fa3cab3ac9e2168  DAI/USDC-001
2  0x6c6bc977e13df9b0de53b251522280bb72383700  DAI/USDC-005
3  0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8  USDC/ETH-030
4  0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640  USDC/ETH-005
5  0x3416cf6c708da44db2624d63ea0aaef7113527c6       UNKNOWN
6  0xcbcdf9626bc03e24f779434178a73a0b4bad62ed       UNKNOWN
7  0xc63b0708e2f7e69cb8a1df0e1389a98c35a76d52       UNKNOWN
8  0x4585fe77225b41b697c938b018e2ac67ac5a20c0       UNKNOWN
9  0x4e68ccd3e89f51c3074ca5072bbac773960dfa36       UNKNOWN