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 的命令行界面——领先的区块链数据平台。使用它可以编写并执行针对链上数据的 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 环境变量和已保存的配置）

输出格式（每个命令的标志）

大多数命令都支持 -o, --output <FORMAT>，取值为 text（默认值，便于人类阅读的表格）或 json（便于机器读取）。

始终对支持该选项的每个命令使用 -o json。与 text 相比，JSON 输出包含更多详细信息（完整的 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