Docs
⌘ K

8 dakika

GraphQL API'ı

The Graph’te kullanılan GraphQL Sorgu API’ı hakkında bilgi edinin.

GraphQL Nedir?

[GraphQL] (https://graphql.org/learn/⁠), API’lar için bir sorgu dili ve bu sorguları mevcut verileriniz üzerinde çalıştıran bir sorgu dilidir. The Graph, Subgraph’leri sorgulamak için GraphQL kullanır.

GraphQL’in daha kapsamlı rolünü anlamak için geliştirme ve bir Subgraph oluşturma bölümlerini inceleyin.

GraphQL Sorguları

Subgraph şemanızda, Entities (Varlıklar) olarak adlandırılan türleri tanımlarsınız. Her bir Entity (Varlık) türü için, üst düzey Query türü üzerinde entity ve entities alanları otomatik olarak oluşturulur.

Not: The Graph’te, graphql sorgularının başına query (sorgu) ifadesinin eklenmesi gerekmez.

Örnekler

Şemanızda tanımlı tek bir Token varlığı için sorgu:

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

Not: Tek bir varlık sorgulanırken id alanı zorunludur ve bir dize olarak yazılmalıdır.

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

{  tokens {    id    owner  }}

Sıralama

Bir koleksiyon sorgularken şunları yapabilirsiniz:

  • Belirli bir özniteliğe göre sıralama yapmak için orderBy parametresini kullanın.
  • Sıralama yönünü belirtmek için orderDirection kullanın; artan sıralama için asc, azalan sıralama için desc.

Örnek

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

İç içe varlık sıralaması için örnek

Graph Düğümü v0.30.0⁠ sürümünden itibaren, varlıklar iç içe ve varlıklara göre sıralanabilir.

Aşağıdaki örnek, token’ların sahip adına göre nasıl sıralandığını gösteriyor:

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

Şu anda, @entity ve @derivedFrom alanlarında bir seviye derinliğindeki String veya ID türlerine göre sıralama yapabilirsiniz. Ne yazık ki, bir seviye derinliğindeki varlıklarda arayüzlere göre sıralama⁠, alanı bir dizi ya da iç içe bir varlık olan ögelere göre sıralama henüz desteklenmemektedir.

Sayfalandırma

Bir koleksiyon sorgularken aşağıdakileri uygulamanız önerilir:

  • Koleksiyonun başından itibaren sayfalama yapmak için first parametresini kullanın.
    • Varsayılan sıralama düzeni, oluşturulma zamanına göre değil, artan alfasayısal sıraya göre ID alanına göre yapılır.
  • Varlıkları atlamak ve sayfalama yapmak için skip parametresini kullanın. Örneğin, first:100 ilk 100 varlığı gösterir. first:100, skip:100 ise sonraki 100 varlığı gösterir.
  • Sorgularda skip değerlerini kullanmaktan kaçının, çünkü genellikle düşük performans gösterirler. Çok sayıda ögeyi getirmek için, yukarıdaki örnekte gösterildiği gibi bir özniteliğe göre varlıklar arasında sayfalama yapmak en iyi yaklaşımdır.

first kullanımına örnek

İlk 10 tokeni sorgulayın:

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

Bir koleksiyonun ortasındaki varlık gruplarını sorgulamak için, skip parametresi first parametresiyle birlikte kullanılabilir. Bu, koleksiyonun başından itibaren belirli sayıda varlığı atlayarak sorgulama yapmanızı sağlar.

first ve skip kullanımına örnek

Koleksiyonun başından itibaren 10 öge atlayarak 10 Token varlığı sorgulama:

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

first ve id_ge kullanımına örnek

Bir istemcinin çok sayıda varlık alması gerektiğinde, sorguları bir öznitelik temelinde oluşturmak ve bu özniteliğe göre filtrelemek daha yüksek performans sağlar. Örneğin, bir istemci aşağıdaki sorguyu kullanarak çok sayıda token alabilir:

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

İlk seferde lastID = "" ile sorgu gönderilecek ve sonraki istekler için lastID değeri önceki istekteki son varlığın id özelliğine göre ayarlanacaktır. Bu yaklaşım, artan skip değerlerini kullanmaktan önemli ölçüde daha iyi performans gösterir.

Filtreleme

  • where parametresini sorgularınızda farklı özellikleri filtrelemek için kullanabilirsiniz.
  • Birden çok değeri where parametresi içinde filtreleyebilirsiniz.

where kullanımına örnek

outcome değeri failed olan challenge’ları sorgulama:

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

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

Aralık filtreleme için örnek

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

Blok filtreleme için örnek

Belirtilen bir blokta veya sonrasında güncellenen varlıkları, _change_block(number_gte: Int) ile de filtreleyebilirsiniz.

Bu, yalnızca değişen varlıkları getirmek istiyorsanız kullanışlı olabilir. Örneğin, son yoklamanızdan bu yana değişen varlıklar için. Ya da, subgraph’inizde varlıkların nasıl değiştiğini araştırmak veya hata ayıklamak için faydalı olabilir (bir blok filtresiyle beraber kullanıldığında, yalnızca belirli bir blokta değişen varlıkları izole edebilirsiniz).

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

İç içe varlık filtreleme örneği

İç içe varlıklara göre 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    }  }}

