subgraphs

Goldsky サブグラフ

サブグラフは、オンチェーンイベントをインデックス化し、クエリ可能なエンドポイントを介して公開する、ホスト型の GraphQL API です。構造化されたオンチェーンデータに対して柔軟な GraphQL クエリを必要とする フロントエンドアプリケーションや dApp に最適です。

代わりに Turbo パイプラインで解決できるでしょうか？ GraphQL でのクエリではなく、生のオンチェーンデータをデータベース（PostgreSQL、ClickHouse、Kafka、S3）にストリーミングすることが目的なら、Turbo パイプラインのほうが高速で低コストであり、カスタムのインデックス作成コードも必要ありません。「Turbo パイプラインの構築を手伝って」と伝えると、turbo-builder スキルが案内します。

---

サブグラフを使用する場面

ユースケース	最適なツール
フロントエンド／dApp で GraphQL API が必要	サブグラフ
インデックス作成ハンドラーにカスタムビジネスロジックが必要	サブグラフ
既存の TheGraph サブグラフを移行	サブグラフ
生のブロックチェーンデータをデータベースにストリーミング	Turbo パイプライン
ClickHouse または Kafka でリアルタイム分析	Turbo パイプライン
サブグラフのデータを独自のデータベースに同期	Mirror + サブグラフソース

---

サブグラフを初期化する

新しいサブグラフプロジェクトをローカルでスキャフォールドします。

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

主な初期化フラグ

フラグ	説明
--target-path <path>	サブグラフファイルを書き込むディレクトリ
--from-config <path>	即時サブグラフ JSON 設定ファイルのパス
--abi <source>	コントラクトの ABI ソース
--contract <address>	監視するコントラクトアドレス
--contract-events <names>	インデックス化するイベント名
--contract-calls <names>	インデックス化する呼び出し名
--contract-name <name>	コントラクト名
--network <network>	コントラクトのネットワーク — 対応ネットワークについてはドキュメントを参照してください
--start-block <block>	インデックス作成を開始するブロック
--description <text>	サブグラフの説明
--call-handlers	呼び出しハンドラーを有効化
--build	ファイルの書き込み後にサブグラフをビルド
--deploy	ビルド後にサブグラフをデプロイ
--force	指定したパスにある既存ファイルを上書き

---

サブグラフをデプロイする

Goldsky は複数のデプロイ方法をサポートしています。

ソースから（最も一般的）

ローカルディレクトリにコンパイル済みのサブグラフが必要です。

# Install CLI and log in
curl https://goldsky.com | sh
goldsky login

# Deploy from local build output
goldsky subgraph deploy my-subgraph/1.0.0 --path ./build

ABI から（即時サブグラフ）

AssemblyScript を使わずに、コントラクト ABI からサブグラフを直接生成してデプロイします。

goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

IPFS ハッシュから

すでに IPFS に公開されているサブグラフをデプロイします。

goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...

カスタムゲートウェイを指定するには --ipfs-gateway <url> を使用します（デフォルトは https://ipfs.network.thegraph.com です）。

ノーコード（ダッシュボードウィザード）

Goldsky ダッシュボードを使用すると、コードを書かずに一般的な規格（ERC-20、ERC-721 など）向けのビルド済みサブグラフをデプロイできます。app.goldsky.com → サブグラフ → 作成に移動してください。

The Graph から移行する

ワンステップで移行でき、コードの変更は不要です。

goldsky subgraph deploy my-subgraph/1.0.0 \
  --from-url <your-thegraph-deployment-url>

docs.goldsky.com/subgraphs/deploying-subgraphs を参照してください。

デプロイフラグのリファレンス

フラグ	説明
--path <dir>	コンパイル済みサブグラフディレクトリのパス
--from-url <url>	公開デプロイ済みサブグラフの GraphQL エンドポイント（The Graph の移行用）
--from-ipfs-hash <hash>	公開デプロイ済みサブグラフの IPFS ハッシュ
--from-abi <path>	ABI ファイルからサブグラフを生成
--ipfs-gateway <url>	カスタム IPFS ゲートウェイ（デフォルト：https://ipfs.network.thegraph.com）
--tag <tags>	デプロイ後にサブグラフにタグを付与（複数の場合はカンマ区切り）
--start-block <number>	開始ブロックを上書き
--graft-from <name/version>	既存のサブグラフの最新ブロックからグラフト
--remove-graft	デプロイ前にサブグラフからグラフトを削除
--enable-call-handlers	呼び出しハンドラーを有効化（--from-abi と併用する場合のみ）
--description <text>	サブグラフの説明／メモ

注意： --path、--from-url、--from-ipfs-hash、--from-abi は同時に指定できません。いずれか1つだけを使用してください。

---

GraphQL エンドポイント

デプロイされたサブグラフごとに、パブリック GraphQL エンドポイントが用意されます。

https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn

エンドポイント URL を取得するには：

goldsky subgraph list

パブリックエンドポイントとプライベートエンドポイント

デフォルトでは、エンドポイントはパブリックです。エンドポイントの公開範囲を設定するには：

# Disable public endpoint
goldsky subgraph update my-subgraph/1.0.0 --public-endpoint disabled

# Enable private endpoint (requires API key)
goldsky subgraph update my-subgraph/1.0.0 --private-endpoint enabled

プライベートエンドポイントで API キーを必須にするには：

1. app.goldsky.com → Settings → API Keys に移動し、キーを作成します。
2. リクエストに Authorization ヘッダーを追加します：

   Authorization: Bearer <your-api-key>
   

---

サブグラフのタグ

タグを使うと、人が読みやすいエイリアス（prod など）を特定のサブグラフバージョンに固定できるため、再デプロイしてもフロントエンドの URL は変わりません。

