GraphQL API

Reading time: 9 min

Learn about the GraphQL Query API used in The Graph.

GraphQL is a query language for APIs and a runtime for executing those queries with your existing data. The Graph uses GraphQL to query subgraphs.

To understand the larger role that GraphQL plays, review developing and creating a subgraph.

In your subgraph schema you define types called Entities. For each Entity type, entity and entities fields will be generated on the top-level Query type.

Query for a single Token entity defined in your schema:

{
  token(id: "1") {
    id
    owner
  }
}

Tüm Token varlıklarını sorgulayın:

{
  tokens {
    id
    owner
  }
}

When querying a collection, you may:

• Use the orderBy parameter to sort by a specific attribute.
• Use the orderDirection to specify the sort direction, asc for ascending or desc for descending.

{
  tokens(orderBy: price, orderDirection: asc) {
    id
    owner
  }
}

Graph Düğümü v0.30.0'dan itibaren varlıklar iç içe geçmiş varlıklar bazında sıralanabilir.

The following example shows tokens sorted by the name of their owner:

{
  tokens(orderBy: owner__name, orderDirection: asc) {
    id
    owner {
      name
    }
  }
}

When querying a collection, it's best to:

• Use the first parameter to paginate from the beginning of the collection.
  • The default sort order is by ID in ascending alphanumeric order, not by creation time.
• Use the skip parameter to skip entities and paginate. For instance, first:100 shows the first 100 entities and first:100, skip:100 shows the next 100 entities.
• Avoid using skip values in queries because they generally perform poorly. To retrieve a large number of items, it's best to page through entities based on an attribute as shown in the previous example above.

İlk 10 tokeni sorgulayın:

{
  tokens(first: 10) {
    id
    owner
  }
}

Bir koleksiyonun ortasındaki varlık gruplarını sorgulamak için skip parametresi, koleksiyonun başından başlayarak belirli sayıda varlığı atlamak üzere first parametresi ile birlikte kullanılabilir.

10 Token varlığını sorgulayın, bunları koleksiyonun başlangıcından itibaren 10 sıra kaydırın:

{
  tokens(first: 10, skip: 10) {
    id
    owner
  }
}

If a client needs to retrieve a large number of entities, it's more performant to base queries on an attribute and filter by that attribute. For example, a client could retrieve a large number of tokens using this query:

query manyTokens($lastID: String) {
  tokens(first: 1000, where: { id_gt: $lastID }) {
    id
    owner
  }
}

The first time, it would send the query with lastID = "", and for subsequent requests it would set lastID to the id attribute of the last entity in the previous request. This approach will perform significantly better than using increasing skip values.

• You can use the where parameter in your queries to filter for different properties.
• You can filter on multiple values within the where parameter.

failed ile sonuçlanan sorgu zorlukları:

