mirror

Goldsky Mirror パイプライン

Mirror は、Goldsky のオリジナルのストリーミングパイプライン製品です。ソース（サブグラフのエンティティまたはダイレクトインデックス作成データセット）からオンチェーンデータを読み取り、必要に応じて変換を適用し、結果をシンク（データベースまたはメッセージキュー）に書き込みます。

Mirror と Turbo — どちらを使うべきですか？

	Mirror	Turbo
サブグラフソース	はい	いいえ
速度と信頼性	良好	より高速で信頼性が高い
シンクの選択肢	以下の一般的な Mirror シンクを参照してください	Turbo シンクカタログを参照してください
設定の複雑さ	中程度	よりシンプルな YAML
データセットの対応範囲	130 以上のチェーン	130 以上のチェーン、より充実したカタログ

サブグラフソースが必要でない限り、Turbo を使ってください。 Turbo はより高速で信頼性が高く、Mirror との機能差を積極的に縮めています。特にシンクのサポートが充実しています。サブグラフが不要な場合は、「Turbo パイプラインの構築を手伝って」と伝えると、/turbo-builder スキルがより迅速なセットアップを案内します。

---

Mirror パイプラインの仕組み

Source (subgraph entity or direct-indexing dataset)
  ↓
Transforms (optional SQL or external handlers)
  ↓
Sink (PostgreSQL, ClickHouse, Kafka, S3, etc.)

パイプラインは YAML ファイル（apiVersion: 3）で定義し、goldsky pipeline apply でデプロイします。

---

パイプライン YAML の構造

トップレベルのフィールド：

フィールド	型	必須	説明
name	string	はい	小文字、数字、ハイフンのみを使用します。50 文字未満です。
apiVersion	number	はい	常に 3
resource_size	string	いいえ	s（デフォルト）、m、l、xl、xxl
description	string	いいえ	パイプラインの説明
sources	object	はい	少なくとも 1 つのソース
transforms	object	いいえ	不要な場合は {} を使用します
sinks	object	はい	少なくとも 1 つのシンク

---

ソース

ソースの種類	YAML の type 値	説明
サブグラフエンティティ	subgraph_entity	Goldsky がホストするサブグラフから Mirror データを取得します
データセット（ダイレクトインデックス作成）	dataset	未加工のオンチェーンデータセット（ブロック、ログ、トランザクション、トレース、送金）

サブグラフエンティティソース

sources:
  subgraph_account:
    type: subgraph_entity
    name: account                # Entity name in your subgraph
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter: ""                   # Optional SQL WHERE clause for fast scan
    subgraphs:
      - name: my-subgraph        # Deployed subgraph name
        version: 1.0.0
      - name: my-subgraph-arb    # Cross-chain: add more subgraphs
        version: 1.0.0

フィールド： type（必須：subgraph_entity）、name（必須：エンティティ名）、subgraphs（必須：{name, version} のリスト）、start_at（任意）、filter（任意）、description（任意）。

データセットソース

sources:
  base_logs:
    type: dataset
    dataset_name: base.logs      # Use `goldsky dataset list --output json` to discover names
    version: 1.0.0               # Use `goldsky dataset get <name>` for versions
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter: "address = '0x...'"  # Optional — enables Fast Scan for backfills

フィールド： type（必須：dataset）、dataset_name（必須）、version（必須）、start_at（任意）、filter（任意）、description（任意）。

高速スキャン： データセットソースで start_at: earliest を指定し、filter を定義すると、ソースレベルでフィルターが事前適用されるため、過去データのバックフィルが大幅に高速化します。データセットスキーマに存在する属性を使用してください（確認するには goldsky dataset get <dataset_name> を実行します）。

docs.goldsky.com/mirror/sources/supported-sourcesを参照してください。

---

シンク

一般的な Mirror の宛先を以下に示します。サポートされているシンクタイプのすべてを網羅した一覧ではありません。これらの例から製品全体の数を推測するのではなく、ユーザーが必要とする具体的な宛先を確認してください。

