workbenchdata/parquet-to-arrow

parquet-to-arrow 镜像文档

镜像概述

parquet-to-arrow是一个包含静态链接Linux二进制工具的Docker镜像，专为处理Parquet文件设计。提供高效的Parquet文件转换、流式文本输出及文件比较功能，可轻松集成到Docker构建流程中，为容器内应用提供Parquet文件处理能力。

核心功能和特性

包含工具

parquet-to-arrow

• 用途：将Parquet文件转换为Arrow格式
• 用法：parquet-to-arrow input.parquet output.arrow
• 特性：
  • 保留字典编码：Parquet字典直接转换为Arrow字典，确保数据高效表示（参考Arrow官方博客）

parquet-to-text-stream

• 用途：将Parquet文件流式输出为通用文本格式（CSV/JSON）
• 用法：parquet-to-text-stream [OPTIONS] input.parquet <FORMAT> > out.csv（<FORMAT>为csv或json）
• 特性：
  • 内存使用可控：处理大型数据集时仅在内存中保留少量行和所有列字典
  • 快速首字节输出：流式客户端可快速获取结果
  • CSV输出：
    • 符合RFC4180标准
    • null/inf/-inf/NaN输出为空字符串；浮点数格式化为十进制；时间戳采用ISO8601最小字符表示（如"2019-09-24T00Z"）
  • JSON输出：
    • null/inf/-inf/NaN输出为null；浮点数符合ECMAScript标准
    • 时间戳采用ISO8601最小字符表示（如"2019-09-24"）
  • 可选参数：
    • --row-range=100-200：仅处理100-199行（提升速度）
    • --column-range=10-20：仅处理10-19列（提升速度）

parquet-diff

• 用途：比较两个Parquet文件是否完全相等，相等时返回状态码0
• 用法：parquet-diff file1.parquet file2.parquet
• 特性：
  • 内存使用可控：每次仅在内存中保留两列数据
  • 严格检查项：
    • 行组数量和长度
    • 物理类型（如int32与int64视为不同）
    • 逻辑类型（如int8与int16视为不同）
    • 时间戳精度（包括isAdjustedToUTC属性）
    • Unicode字节序列（不考虑Unicode规范等价性）
  • 宽松检查项：
    • 列编码方式（字典编码与普通字符串若值相同则视为相等）
    • 文件版本（Parquet v1.0与v2.0可能被视为相等）
    • null值（[1, null, 2]与另一个相同数组视为相等）

使用场景和适用范围

• Docker环境集成：作为多阶段构建的基础镜像，为应用提供Parquet文件处理工具
• 数据转换：需要将Parquet文件转换为Arrow格式以提高后续处理效率的场景
• 数据导出：需要将Parquet数据流式导出为CSV/JSON格式供外部系统使用的场景
• 数据校验：需要验证Parquet文件内容一致性（如数据管道前后对比）的场景
• 内存敏感环境：处理大型Parquet文件时需要控制内存占用的场景

使用方法和配置说明

Docker集成示例

在Dockerfile中通过多阶段构建集成工具：

dockerfile
# 替换VERSION为最新Git标签版本
FROM workbenchdata/parquet-to-arrow:VERSION AS parquet-to-arrow

FROM debian:buster AS my-normal-build
# ... 常规构建步骤 ...
# 复制工具到目标镜像
COPY --from=parquet-to-arrow /usr/bin/parquet-to-arrow /usr/bin/parquet-to-arrow
COPY --from=parquet-to-arrow /usr/bin/parquet-to-text-stream /usr/bin/parquet-to-text-stream
COPY --from=parquet-to-arrow /usr/bin/parquet-diff /usr/bin/parquet-diff
# ... 常规构建步骤 ...

集成后，容器内程序可直接调用上述工具。

开发指南

构建与测试

使用以下命令构建并运行单元测试：

bash
docker build .

快速开发循环

通过中间镜像启动开发环境，实时修改代码：

bash
# 从构建输出中获取IMAGE_ID
docker run -it --rm --volume "$(pwd):/app" IMAGE_ID bash

挂载本地目录后，可直接在容器内使用make或pytest测试代码变更。

性能基准测试

使用/usr/bin/time进行基础性能测试：

bash
# 构建Release模式镜像
docker build . --target cpp-build

# 测试Parquet转CSV性能（替换big.parquet为测试文件）
docker run -it --rm -v $(pwd):/data \
    $(docker build . --target cpp-build -q) \
    sh -c '/usr/bin/time parquet-to-text-stream /data/big.parquet csv >/dev/null'

性能参考：63MB Parquet文件（含字典编码，100万行，70列）在3.5GHz Intel Skylake处理器上转换为CSV约需3-4秒（2020-09-21测试）。

调试

使用GDB调试工具（以parquet-to-text-stream为例）：

bash
# 构建Debug模式镜像
docker build . --build-arg CMAKE_BUILD_TYPE=Debug --target cpp-build

# 启动GDB调试（替换test.parquet为测试文件）
docker run -it --rm -v $(pwd):/data \
    $(docker build . --build-arg CMAKE_BUILD_TYPE=Debug --target cpp-build -q) \
    gdb --args /usr/bin/parquet-to-text-stream ./test.parquet csv

部署流程

1. 更新CHANGELOG.md记录变更
2. 提交代码：git commit
3. 创建版本标签（遵循语义化版本，如v1.2.3）：git tag VERSION
4. 推送标签和代码：git push --tags && git push
5. 等待Docker Hub自动构建并发布新镜像