Advance Subgraph Features

Reading time: 14 min

Add and implement advanced subgraph features to enhanced your subgraph's built.

Starting from specVersion 0.0.4, subgraph features must be explicitly declared in the features section at the top level of the manifest file, using their camelCase name, as listed in the table below:

For instance, if a subgraph uses the Full-Text Search and the Non-fatal Errors features, the features field in the manifest should be:

specVersion: 0.0.4
description: Gravatar for Ethereum
features:
  - fullTextSearch
  - nonFatalErrors
dataSources: ...

Zaman serileri ve toplulaştırmalar, subgraph'inizin günlük ortalama fiyat, saatlik toplam transferler gibi istatistikleri takip etmesini sağlar.

Bu özellik, iki yeni subgraph varlık türünü tanıtır. Zaman Serisi varlıkları, zaman damgaları ile veri noktalarını kaydeder. Toplulaştırma varlıkları ise saatlik veya günlük bazda Zaman Serisi veri noktaları üzerinde önceden belirlenmiş hesaplamalar yapar ve sonuçları GraphQL üzerinden kolay erişim için saklar.

type Data @entity(timeseries: true) {
  id: Int8!
  timestamp: Timestamp!
  price: BigDecimal!
}

type Stats @aggregation(intervals: ["hour", "day"], source: "Data") {
  id: Int8!
  timestamp: Timestamp!
  sum: BigDecimal! @aggregate(fn: "sum", arg: "price")
}

Timeseries entities are defined with @entity(timeseries: true) in schema.graphql. Every timeseries entity must have a unique ID of the int8 type, a timestamp of the Timestamp type, and include data that will be used for calculation by aggregation entities. These Timeseries entities can be saved in regular trigger handlers, and act as the “raw data” for the Aggregation entities.

Aggregation entities are defined with @aggregation in schema.graphql. Every aggregation entity defines the source from which it will gather data (which must be a Timeseries entity), sets the intervals (e.g., hour, day), and specifies the aggregation function it will use (e.g., sum, count, min, max, first, last). Aggregation entities are automatically calculated on the basis of the specified source at the end of the required interval.

• hour: sets the timeseries period every hour, on the hour.
• day: sets the timeseries period every day, starting and ending at 00:00.

• sum: Total of all values.
• count: Number of values.
• min: Minimum value.
• max: Maximum value.
• first: First value in the period.
• last: Last value in the period.

{
  stats(interval: "hour", where: { timestamp_gt: 1704085200 }) {
    id
    timestamp
    sum
  }
}

Not:

Zaman Serisi ve Toplulaştırmalar özelliklerini kullanmak için, subgraph’inizin spec sürümü ≥1.1.0 olmalıdır. Bu özelliğin, geriye dönük uyumluluğu etkileyebilecek önemli değişikliklerden geçebileceğini unutmayın.

Read more about Timeseries and Aggregations.

Halihazırda senkronize edilmiş subgraphlarda indeksleme hataları varsayılan olarak subgraph başarısız olmasına ve senkronizasyonun durmasına neden olur. Hatalara rağmen senkronizasyonun devam etmesi için subgraphlar, hata tetikleyen işleyicinin yapılan değişikliklerini yok sayarak yapılandırılabilir. Bu, subgraph yazarlarının subgraphlarını düzeltmeleri için zaman kazandırırken, sorguların en son blokta sunulmaya devam etmesini sağlar, ancak hata nedeniyle sonuçlar tutarsız olabilir. Bazı hatalar hala her zaman ölümcül olacaktır. Ölümcül olmaması için hatanın belirlenmiş olması gerekmektedir.

Ölümcül olmayan hataların etkinleştirilmesi, subgraph manifestinde aşağıdaki özellik bayrağının ayarlanmasını gerektirir:

specVersion: 0.0.4
description: Gravatar for Ethereum
features:
    - nonFatalErrors
    ...

The query must also opt-in to querying data with potential inconsistencies through the subgraphError argument. It is also recommended to query _meta to check if the subgraph has skipped over errors, as in the example:

foos(first: 100, subgraphError: allow) {
  id
}

_meta {
  hasIndexingErrors
}

If the subgraph encounters an error, that query will return both the data and a graphql error with the message "indexing_error", as in this example response:

"data": {
    "foos": [
        {
          "id": "0xdead"
        }
    ],
    "_meta": {
        "hasIndexingErrors": true
    }
},
"errors": [
    {
        "message": "indexing_error"
    }
]

