dune

前提条件

Dune CLI はすでにインストールされ、認証済みであるものとします。事前のインストール確認や認証確認は実行しないでください。要求された dune コマンドを直接実行してください。

dune コマンドが失敗した場合は、エラーを調べて原因を特定し、install-and-recovery.md の復旧手順に従ってください。

• 「command not found」 → CLI がインストールされていません。CLI Not Found Recovery を参照してください。
• 401／「unauthorized」／「missing API key」 → 認証に失敗しています。Authentication Failure Recovery を参照してください。
• 不明なサブコマンドまたはフラグ／予期しない出力 → バージョンの不一致が考えられます。Version Compatibility を参照してください。

Dune CLI

Dune 用のコマンドラインインターフェースです。Dune は、主要なブロックチェーンデータプラットフォームです。これを使って、オンチェーンデータに対する DuneSQL クエリの作成と実行、データセットの検出、ドキュメントの検索、クレジット使用量の監視を行えます。

認証

docs search を除くすべてのコマンドには、Dune API キーによる認証が必要です。キーは次の優先順位で解決されます。

# 1. Flag (highest priority -- overrides everything)
dune query run 12345 --api-key <key>

# 2. Environment variable
export DUNE_API_KEY=<key>
dune query run 12345

# 3. Saved config file (lowest priority)
dune auth --api-key <key>        # saves to ~/.config/dune/config.yaml
dune query run 12345              # uses saved key

キーを対話形式で保存するには（標準入力からの入力を求められます）：

dune auth

設定ファイルの場所：~/.config/dune/config.yaml

グローバルフラグ

フラグ	説明
--api-key <KEY>	Dune API キー（DUNE_API_KEY 環境変数および保存済み設定を上書きします）

出力形式（コマンドごとのフラグ）

ほとんどのコマンドは、値に text（デフォルト。人が読みやすい表形式）または json（機械可読形式）を指定する -o, --output <FORMAT> をサポートしています。

サポートされているすべてのコマンドで、常に -o json を使用してください。 JSON 出力は text より多くの詳細情報を含み（要約された表ではなく、API 応答オブジェクト全体を返します）、曖昧さなく解析できます。text 形式は人がターミナルで使うためのもので、フィールドが省略されます。

DuneSQL

Dune では、クエリエンジンとして Trino ベースの SQL 方言である DuneSQL を使用します。主な点は次のとおりです。

• --sql フラグに渡す SQL や保存済みクエリは、すべて有効な DuneSQL である必要があります
• DuneSQL は標準 SQL に、ブロックチェーンデータ型（アドレス、ハッシュなど）の拡張を加えたものです
• 一般的な型、関数、パターン、注意点については dunesql-cheatsheet.md を参照してください
• dune docs search --query "DuneSQL functions" を使用して、構文や関数を調べてください
• リファレンスドキュメント：Writing Efficient Queries、Functions and Operators

主な概念

パフォーマンス階層

利用可能な階層：small、medium、large。デフォルトでは --performance を渡さないでください。省略すると API が自動的に選択します。次の場合にのみ指定してください。

• ユーザーが明示的に階層を指定した場合
• クエリが明らかに複雑な場合（大規模な結合や集計など）
• 前回の実行でタイムアウトまたはリソース制限エラーが返された場合

実行状態

クエリを送信すると、実行は次の状態を経て進みます。

状態	意味	アクション
QUERY_STATE_PENDING	実行待ちのキューに入っています	待機
QUERY_STATE_EXECUTING	現在実行中です	待機
QUERY_STATE_COMPLETED	結果を利用できます	結果を取得
QUERY_STATE_FAILED	実行に失敗しました	エラーメッセージを確認し、SQL を修正して再試行
QUERY_STATE_CANCELLED	ユーザーまたはシステムによってキャンセルされました	必要に応じて再実行

データセットのカテゴリ

カテゴリ	説明
canonical	ブロック、トランザクション、トレース、ログなどの中核的なブロックチェーンデータ
decoded	ABI デコード済みのコントラクトデータ（イベントや関数呼び出し）
spell	Dune Spellbook による変換（dex.trades のような、キュレーション済みの高レベルなテーブル）
community	コミュニティが提供するデータセット

データセットの種類

種類	説明
dune_table	Dune が管理するコアテーブル
decoded_table	コントラクト ABI でデコードされたテーブル
spell	Spellbook の変換テーブル
uploaded_table	ユーザーがアップロードした CSV／データテーブル
transformation_table	マテリアライズされた変換テーブル
transformation_view	仮想変換ビュー

クエリパラメーター

パラメーターを使うと、変数入力を含む再利用可能なクエリを作成できます。--param key=value として渡します（複数回指定できます）。API は型を自動検出しますが、パラメーターでは次の型をサポートしています：text、number、datetime、enum。

dune query run 12345 --param wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --param days=30 -o json

コマンドの概要

