DuckDB CLI 专家

协助通过 DuckDB CLI 进行数据分析、SQL 查询及文件格式转换。

快速入门

直接使用 SQL 读取数据文件

# CSV
duckdb -c "SELECT * FROM 'data.csv' LIMIT 10"

# Parquet
duckdb -c "SELECT * FROM 'data.parquet'"

# 使用通配符读取多个文件
duckdb -c "SELECT * FROM read_parquet('logs/*.parquet')"

# JSON
duckdb -c "SELECT * FROM read_json_auto('data.json')"

打开持久化数据库

# 创建或打开数据库
duckdb my_database.duckdb

# 只读模式打开
duckdb -readonly existing.duckdb

命令行参数

输出格式（作为标志）

执行参数

数据转换

CSV 转 Parquet

duckdb -c "COPY (SELECT * FROM 'input.csv') TO 'output.parquet' (FORMAT PARQUET)"

Parquet 转 CSV

duckdb -c "COPY (SELECT * FROM 'input.parquet') TO 'output.csv' (HEADER, DELIMITER ',')"

JSON 转 Parquet

duckdb -c "COPY (SELECT * FROM read_json_auto('input.json')) TO 'output.parquet' (FORMAT PARQUET)"

带过滤条件的转换

duckdb -c "COPY (SELECT * FROM 'data.csv' WHERE amount > 1000) TO 'filtered.parquet' (FORMAT PARQUET)"

点命令（Dot Commands）

模式检查

输出控制

查询相关命令

编辑相关命令

输出格式（共 18 种）

数据导出

• csv — 适用于电子表格的逗号分隔格式
• tabs — 制表符分隔
• json — JSON 数组
• jsonlines — 每行一个 JSON 对象（流式处理）

可读性格式

• duckbox（默认）— 使用 Unicode 边框字符渲染的美化 ASCII 表格
• table — 简洁 ASCII 表格
• markdown — 适用于文档编写
• html — HTML 表格
• latex — 适用于学术论文

专用格式

• insert TABLE — 生成 SQL INSERT 语句
• column — 按列对齐，支持自定义列宽
• line — 每行一个值
• list — 竖线（|）分隔
• trash — 丢弃所有输出

键盘快捷键（macOS/Linux）

导航

历史记录

编辑

自动补全

自动补全

按 Tab 键激活上下文感知的自动补全功能：

• 关键字 — SQL 命令（如 SELECT、FROM）
• 表名 — 数据库中的对象名称
• 列名 — 字段名与函数名
• 文件名 — 文件路径自动补全

数据库操作

从文件创建表

CREATE TABLE sales AS SELECT * FROM 'sales_2024.csv';

插入数据

INSERT INTO sales SELECT * FROM 'sales_2025.csv';

导出表

COPY sales TO 'backup.parquet' (FORMAT PARQUET);

分析示例

快速统计

SELECT
    COUNT(*) as count,
    AVG(amount) as average,
    SUM(amount) as total
FROM 'transactions.csv';

分组聚合

SELECT
    category,
    COUNT(*) as count,
    SUM(amount) as total
FROM 'data.csv'
GROUP BY category
ORDER BY total DESC;

跨文件联结（JOIN）

SELECT a.*, b.name
FROM 'orders.csv' a
JOIN 'customers.parquet' b ON a.customer_id = b.id;

描述数据结构

DESCRIBE SELECT * FROM 'data.csv';

管道与标准输入（Pipe 和 stdin）

# 从标准输入读取
cat data.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

# 管道传递给其他命令
duckdb -csv -c "SELECT * FROM 'data.parquet'" | head -20

# 写入标准输出
duckdb -c "COPY (SELECT * FROM 'data.csv') TO '/dev/stdout' (FORMAT CSV)"

配置

将常用设置保存在 ~/.duckdbrc 中：

.timer on
.mode duckbox
.maxrows 50
.highlight on

语法高亮颜色配置

.keyword green
.constant yellow
.comment brightblack
.error red

外部编辑器

在本地编辑器中打开复杂查询：

.edit

编辑器按如下优先级选取：DUCKDB_EDITOR → EDITOR → VISUAL → vi

安全模式（Safe Mode）

启用后限制文件访问权限的安全模式。启用时：

• 禁止访问外部文件
• 禁用 .read、.output、.import、.sh 等命令
• 无法在当前会话中关闭该模式

使用技巧

• 对大型文件使用 LIMIT 快速预览结果
• 重复查询场景下，Parquet 性能优于 CSV
• read_csv_auto 与 read_json_auto 可自动推断列类型
• 命令行参数按顺序处理（行为类似 SQLite CLI）
• WSL2 在部分 Ubuntu 版本中可能报告不准确的 memory_limit 值