@entity
and id
fields are required, with types like Bytes
, BigInt
, String
, Boolean
, Int
, and BigDecimal
@derivedFrom
schema.graphql
file and is auto-generated when you run the graph init
command. It is essential for subgraph deployment. You can create multiple schema files with different names, just make sure to add them in subgraph.yaml
.
This article provides a general overview of subgraph schemas. Most of the examples are simplified versions of Messari’s subgraphs. For more in-depth information on how to use a subgraph, you can also check out these great articles in this category.
@entity
in the schema. Without explicitly declaring, it causes a compilation error. Entities can be related to other entities. For example:
TransferEvent
entity has a Token
entity in its field. It is a one-to-many relationship. We will go into different types of relationships later.
TransferEvent
entity is defined as immutable. Immutable entities are much faster to write and query so always define an entity as immutable if possible.
By default, all entities are mutable meaning that they can be changed during execution. Immutable entities, as the name suggested, can’t be modified once it is created. It can only be modified if only the changes happen in the same block in which it is created.
When you define your schema, you should have a clear idea of how your subgraph stores data. For example, the Owner
entity and Token
entity are always updated when a transfer happens; therefore they should not be immutable entities. TransferEvent
is the transaction details, and is considered finalized once it is confirmed; it is very unlikely to be modified therefore should be an immutable entity.
Bytes
— hexadecimal string. Commonly used for hashes and addresses.String
— values of string
typeBoolean
— values of boolean
typeInt
— integer values in GraphQL are limited to 32 bytes. This type can be used to store int8
, uint8
, int16
, uint16
, int24
, uint24
, and int32
data.BigInt
— this type can store integers that are beyond 32 bytes, such as uint32
, int64
, uint64
until int256
and uint256.
BigDecimal
— handling decimals on Ethereum can be tricky. The Graph supports high-precision decimals represented as a significand and exponent. The exponent range is from -6,143 to +6,144. Rounded to 34 significant digits.enum
types. For example:
id
and name
are mandatory for Token
entity. If any of these fields are missing during indexing, an error occurs.
id
field is mandatory for all entities. It must be unique and it serves as the primary key. The id
field must be either byte
or string
type.
If your subgraph is indexing transactions, you can use the transaction hash as id
. For a token, this id
can be either the token’s smart contract address or a unique string. Below are some ideas for unique ID values:
event.params.id.toHex()
event.transaction.from.toHex()
event.transaction.hash.toHex() + "-" + event.logIndex.toString()
Token
entity should keep an owner list. An owner can potentially hold more than one token so the Owner
entity also keeps a list of tokens. The schema:
@derivedFrom
is used, it is called reverse lookup.
When a field is defined as @derivedFrom
, it is never actually created during indexing. Instead, it is referencing another field in the other entity. In the above case, when an owner’s tokens
field is queried, GraphQL looks into the owners
field of the Token
entity to find all the tokens with a particular owner in its owners
field and returns that as a result.
graph init
with contract address: 0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE
.
Change the subgraph.yaml
to the following:
schema.graphql
in the following manner:
Account
entity keeps all the balance of SHIB token holder’s account balances. The Transfer
entity keeps a record of all transactions that are related to SHIB token. Here we use transaction hash as its ID.
Next, to generate schema.ts
in the generated
directory run:
src
directory to define our event mapping.
npm install
and graph build
to compile the code and deploy it to Chainstack Subgraphs with the deployment command which can be found in your Chainstack console.
When deployment completes, open the GraphQL UI URL in your browser to see the result.