Apache DataFusion 常用 CLI 命令与工具详解

Apache DataFusion 提供两种常用交互方式：命令行工具 datafusion-cli（可直接跑 SQL、读取数据文件）与 Python 绑定 API（在应用中嵌入查询引擎）。本文汇总两者的常用命令、元命令与方法，所有回显基于 Apache DataFusion 55.2.0 / Python 绑定 48.0.0 实测环境。

一、datafusion-cli 概述与启动

datafusion-cli 是 DataFusion 的官方命令行客户端，支持交互式 REPL 与一次性命令执行，可查询 CSV/Parquet/JSON 等文件、执行 DDL/DML 与元命令。启动方式：

$ datafusion-cli                 # 进入交互式 REPL
$ datafusion-cli -p /root        # 指定数据目录后进入 REPL
$ datafusion-cli -c "SELECT 1;"  # 执行单条命令后退出
$ datafusion-cli -f query.sql    # 执行脚本文件后退出

二、启动参数速查

datafusion-cli --help 实测输出整理如下：

参数	默认	说明
`-p, --data-path <PATH>`	当前目录	数据文件基准目录
`-b, --batch-size <N>`	引擎默认(8192)	每批行数
`-c, --command [<CMD>...]`	—	执行命令串后退出，可重复
`-f, --file [<FILE>...]`	—	执行脚本文件后退出
`-r, --rc [<RC>...]`	`~/.datafusionrc`	启动时加载的脚本
`-m, --memory-limit <SIZE>`	无限制	内存上限，如 `10g`
`-d, --disk-limit <SIZE>`	100g	溢写磁盘上限
`--mem-pool-type <T>`	greedy	内存池类型
`--format <FMT>`	automatic	输出格式 csv/tsv/table/json/nd-json
`-q, --quiet`	关闭	仅打印结果
`--maxrows <N>`	40	表格显示最大行数

示例：指定数据目录并静默执行聚合与 JOIN：

$ datafusion-cli -p /root -q -f /root/queries.sql
+---------+-----+------------+
| dept_id | cnt | avg_salary |
+---------+-----+------------+
| 10      | 2   | 6000.0     |
| 20      | 1   | 6000.0     |
| 30      | 1   | 8000.0     |
+---------+-----+------------+

三、元命令（meta-commands）

在交互式 REPL 中输入 \? 可列出全部元命令，实测输出：

$ printf "%s\n" "\?" | datafusion-cli
+----------------------------------+------------------------------+
| Command                          | Description                  |
+----------------------------------+------------------------------+
| \d                               | list tables                  |
| \d name                          | describe table               |
| \q                               | quit datafusion-cli          |
| \?                               | help                         |
| \i filename                      | reads input from the file    |
| \h                               | function list                |
| \h function                      | search function              |
| \quiet (true|false)?             | print or set quiet mode      |
| \pset [NAME [VALUE]]             | set table output option      |
| \object_store_profiling (...)    | set object store profile     |
+----------------------------------+------------------------------+

3.1 \d 与 \d name

\d 列出当前 catalog 下的表；\d <name> 描述指定表的列结构。实测：

<\d>            # 列出表（含 information_schema 视图）
+---------------+--------------------+-------------+------------+
| table_catalog | table_schema       | table_name  | table_type |
+---------------+--------------------+-------------+------------+
| datafusion    | public             | employees   | BASE TABLE |
| datafusion    | information_schema | tables      | VIEW       |
| ...           | information_schema | ...         | VIEW       |
+---------------+--------------------+-------------+------------+
<\d employees>  # 描述表字段
+---------------+--------------+------------+-------------+-----------+-------------+
| table_catalog | table_schema | table_name | column_name | data_type | is_nullable |
+---------------+--------------+------------+-------------+-----------+-------------+
| datafusion    | public       | employees  | id          | Int64     | YES         |
| datafusion    | public       | employees  | name        | Utf8      | YES         |
| datafusion    | public       | employees  | dept_id     | Int64     | YES         |
| datafusion    | public       | employees  | salary      | Int64     | YES         |
+---------------+--------------+------------+-------------+-----------+-------------+

3.2 \h 帮助与 \i 读文件

\h：列出可查询帮助的 SQL 命令（CREATE TABLE、DROP TABLE、EXPLAIN、INSERT、SELECT、SHOW 等）。
\h SHOW：查看具体语法，实测：

$ printf "%s\n" "\h SHOW" | datafusion-cli
Command:     SHOW
Description: show the value of a run-time parameter
Syntax:
SHOW name