Dosya veri kaynakları, indeksleme sırasında zincir dışı verilere sağlam ve genişletilebilir bir şekilde erişmek için yeni bir subgraph fonksiyonudur. Dosya veri kaynakları IPFS'den ve Arweave'den dosya getirmeyi desteklemektedir.

İşleyici yürütülürken dosyaları “sıra sıra” almak yerine, Dosya Veri Kaynakları, belirli bir dosya kimliği için yeni veri kaynakları olarak kullanılabilecek şablonlar sunar. Bu yeni veri kaynakları dosyaları getirir. Başarısız olurlarsa yeniden denerler ve dosya bulunduğunda bu işe mahsus bir işleyici çalıştırırlar.

This is similar to the existing data source templates, which are used to dynamically create new chain-based data sources.

File data sources requires graph-ts >=0.29.0 and graph-cli >=0.33.1

Dosya veri kaynakları zincir tabanlı varlıklara erişemez veya bunları güncelleyemez, ancak dosya belirli varlıkları güncellemelidir.

Bu, mevcut varlıklardaki alanları ayrı varlıklara bölmeyi gerektirebilir ve bunlar birbirine bağlanabilir.

Özgün birleştirilmiş varlık:

type Token @entity {
  id: ID!
  tokenID: BigInt!
  tokenURI: String!
  externalURL: String!
  ipfsURI: String!
  image: String!
  name: String!
  description: String!
  type: String!
  updatedAtTimestamp: BigInt
  owner: User!
}

Yeni, ayrılmış varlık:

type Token @entity {
  id: ID!
  tokenID: BigInt!
  tokenURI: String!
  ipfsURI: TokenMetadata
  updatedAtTimestamp: BigInt
  owner: String!
}

type TokenMetadata @entity {
  id: ID!
  image: String!
  externalURL: String!
  name: String!
  description: String!
}

Ana varlık ve sonuç dosya veri kaynak varlığı arasındaki ilişki bire bir ise, en basit kalıp, IPFS CID'yi arama anahtarı olarak kullanarak ana varlığını sonuç dosya varlığına bağlamaktır. Yeni dosya tabanlı varlıklarınızın modellemesiyle ilgili sorun yaşarsanız Discord üzerinden iletişime geçin!

Bu, ilgi alanı dosyası tespit edildiğinde oluşturulacak veri kaynağıdır.

templates:
  - name: TokenMetadata
    kind: file/ipfs
    mapping:
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      file: ./src/mapping.ts
      handler: handleMetadata
      entities:
        - TokenMetadata
      abis:
        - name: Token
          file: ./abis/Token.json

The file data source must specifically mention all the entity types which it will interact with under entities. See limitations for more details.

This handler should accept one Bytes parameter, which will be the contents of the file, when it is found, which can then be processed. This will often be a JSON file, which can be processed with graph-ts helpers (documentation).

The CID of the file as a readable string can be accessed via the dataSource as follows:

const cid = dataSource.stringParam()

Örnek işleyici:

import { json, Bytes, dataSource } from '@graphprotocol/graph-ts'
import { TokenMetadata } from '../generated/schema'

export function handleMetadata(content: Bytes): void {
  let tokenMetadata = new TokenMetadata(dataSource.stringParam())
  const value = json.fromBytes(content).toObject()
  if (value) {
    const image = value.get('image')
    const name = value.get('name')
    const description = value.get('description')
    const externalURL = value.get('external_url')

    if (name && image && description && externalURL) {
      tokenMetadata.name = name.toString()
      tokenMetadata.image = image.toString()
      tokenMetadata.externalURL = externalURL.toString()
      tokenMetadata.description = description.toString()
    }

    tokenMetadata.save()
  }
}

Artık zincir tabanlı işleyicilerin yürütülmesi sırasında dosya veri kaynakları oluşturabilirsiniz:

• Import the template from the auto-generated templates
• call TemplateName.create(cid: string) from within a mapping, where the cid is a valid content identifier for IPFS or Arweave

For IPFS, Graph Node supports v0 and v1 content identifiers, and content identifers with directories (e.g. bafyreighykzv2we26wfrbzkcdw37sbrby4upq7ae3aqobbq7i4er3tnxci/metadata.json).

For Arweave, as of version 0.33.0 Graph Node can fetch files stored on Arweave based on their transaction ID from an Arweave gateway (example file). Arweave supports transactions uploaded via Irys (previously Bundlr), and Graph Node can also fetch files based on Irys manifests.

