9 minutes
The Graph QL Schema
Přehled
The schema for your Subgraph is in the file schema.graphql
. GraphQL schemas are defined using the GraphQL interface definition language.
Note: If you’ve never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the GraphQL API section.
Defining Entities
Before defining entities, it is important to take a step back and think about how your data is structured and linked.
- All queries will be made against the data model defined in the Subgraph schema. As a result, the design of the Subgraph schema should be informed by the queries that your application will need to perform.
- It may be useful to imagine entities as “objects containing data”, rather than as events or functions.
- You define entity types in
schema.graphql
, and Graph Node will generate top-level fields for querying single instances and collections of that entity type. - Each type that should be an entity is required to be annotated with an
@entity
directive. - By default, entities are mutable, meaning that mappings can load existing entities, modify them and store a new version of that entity.
- Mutability comes at a price, so for entity types that will never be modified, such as those containing data extracted verbatim from the chain, it is recommended to mark them as immutable with
@entity(immutable: true)
. - If changes happen in the same block in which the entity was created, then mappings can make changes to immutable entities. Immutable entities are much faster to write and to query so they should be used whenever possible.
- Mutability comes at a price, so for entity types that will never be modified, such as those containing data extracted verbatim from the chain, it is recommended to mark them as immutable with
Dobrý příklad
The following Gravatar
entity is structured around a Gravatar object and is a good example of how an entity could be defined.
1type Gravatar @entity(immutable: true) {2 id: Bytes!3 owner: Bytes4 displayName: String5 imageUrl: String6 accepted: Boolean7}
Špatný příklad
The following example GravatarAccepted
and GravatarDeclined
entities are based around events. It is not recommended to map events or function calls to entities 1:1.
1type GravatarAccepted @entity {2 id: Bytes!3 owner: Bytes4 displayName: String5 imageUrl: String6}78type GravatarDeclined @entity {9 id: Bytes!10 owner: Bytes11 displayName: String12 imageUrl: String13}
Nepovinná a povinná pole
Entity fields can be defined as required or optional. Required fields are indicated by the !
in the schema. If the field is a scalar field, you get an error when you try to store the entity. If the field references another entity then you get this error:
1Vyřešení nulové hodnoty pro pole 'name', které není nulové
Each entity must have an id
field, which must be of type Bytes!
or String!
. It is generally recommended to use Bytes!
, unless the id
contains human-readable text, since entities with Bytes!
id’s will be faster to write and query as those with a String!
id
. The id
field serves as the primary key, and needs to be unique among all entities of the same type. For historical reasons, the type ID!
is also accepted and is a synonym for String!
.
For some entity types the id
for Bytes!
is constructed from the id’s of two other entities; that is possible using concat
, e.g., let id = left.id.concat(right.id)
to form the id from the id’s of left
and right
. Similarly, to construct an id from the id of an existing entity and a counter count
, let id = left.id.concatI32(count)
can be used. The concatenation is guaranteed to produce unique id’s as long as the length of left
is the same for all such entities, for example, because left.id
is an Address
.
Vestavěné typy skalárů
Podporované skaláry GraphQL
The following scalars are supported in the GraphQL API:
Typ | Popis |
---|---|
Bytes | Pole bajtů reprezentované jako hexadecimální řetězec. Běžně se používá pro hashe a adresy Ethereum. |
String | Scalar for string values. Null characters are not supported and are automatically removed. |
Boolean | Scalar for boolean values. |
Int | The GraphQL spec defines Int to be a signed 32-bit integer. |
Int8 | An 8-byte signed integer, also known as a 64-bit signed integer, can store values in the range from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. Prefer using this to represent i64 from ethereum. |
BigInt | Large integers. Used for Ethereum’s uint32 , int64 , uint64 , …, uint256 types. Note: Everything below uint32 , such as int32 , uint24 or int8 is represented as i32 . |
BigDecimal | BigDecimal High precision decimals represented as a significand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. |
Timestamp | It is an i64 value in microseconds. Commonly used for timestamp fields for timeseries and aggregations. |
Enums
Výčty můžete vytvářet také v rámci schématu. Syntaxe enumů je následující:
1enum TokenStatus {2 OriginalOwner3 SecondOwner4 ThirdOwner5}
Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the tokenStatus
to SecondOwner
by first defining your entity and subsequently setting the field with entity.tokenStatus = "SecondOwner"
. The example below demonstrates what the Token entity would look like with an enum field:
More detail on writing enums can be found in the GraphQL documentation.
Vztahy entit
Entita může mít vztah k jedné nebo více jiným entitám ve vašem schématu. Tyto vztahy lze procházet v dotazech. Vztahy v Graf jsou jednosměrné. Obousměrné vztahy je možné simulovat definováním jednosměrného vztahu na obou “koncích” vztahu.
Vztahy se definují u entit stejně jako u jiných polí s tím rozdílem, že zadaný typ je typ jiné entity.
Vztahy jeden na jednoho
Define a Transaction
entity type with an optional one-to-one relationship with a TransactionReceipt
entity type:
1type Transaction @entity(immutable: true) {2 id: Bytes!3 transactionReceipt: TransactionReceipt4}56type TransactionReceipt @entity(immutable: true) {7 id: Bytes!8 transaction: Transaction9}
Vztahy jeden k mnoha
Define a TokenBalance
entity type with a required one-to-many relationship with a Token entity type:
1type Token @entity(immutable: true) {2 id: Bytes!3}45type TokenBalance @entity {6 id: Bytes!7 amount: Int!8 token: Token!9}
Zpětné vyhledávání
Reverse lookups can be defined on an entity through the @derivedFrom
field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived.
For one-to-many relationships, the relationship should always be stored on the ‘one’ side, and the ‘many’ side should always be derived. Storing the relationship this way, rather than storing an array of entities on the ‘many’ side, will result in dramatically better performance for both indexing and querying the Subgraph. In general, storing arrays of entities should be avoided as much as is practical.
Příklad
We can make the balances for a token accessible from the token by deriving a tokenBalances
field:
1type Token @entity(immutable: true) {2 id: Bytes!3 tokenBalances: [TokenBalance!]! @derivedFrom(field: "token")4}56type TokenBalance @entity {7 id: Bytes!8 amount: Int!9 token: Token!10}
Here is an example of how to write a mapping for a Subgraph with reverse lookups:
1let token = new Token(event.address) // Create Token2token.save() // tokenBalances is derived automatically34let tokenBalance = new TokenBalance(event.address)5tokenBalance.amount = BigInt.fromI32(0)6tokenBalance.token = token.id // Reference stored here7tokenBalance.save()
Vztahy mnoho k mnoha
Pro vztahy mnoho-více, jako jsou uživatelé, z nichž každý může patřit do libovolného počtu organizací, je nejjednodušší, ale obecně ne nejvýkonnější, modelovat vztah jako pole v každé z obou zúčastněných entit. Pokud je vztah symetrický, je třeba uložit pouze jednu stranu vztahu a druhou stranu lze odvodit.
Příklad
Define a reverse lookup from a User
entity type to an Organization
entity type. In the example below, this is achieved by looking up the members
attribute from within the Organization
entity. In queries, the organizations
field on User
will be resolved by finding all Organization
entities that include the user’s ID.
1type Organization @entity {2 id: Bytes!3 name: String!4 members: [User!]!5}67type User @entity {8 id: Bytes!9 name: String!10 organizations: [Organization!]! @derivedFrom(field: "members")11}
A more performant way to store this relationship is through a mapping table that has one entry for each User
/ Organization
pair with a schema like
1type Organization @entity {2 id: Bytes!3 name: String!4 members: [UserOrganization!]! @derivedFrom(field: "organization")5}67type User @entity {8 id: Bytes!9 name: String!10 organizations: [UserOrganization!] @derivedFrom(field: "user")11}1213type UserOrganization @entity {14 id: Bytes! # Set to `user.id.concat(organization.id)`15 user: User!16 organization: Organization!17}
Tento přístup vyžaduje, aby dotazy sestupovaly do další úrovně, aby bylo možné získat například organizace pro uživatele:
1query usersWithOrganizations {2 users {3 organizations {4 # this is a UserOrganization entity5 organization {6 name7 }8 }9 }10}
This more elaborate way of storing many-to-many relationships will result in less data stored for the Subgraph, and therefore to a Subgraph that is often dramatically faster to index and to query.
Přidání komentářů do schématu
As per GraphQL spec, comments can be added above schema entity attributes using the hash symbol #
. This is illustrated in the example below:
1type MyFirstEntity @entity {2 # unique identifier and primary key of the entity3 id: Bytes!4 address: Bytes!5}
Definování polí fulltextového vyhledávání
Fulltextové vyhledávací dotazy filtrují a řadí entity na základě textového vyhledávacího vstupu. Fulltextové dotazy jsou schopny vracet shody podobných slov tím, že zpracovávají vstupní text dotazu do kmenů před jejich porovnáním s indexovanými textovými daty.
Definice fulltextového dotazu obsahuje název dotazu, jazykový slovník použitý ke zpracování textových polí, algoritmus řazení použitý k seřazení výsledků a pole zahrnutá do vyhledávání. Každý fulltextový dotaz může zahrnovat více polí, ale všechna zahrnutá pole musí být z jednoho typu entity.
To add a fulltext query, include a _Schema_
type with a fulltext directive in the GraphQL schema.
1type _Schema_2 @fulltext(3 name: "bandSearch"4 language: en5 algorithm: rank6 include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }]7 )89type Band @entity {10 id: Bytes!11 name: String!12 description: String!13 bio: String14 wallet: Address15 labels: [Label!]!16 discography: [Album!]!17 members: [Musician!]!18}
The example bandSearch
field can be used in queries to filter Band
entities based on the text documents in the name
, description
, and bio
fields. Jump to GraphQL API - Queries for a description of the fulltext search API and more example usage.
1query {2 bandSearch(text: "breaks & electro & detroit") {3 id4 name5 description6 wallet7 }8}
Feature Management: From specVersion
0.0.4
and onwards, fullTextSearch
must be declared under the features
section in the Subgraph manifest.
Podporované jazyky
Výběr jiného jazyka bude mít na rozhraní API fulltextového vyhledávání rozhodující, i když někdy nenápadný vliv. Pole zahrnutá do pole fulltextového dotazu jsou zkoumána v kontextu zvoleného jazyka, takže lexémy vytvořené analýzou a vyhledávacími dotazy se v jednotlivých jazycích liší. Například: při použití podporovaného tureckého slovníku je “token” odvozeno od “toke”, zatímco anglický slovník jej samozřejmě odvozuje od “token”.
Podporované jazykové slovníky:
Code | Slovník |
---|---|
jednoduchý | General |
da | Danish |
nl | Dutch |
en | English |
fi | Finnish |
fr | French |
de | German |
hu | Hungarian |
it | Italian |
no | Norwegian |
pt | Portuguese |
ro | Romanian |
ru | Russian |
es | Spanish |
sv | Swedish |
tr | Turkish |
Algoritmy řazení
Podporované algoritmy pro řazení výsledků:
Algorithm | Description |
---|---|
rank | Pro seřazení výsledků použijte kvalitu shody (0-1) fulltextového dotazu. |
proximityRank | Similar to rank but also includes the proximity of the matches. |