GraphQL API

Reading time: 17 min

This guide explains the GraphQL Query API that is used for The Graph Protocol.

サブグラフのスキーマには、Entitiesと呼ばれるタイプが定義されています。各Entityタイプには、トップレベルのQueryタイプにentityとentitiesフィールドが生成されます。なお、The Graph を使用する際には、graphqlのquery の先頭にクエリを含める必要はありません。

スキーマで定義された 1 つのTokenエンティティに対するクエリ:

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

すべての Token エンティティをクエリします。

{
  tokens {
    id
    owner
  }
}

コレクションをクエリする場合、orderBy パラメータを使用して特定の属性で並べ替えることができます。さらに、orderDirection を使用してソート方向を指定できます。昇順の場合は asc、降順の場合は desc です。

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

グラフ ノード v0.30.0 の時点で、エンティティを並べ替えることができますネストされたエンティティに基づいています。

次の例では、所有者の名前でトークンを並べ替えます。

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

コレクションをクエリする場合、first パラメータを使用して、コレクションの先頭から改ページすることができます。デフォルトのソート順は、作成時間順ではなく、英数字の昇順の ID 順であることに注意してください。

さらに、 skip パラメーターを使用してエンティティをスキップし、ページ分割することができます。例えばfirst:100 は最初の 100 個のエンティティを示し、first:100, skip:100 は次の 100 個のエンティティを示します。

クエリは一般にパフォーマンスが低いため、非常に大きな skip 値を使用しないでください。多数のアイテムを取得するには、最後の例で示したように、属性に基づいてエンティティをページングする方がはるかに優れています。

最初の 10 個のトークンを照会します。

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

コレクションの途中にあるエンティティのグループをクエリするには、skip パラメータを first パラメータと組み合わせて使用​​して、最初から指定された数のエンティティをスキップできます。コレクションの。

コレクションの先頭から 10 桁ずれた 10 個の Token エンティティをクエリします。

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

クライアントが多数のエンティティを取得する必要がある場合は、属性に基づいてクエリを実行し、その属性でフィルター処理する方がはるかに効率的です。たとえば、クライアントは次のクエリを使用して多数のトークンを取得します。

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

初めて、lastID = "" でクエリを送信し、後続のリクエストでは lastID を最後の id 属性に設定します。前のリクエストのエンティティ。このアプローチは、skip 値を増やして使用するよりもはるかに優れたパフォーマンスを発揮します。

クエリで where パラメータを使用して、さまざまなプロパティをフィルタリングできます。 where パラメータ内で複数の値をフィルタリングできます。

failed 結果のクエリ チャレンジ:

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

値の比較には、_gt、_lte などのサフィックスを使用できます。

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

_change_block(number_gte: Int) でエンティティをフィルタリングすることもできます - これは、指定されたブロック内またはそれ以降に更新されたエンティティをフィルタリングします。

これは、前回のポーリング以降など、変更されたエンティティのみをフェッチする場合に役立ちます。または、サブグラフでエンティティがどのように変化しているかを調査またはデバッグするのに役立ちます (ブロック フィルターと組み合わせると、特定のブロックで変更されたエンティティのみを分離できます)。

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

_ サフィックスが付いたフィールドでは、ネストされたエンティティに基づくフィルタリングが可能です。

これは、子レベルのエンティティが指定された条件を満たすエンティティのみをフェッチする場合に役立ちます。