Örnek:

import { TokenMetadata as TokenMetadataTemplate } from '../generated/templates'

const ipfshash = 'QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm'
//Bu örnek kod, bir Crypto coven subgraph'ı içindir. Yukarıdaki ipfs hash'ı, tüm kripto NFT'leri için token üst verilerine sahip bir dizindir.

export function handleTransfer(event: TransferEvent): void {
  let token = Token.load(event.params.tokenId.toString())
  if (!token) {
    token = new Token(event.params.tokenId.toString())
    token.tokenID = event.params.tokenId

    token.tokenURI = '/' + event.params.tokenId.toString() + '.json'
    const tokenIpfsHash = ipfshash + token.tokenURI
    //Bu, tek bir Crypto coven NFT için üst verilere giden bir yol oluşturur. Dizini "/" + dosya adı + ".json" ile birleştirir.

    token.ipfsURI = tokenIpfsHash

    TokenMetadataTemplate.create(tokenIpfsHash)
  }

  token.updatedAtTimestamp = event.block.timestamp
  token.owner = event.params.to.toHexString()
  token.save()
}

Bu, Graph Düğümü'nün yapılandırılmış IPFS veya Arweave uç noktasını sorgulayacak yeni bir veri kaynağı dosyası oluşturacak ve bulunamazsa yeniden deneyecek. Dosya bulunduğunda, dosya veri kaynağı işleyicisi çalıştırılacaktır.

This example is using the CID as the lookup between the parent Token entity and the resulting TokenMetadata entity.

Tebrikler, dosya veri kaynaklarını kullanıyorsunuz!

You can now build and deploy your subgraph to any Graph Node >=v0.30.0-rc.0.

Dosya veri kaynağı işleyicileri ve varlıkları yürütüldüklerinde belirleyici olmaları ve zincir tabanlı veri kaynaklarının bozulmasını önlemeleri için, diğer subgraph varlıklarından izole edilir,. Açıkça şunlardır:

• Dosya Veri Kaynakları tarafından oluşturulan varlıklar değiştirilemez ve güncellenemez
• Dosya Veri Kaynağı işleyicileri, diğer dosya veri kaynaklarından varlıklara erişemez
• Dosya Veri Kaynaklarıyla ilişkili varlıklara zincir tabanlı işleyicilerden erişilemez

Ek olarak, zincir üstü bir veri kaynağı veya başka bir dosya veri kaynağı olsun, bir dosya veri kaynağından veri kaynakları oluşturmak mümkün değildir. Bu kısıtlama gelecekte kaldırılabilir.

NFT meta verilerini ilgili tokenleri bağlarken, Üst veri varlığına Token varlığından başvurmak için üst verinin IPFS hash değerini kullanın. Üst veri varlığını IPFS hash değerini bir kimlik olarak kullanarak kaydedin.

You can use DataSource context when creating File Data Sources to pass extra information which will be available to the File Data Source handler.

If you have entities which are refreshed multiple times, create unique file-based entities using the IPFS hash & the entity ID, and reference them using a derived field in the chain-based entity.

File data sources currently require ABIs, even though ABIs are not used (issue). Workaround is to add any ABI.

Handlers for File Data Sources cannot be in files which import eth_call contract bindings, failing with "unknown import: ethereum::ethereum.call has not been defined" (issue). Workaround is to create file data source handlers in a dedicated file.

Crypto Coven Subgraph migration

GIP File Data Sources

Konu filtreleri veya endekslenmiş argüman filtreleri olarak da bilinen bu özellik, subgraph'lerin endekslenmiş argümanlarının değerlerine göre blok zinciri olaylarını hassas bir şekilde filtrelemesine olanak tanır.

• Bu filtreler, blokzincirindeki büyük olay akışından ilgilenilen belirli olayları izole etmeye yardımcı olarak, subgraph'lerin yalnızca alakalı verilere odaklanmasını ve böylece daha verimli çalışmasını sağlar.

• Bu özellik, belirli adresleri ve bunların blokzincirindeki çeşitli akıllı sözleşmelerle olan etkileşimlerini izleyen kişisel subgraph'ler oluşturmak için faydalıdır.

Bir akıllı sözleşme olay yaydığında, endekslenmiş olarak işaretlenen tüm argümanlar bir subgraph'in manifestosunda filtre olarak kullanılabilir. Bu durum, subgraph'in yalnızca ilgili endekslenmiş argümanlara uyan olayları dinleyip diğerlerini görmezden gelmesini sağlar.