シンク	YAML type の値	備考
PostgreSQL	postgres	最も一般的です。OLTP 向けで、テーブルを自動作成し、INSERT ON CONFLICT によるアップサートに対応します。NeonDB によるホステッドオプションもあります。
ClickHouse	clickhouse	OLAP 向けです。デフォルトで ReplacingMergeTree を使用し、最高のパフォーマンスを得るには append_only_mode を使用します
MySQL	mysql	OLTP ワークロード向けです
Elasticsearch	elasticsearch	リアルタイム検索と分析向けです
Kafka	kafka	トピックへの高スループットのストリーミングに対応し、topic_partitions を設定できます
オブジェクトストレージ	file	S3、GCS、R2 に対応します。Parquet 形式で、追記専用です。partition_columns に対応します
AWS SQS	sqs	メッセージキューイング向けです
Webhook	webhook	外部エンドポイントへの HTTP POST です

ユーザー管理の宛先に書き込むすべてのシンクには、Goldsky Secret（secret_name）が必要です。goldsky secret create で作成してください。

シンクでは、シンクレベルで列の型をキャストするための schema_override に対応しています（例：string から jsonb）。

シンクの例

# PostgreSQL
sinks:
  my_pg:
    type: postgres
    table: transfers
    schema: public
    secret_name: MY_PG_SECRET
    from: my_transform

# ClickHouse
sinks:
  my_ch:
    type: clickhouse
    table: transfers
    database: my_db
    secret_name: MY_CH_SECRET
    from: my_source

# Kafka
sinks:
  my_kafka:
    type: kafka
    topic: accounts
    topic_partitions: 2
    secret_name: MY_KAFKA_SECRET
    from: my_source

# Object Storage (S3/GCS/R2)
sinks:
  my_s3:
    type: file
    path: s3://bucket/path/
    format: parquet
    secret_name: MY_S3_SECRET
    from: my_source

# SQS
sinks:
  my_sqs:
    type: sqs
    url: https://sqs.us-east-1.amazonaws.com/123456/my-queue
    secret_name: MY_SQS_SECRET
    from: my_source

docs.goldsky.com/mirror/sinks/supported-sinks を参照してください。

---

変換

タイプ	YAML type の値	説明
SQL	(なし — デフォルト)	SQL でレコードをフィルタリング、結合、または再構成します
外部ハンドラー	handler	カスタムロジックを実行するため、レコードを HTTP エンドポイントに POST します

SQL 変換

transforms:
  filtered_logs:
    sql: SELECT id, block_number, address FROM base_logs WHERE block_number > 1000
    primary_key: id

SQL 変換では、ソース名または変換名をテーブル名として参照します。連鎖にも対応しており、ある変換から別の変換を読み取ることができます。

組み込みのデコード関数：

• _gs_log_decode(abi, topics, data) — 生のログイベントをデコードします
• _gs_tx_decode(abi, input, output) — 生のトレース／トランザクションデータをデコードします
• _gs_fetch_abi(url, type) — URL から ABI を取得します（etherscan 互換形式または生の JSON）。パイプラインの開始時に一度取得します

外部ハンドラー変換

transforms:
  my_handler:
    type: handler
    primary_key: id
    url: http://example.com/transform
    from: my_source
    batch_size: 100              # Records per batch (default: 100)
    batch_flush_interval: 1s     # Flush interval (default: 1s)
    payload_columns: [col1,col2] # Optional: send subset of columns
    headers:                     # Optional custom headers
      X-Api-Key: my-key

• 失敗時に指数バックオフを行う、少なくとも 1 回の配信
• 最大応答時間：5 分、最大接続時間：1 分
• 戻り値の型のキャストに schema_override を使用できます

docs.goldsky.com/mirror/transforms/sql-transforms を参照してください。

---

YAML の完全な例

サブグラフエンティティから PostgreSQL へ

name: my-subgraph-sync
apiVersion: 3
resource_size: s
sources:
  subgraph_transfer:
    type: subgraph_entity
    name: Transfer
    subgraphs:
      - name: uniswap-v3
        version: 1.0.0
transforms: {}
sinks:
  my_postgres:
    type: postgres
    table: transfers
    schema: public
    secret_name: MY_PG_SECRET
    from: subgraph_transfer

SQL 変換を使用した、データセット（直接インデックス作成）から PostgreSQL への連携

name: base-logs-filtered
apiVersion: 3
resource_size: s
sources:
  base_logs:
    type: dataset
    dataset_name: base.logs
    version: 1.0.0
    start_at: earliest
    filter: "address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'"
transforms:
  select_fields:
    sql: SELECT id, block_number, transaction_hash, data FROM base_logs
    primary_key: id
sinks:
  pg_logs:
    type: postgres
    table: base_logs
    schema: public
    secret_name: MY_PG_SECRET
    from: select_fields

