DuckDB CLI skills

# DuckDB CLI Specialist

帮助通过 DuckDB CLI 进行数据分析、SQL 查询和文件转换。

## 快速开始

### 直接使用 SQL 读取数据文件 ```bash # CSV duckdb -c "SELECT * FROM 'data.csv' LIMIT 10"

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

# Multiple files with glob duckdb -c "SELECT * FROM read_parquet('logs/*.parquet')"

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

### 打开持久化数据库 ```bash # Create/open database duckdb my_database.duckdb

# Read-only mode duckdb -readonly existing.duckdb ```

## 命令行参数

### 输出格式（作为标志） | 标志 | 格式 | |------|--------| | `-csv` | 逗号分隔 | | `-json` | JSON 数组 | | `-table` | ASCII 表格 | | `-markdown` | Markdown 表格 | | `-html` | HTML 表格 | | `-line` | 每行一个值 |

### 执行参数 | 参数 | 描述 | |----------|-------------| | `-c COMMAND` | 运行 SQL 并退出 | | `-f FILENAME` | 从文件运行脚本 | | `-init FILE` | 使用 ~/.duckdbrc 的替代文件 | | `-readonly` | 以只读模式打开 | | `-echo` | 执行前显示命令 | | `-bail` | 遇到第一个错误时停止 | | `-header` / `-noheader` | 显示/隐藏列标题 | | `-nullvalue TEXT` | NULL 值的文本 | | `-separator SEP` | 列分隔符 |

## 数据转换

### CSV 转 Parquet ```bash duckdb -c "COPY (SELECT * FROM 'input.csv') TO 'output.parquet' (FORMAT PARQUET)" ```

### Parquet 转 CSV ```bash duckdb -c "COPY (SELECT * FROM 'input.parquet') TO 'output.csv' (HEADER, DELIMITER ',')" ```

### JSON 转 Parquet ```bash duckdb -c "COPY (SELECT * FROM read_json_auto('input.json')) TO 'output.parquet' (FORMAT PARQUET)" ```

### 带过滤的转换 ```bash duckdb -c "COPY (SELECT * FROM 'data.csv' WHERE amount > 1000) TO 'filtered.parquet' (FORMAT PARQUET)" ```

## 点命令

### 模式检查 | 命令 | 描述 | |---------|-------------| | `.tables [pattern]` | 显示表（使用 LIKE 模式）| | `.schema [table]` | 显示 CREATE 语句 | | `.databases` | 显示已附加的数据库 |

### 输出控制 | 命令 | 描述 | |---------|-------------| | `.mode FORMAT` | 更改输出格式 | | `.output file` | 将输出发送到文件 | | `.once file` | 将下一个输出发送到文件 | | `.headers on/off` | 显示/隐藏列标题 | | `.separator COL ROW` | 设置分隔符 |

### 查询 | 命令 | 描述 | |---------|-------------| | `.timer on/off` | 显示执行时间 | | `.echo on/off` | 执行前显示命令 | | `.bail on/off` | 出错时停止 | | `.read file.sql` | 从文件运行 SQL |

### 编辑 | 命令 | 描述 | |---------|-------------| | `.edit` 或 `\e` | 在外部编辑器中打开查询 | | `.help [pattern]` | 显示帮助 |

## 输出格式（共 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）

### 导航 | 快捷键 | 操作 | |----------|--------| | `Home` / `End` | 行首/行尾 | | `Ctrl+Left/Right` | 跳跃一个词 | | `Ctrl+A` / `Ctrl+E` | 缓冲区开始/结束 |

### 历史 | 快捷键 | 操作 | |----------|--------| | `Ctrl+P` / `Ctrl+N` | 上一个/下一个命令 | | `Ctrl+R` | 搜索历史 | | `Alt+<` / `Alt+>` | 历史记录中第一个/最后一个 |

### 编辑 | 快捷键 | 操作 | |----------|--------| | `Ctrl+W` | 向后删除一个词 | | `Alt+D` | 向前删除一个词 | | `Alt+U` / `Alt+L` | 单词大写/小写 | | `Ctrl+K` | 删除到行尾 |

### 自动补全 | 快捷键 | 操作 | |----------|--------| | `Tab` | 自动补全 / 下一个建议 | | `Shift+Tab` | 上一个建议 | | `Esc+Esc` | 撤销自动补全 |

## 自动补全

按 `Tab` 激活上下文感知自动补全： - **关键词** - SQL 命令 - **表名** - 数据库对象 - **列名** - 字段和函数 - **文件名** - 路径补全

## 数据库操作

### 从文件创建表 ```sql CREATE TABLE sales AS SELECT * FROM 'sales_2024.csv'; ```

### 插入数据 ```sql INSERT INTO sales SELECT * FROM 'sales_2025.csv'; ```

### 导出表 ```sql COPY sales TO 'backup.parquet' (FORMAT PARQUET); ```

## 分析示例

### 快速统计 ```sql SELECT COUNT(*) as count, AVG(amount) as average, SUM(amount) as total FROM 'transactions.csv'; ```

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

### 文件连接 ```sql SELECT a.*, b.name FROM 'orders.csv' a JOIN 'customers.parquet' b ON a.customer_id = b.id; ```

### 描述数据 ```sql DESCRIBE SELECT * FROM 'data.csv'; ```

## 管道和标准输入

```bash # Read from stdin cat data.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

# Pipe to another command duckdb -csv -c "SELECT * FROM 'data.parquet'" | head -20

# Write to stdout duckdb -c "COPY (SELECT * FROM 'data.csv') TO '/dev/stdout' (FORMAT CSV)" ```

## 配置

将常用设置保存在 `~/.duckdbrc` 中： ```sql .timer on .mode duckbox .maxrows 50 .highlight on ```

### 语法高亮颜色 ```sql .keyword green .constant yellow .comment brightblack .error red ```

## 外部编辑器

在编辑器中打开复杂查询： ```sql .edit ```

编辑器选择顺序：`DUCKDB_EDITOR` → `EDITOR` → `VISUAL` → `vi`

## 安全模式

限制文件访问的安全模式。启用后： - 无外部文件访问 - 禁用 `.read`、`.output`、`.import`、`.sh` 等 - **无法**在同一会话中禁用

## 提示

- 对大文件使用 `LIMIT` 进行快速预览 - 对于重复查询，Parquet 比 CSV 更快 - `read_csv_auto` 和 `read_json_auto` 会猜测列类型 - 参数按顺序处理（类似 SQLite CLI） - 在某些 Ubuntu 版本上，WSL2 可能会显示不正确的 `memory_limit` 值