• The event's first indexed argument corresponds to topic1, the second to topic2, and so on, up to topic3, since the Ethereum Virtual Machine (EVM) allows up to three indexed arguments per event.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Token {
    // Adresler için endekslenmiş parametreleriyle birlikte olay bildirimi
    event Transfer(address indexed from, address indexed to, uint256 value);

    // Token transferini simüle eden fonksiyon
    function transfer(address to, uint256 value) public {
        // Transfer olayını from, to ve value ile yayma
        emit Transfer(msg.sender, to, value);
    }
}

Bu örnekte:

• The Transfer event is used to log transactions of tokens between addresses.
• The from and to parameters are indexed, allowing event listeners to filter and monitor transfers involving specific addresses.
• The transfer function is a simple representation of a token transfer action, emitting the Transfer event whenever it is called.

Konu filtreleri, subgraph manifestosunda doğrudan olay işleyici yapılandırması içinde tanımlanır. Yapılandırma örneği:

eventHandlers:
  - event: SomeEvent(indexed uint256, indexed address, indexed uint256)
    handler: handleSomeEvent
    topic1: ['0xValue1', '0xValue2']
    topic2: ['0xAddress1', '0xAddress2']
    topic3: ['0xValue3']

Bu bağlamda:

• topic1 corresponds to the first indexed argument of the event, topic2 to the second, and topic3 to the third.
• Her konu (topic) bir veya daha fazla değere sahip olabilir ve bir olay yalnızca karşılık geldiği konudaki değerlerden biriyle eşleşiyorsa işlenir.

• Tek Bir Konu İçinde: VEYA koşulu olarak çalışır. Olay, verilen konunun listesindeki herhangi bir değerle eşleşirse işlenecektir.
• Farklı Konular Arasında: VE koşulu olarak çalışır. Bir olayın ilgili işleyiciyi tetiklemesi için farklı konular arasındaki belirlenmiş tüm koşulları karşılaması gerekir.

eventHandlers:
  - event: Transfer(indexed address,indexed address,uint256)
    handler: handleDirectedTransfer
    topic1: ['0xAddressA'] # Sender Address
    topic2: ['0xAddressB'] # Receiver Address

Bu konfigürasyonda:

• topic1 is configured to filter Transfer events where 0xAddressA is the sender.
• topic2 is configured to filter Transfer events where 0xAddressB is the receiver.
• The subgraph will only index transactions that occur directly from 0xAddressA to 0xAddressB.

eventHandlers:
  - event: Transfer(indexed address,indexed address,uint256)
    handler: handleTransferToOrFrom
    topic1: ['0xAddressA', '0xAddressB', '0xAddressC'] # Sender Address
    topic2: ['0xAddressB', '0xAddressC'] # Receiver Address

Bu konfigürasyonda:

• topic1 is configured to filter Transfer events where 0xAddressA, 0xAddressB, 0xAddressC is the sender.
• topic2 is configured to filter Transfer events where 0xAddressB and 0xAddressC is the receiver.
• Subgraph, birden fazla adres arasında her iki yönde gerçekleşen işlemleri endeksleyerek tüm adresleri içeren etkileşimlerin kapsamlı bir şekilde izlenmesini sağlar.

Declarative eth_calls are a valuable subgraph feature that allows eth_calls to be executed ahead of time, enabling graph-node to execute them in parallel.

Bu özellik:

• Ethereum blokzincirinden veri getirme performansını önemli ölçüde artırır. Bunu birden fazla çağrı için toplam süreyi azaltarak ve subgraph'in genel verimliliğini optimize ederek yapar.
• Daha hızlı veri çekmeye olanak tanıyarak, daha hızlı sorgu yanıtları alınmasını ve daha iyi bir kullanıcı deneyimi sağlar.
• Birden fazla Ethereum çağrısından veri toplaması gereken uygulamalar için bekleme sürelerini azaltarak veri çekme sürecini daha verimli hale getirir.

• Declarative eth_calls: Ethereum calls that are defined to be executed in parallel rather than sequentially.
• Paralel Yürütme: Bir çağrıyı başlatmak için diğerinin bitmesini beklemek yerine, birden fazla çağrı aynı anda başlatılabilir.
• Zaman Verimliliği: Tüm çağrılar için geçen toplam süre, bireysel çağrı sürelerinin toplamından (işlemler ardışık yapıldığında), en uzun çağrının süresine dönüşür (işlemler paralel yapıldığında).