{
  challenges(where: { application_: { id: 1 } }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Graph Node v0.30.0 の時点で、複数のグループをグループ化できます同じ where 引数で and または or 演算子を使用して複数の基準に基づいて結果をフィルタリングします。

次の例では、outcome succeeded および number が 100 以上のチャレンジをフィルタリングしています。

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

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

次の例では、outcome succeeded または number が 100 以上のチャレンジをフィルタリングしています。

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

パラメータのサフィックスの全リスト:

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

さらに、次のグローバル フィルターを where 引数の一部として使用できます。

_change_block(number_gte: Int)

デフォルトである最新のブロックだけでなく、過去の任意のブロックについてもエンティティの状態を照会できます。クエリが発生するブロックは、クエリのトップレベル フィールドに block 引数を含めることで、ブロック番号またはブロック ハッシュのいずれかで指定できます。

そのようなクエリの結果は時間の経過とともに変化しません。つまり、特定の過去のブロックでクエリを実行しても、いつ実行されたとしても同じ結果が返されます。ただし、チェーンの先頭に非常に近いブロックでクエリを実行する場合を除いては、そのブロックがメインチェーン上にないことが判明し、チェーンが再構築される場合に結果が変わる可能性があります。ブロックが最終的とみなせるようになると、クエリの結果は変わらなくなります。

現在の実装には、これらの保証を破る可能性がある特定の制限がまだ存在することに注意してください。実装は常に特定のブロックハッシュがメインチェーン上に存在しないことを判断できるわけではなく、また、まだ最終的とみなせないブロックのブロックハッシュによるクエリの結果が、同時に実行されるブロックの再構築によって影響を受ける可能性があります。これらの制限は、ブロックが最終的であり、メインチェーン上に存在することが確認されている場合には、ブロックハッシュによるクエリの結果に影響を与えません。詳細はこの問題で説明されています。

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

このクエリは、ブロック番号 8,000,000 を処理した直後に存在していた Challenge エンティティとそれに関連する Application エンティティを返します。

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

このクエリは Challenge エンティティとそれに関連付けられた Application エンティティを返します。これは、指定されたハッシュでブロックを処理した直後に存在していたためです。

フルテキスト検索クエリフィールドは、サブグラフスキーマに追加してカスタマイズできる、表現力豊かなテキスト検索 API を提供します。サブグラフにフルテキスト検索を追加するには、「Defining Fulltext Search Fields」を参照してください。

全文検索クエリには、検索語を提供するための必須フィールド text が 1 つあります。この text 検索フィールドでは、いくつかの特別な全文演算子を使用できます。

全文検索演算子:

or 演算子を使用すると、このクエリはフルテキスト フィールドに「anarchism」または「crumpet」のいずれかのバリエーションを持つブログ エンティティにフィルター処理されます。

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

follow by 演算子は、フルテキスト ドキュメント内で特定の距離だけ離れた単語を指定します。次のクエリは、"decentralize" の後に "philosophy" が続くすべてのブログを返します。

{
  blogSearch(text: "decentralized <-> philosophy") {
    id
    title
    body
    author
  }
}

全文演算子を組み合わせて、より複雑なフィルターを作成します。口実検索演算子を follow by このサンプル クエリと組み合わせて使用​​すると、"lou" で始まり、その後に "music" が続く単語を持つすべてのブログ エンティティが一致します。

{
  blogSearch(text: "lou:* <-> music") {
    id
    title
    body
    author
  }
}

グラフ ノードは、受信した GraphQL クエリの 仕様ベース の検証を実装しますgraphql-tools-rs,これはに基づいていますgraphql-js リファレンス実装.検証ルールに失敗したクエリは、標準エラーで失敗します - にアクセスしてください詳細については、GraphQL 仕様をご覧ください。

データ ソースのスキーマ、つまりクエリに使用できるエンティティ タイプ、値、および関係は、GraphQL インターフェイス定義言語 (IDL)。

GraphQL スキーマは通常、クエリ、サブスクリプション、および ミューテーション のルート タイプを定義します。グラフは クエリ のみをサポートします。サブグラフのルート Query タイプは、サブグラフ マニフェストに含まれる GraphQL スキーマから自動的に生成されます。

スキーマ内の @entity ディレクティブを持つすべての GraphQL タイプはエンティティとして扱われ、 ID フィールドが必要です。

すべてのサブグラフには、サブグラフ メタデータへのアクセスを提供する、自動生成された _Meta_ オブジェクトがあります。これは、次のように照会できます。

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

ブロックが提供されている場合、メタデータはそのブロックのものであり、そうでない場合は、最新のインデックス付きブロックが使用されます。提供される場合、ブロックはサブグラフの開始ブロックの後にあり、最後にインデックス付けされたブロック以下でなければなりません。

deployment は、subgraph.yaml ファイルの IPFS CID に対応する一意の ID です。

block は、最新のブロックに関する情報を提供します (_meta に渡されたブロック制約を考慮します):

• hash: ブロックのハッシュ
• number: ブロック番号
• timestamp: 可能であれば、ブロックのタイムスタンプ (これは現在、EVMネットワークのインデックスを作成するサブグラフでのみ利用可能)

hasIndexingErrors は、サブグラフが過去のブロックでインデックス作成エラーに遭遇したかどうかを識別するブール値です