Docs
⌘ K

8 dakika

Sorgulama - Örnek Uygulamalar

The Graph, blokzincirlerinden veri sorgulamak için merkeziyetsiz bir yöntem sağlar. Verileri bir GraphQL API’si aracılığıyla sunulur ve bu da GraphQL diliyle sorgulamayı kolaylaştırır.

Subgraph’inizi optimize etmek için gerekli temel GraphQL dili kurallarını ve örnek uygulamaları öğrenin.

Bir GraphQL API’sini sorgulama

Bir GraphQL Sorgusunun Anatomisi

REST API’den farklı olarak, bir GraphQL API’si, hangi sorguların gerçekleştirilebileceğini tanımlayan bir Şema üzerine kuruludur.

Örneğin, token sorgusunu kullanarak bir token almak için yapılacak sorgu aşağıdaki gibi olacaktır:

query GetToken($id: ID!) {  token(id: $id) {    id    owner  }}

ve bu sorgu (doğru $id değişkeni geçirildiğinde) aşağıdaki öngörülebilir JSON yanıtını döndürecektir:

{  "token": {    "id": "...",    "owner": "..."  }}

GraphQL sorguları, bir spesifikasyon⁠ temelinde tanımlanmış olan GraphQL dilini kullanır.

Yukarıdaki GetToken sorgusu, birden fazla dil bileşeninden oluşur (aşağıda [...] yer tutucularıyla gösterilmiştir):