Bir kullanıcının işlemleri, bakiyesi ve token varlıkları hakkında veri almak için üç Ethereum çağrısı yapması gereken bir subgraph'iniz olduğunu düşünün.

Geleneksel olarak, bu çağrılar ardışık olarak yapılabilir:

1. Çağrı 1 (İşlem geçmişi): 3 saniye sürer
2. Çağrı 2 (Bakiye): 2 saniye sürer
3. Çağrı 3 (Token varlıkları): 4 saniye sürer

Toplam geçen süre = 3 + 2 + 4 = 9 saniye

Bu özellik sayesinde bu çağrıların paralel olarak gerçekleştirileceğini belirtebilirsiniz:

1. Çağrı 1 (İşlem geçmişi): 3 saniye sürer
2. Çağrı 2 (Bakiye): 2 saniye sürer
3. Çağrı 3 (Token varlıkları): 4 saniye sürer

Bu çağrılar paralel olarak yürütüldüğünden, toplam süre en uzun süren çağrının süresine eşittir.

Toplam süre = max (3, 2, 4) = 4 saniye

1. Bildirimsel Tanım: Subgraph manifestosunda, Ethereum çağrılarını paralel olarak çalıştırılabilecek şekilde tanımlarsınız.
2. Paralel Çalıştırma Motoru: Graph Düğümü'nün yürütme motoru bu bildirimleri tanır ve çağrıları aynı anda çalıştırır.
3. Sonuçların Birleştirilmesi: Tüm çağrılar tamamlandığında, sonuçlar birleştirilir ve sonraki işlemler için subgraph tarafından kullanılır.

Declared eth_calls can access the event.address of the underlying event as well as all the event.params.

Subgraph.yaml using event.address:

eventHandlers:
event: Swap(indexed address,indexed address,int256,int256,uint160,uint128,int24)
handler: handleSwap
calls:
  global0X128: Pool[event.address].feeGrowthGlobal0X128()
  global1X128: Pool[event.address].feeGrowthGlobal1X128()

Yukarıdaki örnek için detaylar:

• global0X128 is the declared eth_call.
• The text (global0X128) is the label for this eth_call which is used when logging errors.
• The text (Pool[event.address].feeGrowthGlobal0X128()) is the actual eth_call that will be executed, which is in the form of Contract[address].function(arguments)
• The address and arguments can be replaced with variables that will be available when the handler is executed.

Subgraph.yaml using event.params

calls:
  - ERC20DecimalsToken0: ERC20[event.params.token0].decimals()

When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the startBlock defined with each data source) In some circumstances; it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called Grafting. Grafting is, for example, useful during development to get past simple errors in the mappings quickly or to temporarily get an existing subgraph working again after it has failed.

A subgraph is grafted onto a base subgraph when the subgraph manifest in subgraph.yaml contains a graft block at the top-level:

description: ...
graft:
  base: Qm... # Subgraph ID of base subgraph
  block: 7345624 # Block number

When a subgraph whose manifest contains a graft block is deployed, Graph Node will copy the data of the base subgraph up to and including the given block and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph.

Graftlama, temel verileri indekslemek yerine kopyaladığından, subgraph'ı istenen bloğa getirmek sıfırdan indekslemeye nazaran çok daha hızlıdır, ancak ilk veri kopyası çok büyük subgraphlar için yine birkaç saat sürebilir. Graftlanmış subgraph başlatılırken, Graph Düğümü halihazırda kopyalanmış olan varlık türleri hakkında bilgileri kaydedecektir.

Graftlanan subgraph, temel subgraphla tamamen aynı olmayan, ancak onunla uyumlu olan bir GraphQL şeması kullanabilir. Kendi başına geçerli bir subgraph şeması olmalıdır, ancak şu şekillerde temel subgraph şemasından sapabilir:

• Varlık türlerini ekler veya kaldırır
• Varlık türlerinden öznitelikleri kaldırır
• Varlık türlerine null yapılabilir öznitelikler ekler
• Null yapılamayan öznitelikleri null yapılabilir özniteliklere dönüştürür
• Numaralandırmalara değerler ekler
• Arayüzleri ekler veya kaldırır
• Arayüzün hangi varlık türleri için uygulandığını değiştirir