クエリ > クエリのベストプラクティス

クエリのベストプラクティス

Reading time: 16 min

The Graphは、ブロックチェーンのデータをクエリするための分散化された方法を提供します。

The GraphのネットワークのデータはGraphQL APIで公開され、GraphQL言語によるデータクエリーが容易になります。

このページでは、GraphQLの言語ルールとGraphQLクエリのベストプラクティスに必要不可欠な情報をご案内しています。

GraphQL APIのクエリ

⁠このセクションへのリンク

GraphQLクエリの構造

⁠このセクションへのリンク

REST APIとは異なり、GraphQL APIは実行可能なクエリを定義するSchemaをベースに構築されています。

例えば、tokenクエリを使ってトークンを取得するクエリは次のようになります。

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

以下のような予測可能なJSONレスポンスが返ってきます（適切な$id変数値を渡す場合）。

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

GraphQLクエリは、仕様で定義されているGraphQL言語を使用します。

上記の GetToken クエリは、複数の言語部分で構成されています (以下では [...] プレースホルダーに置き換えられています)。

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

構文の「やるべきこと」「やってはいけないこと」を挙げればきりがありませんが、ここではGraphQLクエリを書く際に覚えておきたい基本的なルールを紹介します：

各queryNameは、1回の操作で1回だけ使用しなければなりません。
各フィールドは、選択の中で一度だけ使用しなければなりません(トークンの下にidを二度照会することはできません)。
Some fields or queries (like tokens) return complex types that require a selection of sub-field. Not providing a selection when expected (or providing one when not expected - for example, on id) will raise an error. To know a field type, please refer to Graph Explorer.
引数に代入される変数は、その型と一致しなければなりません。
与えられた変数のリストにおいて、各変数は一意でなければなりません。
定義された変数はすべて使用する必要があります。

上記のルールに従わない場合、Graph APIからエラーが発生します。

For a complete list of rules with code examples, please look at our GraphQL Validations guide.

GraphQL APIへのクエリの送信

⁠このセクションへのリンク

GraphQLは、HTTPを介して転送される言語と一連の規約です。

これは、標準のfetch（ネイティブであれば、@whatwg-node/fetchやisomorphic-fetchを介しても）を使用して、GraphQL APIにクエリを送信できることを意味します。

ただし、「アプリケーションからのクエリ」で述べたように、以下のような固有の機能をサポートするgraph-clientを使用することをおすすめします。

クロスチェーンのサブグラフ処理：1回のクエリで複数のサブグラフからクエリを実行可能
自動ブロック追跡
自動ページング
完全なタイプ付け結果

graph-client を使用してグラフをクエリする方法は次のとおりです。

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()

その他の GraphQL クライアントの代替手段については、「アプリケーションからのクエリ」で説明します。

GraphQL クエリ構文の基本ルールを説明したので、今度は GraphQL クエリ記述のベストプラクティスを見てみましょう。

ベストプラクティス

⁠このセクションへのリンク

常に静的なクエリを記述

⁠このセクションへのリンク

一般的な (悪い) プラクティスは、次のようにクエリ文字列を動的に構築することです。

const id = params.id
const fields = ['id', 'owner']
const query = `
query GetToken {
  token(id: ${id}) {
    ${fields.join('\n')}
  }
}
`

// Execute query...

上記のスニペットは有効な GraphQL クエリを生成しますが、多くの欠点があります。

クエリ全体を理解するのが難しくなります。
開発者は、文字列補間を安全にサニタイズする責任があるということです。
リクエストパラメータの一部として変数の値を送信しないでください。サーバー側でのキャッシュの可能性を防止
それは ** ツールがクエリを静的に分析するのを防ぐ** (例: Linter、またはタイプ生成ツール) です。

このため、クエリは常に静的文字列として記述することをお勧めします:

import { execute } from 'your-favorite-graphql-client'

const id = params.id
const query = `
query GetToken($id: ID!) {
  token(id: $id) {
    id
    owner
  }
}
`

const result = await execute(query, {
  variables: {
    id,
  },
})