サブグラフソースがありませんか？ ほぼ間違いなく、代わりに Turbo を使用してください。Turbo はより高速で信頼性が高く、データセットカタログが充実しており、構文もよりシンプルです。/turbo-builder を使用して開始してください。

---

CLI リファレンス — すべてのパイプラインコマンド

すべてのコマンドで使用できるグローバルオプション：--token <string>（CLI 認証トークン）、--color（出力に色を付けます。デフォルトは true）、-h, --help。

goldsky pipeline apply <config-path>

YAML 設定ファイルからパイプラインを作成または更新します。べき等です。

フラグ	型	説明
--status	ACTIVE | INACTIVE | PAUSED	パイプラインの希望ステータス
--from-snapshot	string	開始するスナップショット：last、new、none、またはスナップショット ID。last = 利用可能な最新のスナップショット。new = 最初に新しいスナップショットを作成します。none = 最初から開始します。デフォルト：new
--force	boolean	確認プロンプトをスキップします（CI に便利です）
--skip-transform-validation	boolean	更新時の変換の検証をスキップします
--save-progress	boolean	(非推奨、--from-snapshot を使用) 適用前にスナップショットを試みます
--use-latest-snapshot	boolean	(非推奨、--from-snapshot を使用) 最新のスナップショットから開始します
--skip-validation	boolean	(非推奨) --skip-transform-validation と同じです

goldsky pipeline apply my-pipeline.yaml --status ACTIVE
goldsky pipeline apply my-pipeline.yaml --status ACTIVE --from-snapshot last
goldsky pipeline apply my-pipeline.yaml --force   # CI/CD usage

goldsky pipeline start <nameOrConfigPath>

パイプラインを開始します（--status ACTIVE を指定した apply と同等です）。

フラグ	型	説明
--from-snapshot	string	last、new、none、またはスナップショット ID
--use-latest-snapshot	boolean	(非推奨です。代わりに --from-snapshot を使用してください)

goldsky pipeline stop <nameOrConfigPath>

スナップショットを取得せずにパイプラインを停止します。ステータスを INACTIVE、ランタイムを TERMINATED に設定します。

グローバルオプション以外に追加のフラグはありません。

goldsky pipeline pause <nameOrConfigPath>

スナップショットを取得してパイプラインを一時停止し、中断したところから再開できるようにします。ステータスを PAUSED、ランタイムを TERMINATED に設定します。

グローバルオプション以外に追加のフラグはありません。

goldsky pipeline restart <nameOrConfigPath>

設定を変更せずにパイプラインを再起動します。シンクデータベースが再起動された場合や、接続が停止している場合などに便利です。

フラグ	型	説明
--from-snapshot	string	必須です。 last、new、none、またはスナップショット ID
--disable-monitoring	boolean	再起動後のモニタリングをスキップします（デフォルト：false）

goldsky pipeline restart my-pipeline --from-snapshot last
goldsky pipeline restart my-pipeline --from-snapshot none  # restart from scratch

goldsky pipeline get <nameOrConfigPath>

パイプラインの設定とステータスを取得します。

フラグ	型	説明
--outputFormat, --output	json | table | yaml	出力形式（デフォルト：yaml）
--definition	boolean	パイプライン定義（ソース、変換、シンク）のみを出力します
-v, --version	string	パイプラインのバージョン（デフォルト：latest）

goldsky pipeline list

プロジェクト内のすべてのパイプラインを一覧表示します。

フラグ	型	説明
--output, --outputFormat	json | table | yaml	出力形式（デフォルト：table）
--outputVerbosity	summary | usablewithapplycmd | all	詳細レベル（デフォルト：summary）
--include-runtime-details	boolean	ランタイムのステータスとエラーを含めます（デフォルト：false）

goldsky pipeline list --output json
goldsky pipeline list --include-runtime-details

goldsky pipeline info <nameOrConfigPath>

パイプラインの情報（ステータス、設定、ランタイムの詳細）を表示します。

フラグ	型	説明
-v, --version	string	パイプラインのバージョン（デフォルト：latest）

goldsky pipeline monitor <nameOrConfigPath>

パイプラインのランタイム（ステータス、メトリクス（受信／書き込みレコード数）、エラー）をモニタリングします。10 秒ごとに更新されます。

フラグ	型	説明
--update-request	boolean	実行中の更新リクエストをモニタリングします
--max-refreshes, --maxRefreshes	number	データの最大更新回数
-v, --version	string	パイプラインのバージョン（デフォルト：latest）