Mantıksal operatörler

Graph Düğümü v0.30.0⁠ sürümünden itibaren, birden fazla kritere dayalı sonuçları filtrelemek için aynı where argümanı içinde birden çok parametreyi and veya or operatörleriyle gruplayabilirsiniz.

AND Operatörü

Aşağıdaki örnek, outcome değeri succeeded olan ve number alanı 100 veya daha büyük olan challenge’ları filtreler.

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

Sözdizimsel şeker: Yukarıdaki sorguyu, virgülle ayrılmış bir alt ifade kullanıp and operatörünü kaldırarak sadeleştirebilirsiniz.

{  challenges(where: { number_gte: 100, outcome: "succeeded" }) {    challenger    outcome    application {      id    }  }}
OR Operatörü

Aşağıdaki örnek, outcome değeri succeeded olan veya number alanı 100 veya daha büyük olan challenge’ları filtreler.

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

Not: Sorguları oluştururken or operatörünün performans üzerindeki etkisini dikkate almak önemlidir. or, arama sonuçlarını genişletmek için faydalı bir araç olsa da, ciddi performans maliyetlerine yol açabilir. or operatörünün başlıca sorunlarından biri, sorguların yavaşlamasına neden olmasıdır. Bunun nedeni, or kullanıldığında veritabanının birden fazla endeksi taramak zorunda kalmasıdır; bu da zaman alıcı bir işlemdir. Bu tür sorunlardan kaçınmak için geliştiricilere mümkün olduğunca or yerine and operatörlerini kullanmaları önerilir. Bu sayede daha hassas filtreleme yapılabilir ve sorgular daha hızlı ve doğru şekilde çalışabilir.

Tüm Filtreler

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

Lütfen bazı son eklerin yalnızca belirli türler için desteklendiğini unutmayın. Örneğin, Boolean türü yalnızca _not, _in ve _not_in son eklerini destekler; ancak _ soneki yalnızca nesne ve arayüz türleri için kullanılabilir.

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

_change_block(number_gte: Int)

Zaman yolculuğu sorguları

Varlıklarınızın durumunu en son blok için (varsayılan), ya da geçmişteki herhangi bir blok için sorgulayabilirsiniz. Sorgunun hangi blokta yapılacağını belirtmek için, üst seviye sorgu alanlarında block argümanı eklenerek ilgili blok numarası veya blok hash’i kullanılabilir.

Böyle bir sorgunun sonucu zamanla değişmez; yani, geçmişteki belirli bir blokta yapılan bir sorgu, ne zaman çalıştırılırsa çalıştırılsın aynı sonucu döndürür. Ancak, zincirin en ucuna (head) çok yakın bir blokta sorgulama yapılırsa, bu blok ana zincirde yer almıyorsa ve zincir yeniden düzenlenirse sonuç değişebilir. Bir blok artık kesin (final) olarak kabul edilebildiğinde, o blok için yapılan sorgunun sonucu değişmeyecektir.

Not: Mevcut uygulama, bu güvenceleri ihlal edebilecek bazı sınırlamalara hâlâ tabidir. Uygulama, verilen bir blok hash’inin ana zincirde yer almadığını her zaman tespit edemez veya henüz kesin (final) olarak kabul edilmeyen bir blok için yapılan bir blok hash sorgusunun, sorgu ile eşzamanlı olarak gerçekleşen bir zincir yeniden düzenlemesinden etkilenip etkilenmeyeceğini öngöremez. Ancak bu sınırlamalar, blok kesinleşmiş ve ana zincirde yer aldığı biliniyorsa, blok hash ile yapılan sorguların sonuçlarını etkilemez. Bu sınırlamalar hakkında ayrıntılı bilgi için bu GitHub issue’su⁠ incelenebilir.

Örnek

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

