# elephant

**Repository Path**: psdnfu/elephant

## Basic Information

- **Project Name**: elephant
- **Description**: # elephant

Spark-SQL CLI + CSV/Parquet 数据处理，基于 Rust + Arrow 54 + Parquet 54（v0.16.1）。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# elephant

Spark-SQL CLI + CSV/Parquet 数据处理，基于 Rust + Arrow 54 + Parquet 54（v0.18.0）。

**workspace**: `elephant-common` + `elephant-storage` + `elephant-session` + `elephant` CLI binary

## 仓库

| 平台 | 地址 |
|------|------|
| Gitee (码云) | https://gitee.com/wanxiangtech/elephant |
| GitHub | https://github.com/wanxiangtech/elephant |

```bash
# Gitee
git clone https://gitee.com/wanxiangtech/elephant.git

# GitHub
git clone https://github.com/wanxiangtech/elephant.git
```

## CLI 子命令


| 子命令      | 说明                                                 |
| -------- | -------------------------------------------------- |
| `run`    | 执行 YAML 流水线（16 种算子 + `operation: sql`）             |
| `sql`    | 执行单条 Spark-SQL（位置参数 / `-f` / stdin）；`--tui` 启动交互界面 |
| `env`    | 管理工作区 `env.toml`（`init` / `get` / `set` / `info`）  |
| `remote` | 管理 SFTP/FTP 远程连接                                   |


无子命令时打印 help 并退出（exit 2）。

## 快速开始

```sh
# 编译
cargo build --release

# 执行 SQL（位置参数）
cargo run -- sql "SHOW TABLES"

# 从文件执行
cargo run -- sql -f query.sql

# 交互式 TUI
cargo run -- sql --tui

# YAML 流水线
cargo run -- run examples/demo_01_filter_sort.yaml -y

# 安装后
cargo install --path . --locked
elephant sql "CREATE TABLE log OPTIONS(path='input/data.csv')"
elephant sql "SELECT * FROM log LIMIT 10"
```

## 支持的 SQL（v1）


| 语句           | 示例                                                                                   |
| ------------ | ------------------------------------------------------------------------------------ |
| SELECT       | `elephant sql "SELECT * FROM log LIMIT 10"`（须先注册表）                                   |
| CREATE VIEW  | `elephant sql "CREATE TEMP VIEW v AS SELECT * FROM log"`（基于已有 table/view）            |
| CREATE TABLE | `elephant sql "CREATE TABLE t OPTIONS(path='/path/data.csv')"` — 文件导入，持久化至 workspace |
| INSERT       | `elephant sql "INSERT OVERWRITE TABLE out SELECT * FROM t"`                          |
| SHOW TABLES  | `elephant sql "SHOW TABLES"`                                                         |
| DROP TABLE   | `elephant sql "DROP TABLE t"` / `DROP TABLE IF EXISTS t`                             |
| DESCRIBE     | `elephant sql "DESCRIBE TABLE t"`                                                    |
| SET          | `elephant sql "SET elephant.shuffle.partitions = 8"`                                 |


**推荐**先用 `CREATE TABLE OPTIONS(path=...)` 注册表名；也支持 `SELECT ... FROM 'path.csv' OPTIONS(...)` 直读文件（见 [SQL_REFERENCE.md](SQL_REFERENCE.md)）。

**WHERE / HAVING** 支持 `IN (1,2)`、`IN ('a','b')`、`IN (SELECT col FROM t)`（非关联子查询）。**不支持** `SELECT 常量, *` 混写（须显式列名）。

**INSERT** 支持 `INSERT INTO t SELECT ...` 及子查询内 `FROM 'path' OPTIONS()`；`INSERT INTO t(c1,c2)` 列列表仅语法合法，不参与列映射。

每次只执行**一条** SQL。完整语法、限制与示例见 [SQL_REFERENCE.md](SQL_REFERENCE.md) 或 TUI `help` / `show function`。

`CREATE TABLE` 分三阶段执行，日志可见各步骤：

1. **read**：CSV/Parquet 读入 `{workspace}/read/{uuid}/` 并按 `shard_size_mb` 分片
2. **shard 入库**：分片 rename 至 `{workspace}/tables/{name}/`，写入 `catalog.toml`
3. **cleanup**：删除已搬空的 `read/{uuid}/`

CLI 输出 **行数** 与 **列类型**；后续查询需使用相同 `--workspace`：

```sh
elephant sql "CREATE TABLE log OPTIONS(path='input/data.csv')"
elephant sql "SELECT * FROM log LIMIT 10"
```

### sql 子命令选项


| 选项                 | 说明                                 |
| ------------------ | ---------------------------------- |
| `SQL`（位置参数）        | 单条 SQL 语句                          |
| `-f, --file FILE`  | 从文件读取 SQL                          |
| （stdin 管道）         | 无参数且 stdin 非 TTY 时读 stdin          |
| `--workspace PATH` | 工作区目录（默认 `./.workspace`）           |
| `--tui`            | 启动交互式 SQL TUI（不可与 SQL 参数或 `-f` 同用） |


## 交互式 TUI（`elephant sql --tui`）

```sh
elephant sql --tui
elephant sql --tui --workspace ./my_ws
```


| 操作          | 说明            |
| ----------- | ------------- |
| F5 / Ctrl+G | 执行输入          |
| Enter       | 换行            |
| ↑ / ↓       | 命令历史（光标在首/末行） |
| Alt+↑/↓     | 滚动输出          |
| Ctrl+L      | 清空输出          |
| q / Ctrl+C  | 退出            |


内置元命令（F5 执行，非 SQL 引擎语法）：


| 命令                  | 说明          |
| ------------------- | ----------- |
| `help`              | SQL 语句与子句参考 |
| `show tables`       | 列出工作区已注册表   |
| `show function`     | 转换函数与聚合函数参考 |
| `drop table <name>` | 删除指定表       |
| `clean cache`       | 清空 SQL 阶段缓存 |

TUI 在启动时创建**一个** `ElephantSession`（`RetainUntilClose` 策略）：同一会话内 `CREATE TEMP TABLE` / 视图在多次 F5 执行之间保持可见；每次执行后**不**清理 read staging。退出 TUI（`q` / Ctrl+C）时调用 `session.shutdown()`，移除内存中的 TEMP 表并清理 `workspace/read/`、`step_*` 等 scratch（保留 `tables/`、`cache/`、`catalog.toml`）。手动回收阶段缓存仍用 `clean cache`。

## AI 辅助开发配置

| 路径 | 用途 |
| ---- | ---- |
| [AGENTS.md](AGENTS.md) | Cursor 等项目入口（4-crate 架构摘要） |
| [.codewhale/](.codewhale/) | CodeWhale TUI：流程、限制、角色 agent |
| [.cursor/rules/](.cursor/rules/) | Cursor 精简规则（架构 / SQL / 工作流） |

版本与文档同步：`./bump-version.sh patch`（见 [version.yaml](version.yaml)）。

## YAML 流水线（`elephant run`）

```sh
elephant run pipeline.yaml -y
elephant run pipeline.yaml --dry-run   # 仅预校验
elephant run pipeline.yaml --resume    # 断点续跑
```

`elephant run` 使用 `PipelineRun` 清理策略：流水线执行过程中保留 read/staging 与 scratch；正常结束（非 `--resume`）时**仅清空** `workspace/cache/` 中的阶段缓存，**不删除** `tables/` 与 `catalog.toml` 中的持久表。单次 `elephant sql "..."` 仍为默认 `OneShot`：每条语句物化后会清理 read staging。