dune

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites

前提条件

Assume the Dune CLI is already installed and authenticated. Do not run upfront install or auth checks. Just execute the requested

dune

command directly.

If a

dune

command fails, inspect the error to determine the cause and follow the recovery steps in install-and-recovery.md:

"command not found" → CLI not installed. See CLI Not Found Recovery.
401 / "unauthorized" / "missing API key" → Auth failure. See Authentication Failure Recovery.
Unknown subcommand or flag / unexpected output → Possible version mismatch. See Version Compatibility.

假设 Dune CLI 已完成安装与认证。请勿预先执行安装或认证检查，直接运行用户请求的

dune

命令即可。

若

dune

命令执行失败，请检查错误信息以确定原因，并遵循install-and-recovery.md中的恢复步骤：

“command not found” → CLI未安装，请查看CLI未找到恢复方案。
401 / “unauthorized” / “missing API key” → 认证失败，请查看认证失败恢复方案。
未知子命令或参数 / 意外输出 → 可能存在版本不匹配，请查看版本兼容性。

Dune CLI

A command-line interface for Dune -- the leading blockchain data platform. Use it to write and execute DuneSQL queries against on-chain data, discover datasets, search documentation, and monitor credit usage.

这是面向Dune（领先的区块链数据平台）的命令行界面。可通过它编写并执行针对链上数据的DuneSQL查询、发现数据集、搜索文档，以及监控积分使用情况。

Authentication

认证

All commands except

docs search

require authentication via a Dune API key. The key is resolved in this priority order:

bash

undefined

除

docs search

之外的所有命令，都需要通过Dune API密钥进行认证。密钥的读取优先级如下：

bash

undefined

1. Flag (highest priority -- overrides everything)

1. 命令行参数（优先级最高，覆盖所有其他配置）

dune query run 12345 --api-key <key>

2. Environment variable

2. 环境变量

export DUNE_API_KEY=<key> dune query run 12345

3. Saved config file (lowest priority)

3. 已保存的配置文件（优先级最低）

dune auth --api-key <key> # saves to ~/.config/dune/config.yaml dune query run 12345 # uses saved key


To save your key interactively (prompted from stdin):

```bash
dune auth

Config file location:

~/.config/dune/config.yaml

dune auth --api-key <key> # 保存至 ~/.config/dune/config.yaml dune query run 12345 # 使用已保存的密钥


若要交互式保存密钥（从标准输入获取）：

```bash
dune auth

配置文件路径：

~/.config/dune/config.yaml

Global Flags

全局参数

Flag	Description
`--api-key <KEY>`	Dune API key (overrides `DUNE_API_KEY` env var and saved config)

参数	描述
`--api-key <KEY>`	Dune API密钥（覆盖 `DUNE_API_KEY` 环境变量与已保存的配置）

Output Format (per-command flag)

输出格式（按命令配置的参数）

Most commands support

-o, --output <FORMAT>

with values

text

(default, human-readable tables) or

json

(machine-readable).

Always use
-o json
on every command that supports it. JSON output contains more detail than
text
(full API response objects vs. summarized tables) and is unambiguous to parse. The
text
format is for human terminal use and drops fields.

大多数命令支持

-o, --output <FORMAT>

参数，可选值为

text

（默认，人类可读的表格格式）或

json

（机器可读格式）。

请始终在支持该参数的命令中使用
-o json
。JSON输出包含比
text
格式更多的细节（完整的API响应对象 vs 汇总表格），且解析时无歧义。
text
格式仅适用于人类在终端中使用，会丢弃部分字段。

DuneSQL

Dune uses DuneSQL, a Trino-based SQL dialect, as its query engine. Key points:

All SQL passed to
```
--sql
```
flags or saved queries must be valid DuneSQL
DuneSQL supports standard SQL with extensions for blockchain data types (addresses, hashes, etc.)
See dunesql-cheatsheet.md for common types, functions, patterns, and pitfalls

Use

dune docs search --query "DuneSQL functions"

to look up syntax and functions

Reference docs: Writing Efficient Queries, Functions and Operators

Dune 使用DuneSQL（基于Trino的SQL方言）作为查询引擎。核心要点：

所有通过
```
--sql
```
参数传入的SQL语句或已保存的查询，都必须是有效的DuneSQL语法
DuneSQL支持标准SQL，并扩展了区块链数据类型（地址、哈希等）的相关语法
常见类型、函数、模式与注意事项，请查看dunesql-cheatsheet.md

可使用

dune docs search --query "DuneSQL functions"

查询语法与函数

参考文档：编写高效查询、函数与操作符

Key Concepts