Bu sorgu, blok numarası 8.000.000 işlendiği andan hemen sonraki halleriyle Challenge varlıklarını ve bunlara bağlı Application varlıklarını döndürecektir.

Örnek

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

Bu sorgu, verilen hash’e sahip blok işlendiği andan hemen sonraki halleriyle Challenge varlıklarını ve bunlara bağlı Application varlıklarını döndürecektir.

Tam Metin Arama Sorguları

Tam metin arama sorgu alanları, Subgraph şemasına eklenebilen ve özelleştirilebilen gelişmiş bir metin arama API’si sağlar. Subgraph’inize tam metin arama eklemek için Tam Metin Arama Alanlarını Tanımlama bölümüne bakın.

Tam metin arama sorgularında, arama terimlerinin girildiği zorunlu bir text alanı bulunur. Bu text arama alanında kullanılabilecek çeşitli özel tam metin operatörleri mevcuttur.

Tam metin arama operatörleri:

SembolOperatörTanım
&AndSağlanan tüm arama terimlerini içeren varlıkları filtrelemek için birden fazla arama terimini birleştirir
|OrOr (veya) operatörüyle ayrılmış birden fazla arama terimi içeren sorgular, sağlanan terimlerden herhangi biriyle eşleşen tüm varlıkları döndürür
<->Follow byİki kelime arasındaki mesafeyi belirtmeyi sağlar.
:*PrefixÖn eki (Prefix’i) eşleşen kelimeleri bulmak için ön ek arama terimini kullanın (en az 2 karakter gereklidir).

Örnekler

or operatörü kullanılarak yapılan bu sorgu, tam metin alanlarında “anarchism” veya “crumpet” kelimelerinin varyasyonlarını içeren blog varlıklarını döndürecektir.

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

follow by operatörü, tam metin belgelerinde belirli bir mesafe ile birbirini izleyen kelimeleri belirtir. Aşağıdaki sorgu, “decentralize” kelimesinin varyasyonları ardından belirli bir mesafede “philosophy” kelimesini içeren tüm blogları döndürecektir.

{  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  }}

Validasyon

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.

Şema

Veri kaynaklarınızın şeması, yani sorgulanabilir olan entity türleri, değerler ve ilişkiler, GraphQL Arayüz Tanım Dili (IDL)⁠ kullanılarak tanımlanır.

GraphQL şemaları genellikle queries, subscriptions ve mutations için kök türleri tanımlar. The Graph yalnızca queries desteği sunar. Subgraph’iniz için kök Query türü, Subgraph manifesto dosyanıza dahil edilen GraphQL şemasından otomatik olarak oluşturulur.

Not: API’miz mutation (mutasyon) işlemlerini desteklemez, çünkü geliştiricilerin kendi uygulamaları üzerinden doğrudan temel blokzincirine işlem göndermeleri beklenir.

Varlıklar

Şemanızda @entity yönergesiyle tanımlanan tüm GraphQL türleri varlık olarak kabul edilir ve bir ID alanına sahip olmaları gerekir.

Not: Şu anda, şemanızdaki tüm türlerin @entity yönergesine sahip olması gerekir. Gelecekte, @entity yönergesi olmayan türler değer nesnesi olarak değerlendirilecek, ancak bu henüz desteklenmemektedir.

Subgraph Üst Verisi

Tüm Subgraph’lerde, Subgraph metadatasına erişim sağlayan otomatik olarak oluşturulmuş bir _Meta_ nesnesi bulunur. Buna aşağıdaki şekilde sorgu yapabilirsiniz:

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

Bir blok belirtilirse, metadata o bloğa ait durumu yansıtır; belirtilmezse en son endekslenmiş blok kullanılır. Belirtilen blok, Subgraph’in başlangıç bloğundan sonra ve en son endekslenmiş bloğa eşit ya da ondan küçük olmalıdır.

deployment, subgraph.yaml dosyasının IPFS CID’sine karşılık gelen özgün bir kimliktir.

block, _meta’ya iletilen herhangi bir blok kısıtlamasını dikkate alarak, en son blok hakkında bilgi sağlar:

  • hash: bloğun hash değeri
  • number: blok numarası
  • timestamp: eğer mevcuts, blokun zaman damgası (bu şu anda yalnızca EVM ağlarını endeksleyen Subgraph’ler için kullanılabilir)

hasIndexingErrors, spesifik bir Subgraph’in geçmişteki bir blokta endeksleme hatalarıyla karşılaşıp karşılaşmadığını belirten bir boolean ifadedir