{
  challenges(where: { outcome: "failed" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Değer karşılaştırması için _gt, _lte gibi son ekler kullanabilirsiniz:

{
  applications(where: { deposit_gt: "10000000000" }) {
    id
    whitelisted
    deposit
  }
}

You can also filter entities that were updated in or after a specified block with _change_block(number_gte: Int).

Örneğin bu, son yoklamanızdan bu yana yalnızca değişen varlıkları almak istiyorsanız yararlı olabilir. Ya da alternatif olarak, subgraph'ınızda varlıkların nasıl değiştiğini araştırmak veya hata ayıklamak için yararlı olabilir (bir blok filtresiyle birleştirilirse, yalnızca belirli bir blokta değişen varlıkları izole edebilirsiniz).

{
  applications(where: { _change_block: { number_gte: 100 } }) {
    id
    whitelisted
    deposit
  }
}

İç içe geçmiş varlıklar temelinde filtreleme, _ son ekine sahip alanlarda mümkündür.

Bu, yalnızca alt düzey varlıkları sağlanan koşulları karşılayan varlıkları getirmek istiyorsanız yararlı olabilir.

{
  challenges(where: { application_: { id: 1 } }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Graph Düğümü'nün v0.30.0 sürümüne göre, birden fazla parametreyi aynı where argümanında gruplayabilirsiniz. Bu, sonuçları birden fazla kritere göre filtrelemek için and veya or operatörlerini kullanmanıza olanak tanır.

The following example filters for challenges with outcome succeeded and number greater than or equal to 100.

{
  challenges(where: { and: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {
    challenger
    outcome
    application {
      id
    }
  }
}

{
  challenges(where: { number_gte: 100, outcome: "succeeded" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

The following example filters for challenges with outcome succeeded or number greater than or equal to 100.

{
  challenges(where: { or: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Parametre eklerinin tam listesi:

_
_not
_gt
_lt
_gte
_lte
_in
_not_in
_contains
_contains_nocase
_not_contains
_not_contains_nocase
_starts_with
_starts_with_nocase
_ends_with
_ends_with_nocase
_not_starts_with
_not_starts_with_nocase
_not_ends_with
_not_ends_with_nocase

Ayrıca, aşağıdaki global filtreler where argümanının bir parçası olarak kullanılabilir:

_change_block(number_gte: Int)

Varlıklarınızın durumunu yalnızca varsayılan olan en son blok için değil, aynı zamanda geçmişteki rastgele bir blok için de sorgulayabilirsiniz. Bir sorgunun gerçekleşmesi gereken blok, sorguların üst düzey alanlarına bir block bağımsız değişkeni eklenerek blok numarası veya blok karması ile belirtilebilir.

The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change.

{
  challenges(block: { number: 8000000 }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Bu sorgu, 8.000.000 numaralı bloğun işlenmesinden hemen sonra var oldukları şekliyle Challenge varlıklarını ve bunlarla ilişkili Application varlıklarını döndürür.

{
  challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Bu sorgu, verilen hash ile bloğun işlenmesinden hemen sonra var olan şekliyle Challenge varlıklarını ve bunlarla ilişkili Application varlıklarını döndürür.

Tam metin arama sorgu alanları, subgraph şemasına eklenebilen ve özelleştirilebilen etkileyici bir metin arama API'si sağlar. Subgraph'ınıza tam metin araması eklemek için Tam Metin Arama Alanlarını Tanımlama bölümüne göz atın.

Tam metin arama sorgularının kullanması gereken bir zorunlu alanı vardır, bu alan text adını taşır ve arama terimlerini sağlamak için kullanılır. Bu text arama alanında kullanılmak üzere birkaç özel tam metin operatörü mevcuttur.

Tam metin arama operatörleri:

or operatörünü kullanan bu sorgu, tam metin alanlarında "anarchism" veya "crumpet" varyasyonları bulunan blog varlıklarını filtreleyecektir.

{
  blogSearch(text: "anarchism | crumpets") {
    id
    title
    body
    author
  }
}

follow by operatörü, tam metin belgelerinde belirli bir mesafe uzaklıktaki kelimeleri belirtir. Aşağıdaki sorgu "decentralize" ve ardından "philosophy" kelimelerinin geçtiği tüm blogları döndürür

{
  blogSearch(text: "decentralized <-> philosophy") {
    id
    title
    body
    author
  }
}

Daha karmaşık filtreler oluşturmak için tam metin operatörlerini birleştirin. Bu örnek sorgu, bir pretext arama işleci ile bir follow by işlecini birleştirerek "lou" ile başlayan ve ardından "music" ile devam eden sözcükleri içeren tüm blog varlıklarıyla eşleşecektir.

{
  blogSearch(text: "lou:* <-> music") {
    id
    title
    body
    author
  }
}

Graph Düğümü, graphql-js referans uygulamasını temel alan graphql-tools-rs'yi kullanarak aldığı GraphQL sorgularının spesifikasyon tabanlı doğrulamasını gerçekleştirir. Bir doğrulama kuralını geçemeyen sorgular standart bir hata ile sonuçlanır. Daha fazla bilgi için GraphQL spec'i ziyaret edin.

The schema of your dataSources, i.e. the entity types, values, and relationships that are available to query, are defined through the GraphQL Interface Definition Langauge (IDL).

GraphQL schemas generally define root types for queries, subscriptions and mutations. The Graph only supports queries. The root Query type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest.

Şemanızda @entity yönergeleri bulunan tüm GraphQL türleri varlık olarak değerlendirilir ve bir ID alanına sahip olmalıdır.

Tüm subgraphlar, subgraph üst verisine erişim sağlayan otomatik olarak oluşturulmuş bir _Meta_ nesnesine sahiptir. Bu aşağıdaki gibi sorgulanabilir:

{
  _meta(block: { number: 123987 }) {
    block {
      number
      hash
      timestamp
    }
    deployment
    hasIndexingErrors
  }
}

Eğer bir blok belirtilirse, üst veri o blokla ilgilidir; belirtilmezse en son dizinlenen blok dikkate alınır. Eğer belirtilirse, blok subgraph başlangıç bloğundan sonra olmalıdır ve en son indekslenen bloğa eşit veya daha küçük olmalıdır.

deployment eşsiz bir kimliktir ve subgraph.yaml dosyasının IPFS CID'sine karşılık gelir.

block en son blok hakkında bilgi sağlar (_meta'ya aktarılan blok kısıtlamalarını dikkate alarak):

• hash: the hash of the block
• number: the block number
• timestamp: the timestamp of the block, if available (this is currently only available for subgraphs indexing EVM networks)

hasIndexingErrors ifadesi, subgraph'ın önceki bazı bloklarda indeksleme hatalarıyla karşılaşıp karşılaşmadığını belirleyen bir boolean değeridir