核心概念

Performance Tiers

性能层级

Query execution supports two tiers:

Tier	Flag Value	Description
Medium	`medium` (default)	Standard compute resources. Suitable for most queries.
Large	`large`	Higher compute resources. Use for complex queries, large joins, or heavy aggregations. Costs more credits.

查询执行支持两种层级：

层级	参数值	描述
中等	`medium` （默认）	标准计算资源，适用于大多数查询。
大型	`large`	更高配置的计算资源，适用于复杂查询、大型关联或重度聚合操作，消耗更多积分。

Execution States

执行状态

After submitting a query, the execution progresses through these states:

State	Meaning	Action
`QUERY_STATE_PENDING`	Queued for execution	Wait
`QUERY_STATE_EXECUTING`	Currently running	Wait
`QUERY_STATE_COMPLETED`	Results available	Fetch results
`QUERY_STATE_FAILED`	Execution failed	Check error message; fix SQL and retry
`QUERY_STATE_CANCELLED`	Cancelled by user or system	Re-execute if needed

提交查询后，执行过程会经历以下状态：

状态	含义	操作
`QUERY_STATE_PENDING`	等待执行队列	等待
`QUERY_STATE_EXECUTING`	正在执行	等待
`QUERY_STATE_COMPLETED`	结果已生成	获取结果
`QUERY_STATE_FAILED`	执行失败	检查错误信息；修正SQL后重试
`QUERY_STATE_CANCELLED`	被用户或系统取消	如有需要重新执行

Dataset Categories

数据集分类

Category	Description
`canonical`	Core blockchain data (blocks, transactions, traces, logs)
`decoded`	ABI-decoded contract data (events and function calls)
`spell`	Dune Spellbook transformations (curated, higher-level tables like `dex.trades` )
`community`	Community-contributed datasets

分类	描述
`canonical`	核心区块链数据（区块、交易、追踪记录、日志）
`decoded`	经ABI解码的合约数据（事件与函数调用）
`spell`	Dune Spellbook转换后的数据集（经过整理的高阶表格，如 `dex.trades` ）
`community`	社区贡献的数据集

Dataset Types

数据集类型

Type	Description
`dune_table`	Core Dune-maintained tables
`decoded_table`	Contract ABI-decoded tables
`spell`	Spellbook transformation tables
`uploaded_table`	User-uploaded CSV/data tables
`transformation_table`	Materialized transformation tables
`transformation_view`	Virtual transformation views

类型	描述
`dune_table`	Dune官方维护的核心表格
`decoded_table`	合约ABI解码后的表格
`spell`	Spellbook转换后的表格
`uploaded_table`	用户上传的CSV/数据表格
`transformation_table`	物化转换表格
`transformation_view`	虚拟转换视图

Query Parameters

查询参数

Parameters let you create reusable queries with variable inputs. Pass them as

--param key=value

(repeatable). The API auto-detects the type, but parameters support these types:

text

number

datetime

enum

bash

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

参数可让你创建支持变量输入的可复用查询，通过

--param key=value

传入（可重复使用）。API会自动检测类型，参数支持的类型包括：

text

、

number

、

datetime

、

enum

。

bash

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

Command Overview

命令概览

Command	Description	Auth
`dune auth`	Save API key to config file	No
`dune query create`	Create a new saved query	Yes
`dune query get <id>`	Fetch a saved query's SQL and metadata	Yes
`dune query update <id>`	Update an existing query	Yes
`dune query archive <id>`	Archive a saved query	Yes
`dune query run <id>`	Execute a saved query and wait for results	Yes
`dune query run-sql`	Execute raw DuneSQL directly (no saved query needed)	Yes
`dune execution results <id>`	Fetch results of a previous execution	Yes
`dune dataset search`	Search the Dune dataset catalog	Yes
`dune dataset search-by-contract`	Find decoded tables for a contract address	Yes
`dune docs search`	Search Dune documentation	No
`dune usage`	Show credit and resource usage	Yes

命令	描述	是否需要认证
`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 docs search`	搜索Dune文档	否
`dune usage`	查看积分与资源使用情况	是

Common Workflows

常见工作流

Ad-hoc SQL Analysis

临时SQL分析

bash

undefined

bash

undefined

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

undefined

dune query run-sql --sql "SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5" -o json

undefined

Discover Tables, Then Query

发现表格后执行查询

bash

undefined

bash

undefined

1. Find relevant tables with column schemas

1. 查找包含列结构的相关表格

dune dataset search --query "uniswap swaps" --categories decoded --include-schema -o json

2. Write and execute SQL using discovered table/column names

