The Graph 입문 가이드 (3)

Published in

Boom💥Labs — The open basecamp for Web3 Builders.

9 min readAug 28, 2022

Boom Labs는 Web 3 개발자들을 온보딩시키고, 생태계를 활성화시키기 위해 교육을 비롯한 여러 활동들을 하고 있습니다. 저희 비전에 공감하여 동참하고자 하는 분들은 Boom Labs의 문을 두드려주세요!

Disclaimer: 이 글은 정보 전달을 위한 목적으로 작성되었으며, 특정 프로젝트에 대한 투자 권고, 법률적 자문 등 목적으로 하지 않습니다. 모든 투자의 책임은 개인에게 있으며, 이로 발생된 결과에 대해 어떤 부분에서도 Boom Labs는 책임을 지지 않습니다. 본문이 포괄하는 내용들은 특정 자산에 대한 투자를 추천하는 것이 아니며, 언제나 본문의 내용만을 통한 의사결정은 지양하시길 바랍니다.

TL;DR : Subgraph 쿼리는 graphQL을 활용해서 제작합니다. theGraph 플레이그라운드 뿐만 아니라 graphQL 클라이언트 라이브러리를 사용해 프론트나 백엔드 환경에서 subgraph 쿼리를 할 수 있습니다.

subgraph 쿼리하기

이전 글에서 얘기한 것처럼 subgraph 쿼리는 graphQL을 사용해 요청합니다.

그러므로 먼저 graphQL 쿼리를 어떻게 작성하면 될지 살펴보겠습니다.

쿼리 정의

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

query : graphQL 요청 타입
operationName : 해당 쿼리 요청을 보낼 이름
([variableName]: [variableType]) : 해당 쿼리에서 필터링을 위해 사용될 변수 이름과 타입
queryName : entity 이름(이전에 작성한 graphQL 스키마 타입 이름) + s 를 붙여 정의
([argumentName]: [variableName] : 오더, 필터링을 위해 정의

쿼리 예시

token entity라는 entity가 정의되었고, entity 1개를 요청할 때

entity 1개를 요청할때는 무조건 id 필드가 필요

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

2. entity 여러개를 요청할 때

query {
  tokens(first: 100) {
    id
    owner
  }
}

3. attribute로 정렬을 하고싶을 때

orderBy, orderDirection 사용

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

4. pagination을 하고싶을 때

skip 파라미터를 사용하면 11번째 데이터부터 쿼리가 가능.

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

5. 필터링을 하고싶을때

where 파라미터를 사용
outcome 이라는 필드의 값이 failed 인 데이터만 쿼리

query {
  challenges(first: 100, where: {outcome: "failed"}) {
    challenger
    outcome
    application(first: 100) {
      id
    }
  }
}

이외에도 gt, lte 등 다양한 필터가 있습니다. 더 많은 필터는 링크를 참고하세요.

스키마

graphql 요청은 query, subscription, mutation 이 있지만 더 그래프에서 쓸 때는 query 를 가장 많이 사용합니다. (mutation 은 데이터를 변경할때 사용하기 때문에 데이터 읽기만 하는 the Graph 에선 사용하지 않습니다.)
the Graph 에서는 기본 graphql 타입을 사용할뿐만 아니라 블록체인에서 쓰는 데이터 타입을 같이 사용합니다.
Int, Float, String, Boolean, ID , Bytes,BigInt, enums 등을 지원합니다.
타입에 관해 더 알고싶다면 GraphQL documentation 를 참고하면 좋을 것 같습니다.

graphQL 클라이언트

2편의 마지막에서 얘기한 것처럼 theGraph 플레이그라운드에서 쿼리를 할 수 있습니다만, 실제 서비스에서 플레이그라운드를 이용해 쿼리하는 것은 적합하지 않습니다.

그래서 보통은 graphql 클라이언트를 이용해서 쿼리를 요청하는데요. 일반 graphQL 클라이언트를 사용하여 쿼리를 요청하면 됩니다.

graphQL 클라이언트는 아래와 같은 종류가 있습니다.

참고 : the Graph용 graphql 클라이언트 graph-client도 있습니다. Cross-chain Subgraph Handling, Automatic block tracking 등 the Graph 특화 기능이 존재하기 때문에 유용합니다. graph-client는 별도의 글로 한번 더 다뤄보겠습니다.

이 글에선 graphql-request 클라이언트를 사용해보겠습니다.(해당 라이브러리가 가볍게 쓰기 좋아서 선택했습니다.)

클라이언트 예제 코드는 아래와 같습니다.

const {gql, request, GraphQLClient } = require("graphql-request");
const endpoint = 'https://api.thegraph.com/subgraphs/name/{id}/{subgraph_name}';
const client = new GraphQLClient(endpoint, { headers: {} });
let variables = {};
let query;query = gql`
    query manyDatas($lastTS: BigInt) {
        datas(first: 5, orderBy: blockTimeStamp, orderDirection: desc, where: { blockTimeStamp_gt: $lastTS }) {
                id
                tokenAddress
                creator
                blockTimeStamp
            }   
        }
    `;
variables = { 
    "lastTS": lastTimeStampForGraphQuery 
};return await client.request(query, variables);

응용 쿼리

the Graph 공식 문서에는 the Graph 쿼리를 더 잘 쓰는 법이 나와있는데요.

특정 block을 필터링 할 수도 있으며, 과거의 특정 블록 시점만 쿼리를 한다거나, 문자열로 검색을 요청할 수도 있습니다.

응용 쿼리를 작성해보고 싶다면, 아래의 문서들을 참고하시면 좋을 것 같습니다.

타입스크립트 지원

타입스크립트 환경에서 쿼리를 요청할때 필요한 서브그래프의 타입이 필요할 때가 있습니다.

theGraph는 typescript를 지원하므로 아래와 같은 방법으로 type code를 만들 수 있는데요.

import { execute } from 'your-favorite-graphql-client'
import { GetTokenQuery } from './generated.'const id = params.id
const query = `
query GetToken($id: ID!) {
  token(id: $id) {
    id
    owner
  }
}
`const result: GetTokenQuery = await execute(query, {
  variables: {
    id,
  },
})// `result` is typed!

타입을 만들기 위해선 Graphql code generator가 필요합니다.

아래의 패키지들을 설치합니다.

yarn add graphql @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations

2. package.json 의 스크립트를 변경합니다.

{
  // ...
  "scripts": {
    // ...
    "generate": "graphql-codegen",
    // ...
  }
  // ...
}

3. 프로젝트 홈 디렉토리에 codegen.yaml 파일을 생성

schema: <http://my-graphql-api.com/graphql> => 사용하고자 하는 subgraph API 엔드포인트
documents: './src/**/*.ts' => gql 태그가 존재하는 파일을 찾는 범위 
generates:
  graphql/generated.ts:
    plugins:
      - typescript
      - typescript-operations

4.yarn generate 로 generated 폴더 생성

5. 생성된 타입을 import 하여 사용

type generation : https://thegraph.com/docs/en/querying/querying-best-practices/#type-script-types-generation
codegen.yml 참고 : https://www.graphql-code-generator.com/docs/config-reference/codegen-config

글을 마치며

이번 글에서는 서브그래프 쿼리 작성법, 쿼리 요청에 대해 알아보았습니다.
총 세 편의 글로 the Graph 입문을 다뤄봤는데, 이 글들을 통해 the Graph 사용법을 익혀 독자분들이 블록체인 데이터를 더욱 잘 활용하시면 좋겠습니다.
추후에 the Graph client 사용법, 응용 쿼리 등 the Graph 중급 가이드 글로 찾아뵙겠습니다.