关于PyArrow中pyarrow.parquet与pyarrow.dataset的疑问及困惑

读取Parquet数据集时存在两种方式：

type1 = pyarrow.parquet.ParquetDataset("Pqfolder/", use_legacy_dataset=False)
# or
type2 = pyarrow.dataset.dataset('Pqfolder/', format='parquet')

模块归属与API结构问题 #

• pyarrow.parquet 和 pyarrow.dataset 都是PyArrow的一级子模块，并非嵌套在pyarrow.api下。PyArrow的API按功能领域划分一级子模块：
  • pyarrow.parquet 专注Parquet格式专属的读写、元数据处理等功能；
  • pyarrow.dataset 是通用数据集抽象层，支持多格式（Parquet、CSV等）的统一处理。
    这种设计让不同功能领域的API边界清晰，用户可直接按需导入对应模块，无需中间层级跳转。

保留pyarrow.parquet的意义 #

尽管pyarrow.dataset提供了更灵活的过滤能力（比如Scanner的表达式过滤），pyarrow.parquet仍有不可替代的价值：

• Parquet专属深度功能：包含大量Parquet格式特有的操作，比如精细控制压缩编码、页大小、字典编码等写入参数，或直接操作Parquet文件元数据（修改统计信息、合并元数据），这些是通用dataset模块不会覆盖的。
• 兼容性与迁移成本：早期PyArrow仅提供pyarrow.parquet模块，大量现有代码依赖它。保留该模块可避免用户大规模修改代码，保证向后兼容。
• 轻量场景适配：对于仅需简单读写单个Parquet文件或小数据集的场景，pyarrow.parquet的API更直接，无需引入通用数据集抽象的额外复杂度。

软件设计参考资料 #

PyArrow的API设计遵循Apache Arrow项目的整体架构理念，可参考：

• Apache Arrow官方设计文档：项目仓库docs/design目录下有模块划分、API演进的详细讨论，涵盖数据集抽象和Parquet模块的设计初衷。
• PyArrow版本发布说明：每个大版本的更新文档会说明API演进逻辑，比如dataset模块的引入背景与定位，能帮你理解功能冗余背后的迭代原因。
• Apache Arrow社区会议记录：其中会讨论API设计的决策过程，可了解开发团队对功能覆盖与兼容性的权衡思路。

内容的提问来源于stack exchange，提问作者ThePunisher