そうすることで多くのメリットがもたらされます:

読みやすく、メンテナンスしやすいクエリ
GraphQLのサーバーは、変数のサニタイズを処理します
サーバーレベルで変数がキャッシュできます。
ツールでクエリを静的に分析できる（これについては、次のセクションで詳しく説明します。）

注: 静的クエリに条件付きでフィールドを含める方法

特定の条件でのみ owner フィールドを含めることができます。

このために、次のように @include(if:...) ディレクティブを利用できます:

import { execute } from 'your-favorite-graphql-client'

const id = params.id
const query = `
query GetToken($id: ID!, $includeOwner: Boolean) {
  token(id: $id) {
    id
    owner @include(if: $includeOwner)
  }
}
`

const result = await execute(query, {
  variables: {
    id,
    includeOwner: true,
  },
})

注: 反対のディレクティブは @skip(if: ...) です。

Ask for what you want

⁠このセクションへのリンク

GraphQL は、「欲しいものを聞いてください」というキャッチフレーズで有名になりました。

このため、GraphQLでは、個々にリストすることなくすべての利用可能なフィールドを取得する方法はありません。

GraphQL APIをクエリする際には、実際に使用するフィールドのみをクエリするように常に考えてください。

過剰なデータ取得の一般的な原因は、エンティティのコレクションです。デフォルトでは、クエリはコレクション内のエンティティを100個取得しますが、通常、実際に使用される量（たとえば、ユーザーに表示される量）よりもはるかに多いです。そのため、クエリはほぼ常にfirstを明示的に設定し、実際に必要なだけのエンティティを取得するようにする必要があります。これは、クエリ内のトップレベルのコレクションだけでなく、さらにエンティティのネストされたコレクションにも当てはまります。

たとえば、次のクエリでは:

query listTokens {
  tokens {
    # will fetch up to 100 tokens
    id
    transactions {
      # will fetch up to 100 transactions
      id
    }
  }
}

応答には、100 個のトークンごとに 100 個のトランザクションが含まれる可能性があります。

アプリケーションが 10 トランザクションのみを必要とする場合、クエリではトランザクションフィールドに first: 10 を明示的に設定する必要があります。

Use a single query to request multiple records

⁠このセクションへのリンク

By default, subgraphs have a singular entity for one record. For multiple records, use the plural entities and filter: where: {id_in:[X,Y,Z]} or where: {volume_gt:100000}

Example of inefficient querying:

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

Example of optimized querying:

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

Combine multiple queries in a single request

⁠このセクションへのリンク

アプリケーションでは、次のように複数の種類のデータをクエリする必要がある場合があります:

import { execute } from "your-favorite-graphql-client"

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)
)

この実装は完全に有効ですが、GraphQL API を使用した 2 つの往復が必要になります。

幸いなことに、次のように同じ GraphQL リクエストで複数のクエリを送信することも有効です:

import { execute } from "your-favorite-graphql-client"

const query = `
query GetTokensandCounters {
  tokens(first: 50) {
    id
    owner
  }
  counters {
    id
    value
  }
}
`

このアプローチは、ネットワークに費やす時間を減少させる（APIへの往復を省略する）ため、全体的なパフォーマンスを向上させます。また、より簡潔な実装を提供します。

GraphQLフラグメントの活用

⁠このセクションへのリンク

GraphQL クエリを作成するのに役立つ機能は、GraphQL Fragment です。

次のクエリを見ると、いくつかのフィールドが複数のSelection-Sets（{ ... }）で繰り返されていることがわかります：

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

このような繰り返しフィールド (id、active、status) は、多くの問題を引き起こします。

より広範囲なクエリに対応するために読みにくくなります
クエリに基づいて TypeScript 型を生成するツールを使用する場合 (前のセクションで詳しく説明します)、newDelegate および oldDelegate は、2 つの異なるインラインインターフェイスになります。

クエリのリファクタリングされたバージョンは次のようになります:

query {
  bondEvents {
    id
    newDelegate {
      ...DelegateItem
    }
    oldDelegate {
      ...DelegateItem
    }
  }
}

