クエリ > GraphQL API

GraphQL API

Graph Protocol で使用される GraphQL Query API について説明します。

クエリ

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

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

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

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

注: 単一のエンティティを照会する場合、id フィールドは必須であり、文字列でなければなりません。

すべての 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
    }
  }
}

現在、@entity および @derivedFrom フィールドで、1 レベルの深い String または ID 型で並べ替えることができます。残念ながら、1 レベルの深さのエンティティのインターフェイスによる並べ替え、配列およびネストされたエンティティであるフィールドによる並べ替えは、まだサポートされていません。

ページネーション

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

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

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

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

first を使用した例

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

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

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

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

first と skip を使用した例

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

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

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

first と id_ge を使用した例

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

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

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

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

クエリで where パラメータを使用して、さまざまなプロパティをフィルタリングできます。 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
    }
  }
}

シンタックス シュガー: コンマで区切られた部分式を渡すことで and 演算子を削除することで、上記のクエリを簡素化できます。

{
  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
    }
  }
}

注意：クエリを構築する際には、または演算子の使用によるパフォーマンスへの影響を考慮することが重要です。またはは検索結果を広げるための便利なツールとなり得ますが、重要なコストも伴います。またはの主な問題の1つは、クエリの遅延を引き起こす可能性があることです。これは、またはがデータベースに複数のインデックスをスキャンする必要があるため、時間のかかるプロセスとなるからです。これらの問題を避けるために、開発者は可能な限りまたはの代わりにかつ演算子を使用することが推奨されます。これにより、より正確なフィルタリングが可能となり、より高速で正確なクエリが実行できるでしょう。

すべてのフィルター

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

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

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

一部の接尾辞は、特定のタイプでのみサポートされていることに注意してください。たとえば、Boolean は _not、_in、および _not_in のみをサポートしますが、_ はサポートしません。オブジェクト型とインターフェイス型でのみ使用できます。

さらに、次のグローバル フィルターを 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複数の検索語をオペレーターで区切って検索すると、指定した語のいずれかにマッチするすべてのエンティティが返されます。
<->Follow by2 つの単語の間の距離を指定します。
:*プレフィックスプレフィックス検索語を使って、プレフィックスが一致する単語を検索します（2 文字必要）

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 スキーマから自動的に生成されます。

注: 開発者はアプリケーションから基盤となるブロックチェーンに対して直接トランザクションを発行することが期待されるため、API はミューテーションを公開しません。

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

注: 現在、スキーマ内のすべてのタイプに @entity ディレクティブが必要です。将来的には、@entity ディレクティブのない型を値オブジェクトとして扱いますが、これはまだサポートされていません。

サブグラフ メタデータ

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

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

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

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

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

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

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

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

⁠ページを編集⁠
前
分散システム
次
Subgraph ID vs Deployment ID
⁠ページを編集⁠