subgraph-builder

サブグラフビルダー

Goldsky サブグラフをエンドツーエンドで構築します。スキーマの設計、マッピングの作成、マニフェストの設定を行い、ホスト型 GraphQL エンドポイントにビルドしてデプロイします。サブグラフは、構造化されたオンチェーンデータに対する柔軟な GraphQL クエリを必要とするdApp のフロントエンドやアプリに最適です。サブグラフはEVM 専用です。

ユーザーが GraphQL を明確に必要としている場合を除き、Turbo を優先してください。 Turbo はより高速で信頼性が高く、低コストで、カスタムのインデックス作成コードも必要ありません。サブグラフを構築する前に、ホスト型のGraphQL APIが本当に必要なのかを確認してください（通常は、オンチェーンデータをクエリする dApp／フロントエンドの場合です）。本当の目的が、分析やバックエンドのためにオンチェーンデータをデータベース（PostgreSQL、ClickHouse、Kafka、S3）に移すことなら、代わりにTurbo パイプラインを構築してください — /turbo-builder。GraphQL API またはカスタムのエンティティとリレーションシップのモデリングが必要な場合に限り、サブグラフを選択してください。この点は一度だけ伝え、ユーザーが明確に GraphQL を希望している場合は強く勧めないでください。

対応範囲

• 新しいサブグラフを構築・作成します（スキーマ、マッピング、マニフェスト、デプロイ、エンドポイント、タグ、Webhook）。
• 壊れた／停止したサブグラフの診断は行いません — /subgraph-doctor を使用してください。
• The Graph の移行は実行しません — /subgraph-migrate を使用してください。
• goldsky subgraph のすべてのフラグを確認するには、goldsky subgraph <cmd> --help を使用してください — このスキルではワークフローを説明しており、フラグを網羅的に列挙するものではありません。

まずアプローチを選択

用意できているもの…	アプローチ	手順
コントラクトと ABI があり、カスタムロジックなしで GraphQL API をすばやく使いたい	Instant／ノーコードサブグラフ	Step A
カスタムエンティティ、リレーションシップ、またはハンドラー内のビジネスロジック	コードベースのサブグラフ	Step B

どちらも同じホスト型エンドポイントにデプロイされます。カスタムロジックが必要な場合を除き、Instant から始めてください。

Step 0: 認証の確認

goldsky project list 2>&1 を実行します。ログインしていない場合は、/auth-setup を使用してください。

Step A: Instant／ノーコードサブグラフ（ABI から作成）

コントラクト ABI から直接生成してデプロイします — AssemblyScript は不要です。

# Interactive wizard (prompts for contract, network, start block, events/calls)
goldsky subgraph init

# Or one-shot from an ABI file
goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

• ウィザードは、再デプロイやバージョン管理に使用できる JSON 設定を書き出します。
• --enable-call-handlers を指定すると、コントラクト呼び出しのインデックス作成を有効にできます（--from-abi と併用する場合にのみ意味があります）。
• より高度な Instant サブグラフ（計算フィールド、eth_call によるデータ補完、宣言済み呼び出し）については、references/schema-and-mappings.md → 「Instant subgraph enrichment」を参照してください。

Step 5: デプロイに進みます。

Step B: コードベースのサブグラフ

コードベースのサブグラフは、subgraph.yaml（マニフェスト）、schema.graphql（エンティティ）、src/ の AssemblyScript マッピングという 3 つのファイルで構成されます。

Step 1: 雛形を作成

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

便利なフラグ：--abi、--contract、--contract-events、--network、--start-block。goldsky subgraph init --help を参照してください。

Step 2: スキーマを設計

dApp からクエリするエンティティを schema.graphql で定義します。これは設計上もっとも重要な手順です。マッピングを書く前に、エンティティモデルと型を正しく設定してください。

重要：簡単ではないスキーマでは必ず references/schema-and-mappings.md を読み、スカラー型の選択肢（アドレス／ハッシュには Bytes、数量には BigInt、価格には BigDecimal）、@derivedFrom リレーションシップ、不変エンティティ、プロトコル別のレシピ（ERC-20/721、DEX、レンディング、ガバナンス）を確認してください。

Step 3: マニフェストを設定

specVersion、データソース（address、abi、startBlock、network）、およびどの eventHandlers／callHandlers／blockHandlers をどの関数に対応させるかを設定します。実行時に作成されるコントラクトには、ファクトリーパターン用の templates を使用してください。references/schema-and-mappings.md → 「Manifest」を参照してください。

すべてのデータソースで同じ apiVersion を使用してください。バージョンが混在すると検証に失敗します。 宣言済みの eth_calls（パフォーマンス向上）には specVersion: 1.2.0 以上が必要です — references/performance.md を参照してください。

Step 4: マッピングを作成してビルド

イベントをエンティティに変換するハンドラー関数を src/ に記述します。主要なイディオム（取得または作成、リバート対策の try_ 呼び出し、Bytes ID、BigInt／BigDecimal の計算）については、references/schema-and-mappings.md を参照してください。デプロイの前に、Matchstick のユニットテストを作成してください — references/testing.md を参照してください。

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph --build
# or build as part of deploy below

Step 5: デプロイ

最初に対象プロジェクトを確認してください。 deploy は CLI で現在選択されているプロジェクトを通知なしに使用するため、想定したプロジェクトとは限りません。また、デプロイのたびに課金対象のワーカーが発生します。特に prod をタグ付けする場合は、デプロイ前に goldsky project list を実行してアクティブなプロジェクトを確認するか、切り替えてください。