\i filename：从文件读取并执行命令。
\quiet true|false、\pset format csv：切换静默模式与输出格式。
\q：退出 REPL。

四、SQL 查询类命令

4.1 SHOW TABLES 与 SHOW <配置项>

$ datafusion-cli -q -c "SHOW TABLES;"          # 等价于 \d 的表列表
$ datafusion-cli -q -c "SHOW datafusion.execution.batch_size;"
| datafusion.execution.batch_size | 8192  |

4.2 DESCRIBE 与 EXPLAIN

DESCRIBE <table> 查看表结构；EXPLAIN <query> 输出查询计划（物理计划）。实测：

$ datafusion-cli -q -c "EXPLAIN SELECT 1;"
+---------------+-------------------------------+
| plan_type     | plan                          |
+---------------+-------------------------------+
| physical_plan | ┌───────────────────────────┐ |
|               | │       ProjectionExec      │ |
|               | │        Int64(1): 1        │ |
|               | └─────────────┬─────────────┘ |
|               | ┌─────────────┴─────────────┐ |
|               | │     PlaceholderRowExec    │ |
|               | └───────────────────────────┘ |
+---------------+-------------------------------+

EXPLAIN ANALYZE 会在执行后附带运行指标（如耗时、行数）。

五、直接查询数据文件

无需建表即可查询文件，路径支持相对 --data-path 或绝对路径：

$ datafusion-cli -p /root -q -c "SELECT dept_id, AVG(salary) FROM 'employees.csv' GROUP BY dept_id;"
$ datafusion-cli -q -c "SELECT * FROM '/root/sales.parquet' LIMIT 5;"

也可建外部表后反复使用：

CREATE EXTERNAL TABLE employees STORED AS CSV
LOCATION '/root/employees.csv'
OPTIONS ('format.has_header' 'true');
SELECT * FROM employees LIMIT 2;

六、Python API 速查

6.1 SessionContext 常用方法

SessionContext 是查询入口，负责注册表、执行 SQL。实测 48.0.0 暴露的主要方法：

方法	说明
`SessionContext(config=None)`	创建会话，可传入 `SessionConfig`
`sql(query)`	执行 SQL，返回 `DataFrame`
`register_csv(name, path, has_header=True)`	注册 CSV 表
`read_csv(path)` / `read_parquet(path)`	读取文件并直接返回 `DataFrame`
`register_parquet(name, path)`	注册 Parquet 表
`register_record_batches(name, batches)`	注册 Arrow 记录批次
`from_pandas(df)` / `from_pydict(d)` / `from_pylist(l)`	由 Python 对象建表
`from_arrow(tbl)` / `from_arrow_table(tbl)`	由 Arrow 表建表
`register_view(name, sql)`	注册视图
`register_udf/udaf/udtf/udwf`	注册自定义函数
`execute(sql)` / `tables()` / `deregister_table(name)`	执行/枚举/注销

6.2 DataFrame 常用方法

方法	说明
`show(n=…)`	以表格打印结果
`collect()`	执行并返回 RecordBatch 列表
`to_pandas()`	转为 pandas DataFrame
`to_arrow_table()` / `to_pydict()` / `to_pylist()`	转 Arrow/字典/列表
`explain()` / `logical_plan()` / `optimized_logical_plan()`	计划相关
`filter()` / `select()` / `aggregate()` / `join()` / `sort()`	链式算子
`write_csv()` / `write_parquet()`	写出结果

最小示例：

from datafusion import SessionContext
ctx = SessionContext()
ctx.register_csv("employees", "/root/employees.csv", has_header=True)
df = ctx.sql("SELECT dept_id, COUNT(*) AS cnt FROM employees GROUP BY dept_id")
print(df.to_pandas())

七、命令与 API 速查表

场景	CLI	Python
执行 SQL	`-c "SELECT ..."`	`ctx.sql("SELECT ...")`
执行脚本	`-f file.sql`	逐条 `ctx.sql(...)`
列出表	`\d` / `SHOW TABLES;`	`ctx.tables()`
描述表	`\d name` / `DESCRIBE name;`	`df.schema()`
查看计划	`EXPLAIN <sql>`	`df.explain()`
读 CSV	`SELECT * FROM 'x.csv'`	`ctx.read_csv("x.csv")`
读 Parquet	`SELECT * FROM 'x.parquet'`	`ctx.read_parquet("x.parquet")`
输出 CSV	`--format csv`	`df.write_csv()`
转 pandas	—	`df.to_pandas()`
退出/资源	`\q`	`del ctx`