コマンド	説明	認証
dune auth	API キーを設定ファイルに保存	不要
dune query create	新しい保存済みクエリを作成	必要
dune query get <id>	保存済みクエリの SQL とメタデータを取得	必要
dune query update <id>	既存のクエリを更新	必要
dune query archive <id>	保存済みクエリをアーカイブ	必要
dune query run <id>	保存済みクエリを実行し、結果を待機	必要
dune query run-sql	生の DuneSQL を直接実行（保存済みクエリは不要）	必要
dune execution results <id>	以前の実行結果を取得	必要
dune dataset search	Dune データセットカタログを検索	必要
dune dataset search-by-contract	コントラクトアドレスに対応するデコード済みテーブルを検索	必要
dune viz create	保存済みクエリに対する可視化を作成	必要
dune viz get <id>	可視化の詳細とオプションを取得	必要
dune viz list	クエリのすべての可視化を一覧表示	必要
dune viz update <id>	既存の可視化を更新	必要
dune viz delete <id>	可視化を完全に削除	必要
dune docs search	Dune のドキュメントを検索	不要
dune usage	クレジットとリソースの使用状況を表示	必要
dune dashboard create	新しいダッシュボードを作成	必要
dune dashboard get <id>	ダッシュボードのメタデータとウィジェットを取得	必要
dune dashboard update <id>	既存のダッシュボードを更新	必要
dune dashboard archive <id>	ダッシュボードをアーカイブ	必要

一般的なワークフロー

アドホックな SQL 分析

# Run a one-off query directly
dune query run-sql --sql "SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5" -o json

テーブルを見つけてからクエリを実行

# 1. Find relevant tables with column schemas
dune dataset search --query "uniswap swaps" --categories decoded --include-schema -o json

# 2. Write and execute SQL using discovered table/column names
dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Swap LIMIT 10" -o json

コントラクトのテーブルを見つけてからクエリを実行

# 1. Find decoded tables for a specific contract
dune dataset search-by-contract --contract-address 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 --include-schema -o json

# 2. Query the discovered tables
dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Transfer LIMIT 10" -o json

再利用可能なクエリを保存して実行

# 1. Create a saved query with parameters
dune query create --name "Top Wallets" --sql "SELECT address, balance FROM ethereum.balances WHERE balance > {{min_balance}} LIMIT {{row_limit}}" -o json

# 2. Run it with parameter values
dune query run <returned-id> --param min_balance=1000 --param row_limit=50 -o json

長時間実行クエリ（送信してポーリング）

# 1. Submit without waiting
dune query run 12345 --no-wait --performance large -o json
# Output: {"execution_id": "01ABC...", "state": "QUERY_STATE_PENDING"}

# 2. Check results later
dune execution results 01ABC... -o json

ダッシュボードをゼロから作成

# 1. Create queries for each section
QUERY_ID=$(dune query create --name "Daily Volume" --sql "SELECT date_trunc('day', block_time) AS day, SUM(amount) AS volume FROM trades GROUP BY 1 ORDER BY 1" -o json | jq -r '.query_id')

# 2. Execute to verify data
dune query run $QUERY_ID -o json

# 3. Create visualizations for each query
VIZ_ID=$(dune viz create --query-id $QUERY_ID --name "Daily Volume Chart" --type chart --options '{"globalSeriesType":"line","columnMapping":{"day":"x","volume":"y"}}' -o json | jq -r '.id')

# 4. Assemble the dashboard
dune dashboard create --name "Trading Dashboard" \
  --text-widgets '[{"text":"# Trading Dashboard\nDaily volume and metrics"}]' \
  --visualization-ids $VIZ_ID -o json

ダッシュボードを更新（既存のウィジェットを保持）

# 1. Fetch current state
dune dashboard get 12345 -o json > dashboard.json

# 2. Modify as needed (add a new visualization widget)
# 3. Pass the complete widget state back
dune dashboard update 12345 \
  --visualization-widgets '[{"visualization_id":111},{"visualization_id":222},{"visualization_id":333}]' \
  -o json

制限事項

次の機能は Dune MCP サーバーまたは Web UI では利用できますが、CLI では利用できません。

• ブロックチェーンの一覧表示（インデックス済みのすべてのブロックチェーンとテーブル数の一覧表示）
• テーブルサイズ分析（特定のテーブルのストレージサイズ）

セキュリティ

• API キーやトークンを応答に絶対に出力しないでください。 CLI の出力をユーザーに提示する前に、API キーに見える文字列（長い英数字のトークン、dune_ で始まる文字列、DUNE_API_KEY の値など）がないか確認してください。該当する値は [REDACTED] に置き換えてください。
• 書き込みコマンド（query create、query update、query archive、viz create、viz update、viz delete、dashboard create、dashboard update、dashboard archive）を実行する前に、必ずユーザーに確認してください。
• すべてのコマンドで必ず -o json を使用してください。JSON 出力は情報がより詳細で、確実に解析できます。
• 一時的なクエリを作成する場合は --temp を使用し、ユーザーの保存済みクエリが増えないようにしてください。
• 他のユーザーにターミナルの履歴を見られる可能性がある場合、コマンドラインで --api-key を絶対に渡さないでください。dune auth または DUNE_API_KEY 環境変数を使用してください。

参考ドキュメント

コマンドの構文やフラグの詳細を確認する必要がある場合は、該当する参考ドキュメントを読み込んでください。

タスク	参考ドキュメント
保存済みクエリの作成、取得、更新、アーカイブ	query-management.md
クエリの実行（run、run-sql）、または実行結果の取得	query-execution.md
データセットの検索、またはコントラクトアドレスに対応するテーブルの検索	dataset-discovery.md
ドキュメントの検索、またはアカウントの使用状況の確認	docs-and-usage.md
DuneSQL の型、関数、一般的なパターン、注意点	dunesql-cheatsheet.md
保存済みクエリのビジュアライゼーションの作成、取得、更新、削除、一覧表示	visualization-management.md
ダッシュボードの作成、取得、更新、アーカイブ	dashboard-management.md
CLI のインストール、認証、バージョンの復旧	install-and-recovery.md