query [operationName]([variableName]: [variableType]) {  [queryName]([argumentName]: [variableName]) {    # "{ ... }" express a Selection-Set, we are querying fields from `queryName`.    [field]    [field]  }}

GraphQL Sorgusu Yazmanın Kuralları

  • Her bir queryName, işlem başına yalnızca bir kez kullanılmalıdır.
  • Her bir field, bir seçim içinde yalnızca bir kez kullanılmalıdır (örneğin, token altında id alanını iki kez sorgulayamayız)
  • Bazı field’lar veya sorgular (örneğin tokens), alt alan seçimi gerektiren karmaşık türler döndürür. Beklendiğinde alt alan seçimi yapmamak (ya da beklenmediğinde böyle bir seçim yapmak, örneğin id üzerinde) bir hata oluşturur. Bir alanın türünü öğrenmek için lütfen Graph Gezgini sayfasına bakın.
  • Bir argümana atanan herhangi bir değişken, onun türüyle eşleşmelidir.
  • Belirli bir değişken listesinde, her bir değişken özgün olmalıdır.
  • Tanımlanan tüm değişkenler kullanılmalıdır.

Not: Bu kurallara uyulmaması, The Graph API’sinin hata vermesi ile sonuçlanacaktır.

Kod örnekleriyle birlikte tam kurallar listesi için GraphQL Doğrulamaları rehberine göz atın.

Bir GraphQL API’sine sorgu göndermek

GraphQL, HTTP üzerinden taşınan bir dil ve kurallar bütünüdür.

Bu, (yerel olarak veya @whatwg-node/fetch ya da isomorphic-fetch aracılığıyla) standart fetch kullanarak bir GraphQL API’sini sorgulayabileceğiniz anlamına gelir.

Ancak, “Bir Uygulamadan Sorgulama” bölümünde belirtildiği gibi, aşağıdaki benzersiz özellikleri destekleyen graph-clientın kullanılması önerilir:

graph-client aracılığıyla The Graph sorgusu nasıl yapılır:

import { execute } from '../.graphclient'const query = `query GetToken($id: ID!) {  token(id: $id) {    id    owner  }}`const variables = { id: '1' }async function main() {  const result = await execute(query, variables)  // `result` is fully typed!  console.log(result)}main()

Daha fazla GraphQL istemcisi alternatifi, “Bir Uygulamadan Sorgulama” bölümünde ele alınmıştır.

En İyi Uygulamalar

Her zaman statik sorgular yazın

Yaygın (ve kötü) bir uygulama, sorgu dizelerini aşağıdaki gibi dinamik olarak oluşturmaktır:

const id = params.idconst fields = ['id', 'owner']const query = `query GetToken {  token(id: ${id}) {    ${fields.join('\n')}  }}`// Sorguyu çalıştır...

Yukarıdaki kod parçası geçerli bir GraphQL sorgusu üretse de, birçok dezavantaja sahiptir:

  • sorguyu bir bütün olarak anlamayı zorlaştırır
  • geliştiriciler, dize enterpolasyonunun güvenliğini sağlamakla sorumludur
  • değişken değerlerinin istek parametreleriyle gönderilmemesi sunucu tarafındaki önbellekleme olasılığını ortadan kaldırır
  • bu, araçların sorguyu statik olarak analiz etmesini engeller (örneğin: Linter veya tür üretim araçları)

Bu nedenle, sorguları her zaman statik dizeler olarak yazmanız önerilir:

import { execute } from 'dilediğiniz-graphql-istemcisi'const id = params.idconst query = `query GetToken($id: ID!) {  token(id: $id) {    id    owner  }}`const result = await execute(query, {  variables: {    id,  },})

Bunu yapmak birçok avantaj sağlar:

  • Okuması ve bakımı kolay sorgular
  • GraphQL sunucusu değişkenlerin güvenli hale getirilmesini üstlenir
  • Değişkenler sunucu düzeyinde önbelleğe alınabilir
  • Sorgular araçlar tarafından statik olarak analiz edilebilir (detaylar sonraki bölümlerde açıklanacaktır)

Statik sorgularda alanlar nasıl koşullu olarak dahil edilir

owner alanını yalnızca belirli bir koşulla dahil etmek isteyebilirsiniz.

Bunun için, @include(if:...) yönergesinden aşağıdaki gibi yararlanabilirsiniz:

import { execute } from 'dilediğiniz-graphql-istemcisi'const id = params.idconst query = `query GetToken($id: ID!, $includeOwner: Boolean) {  token(id: $id) {    id    owner @include(if: $includeOwner)  }}`const result = await execute(query, {  variables: {    id,    includeOwner: true,  },})

Not: Bunun tersi yönerge @skip(if: ...) şeklindedir.

İstediğini sor

GraphQL, “İstediğini sor” sloganıyla ün kazanmıştı.

Bu nedenle, GraphQL’de tüm kullanılabilir alanları tek tek listelemeden almanın bir yolu yoktur.

  • GraphQL API’leri sorgularken, her zaman sadece gerçekten kullanılacak alanları sorgulamayı düşünmelisiniz.
  • Sorguların yalnızca gerçekten ihtiyaç duyduğunuz kadar varlık getirdiğinden emin olun. Varsayılan olarak, sorgular bir koleksiyondan 100 varlık getirir. Bu miktar genellikle gerekenden, örneğin kullanıcıya gösterilecek olandan, çok daha fazladır. Bu durum yalnızca sorgulardaki en üst düzey koleksiyonlar için değil, özellikle iç içe varlık koleksiyonları için de geçerlidir.

Örneğin, aşağıdaki sorguda:

query listTokens {  tokens {    # en fazla 100 token getirilecektir    id    transactions {      # en fazla 100 işlem getirilecektir      id    }  }}

Yanıt, 100 token için 100’er işlem içerebilir.

Uygulama yalnızca 10 işleme ihtiyaç duyuyorsa, sorguda transactions (işlemler) alanına açıkça first: 10 değeri verilmelidir.

Birden fazla kaydı istemek için tek bir sorgu kullanın

Varsayılan olarak, Subgraph’ler tek bir kayıt için tekil bir varlık sunar. Birden fazla kayıt almak için çoğul varlıkları ve filtrelemeyi kullanın: where: {id_in:[X,Y,Z]} veya where: {volume_gt:100000}

Verimsiz bir sorgulama örneği:

query SingleRecord {  entity(id: X) {    id    name  }}query SingleRecord {  entity(id: Y) {    id    name  }}

Optimize edilmiş bir sorgulama örneği:

query ManyRecords {  entities(where: { id_in: [X, Y] }) {    id    name  }}

Birden fazla sorguyu tek bir istekte birleştirin

Uygulamanız buradaki gibi birden fazla veri türünü sorgulamanızı gerektirebilir:

import { execute } from "dilediğiniz-graphql-istemcisi"const tokensQuery = `query GetTokens {  tokens(first: 50) {    id    owner  }}`const countersQuery = `query GetCounters {  counters {    id    value  }}`const [tokens, counters] = Promise.all(  [    tokensQuery,    countersQuery,  ].map(execute))

Bu uygulama tamamen geçerli olsa da, GraphQL API’si ile iki kez veri alışverişi yapılmasını gerektirir.

Neyse ki, aynı GraphQL isteği içinde birden fazla sorgu göndermek de aşağıdaki gibi geçerlidir:

import { execute } from "dilediğiniz-graphql-istemcisi"const query = `query GetTokensandCounters {  tokens(first: 50) {    id    owner  }  counters {    id    value  }}`const  { result: { tokens, counters } } = execute(query)

Bu yaklaşım, ağ üzerinde harcanan süreyi azaltarak genel performansı artırır (API’ye yapılan bir gidiş-dönüşü ortadan kaldırır) ve daha sade bir uygulama sunar.

GraphQL Parçalarını (Fragment) Kullanın

GraphQL sorguları yazarken faydalı bir özellik de GraphQL Fragment’tir.

Aşağıdaki sorguya baktığınızda, bazı alanların birden fazla Seçim Kümesi ({ ... }) içinde tekrarlandığını fark edeceksiniz:

query {  bondEvents {    id    newDelegate {      id      active      status    }    oldDelegate {      id      active      status    }  }}

Bu tür tekrarlanan alanlar (id, active, status) birçok sorunu beraberinde getirir:

  • Daha kapsamlı sorguların okunması zorlaşır.
  • Sorgulara dayanarak TypeScript türleri üreten araçlar kullanıldığında (ilgili detaylar için son bölüme bakınız), newDelegate ve oldDelegate iki ayrı satır içi arayüz (inline interface) olarak tanımlanır.

Sorgunun yeniden düzenlenmiş hali aşağıdaki gibi olacaktır:

query {  bondEvents {    id    newDelegate {      ...DelegateItem    }    oldDelegate {      ...DelegateItem    }  }}# sorguda tekrarlanan alanları ortaklaştırmak için# transcoder üzerinde bir fragment (alt tür) tanımlıyoruzfragment DelegateItem on Transcoder {  id  active  status}

GraphQL fragment kullanmak, okunabilirliği artırır (özellikle büyük sorgularda) ve daha iyi TypeScript türleri üretilmesini sağlar.

Tür üretim aracını kullanırken, yukarıdaki sorgu doğru bir DelegateItemFragment türü (sondaki “Araçlar” bölümüne bakabilirsiniz) oluşturacaktır.

GraphQL Fragment kullanırken yapılması ve kaçınılması gerekenler

Fragment tabanı bir tip olmalıdır

Bir Fragment, geçerli olmayan bir tür üzerinde tanımlanamaz. Kısacası, alanları olmayan bir tür üzerinde kullanılamaz:

fragment MyFragment on BigInt {  # ...}

BigInt, bir skaler (yerel “basit” tür) olduğu için bir fragment’in temeli olarak kullanılamaz.

Fragment Nasıl Yayılır

Fragment’ler belirli türler üzerinde tanımlanırlar ve sorgularda buna uygun şekilde kullanılmalılardır.

Örnek:

query {  bondEvents {    id    newDelegate {      ...VoteItem # Hata! `VoteItem` fragment'i `Transcoder` türü üzerinde kullanılamaz    }    oldDelegate {      ...VoteItem    }  }}fragment VoteItem on Vote {  id  voter}

newDelegate ve oldDelegate, Transcoder türündendir.

Burada Vote türünde bir fragment kullanılamaz.

Fragment’ı atomik bir veri iş birimi olarak tanımlayın

GraphQL’de bir Fragment, kullanım amacına göre tanımlanmalıdır.

Çoğu kullanım senaryosunda, her tür için bir fragment tanımlamak (özellikle tekrarlanan alan kullanımı veya tür üretimi durumlarında) yeterlidir.

İşte fragment kullanımı için temel bir kural:

  • Aynı türdeki alanlar bir sorguda tekrar ediyorsa, bunları bir Fragment içinde gruplayın.
  • Benzer ancak farklı alanlar tekrar ediyorsa, birden fazla “fragment” oluşturun. Örneğin:
# temel fragment (genellikle listeleme işlemlerinde kullanılır)fragment Voter on Vote {  id  voter}# genişletilmiş fragment (bir vote'un detaylı görünümünü sorgularken kullanılır)fragment VoteWithPoll on Vote {  id  voter  choiceID  poll {    id    proposal  }}

Temel Araçlar

Web tabanlı GraphQL gezginleri

Sorgularınızı uygulamanızda çalıştırarak denemek zahmetli olabilir. Bu nedenle, sorgularınızı uygulamaya eklemeden önce test etmek için Graph Gezginini kullanmaktan çekinmeyin. Graph Gezgini, sorgularınızı test etmeniz için önceden yapılandırılmış bir GraphQL playground’u sunar.

Sorgularınızda hata ayıklamak/sorgularınızı test etmek için daha esnek bir yol arıyorsanız, Altair⁠ ve GraphiQL⁠ gibi benzer web tabanlı araçlar da mevcuttur.

GraphQL’de Linting

Yukarıda belirtilen örnek uygulamalar ve sözdizim kurallarına uyum sağlamak için aşağıdaki iş akışı ve IDE (Entegre Geliştirme Ortamı) araçlarını kullanmanız şiddetle tavsiye edilir.

GraphQL ESLint

GraphQL ESLint⁠, GraphQL örnek uygulamalarına zahmetsizce uymanıza yardımcı olur.

“operations-recommended” yapılandırmasını kurmak⁠, aşağıdakiler gibi temel kuralları zorunlu kılar:

  • @graphql-eslint/fields-on-correct-type: alan doğru tür üzerinde mi kullanılmış?
  • @graphql-eslint/no-unused-variables: verilen bir değişken kullanılmadan mı bırakılmış?
  • ve daha fazlası!

Bu sayede, sorguları playground’da test etmeye ya da üretim ortamında çalıştırmaya gerek kalmadan hataları önceden yakalayabilirsiniz!

IDE eklentileri

VSCode ve GraphQL

GraphQL VSCode uzantısı⁠, geliştirme sürecinize aşağıdakileri sağlamak için mükemmel bir eklentidir:

  • Sözdizimi vurgulama
  • Otomatik tamamlama önerileri
  • Şemaya karşı doğrulama
  • Kod parçacıkları (snippets)
  • Fragment’ler ve girdi türleri için tanıma gitme özelliği

graphql-eslint kullanıyorsanız, ESLint VSCode uzantısı⁠ kodunuzda hataları ve uyarıları satır içi şekilde doğru bir biçimde görüntülemek için mutlaka edinilmesi gereken bir araçtır.

WebStorm/Intellij ve GraphQL

JS GraphQL eklentisi⁠, GraphQL ile çalışırken deneyiminizi aşağıdakileri sağlayarak önemli ölçüde iyileştirir:

  • Sözdizimi vurgulama
  • Otomatik tamamlama önerileri
  • Şemaya karşı doğrulama
  • Kod parçacıkları (snippets)

Bu konuyla ilgili daha fazla bilgi için, eklentinin tüm ana özelliklerini gösteren WebStorm makalesine⁠ göz atabilirsiniz.