# we define a fragment (subtype) on Transcoder
# to factorize repeated fields in the query
fragment DelegateItem on Transcoder {
  id
  active
  status
}

GraphQLのfragmentを使用すると、可読性が向上します（特に大規模な場合）し、さらにはより良いTypeScriptの型生成にも結びつきます。

型生成ツールを使用すると、上記のクエリは適切なDelegateItemFragment型を生成します（最後の「ツール」セクションを参照）。

GraphQLフラグメントの注意点

⁠このセクションへのリンク

フラグメントベースは型である必要があります

フラグメントは、適用できない型、つまりフィールドを持たない型に基づくことはできません。

fragment MyFragment on BigInt {
  # ...
}

BigInt はスカラー (ネイティブの「プレーン」タイプ) であり、フラグメントのベースとして使用できません。

フラグメントを拡散する方法

フラグメントは特定のタイプに定義されているため、クエリではそれに応じて使用する必要があります。

例：

query {
  bondEvents {
    id
    newDelegate {
      ...VoteItem # Error! `VoteItem` cannot be spread on `Transcoder` type
    }
    oldDelegate {
      ...VoteItem
    }
  }
}

fragment VoteItem on Vote {
  id
  voter
}

newDelegate と oldDelegate のタイプは Transcoder です。

ここでタイプ Vote のフラグメントを拡散することはできません。

フラグメントをデータのアトミックなビジネス単位として定義する

GraphQL フラグメントは、その使用法に基づいて定義する必要があります。

ほとんどのユースケースでは、1つのタイプに対して1つのフラグメントを定義すること（繰り返しフィールドの使用または型生成の場合）で十分です。

Fragment を使用する場合の経験則は次のとおりです:

同じ型のフィールドがクエリ内で繰り返される場合、それらをFragmentでグループ化します。
同じフィールドが繰り返される場合、複数のフラグメントを作成します。

# base fragment (mostly used in listing)
fragment Voter on Vote {
  id
  voter
}

# extended fragment (when querying a detailed view of a vote)
fragment VoteWithPoll on Vote {
  id
  voter
  choiceID
  poll {
    id
    proposal
  }
}

必須ツール

⁠このセクションへのリンク

GraphQL ウェブベースのエクスプローラ

⁠このセクションへのリンク

Iterating over queries by running them in your application can be cumbersome. For this reason, don't hesitate to use Graph Explorer to test your queries before adding them to your application. Graph Explorer will provide you a preconfigured GraphQL playground to test your queries.

If you are looking for a more flexible way to debug/test your queries, other similar web-based tools are available such as Altair and GraphiQL.

GraphQL Linting

⁠このセクションへのリンク

上記で述べたベストプラクティスと構文ルールに従うためには、以下のワークフローとIDEツールを使用することを強くお勧めします。

GraphQL ESLint

GraphQL ESLint will help you stay on top of GraphQL best practices with zero effort.

Setup the "operations-recommended" config will enforce essential rules such as:

@graphql-eslint/fields-on-correct-type: フィールドは適切なタイプで使用されているか？
@graphql-eslint/no-unused variables: 与えられた変数は未使用のままであるべきか？
ともっと

これにより、プレイグラウンドでクエリをテストしたり、本番環境で実行したりせずにエラーをキャッチできる ようになります。

IDE plugins

⁠このセクションへのリンク

VSCodeとGraphQL

The GraphQL VSCode Extension is a great addition to your development workflow, allowing you to:

構文の強調表示
オートコンプリートの提案
スキーマに対する検証
snippets
フラグメントと入力タイプの定義に移動

graphql-eslintを使用している場合、ESLint VSCode拡張機能はエラーや警告を正しくコード内に表示するために必須です。

WebStorm/Intellij および GraphQL

JS GraphQLプラグインは、以下を提供することで、GraphQLを使用する際のエクスペリエンスを大幅に向上させます。

構文の強調表示
オートコンプリートの提案
スキーマに対する検証
snippets

詳細は、このWebStorm の記事で、プラグインの主な機能をすべて紹介しています。