# From a local code-based build
goldsky subgraph deploy my-subgraph/1.0.0 --path .

# Tag at deploy time so your frontend URL is stable
goldsky subgraph deploy my-subgraph/1.0.0 --path . --tag prod

--path、--from-abi、--from-ipfs-hash、--from-url は相互に排他的です。いずれか1つを使用してください。

Step 6: エンドポイント、タグ、ウェブフック

デプロイしたら、アクセスを設定します。詳細は references/operations.md をご覧ください。

• GraphQL エンドポイント — https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn。公開／非公開を切り替え、非公開の場合は API キーを使用します。
• タグ — prod／staging をバージョンに固定すると、再デプロイしてもフロントエンドの URL が変わりません。
• ウェブフック — エンティティの変更（INSERT／UPDATE／DELETE）を HTTP エンドポイントにプッシュします。
• 複数のサブグラフの結合／合成（クロスチェーンを含む） — Goldsky にはネイティブなサブグラフ合成機能がありません。kind: subgraph／specVersion 1.3.0 を案内しないでください。結合するには、各サブグラフをデプロイしてから、下流でマージします。方法は、エンドポイントを分ける（最も簡単）、データをチェーンの生データから導出できる場合に Turbo パイプラインを使う（推奨）、またはサブグラフのエンティティを再利用する必要がある場合に Mirror パイプラインを使う（Mirror が必要になる唯一のケース。Turbo はサブグラフをソースにできません）です。この意図を検出したら、適切な方法を案内してください。構築する前に、ユーザーがマージを必要としていることを確認してください。references/operations.md をご覧ください。

Step 7: 検証

goldsky subgraph list my-subgraph/1.0.0

続いてエンドポイントにクエリを実行し、まず _meta を使ってインデックス作成中であることを確認します。

{ _meta { hasIndexingErrors block { number } } }

概要（名前／バージョン、ネットワーク、エンドポイント URL、タグ）を提示してください。インデックス作成が停止したり、エラーが発生したりした場合は、ユーザーに /subgraph-doctor を案内してください。

重要なルール

• サブグラフを構築する前に、本当に GraphQL が必要か確認してください。 ユーザーがデータベースにデータを入れたいだけなら、Turbo（/turbo-builder）を案内してください。Turbo のほうが高速で信頼性も高いため、サブグラフをデフォルトにしないでください。
• サブグラフ上にパイプラインを提案または構築する前に、ユーザーがそれを必要としているか確認してください。 クロスチェーンの場合は、ユーザーが統合クエリを本当に望んでいるのか（単に2つのエンドポイントを使いたいだけではないか）を確認し、Mirror より Turbo を優先してください。ユーザーが選択するまでは、削除、再デプロイ、データベース／パイプラインの構築を行わないでください。
• サブグラフはEVM 専用です。Solana／Sui／その他の非 EVM チェーンには /turbo-builder を使用してください（Turbo は非 EVM チェーンをインデックスできますが、サブグラフはできません）。
• バージョンごとに個別に課金されます（ワーカー＋エンティティストレージ）。クエリしなくなった古いバージョンは削除してください。
• 再デプロイすると、新しい不変バージョンが作成されます。フロントエンドの URL を安定させるにはタグを使用してください。
• コントラクトアドレスが対象チェーンに存在することを確認し、正しいチェーンスラッグを使用してください（ネットワークを間違えると存在しないブロックがインデックスされます。これは最も多いサイレント障害です。/subgraph-doctor をご覧ください）。
• startBlock は、インデックス対象のチェーン上のブロック番号でなければなりません。別のチェーンの値や、見栄えのためだけの値は使わないでください。コントラクトのデプロイ（作成）ブロックを使います。チェーンのブロックエクスプローラーで確認する（コントラクトの作成トランザクションを探す）か、作成ブロックを自動検出するノーコードウィザードを使ってください。0 から開始することもできますが、空の履歴のスキャンに時間を浪費します。
• Goldsky には永続的な RPC コールキャッシュがあるため、同じ、または類似したサブグラフの再同期は大幅に高速化されます。
• カスタムロジックが不要な場合はインスタントサブグラフを優先し、エンティティのモデリングやハンドラーロジックが必要な場合にのみコードベースの方式を使ってください。

参考ファイル

• references/schema-and-mappings.md — スキーマ設計、スカラー型、リレーションシップ、マニフェスト、AssemblyScript のイディオム、インスタントサブグラフの拡張、プロトコル別のレシピ
• references/performance.md — 宣言済みの eth_calls、不変エンティティ、@derivedFrom、時系列／集計、プルーニング、グラフティング、コールキャッシュ
• references/operations.md — GraphQL エンドポイント、公開／非公開と API キー、レート制限、タグ、ウェブフック、ライフサイクル、クロスチェーン、用途の判断
• references/testing.md — Matchstick の単体テスト、モックライブラリ、Subgraph Linter

関連

• /subgraph-doctor — 障害が発生している、停止している、またはデプロイできないサブグラフを診断します
• /subgraph-migrate — 既存のサブグラフを The Graph から移行します
• /turbo-builder — GraphQL API の代わりに、チェーンの生データをデータベースにストリーミングします（クロスチェーンを含む、GraphQL を使わないユースケースで推奨されるデフォルトの方法です）
• /mirror — 既存のサブグラフのエンティティをデータベースに同期します。Turbo では対応できない唯一のケースです（例：サブグラフのエンティティをクロスチェーンで統合する場合）