2. 使用发现的表格/列名编写并执行SQL

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Swap LIMIT 10" -o json

undefined

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Swap LIMIT 10" -o json

undefined

Find Contract Tables, Then Query

查找合约表格后执行查询

bash

undefined

bash

undefined

1. Find decoded tables for a specific contract

1. 查找特定合约对应的已解码表格

dune dataset search-by-contract --contract-address 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 --include-schema -o json

2. Query the discovered tables

2. 查询已发现的表格

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Transfer LIMIT 10" -o json

undefined

dune query run-sql --sql "SELECT * FROM uniswap_v3_ethereum.evt_Transfer LIMIT 10" -o json

undefined

Save and Execute a Reusable Query

保存并执行可复用查询

bash

undefined

bash

undefined

1. Create a saved query with parameters

1. 创建带参数的已保存查询

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

2. 传入参数值执行查询

dune query run <returned-id> --param min_balance=1000 --param row_limit=50 -o json

undefined

dune query run <returned-id> --param min_balance=1000 --param row_limit=50 -o json

undefined

Long-Running Query (Submit and Poll)

长时间运行的查询（提交后轮询）

bash

undefined

bash

undefined

1. Submit without waiting

1. 提交查询但不等待结果

dune query run 12345 --no-wait --performance large -o json

Output: {"execution_id": "01ABC...", "state": "QUERY_STATE_PENDING"}

输出: {"execution_id": "01ABC...", "state": "QUERY_STATE_PENDING"}

2. Check results later

2. 稍后查询结果

dune execution results 01ABC... -o json

undefined

dune execution results 01ABC... -o json

undefined

Limitations

局限性

The following capabilities are available via the Dune MCP server or web UI but not via the CLI:

Visualization creation (charts, counters, tables)
Blockchain listing (list all indexed blockchains with table counts)
Table size analysis (storage size of specific tables)

以下功能可通过Dune MCP服务器或Web UI使用，但无法通过CLI实现：

可视化创建（图表、计数器、表格）
区块链列表（列出所有已索引的区块链及其表格数量）
表格大小分析（特定表格的存储大小）

Security

安全注意事项

Never output API keys or tokens in responses. Before presenting CLI output to the user, scan for strings that look like API keys (e.g. long alphanumeric tokens, strings prefixed with
```
dune_
```
, or values from
```
DUNE_API_KEY
```
). Redact them with
```
[REDACTED]
```
.
Always confirm with the user before running write commands (
```
query create
```
,
```
query update
```
,
```
query archive
```
)
Always use
```
-o json
```
on every command -- JSON output is more detailed and reliably parseable
Use
```
--temp
```
when creating throwaway queries to avoid cluttering the user's saved queries
Never pass
```
--api-key
```
on the command line when other users might see the terminal history. Prefer
```
dune auth
```
or the
```
DUNE_API_KEY
```
environment variable.

绝对不要在响应中输出API密钥或令牌。在向用户展示CLI输出前，请扫描类似API密钥的字符串（例如长字母数字令牌、以
```
dune_
```
开头的字符串，或
```
DUNE_API_KEY
```
对应的取值），并使用
```
[REDACTED]
```
进行脱敏。
在执行写入类命令（
query create
、
query update
、
query archive
）前，请务必与用户确认
请始终在支持该参数的命令中使用
-o json
→ JSON输出更详细且解析可靠
创建临时查询时使用
```
--temp
```
参数，避免占用用户的已保存查询列表
当其他用户可能看到终端历史记录时，绝对不要在命令行中传递
--api-key
参数。优先使用
```
dune auth
```
或
```
DUNE_API_KEY
```
环境变量。

Reference Documents

参考文档

Load the relevant reference when you need detailed command syntax and flags:

Task	Reference
Create, get, update, or archive saved queries	query-management.md
Execute queries (run, run-sql) or fetch execution results	query-execution.md
Search datasets or find tables for a contract address	dataset-discovery.md
Search documentation or check account usage	docs-and-usage.md
DuneSQL types, functions, common patterns, and pitfalls	dunesql-cheatsheet.md
CLI install, authentication, and version recovery	install-and-recovery.md

当需要详细的命令语法与参数说明时，请查看以下参考文档：

任务	参考文档
创建、获取、更新或归档已保存查询	query-management.md
执行查询（run、run-sql）或获取执行结果	query-execution.md
搜索数据集或根据合约地址查找表格	dataset-discovery.md
搜索文档或查看账户使用情况	docs-and-usage.md
DuneSQL的类型、函数、常见模式与注意事项	dunesql-cheatsheet.md
CLI安装、认证与版本恢复	install-and-recovery.md