goldsky pipeline delete <nameOrConfigPath>

パイプラインを完全に削除します。

フラグ	型	説明
-f, --force	boolean	確認プロンプトなしで強制的に削除します（デフォルト：false）

goldsky pipeline resize <nameOrConfigPath> <resourceSize>

パイプラインのコンピューティングリソースを変更します。

位置引数	説明
resourceSize	s、m、l、xl、xxl のいずれか（デフォルト：s）

goldsky pipeline resize my-pipeline l

goldsky pipeline validate [config-path]

デプロイせずにパイプラインの YAML 設定を検証します。

フラグ	型	説明
--definition	string	(非推奨) インライン JSON 定義
--definition-path	string	(非推奨) JSON／YAML 定義へのパス

goldsky pipeline validate my-pipeline.yaml

goldsky pipeline export [name]

パイプラインの設定をエクスポートします。

フラグ	型	説明
--all	boolean	すべてのパイプラインの設定をエクスポートします

goldsky pipeline cancel-update <nameOrConfigPath>

実行中の更新リクエストまたはスナップショットリクエストをキャンセルします。時間のかかるスナップショットによって必要な更新がブロックされている場合に便利です。

グローバルオプション以外に追加のフラグはありません。

goldsky pipeline create <name> (対話型／ガイド付き)

パイプラインを対話形式で作成するための、ガイド付き CLI 操作です。

フラグ	型	説明
--resource-size, --resourceSize	s | m | l | xl | xxl	リソースサイズ（デフォルト：s）
--use-dedicated-ip	boolean	専用のエグレス IP を使用します（デフォルト：false）
--skip-transform-validation	boolean	変換の検証をスキップします
--status	ACTIVE | INACTIVE	(非推奨。pipeline start/stop/pause を使用してください)
--description	string	(非推奨。pipeline apply を使用してください)
--definition	string	(非推奨。pipeline apply を使用してください)
--definition-path	string	(非推奨。pipeline apply を使用してください)
--output, --outputFormat	json | table | yaml	出力形式（デフォルト：yaml）

goldsky pipeline get-definition <name> (非推奨)

共有可能なパイプライン定義を取得します。代わりに goldsky pipeline get <name> --definition を使用してください。

スナップショットコマンド

# List snapshots for a pipeline
goldsky pipeline snapshots list <nameOrConfigPath> [-v <version>]

# Create a snapshot manually
goldsky pipeline snapshots create <nameOrConfigPath>

snapshots list は、パイプラインのバージョンで絞り込む -v, --version をサポートしています（デフォルト：すべてのバージョン）。

---

ライフサイクルのクイックリファレンス

操作	コマンド
デプロイ／開始	goldsky pipeline apply <file.yaml> --status ACTIVE
開始（既存）	goldsky pipeline start <name>
一時停止（スナップショットあり）	goldsky pipeline pause <name>
停止（スナップショットなし）	goldsky pipeline stop <name>
再起動（設定変更なし）	goldsky pipeline restart <name> --from-snapshot last
設定を更新	goldsky pipeline apply <file.yaml>（先に YAML を編集してください）
サイズ変更	goldsky pipeline resize <name> <size>
YAML を検証	goldsky pipeline validate <file.yaml>
監視	goldsky pipeline monitor <name>
設定を取得	goldsky pipeline get <name> --definition
設定をエクスポート	goldsky pipeline export <name>
削除	goldsky pipeline delete <name> -f
実行中の操作をキャンセル	goldsky pipeline cancel-update <name>
スナップショットを一覧表示	goldsky pipeline snapshots list <name>
スナップショットを作成	goldsky pipeline snapshots create <name>
すべてのパイプラインを一覧表示	goldsky pipeline list

一時停止と停止の違い：

• pause — スナップショットを作成してパイプラインを一時停止します（ステータス：PAUSED + TERMINATED）。中断したところから再開できます。
• stop — スナップショットを作成せずに停止します（ステータス：INACTIVE + TERMINATED）。再開するとデータが再処理される場合があります。

目標ステータス： ACTIVE、INACTIVE、PAUSED
実行時ステータス： STARTING、RUNNING、FAILING、TERMINATED

---

スナップショット

スナップショットは、実行中のパイプラインの特定時点の状態を記録し、再開に使用します。ソースの読み取り進捗と SQL 変換の状態が含まれますが、シンクの状態は含まれません。