# Create or update a tag
goldsky subgraph tag create my-subgraph/1.0.0 --tag prod

# Tagged endpoint:
# https://api.goldsky.com/api/public/<project-id>/subgraphs/my-subgraph/prod/gn

# Delete a tag
goldsky subgraph tag delete my-subgraph/1.0.0 --tag prod

デプロイ時にタグを付けることもできます：

goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod

docs.goldsky.com/subgraphs/tags をご覧ください。

---

Webhook

サブグラフの Webhook は、エンティティが変更されるたび（INSERT、UPDATE、DELETE）に HTTP エンドポイントへペイロードを送信します。通知やプッシュ型のフローに便利です。

# Create a webhook
goldsky subgraph webhook create my-subgraph/1.0.0 \
  --name my-webhook \
  --url https://example.com/hook \
  --entity Transfer \
  --secret my-secret

# List all webhooks
goldsky subgraph webhook list

# List available entities for a subgraph
goldsky subgraph webhook list-entities my-subgraph/1.0.0

# Delete a webhook
goldsky subgraph webhook delete my-webhook

フラグ	説明
--name <name>	Webhook 名（重複不可）— 必須
--url <url>	イベントの送信先 URL — 必須
--entity <entity>	イベントを送信するサブグラフのエンティティ — 必須
--secret <secret>	各 Webhook リクエストに含めるシークレット

ヒント： データベースへの確実な配信が必要な場合は、Webhook ではなく Mirror を使ってサブグラフのデータを同期してください。こちらのほうが信頼性が高くなります。

docs.goldsky.com/subgraphs/webhooks をご覧ください。

---

サブグラフの管理

サブグラフの一覧表示

# List all subgraphs
goldsky subgraph list

# List a specific subgraph
goldsky subgraph list my-subgraph/1.0.0

# Show only tags or deployments
goldsky subgraph list --filter tags
goldsky subgraph list --filter deployments

# Summary view
goldsky subgraph list --summary

サブグラフの更新

goldsky subgraph update my-subgraph/1.0.0 \
  --public-endpoint enabled \
  --private-endpoint disabled \
  --description "Production deployment"

フラグ	値	説明
--public-endpoint	enabled / disabled	パブリックエンドポイントの公開設定を切り替えます
--private-endpoint	enabled / disabled	プライベートエンドポイントを切り替えます（API キーが必要です）
--description	text	サブグラフの説明／メモ

一時停止と再開

# Pause a subgraph (stops indexing)
goldsky subgraph pause my-subgraph/1.0.0

# Resume a paused subgraph
goldsky subgraph start my-subgraph/1.0.0

サブグラフの削除

goldsky subgraph delete my-subgraph/1.0.0

# Skip confirmation prompt
goldsky subgraph delete my-subgraph/1.0.0 --force

---

ログとデバッグ

問題を診断するには、サブグラフのログを追跡します：

# View recent logs
goldsky subgraph log my-subgraph/1.0.0

# Logs from the last hour, errors only
goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error

# JSON format for parsing
goldsky subgraph log my-subgraph/1.0.0 --format json

フラグ	デフォルト	説明
--since <duration>	1m	指定した期間より新しいログを表示します（例：5s、2m、3h）
--format <format>	text	出力形式：pretty、json、text
--filter <level>	info	最小ログレベル：error、warn、info、debug
--levels <levels>	—	含めるログレベルをカンマ区切りで明示的に指定します
--interval <seconds>	5	ログを確認する間隔（秒）

停止したサブグラフ

サブグラフの進行が止まると、Goldsky は自動的に一時停止し、メールで通知します。診断するには：

1. ログを確認します：goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error
2. ハンドラーエラー、RPC タイムアウト、またはメモリ不足の問題を確認します
3. 問題を修正して再デプロイするか、[email protected] にお問い合わせください

---

クロスチェーンのサブグラフ

複数のチェーンにまたがって同じコントラクトをインデックスするには、チェーンごとに個別のサブグラフをデプロイし、Mirror パイプラインを使ってそれらを 1 つのデータベーステーブルに統合します。

docs.goldsky.com/subgraphs/introduction をご覧ください。

---

CLI コマンドリファレンス

アクション	コマンド
サブグラフを初期化	goldsky subgraph init <name/version>
ソースからデプロイ	goldsky subgraph deploy <name/version> --path .
The Graph からデプロイ	goldsky subgraph deploy <name/version> --from-url <url>
ABI からデプロイ	goldsky subgraph deploy <name/version> --from-abi <path>
IPFS からデプロイ	goldsky subgraph deploy <name/version> --from-ipfs-hash <hash>
サブグラフの一覧を表示	goldsky subgraph list
サブグラフを削除	goldsky subgraph delete <name/version>
サブグラフを一時停止	goldsky subgraph pause <name/version>
サブグラフを開始	goldsky subgraph start <name/version>
サブグラフを更新	goldsky subgraph update <name/version> --public-endpoint enabled
ログを追跡	goldsky subgraph log <name/version>
タグを作成	goldsky subgraph tag create <name/version> --tag <tag>
タグを削除	goldsky subgraph tag delete <name/version> --tag <tag>
Webhook を作成	goldsky subgraph webhook create <name/version> --name <n> --url <u> --entity <e>
Webhook の一覧を表示	goldsky subgraph webhook list
Webhook を削除	goldsky subgraph webhook delete <webhook-name>
Webhook エンティティの一覧を表示	goldsky subgraph webhook list-entities <name/version>

---

関連情報

• /turbo-builder — GraphQL API の代わりに、データベースへのストリーミングパイプラインを構築します
• Goldsky のドキュメント： docs.goldsky.com/subgraphs/introduction