ParqForge
面向数据工作的 Parquet 查看与探索工具。
[English README](../README.md)
ParqForge 是一个本地运行的 Parquet 工具集，用于查看单个 Parquet 文件和 Hive 分区数据集。项目提供适合脚本和管道使用的
CLI，以及 Windows 优先的桌面查看器。
## 特性
- 查看 schema 和文件元信息：列、类型、可空性、压缩、编码、row groups、行数和分区信息。
- 以树形结构浏览分区数据集，显示 Parquet 文件名、大小和创建时间。
- 使用 `head`、`tail` 和 `cat` 预览数据，行号从 1 开始。
- 同时支持单个 `.parquet` 文件和 `key=value/` 分区目录。
- 支持 Bash、Zsh、Fish、PowerShell 和 Elvish 补全。
- Windows 下使用 ParqForge Desktop 图形界面打开文件和数据集。
- 当前版本以只读为主，不修改 Parquet 数据。
## 安装
### CLI
使用 [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) 安装预编译 CLI：
```sh
cargo binstall parqforge-cli
```
也可以从 [Releases](https://github.com/humbinal/parqforge/releases) 下载对应平台压缩包，并将 `pqx` 加入 `PATH`。Linux
同时提供两类包：
- `*-linux-*-musl.tar.gz`（推荐）：静态链接，不要求服务器安装特定版本的 glibc。
- `*-linux-*-gnu.tar.gz`：动态链接 GNU 版，要求 glibc 2.17 或更高版本。
### Windows 桌面版
使用 WinGet 安装：
```powershell
winget install humbinal.ParqForge
```
也可以从 [Releases](https://github.com/humbinal/parqforge/releases) 下载 MSI 安装包或便携版 bundle。MSI 会安装
`ParqForge.exe` 和 `pqx.exe`，将 `pqx` 加入系统 `PATH`，注册 `.parquet` 文件关联，并创建开始菜单快捷方式。
## 快速开始
```sh
# 查看 schema 和数据集元信息
pqx inspect data.parquet
# 浏览分区数据集
pqx tree dataset/
# 预览数据
pqx head data.parquet -n 20
pqx tail data.parquet -n 20
pqx cat data.parquet -n 5
```
所有命令都支持 `--help`。查看全部命令或某个命令的详细选项：
```sh
pqx --help
pqx inspect --help
pqx tree --help
```
## CLI 命令
| 命令 | 用途 |
|---------------------------|-----------------------------|
| `pqx inspect ` | 查看 schema 和数据集元信息 |
| `pqx tree ` | 以树形结构查看 Parquet 文件 |
| `pqx head ` | 查看前若干行 |
| `pqx tail ` | 查看后若干行 |
| `pqx cat ` | 查看前后数据 |
| `pqx completions ` | 生成 Shell 补全脚本 |
`` 可以是单个 Parquet 文件，也可以是类似 `date=2026-07-19/region=us/` 的 Hive 分区目录。
## Shell 补全
```sh
pqx completions bash
pqx completions zsh
pqx completions fish
pqx completions powershell
pqx completions elvish
```
Bash 临时加载：
```sh
source <(pqx completions bash)
```
PowerShell 临时加载：
```powershell
pqx completions powershell | Out-String | Invoke-Expression
```
`pqx` 只输出补全脚本，不会自动修改 Shell 配置。
## 支持项目
如果 ParqForge 对你的工作有帮助，欢迎支持项目的持续开发。赞助完全自愿，主要用于项目维护、文档完善、测试以及后续功能改进。
中国用户可以扫描对应的二维码进行支持：
| 微信支付 |
|-----------------------------------------------------------------------|
| 微信扫一扫，请作者喝杯咖啡 ☕ |
| 
|
| 支付宝 |
|-----------------------------------------------------------------|
| 支付宝扫一扫，请作者喝杯咖啡 ☕ |
| 
|
## 许可证
Apache-2.0，详见 [LICENSE](../LICENSE)。