• 自動スナップショットは、正常に稼働している RUNNING 状態のパイプラインに対して 4 時間ごとに作成されます。
• 更新前： RUNNING 状態のパイプラインに設定変更を適用する前に、スナップショットが自動的に作成されます。
• 一時停止時： 一時停止すると、スナップショットが作成されます。
• 手動： goldsky pipeline snapshots create <name>。
• 再開： 使用できるのは最新のスナップショットのみです。古いスナップショットについては、サポートにお問い合わせください。

--from-snapshot フラグ（apply、start、restart で使用）で、スナップショットの動作を制御します。

• new — 新しいスナップショットを作成して、そこから開始します（デフォルト）
• last — 既存の最新スナップショットを使用します（新しいスナップショットは作成しません）
• none — スナップショットなしで、最初から開始します
• <snapshot-id> — 指定したスナップショットを使用します

---

リソースサイズ

YAML の resource_size または goldsky pipeline resize <name> <size> で設定します。

サイズ	説明
s	デフォルト。ほとんどのユースケース、小規模チェーンのバックフィル、最大 300K 件／秒、最大約 8 個のサブグラフソースに対応します
m、l、xl、xxl	より大きなコンピューティング能力。大規模チェーンのバックフィルや大規模な JOIN 向けです

小さいサイズから始め、必要に応じてスケールアップしてください。リソースサイズは料金に影響します。

---

ネットワーキング

• ミラーパイプラインは AWS us-west-2 からデータを書き込みます。シンクでこのリージョンからの受信接続を許可してください。
• IP アドレスはデフォルトで動的です。
• 専用のエグレス IP はリクエストに応じて利用できます。pipeline create で --use-dedicated-ip を使うか、[email protected] にお問い合わせください。
• VPC ピアリングはリクエストに応じて利用できます。
• 外部ハンドラートランスフォームを使用する場合は、パフォーマンスを最大限に高めるため、us-west-2 の近くにデプロイしてください（p95 < 100ms を目標にします）。

---

データセットの検出

# List available datasets (non-interactive)
goldsky dataset list --output json

# Get schema for a specific dataset
goldsky dataset get <dataset_name>

---

よくある質問

Mirror パイプラインでサブグラフをソースとして使用できますか？ はい。これは Turbo に対する Mirror の最大の利点です。ソースに type: subgraph_entity を設定し、デプロイ済みのサブグラフを指定してください。

Mirror で複数のソースやクロスチェーンデータを扱えますか？ はい。YAML で複数のソースを定義し、SQL トランスフォームを使用して結合またはマージできます。サブグラフの場合は、1 つのソースの subgraphs 配列に複数のサブグラフ（異なるチェーン）を指定できます。

パイプラインにもっとリソースが必要です／動作が遅すぎます。 goldsky pipeline resize <name> l（または xl、xxl）を実行してください。小さいサイズから始めて、必要に応じてスケールアップします。

パイプラインが ACTIVE なのに TERMINATED です。何が起きたのでしょうか？ 希望するステータスは ACTIVE ですが、ランタイムでエラーが発生しています（例：シークレットの誤り、シンクが利用できない、リソースの問題）。goldsky pipeline monitor <name> --include-runtime-details でエラーを確認するか、ダッシュボードを確認してください。問題を修正してから再起動します。

進捗を失わずにパイプラインを更新するにはどうすればよいですか？ YAML を編集し、goldsky pipeline apply <file.yaml> を実行してください。デフォルトでは、更新の適用前にスナップショットが作成されます。新しいスナップショットの作成を省略して最新の既存スナップショットを使用するには、--from-snapshot last を指定してください。

時間のかかるスナップショットが更新を妨げています。どうすればよいですか？ goldsky pipeline cancel-update <name> を実行して進行中の操作をキャンセルし、その後 --from-snapshot last または --from-snapshot none を指定して再適用してください。

---

関連項目

• /turbo-builder — 新しい Turbo パイプラインを構築します（サブグラフソースを使用しない新規プロジェクトに推奨）
• /subgraph-builder — Mirror で同期するサブグラフを構築してデプロイします
• /secrets — シンクの認証情報用のシークレットを作成します
• /datasets — 利用可能なデータセット名とチェーンのプレフィックスを確認します
• Goldsky のドキュメント： docs.goldsky.com/mirror/introduction
• パイプライン設定のリファレンス： docs.goldsky.com/mirror/reference/config-file/pipeline