Subgraph#

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

class subgrounds.subgraph.Filter(field: 'TypeMeta.FieldMeta', op: 'Filter.Operator', value: 'Any')#

class Operator(value)#: An enumeration.

class subgrounds.subgraph.Object(subgraph: 'Subgraph', object: 'TypeMeta.ObjectMeta | TypeMeta.InterfaceMeta')#

class subgrounds.subgraph.Subgraph(url: 'str', schema: 'SchemaMeta', transforms: 'list[DocumentTransform]' = [<subgrounds.transform.transforms.TypeTransform object at 0x7f6291ec6320>, <subgrounds.transform.transforms.TypeTransform object at 0x7f6291ec5570>], is_subgraph: 'bool' = True)#

class subgrounds.subgraph.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:

dict (dict[Any, Any]) -- The dictionary containing the key value pairs used to map fpath's values
type -- The type of the resulting field
fpath (subgrounds.subgraph.fieldpath.FieldPath | subgrounds.subgraph.fieldpath.SyntheticField) -- The FieldPath whose values will be mapped using the dictionary
default (Optional[Any]) -- Default value used when a value is not in the provided dictionary

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