数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载本文围绕 pylibcudf 的pylibcudf.io.parquet_metadata模块展开。该模块提供了一组不加载数据、只解析 Parquet 文件元数据的 API可用于读取数据集 schema、行数、行组分布、footer 键值元数据以及列块column chunk的 min/max 统计信息。读完本文你将掌握read_parquet_metadata、read_parquet_footers、read_parquet_column_chunk_bounds三个核心函数的用法以及ParquetMetadata、FileMetaData、RowGroup、ColumnChunk等元数据对象模型并理解它们在数据剪枝、元数据预物化与高层 cuDF API 中的实际应用。一、模块定位一份由 automodule 驱动的 API 参考页本文的主题入口是仓库中的 Sphinx 文档页面 parquet_metadata.rst它通过automodule指令自动收集pylibcudf.io.parquet_metadata模块的全部公开成员并渲染其 docstring Parquet Metadata .. automodule:: pylibcudf.io.parquet_metadata :members:也就是说该页面最终的正文内容完全来自模块源码中每个类与函数的 docstring。因此理解这个 API 参考页本质上就是理解 parquet_metadata.pyx 中完整的类型签名与文档注释。该页面同时被 pylibcudf API 索引 收录是 pylibcudf IO 模块文档体系的一部分。模块的公开接口由__all__声明共 14 个成员3 个顶层函数加 11 个元数据对象类型__all__ [ ColumnChunk, ColumnChunkMetaData, ColumnChunkStatistics, FileMetaData, ParquetColumnSchema, ParquetMetadata, ParquetSchema, RowGroup, SchemaElement, SortingColumn, read_parquet_column_chunk_bounds, read_parquet_footers, read_parquet_metadata, ]从源码结构看该模块是 C 层 cudf/io/parquet_metadata.hpp 的 Cython 绑定.pyx负责实现与类型转换parquet_metadata.pxd 声明 Python 侧的类型而 libcudf/io/parquet_metadata.pxd 则直接 cimport C 头文件中的parquet_column_schema、parquet_schema、parquet_metadata三个结构以及三个自由函数。二、三个顶层读取函数模块对外暴露三个读取入口分别面向聚合元数据逐文件 footer与列块统计解码三种场景。1. read_parquet_metadata一次调用拿到数据集级元数据def read_parquet_metadata(src_info: SourceInfo) - ParquetMetadata: ...接受一个 SourceInfo可以封装多个文件路径、FilepathSource或Datasource返回ParquetMetadata对象其中包含Parquet schema含嵌套列根列的行数总行组数与每个文件的行组数footer 中的键值key-value元数据每个行组的元数据各列块column chunk的total_uncompressed_size汇总。在 C 实现中该函数通过 reader_impl.cpp 完成它固定关闭 Arrow schema、不做列投影has_column_projection false、不读 page indexread_page_indexes false只调用aggregate_reader_metadata解析数据源元数据随后用walk_schema把展平的 schema 元素递归构造成嵌套的parquet_column_schema树。这正是只读元数据、不读数据性能特性的来源。2. read_parquet_footers逐文件返回可复用的 FileMetaDatadef read_parquet_footers(src_info: SourceInfo) - list[FileMetaData]: ...与上一个函数不同它返回每个输入源一个FileMetaData对象并且 C 侧会读取 page indexreader_impl.cpp 中read_page_indexes true以便后续复用这些预物化的 footer 元数据。这是预物化元数据pre-materialized metadata工作流的关键入口先读一遍 footer再把它传给pylibcudf.io.parquet.read_parquet或ChunkedParquetReader从而避免读取器内部重复解析 footer。仓库测试 test_parquet.py 演示了这一组合source_info plc.io.SourceInfo([source]) options plc.io.parquet.ParquetReaderOptions.builder(source_info).build() parquet_metadatas plc.io.parquet_metadata.read_parquet_footers(source_info) result plc.io.parquet.read_parquet(options, parquet_metadatasparquet_metadatas)注意parquet_metadatas的数量必须与输入源数量一致否则会抛出ValueError测试 test_read_parquet_with_pre_materialized_metadata_len_mismatch 验证了传入空列表时报错的行为。分块读取器ChunkedParquetReader同样接受parquet_metadatas参数见 parquet.pyi测试 test_chunked_parquet_reader_with_pre_materialized_metadata 证明预物化元数据路径与默认路径产出的分块结果完全一致。3. read_parquet_column_chunk_bounds把 min/max 统计解码成 GPU Tabledef read_parquet_column_chunk_bounds( file_metadatas: Sequence[FileMetaData], columns: Sequence[str], stream: CudaStreamLike | None None, mr: DeviceMemoryResource | None None, ) - Table: ...这是三个函数中唯一产生设备端数据的函数它针对指定的叶子列把每个行组内列块column chunk的 min/max 统计解码为 cuDF 列返回一个Table。返回表的列布局约定如下与 pyx 文档 及 C 头文件 parquet_metadata.hpp 一致第 0 列源文件索引第 1 列文件内行组索引file-local row group index之后每请求一列columns[i]产出两个列min 列位于2 2*imax 列位于3 2*i。缺失的 min/max 统计以 null 表示该函数不解释Parquet 的 min/max exactness 标志即is_min_value_exact/is_max_value_exact只原样保留、不做断言。请求的列名按点分路径dotted leaf-column path解析若路径缺失、有歧义、统计 dtype 不受支持或跨文件 dtype 不一致会抛出std::invalid_argument。测试 test_read_parquet_column_chunk_bounds 给出了完整示例两个文件、每个文件 4 行、row_group_size2因此结果表共 4 行文件索引列为[0, 0, 1, 1]行组索引列为[0, 1, 0, 1]对int64列 min/max 分别输出[1, 3, 10, 30]与[2, 4, 20, 40]字符串列按字典序边界输出时间戳列保持timestamp(us)类型。若写入时禁用了统计write_statisticsFalsemin/max 两列全部为 null。另外两个参数可选stream指定 CUDA 流mr指定设备内存资源不传时分别使用默认流与当前设备内存资源.pyx内部通过_get_stream/_get_memory_resource解析。三、ParquetMetadata 与 schema 对象模型1. ParquetMetadata文件集合的元数据聚合ParquetMetadata封装整个数据集可能多文件的元数据其成员方法如下见 pyx 实现方法返回类型说明schema()ParquetSchema整个数据集的 Parquet schemanum_rows()int根列的行数若含 list 列嵌套列行数可能不同num_rowgroups()int所有文件的行组总数num_rowgroups_per_file()list[int]每个文件各自的行组数metadata()dict[str, str]footer 中的键值元数据rowgroup_metadata()list[dict[str, int]]每个行组的元数据键为字符串、值为整数columnchunk_metadata()dict[str, list[int]]叶子列名 → 该列所有列块total_uncompressed_size的列表ParquetMetadata不能被直接构造——.pyx中所有构造器都会抛出ValueError(Construct ParquetMetadata with from_metadata.)对象只能由read_parquet_metadata内部工厂方法创建。这是 pylibcudf 元数据类共用的模式ParquetSchema、ParquetColumnSchema、FileMetaData等同样禁止直接__init__。2. ParquetSchema 与 ParquetColumnSchema带类型的嵌套 schema 树ParquetSchema提供root()返回一个代表包含所有列作为字段的 struct 列的ParquetColumnSchemacolumn_types()遍历根节点的直接子节点返回dict[str, DataType]即列名到 cuDF 数据类型的映射。ParquetColumnSchema的核心成员name()Parquet 列名可能为空字符串num_children()/child(idx)/children()子列数量、按索引取子列、取全部子列用于递归遍历嵌套类型struct / list / mapcudf_type()该列解析后的 cuDF 数据类型——C 侧由to_type_id/to_data_type依据 Parquet 物理类型physical与逻辑类型logical/converted映射而来见 reader_impl.cpp 与 parquet_metadata.hpp。在高层 cuDF 中cudf.io.parquet.read_parquet_metadata正是利用这套 schema API 提取列名并解析 pandas 索引列信息见 cudf/io/parquet.py它调用plc.io.parquet_metadata.read_parquet_metadata通过parquet_metadata.schema().root().children()收集全部列名再读取parquet_metadata.metadata()[pandas]JSON 字符串判断 range index 与非 range index最终返回(num_rows, num_rowgroups, col_names, len(col_names), rowgroup_metadata)五元组。四、FileMetaData单文件的完整 footer 视图FileMetaData对应单个 Parquet 文件的 footer 解析结果比ParquetMetadata粒度更细包含 schema 元素、行组、列块乃至排序信息。1. from_bytes从裸 footer 字节构建classmethod def from_bytes(cls, footer_bytes: Buffer) - FileMetaData: ...接受任何连续的类字节对象memoryview、bytes等。文档特别强调两点字节会被原样转发给 C 的cudf::io::parquet::experimental::hybrid_scan_readerPython 侧不做任何预处理该方法不会剥离Parquet footer 的后缀4 字节 footer 长度 PAR1magic因此调用方通常应只传入 footer 区域本身。测试 test_file_metadata_from_bytes 对比了纯 footer与带后缀 footer两种输入断言两者的version、num_rows、created_by一致而 test_file_metadata_from_bytes_empty 验证空字节输入会抛出RuntimeError(Cannot initialize schema)。在多文件混合扫描场景中FileMetaData.from_bytes还被用于从外部缓存重建各文件的 footer见 test_experimental_hybrid_scan_multifile.py。2. 属性一览属性类型说明versionintParquet 文件格式版本num_rowsint文件总行数created_bystr生成该文件的应用程序标识schemalist[SchemaElement]深度优先展平的 schema 树首个元素为根row_groupslist[RowGroup]文件内所有行组的元数据row_group_num_rowslist[int]每个行组的行数columnchunk_metadatadict[str, list[int]]点分列路径 → 各列块total_uncompressed_size列表两个快捷属性值得单独说明row_group_num_rows等价于[rg.num_rows for rg in file_metadata.row_groups]但实现上直接索引底层 C 向量更快columnchunk_metadata等价于手工遍历行组与列块、用..join(col.meta_data.path_in_schema)聚合total_uncompressed_size的写法pyx 文档 给出了等价的 Python 参考实现同样因为省去逐层包装而更快。3. SchemaElement展平 schema 树的最小单元schema列表之所以能还原成树依赖每个SchemaElement的num_children——它表示紧随其后处于下一层的元素个数深度优先顺序第一个元素恒为根。SchemaElement的属性name字段名根元素为空字符串num_children子元素个数叶子列为 0field_id写入方记录的原始 schema 字段 ID未记录时为None。五、RowGroup 与 ColumnChunk定位数据在哪、有多大1. RowGroup行组级元数据属性类型说明columnslist[ColumnChunk]该行组内每个列的列块元数据total_byte_sizeint行组未压缩总字节数num_rowsint行组行数sorting_columnslist[SortingColumn] \| None可选的排序顺序元数据file_offsetint \| None行组第一个页面的字节偏移total_compressed_sizeint \| None行组压缩后总字节数ordinalint \| None行组在文件内的序号sorting_columns展开为SortingColumn列表每个元素描述一列的排序信息column_idx行组内列索引、descending是否降序、nulls_firstnull 是否排在非 null 之前。部分字段file_offset、total_compressed_size、ordinal是 Parquet 规范中的可选字段读取方未写入时为None测试 test_file_metadata_row_groups_and_column_chunks 与 PyArrow 的parquet_file.metadata.row_group(rg_idx)逐一比对行数、字节数、列块数量与每列num_values、压缩/未压缩大小确保语义对齐。2. ColumnChunk列块定位信息属性类型说明file_pathstr该列块所在文件的相对路径file_offsetint已弃用的列元数据字节偏移offset_index_offset/offset_index_lengthint该列块 OffsetIndex 在文件中的偏移与字节数column_index_offset/column_index_lengthint该列块 ColumnIndex 在文件中的偏移与字节数schema_idxint在展平 schema 中的派生索引meta_dataColumnChunkMetaData该列块的元数据载荷3. ColumnChunkMetaData列块元数据载荷path_in_schema列路径的各段组件嵌套列会给出多段如[a, b]num_values该列块的值数量total_uncompressed_size/total_compressed_size未压缩 / 压缩后的页面总字节数statisticsColumnChunkStatistics对象。4. ColumnChunkStatisticsmin/max 与计数统计属性类型说明has_min_maxbool是否同时具备编码后的最小值与最大值min_encoded/max_encodedbytes \| None编码后的原始统计载荷需结合该列的物理/逻辑类型解释优先使用min_value/max_value其次回退到已弃用的min/maxnull_countint \| None列块内 null 值数量distinct_countint \| None列块内去重值数量is_min_value_exact/is_max_value_exactbool \| Nonemin_value/max_value是否为精确的列块极值测试 test_file_metadata_columnchunk_statistics 展示了编码规则int64列的 min/max 以小端 8 字节打包struct.pack(q, value)返回字符串列直接返回原始 UTF-8 字节test_file_metadata_columnchunk_statistics_without_minmax 验证未写统计时has_min_max为False、min_encoded/max_encoded/exactness 标志均为None。六、典型应用场景与注意事项1. 数据剪枝前的零数据探查read_parquet_column_chunk_bounds的输出天然适合做行组级谓词剪枝拿到文件索引 行组索引 每列 min/max 后可以在不读取任何数据页的情况下排除不可能命中过滤条件的行组。这正是混合扫描hybrid scan流水线的基础——hybrid_scan_io 示例 与 hybrid_scan.hpp 展示了如何用预物化 footer 驱动后续按需读取。2. 元数据预物化复用先用read_parquet_footers得到FileMetaData列表再将其作为parquet_metadatas参数传给read_parquet或ChunkedParquetReader可避免读取器重复解析 footer——这对反复读取同一批文件例如多轮查询收益明显。3. 与高层 cuDF API 的关系cudf.DataFrame.read_parquet_metadata实现见 cudf/io/parquet.py内部直接调用plc.io.parquet_metadata.read_parquet_metadata因此本文介绍的所有底层行为schema 提取、pandas 元数据解析、行组元数据聚合都会影响高层 API 返回的(num_rows, num_rowgroups, column_names, num_columns, rowgroup_metadata)。4. 使用边界与易错点不可直接构造ParquetMetadata、ParquetSchema、ParquetColumnSchema、FileMetaData、RowGroup、ColumnChunk等类均禁止用户直接__init__必须经由对应读取函数或工厂方法创建columns必须是序列read_parquet_column_chunk_bounds的columns传入单个str会抛TypeError且列表内元素也必须全部为strfooter 后缀问题FileMetaData.from_bytes不剥离PAR1后缀与长度字段调用前需自行切出 footer 区域不过实测传入带后缀字节也能正确解析统计语义min_encoded/max_encoded是原始编码字节而非解引用后的值exactness 标志不会被read_parquet_column_chunk_bounds解释需要精确边界语义时应自行检查is_min_value_exact/is_max_value_exact多文件一致性read_parquet_metadata聚合的是整个数据集跨文件的同名列 dtype 不一致会在统计解码阶段报错。七、进一步阅读模块实现parquet_metadata.pyx、parquet_metadata.pyi、parquet_metadata.pxdC 底层parquet_metadata.hpp、reader_impl.cpp测试用例test_parquet.py预物化元数据、from_bytes、行组/列块/统计、column chunk bounds 各专项测试、test_experimental_hybrid_scan.py文档入口pylibcudf IO API 索引、高层 cuDF 的 io.rst以上路径均可直接在当前仓库中打开结合源码与测试深入验证本文所述的每一个 API 行为。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GPU 加速数据管线pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GP数据分析数据工程机器学习Apache Arrow 统计信息 Schema 规范以 Arrow 数组标准化表达统计信息的完整指南Apache Arrow 统计信息 Schema 规范以 Arrow 数组标准化表达统计信息的完整指南 导读 本文详解 Apache Arrow 官方格式规范人工智能AI Agent工具调用Formily Vue useFieldSchema 完全指南在自定义组件中读取当前字段的 Schema 信息Formily Vue useFieldSchema 完全指南在自定义组件中读取当前字段的 Schema 信息 导读 useFieldSchema 是 For前端UI组件上一篇7个实用技巧掌握folium色彩映射从单值映射到自定义色标完全指南下一篇3个维度重构你的数字伴侣开源框架创意实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pylibcudf Parquet 元数据 API 完全指南：读取 footer、schema 与行组统计信息
数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载本文围绕 pylibcudf 的pylibcudf.io.parquet_metadata模块展开。该模块提供了一组不加载数据、只解析 Parquet 文件元数据的 API可用于读取数据集 schema、行数、行组分布、footer 键值元数据以及列块column chunk的 min/max 统计信息。读完本文你将掌握read_parquet_metadata、read_parquet_footers、read_parquet_column_chunk_bounds三个核心函数的用法以及ParquetMetadata、FileMetaData、RowGroup、ColumnChunk等元数据对象模型并理解它们在数据剪枝、元数据预物化与高层 cuDF API 中的实际应用。一、模块定位一份由 automodule 驱动的 API 参考页本文的主题入口是仓库中的 Sphinx 文档页面 parquet_metadata.rst它通过automodule指令自动收集pylibcudf.io.parquet_metadata模块的全部公开成员并渲染其 docstring Parquet Metadata .. automodule:: pylibcudf.io.parquet_metadata :members:也就是说该页面最终的正文内容完全来自模块源码中每个类与函数的 docstring。因此理解这个 API 参考页本质上就是理解 parquet_metadata.pyx 中完整的类型签名与文档注释。该页面同时被 pylibcudf API 索引 收录是 pylibcudf IO 模块文档体系的一部分。模块的公开接口由__all__声明共 14 个成员3 个顶层函数加 11 个元数据对象类型__all__ [ ColumnChunk, ColumnChunkMetaData, ColumnChunkStatistics, FileMetaData, ParquetColumnSchema, ParquetMetadata, ParquetSchema, RowGroup, SchemaElement, SortingColumn, read_parquet_column_chunk_bounds, read_parquet_footers, read_parquet_metadata, ]从源码结构看该模块是 C 层 cudf/io/parquet_metadata.hpp 的 Cython 绑定.pyx负责实现与类型转换parquet_metadata.pxd 声明 Python 侧的类型而 libcudf/io/parquet_metadata.pxd 则直接 cimport C 头文件中的parquet_column_schema、parquet_schema、parquet_metadata三个结构以及三个自由函数。二、三个顶层读取函数模块对外暴露三个读取入口分别面向聚合元数据逐文件 footer与列块统计解码三种场景。1. read_parquet_metadata一次调用拿到数据集级元数据def read_parquet_metadata(src_info: SourceInfo) - ParquetMetadata: ...接受一个 SourceInfo可以封装多个文件路径、FilepathSource或Datasource返回ParquetMetadata对象其中包含Parquet schema含嵌套列根列的行数总行组数与每个文件的行组数footer 中的键值key-value元数据每个行组的元数据各列块column chunk的total_uncompressed_size汇总。在 C 实现中该函数通过 reader_impl.cpp 完成它固定关闭 Arrow schema、不做列投影has_column_projection false、不读 page indexread_page_indexes false只调用aggregate_reader_metadata解析数据源元数据随后用walk_schema把展平的 schema 元素递归构造成嵌套的parquet_column_schema树。这正是只读元数据、不读数据性能特性的来源。2. read_parquet_footers逐文件返回可复用的 FileMetaDatadef read_parquet_footers(src_info: SourceInfo) - list[FileMetaData]: ...与上一个函数不同它返回每个输入源一个FileMetaData对象并且 C 侧会读取 page indexreader_impl.cpp 中read_page_indexes true以便后续复用这些预物化的 footer 元数据。这是预物化元数据pre-materialized metadata工作流的关键入口先读一遍 footer再把它传给pylibcudf.io.parquet.read_parquet或ChunkedParquetReader从而避免读取器内部重复解析 footer。仓库测试 test_parquet.py 演示了这一组合source_info plc.io.SourceInfo([source]) options plc.io.parquet.ParquetReaderOptions.builder(source_info).build() parquet_metadatas plc.io.parquet_metadata.read_parquet_footers(source_info) result plc.io.parquet.read_parquet(options, parquet_metadatasparquet_metadatas)注意parquet_metadatas的数量必须与输入源数量一致否则会抛出ValueError测试 test_read_parquet_with_pre_materialized_metadata_len_mismatch 验证了传入空列表时报错的行为。分块读取器ChunkedParquetReader同样接受parquet_metadatas参数见 parquet.pyi测试 test_chunked_parquet_reader_with_pre_materialized_metadata 证明预物化元数据路径与默认路径产出的分块结果完全一致。3. read_parquet_column_chunk_bounds把 min/max 统计解码成 GPU Tabledef read_parquet_column_chunk_bounds( file_metadatas: Sequence[FileMetaData], columns: Sequence[str], stream: CudaStreamLike | None None, mr: DeviceMemoryResource | None None, ) - Table: ...这是三个函数中唯一产生设备端数据的函数它针对指定的叶子列把每个行组内列块column chunk的 min/max 统计解码为 cuDF 列返回一个Table。返回表的列布局约定如下与 pyx 文档 及 C 头文件 parquet_metadata.hpp 一致第 0 列源文件索引第 1 列文件内行组索引file-local row group index之后每请求一列columns[i]产出两个列min 列位于2 2*imax 列位于3 2*i。缺失的 min/max 统计以 null 表示该函数不解释Parquet 的 min/max exactness 标志即is_min_value_exact/is_max_value_exact只原样保留、不做断言。请求的列名按点分路径dotted leaf-column path解析若路径缺失、有歧义、统计 dtype 不受支持或跨文件 dtype 不一致会抛出std::invalid_argument。测试 test_read_parquet_column_chunk_bounds 给出了完整示例两个文件、每个文件 4 行、row_group_size2因此结果表共 4 行文件索引列为[0, 0, 1, 1]行组索引列为[0, 1, 0, 1]对int64列 min/max 分别输出[1, 3, 10, 30]与[2, 4, 20, 40]字符串列按字典序边界输出时间戳列保持timestamp(us)类型。若写入时禁用了统计write_statisticsFalsemin/max 两列全部为 null。另外两个参数可选stream指定 CUDA 流mr指定设备内存资源不传时分别使用默认流与当前设备内存资源.pyx内部通过_get_stream/_get_memory_resource解析。三、ParquetMetadata 与 schema 对象模型1. ParquetMetadata文件集合的元数据聚合ParquetMetadata封装整个数据集可能多文件的元数据其成员方法如下见 pyx 实现方法返回类型说明schema()ParquetSchema整个数据集的 Parquet schemanum_rows()int根列的行数若含 list 列嵌套列行数可能不同num_rowgroups()int所有文件的行组总数num_rowgroups_per_file()list[int]每个文件各自的行组数metadata()dict[str, str]footer 中的键值元数据rowgroup_metadata()list[dict[str, int]]每个行组的元数据键为字符串、值为整数columnchunk_metadata()dict[str, list[int]]叶子列名 → 该列所有列块total_uncompressed_size的列表ParquetMetadata不能被直接构造——.pyx中所有构造器都会抛出ValueError(Construct ParquetMetadata with from_metadata.)对象只能由read_parquet_metadata内部工厂方法创建。这是 pylibcudf 元数据类共用的模式ParquetSchema、ParquetColumnSchema、FileMetaData等同样禁止直接__init__。2. ParquetSchema 与 ParquetColumnSchema带类型的嵌套 schema 树ParquetSchema提供root()返回一个代表包含所有列作为字段的 struct 列的ParquetColumnSchemacolumn_types()遍历根节点的直接子节点返回dict[str, DataType]即列名到 cuDF 数据类型的映射。ParquetColumnSchema的核心成员name()Parquet 列名可能为空字符串num_children()/child(idx)/children()子列数量、按索引取子列、取全部子列用于递归遍历嵌套类型struct / list / mapcudf_type()该列解析后的 cuDF 数据类型——C 侧由to_type_id/to_data_type依据 Parquet 物理类型physical与逻辑类型logical/converted映射而来见 reader_impl.cpp 与 parquet_metadata.hpp。在高层 cuDF 中cudf.io.parquet.read_parquet_metadata正是利用这套 schema API 提取列名并解析 pandas 索引列信息见 cudf/io/parquet.py它调用plc.io.parquet_metadata.read_parquet_metadata通过parquet_metadata.schema().root().children()收集全部列名再读取parquet_metadata.metadata()[pandas]JSON 字符串判断 range index 与非 range index最终返回(num_rows, num_rowgroups, col_names, len(col_names), rowgroup_metadata)五元组。四、FileMetaData单文件的完整 footer 视图FileMetaData对应单个 Parquet 文件的 footer 解析结果比ParquetMetadata粒度更细包含 schema 元素、行组、列块乃至排序信息。1. from_bytes从裸 footer 字节构建classmethod def from_bytes(cls, footer_bytes: Buffer) - FileMetaData: ...接受任何连续的类字节对象memoryview、bytes等。文档特别强调两点字节会被原样转发给 C 的cudf::io::parquet::experimental::hybrid_scan_readerPython 侧不做任何预处理该方法不会剥离Parquet footer 的后缀4 字节 footer 长度 PAR1magic因此调用方通常应只传入 footer 区域本身。测试 test_file_metadata_from_bytes 对比了纯 footer与带后缀 footer两种输入断言两者的version、num_rows、created_by一致而 test_file_metadata_from_bytes_empty 验证空字节输入会抛出RuntimeError(Cannot initialize schema)。在多文件混合扫描场景中FileMetaData.from_bytes还被用于从外部缓存重建各文件的 footer见 test_experimental_hybrid_scan_multifile.py。2. 属性一览属性类型说明versionintParquet 文件格式版本num_rowsint文件总行数created_bystr生成该文件的应用程序标识schemalist[SchemaElement]深度优先展平的 schema 树首个元素为根row_groupslist[RowGroup]文件内所有行组的元数据row_group_num_rowslist[int]每个行组的行数columnchunk_metadatadict[str, list[int]]点分列路径 → 各列块total_uncompressed_size列表两个快捷属性值得单独说明row_group_num_rows等价于[rg.num_rows for rg in file_metadata.row_groups]但实现上直接索引底层 C 向量更快columnchunk_metadata等价于手工遍历行组与列块、用..join(col.meta_data.path_in_schema)聚合total_uncompressed_size的写法pyx 文档 给出了等价的 Python 参考实现同样因为省去逐层包装而更快。3. SchemaElement展平 schema 树的最小单元schema列表之所以能还原成树依赖每个SchemaElement的num_children——它表示紧随其后处于下一层的元素个数深度优先顺序第一个元素恒为根。SchemaElement的属性name字段名根元素为空字符串num_children子元素个数叶子列为 0field_id写入方记录的原始 schema 字段 ID未记录时为None。五、RowGroup 与 ColumnChunk定位数据在哪、有多大1. RowGroup行组级元数据属性类型说明columnslist[ColumnChunk]该行组内每个列的列块元数据total_byte_sizeint行组未压缩总字节数num_rowsint行组行数sorting_columnslist[SortingColumn] \| None可选的排序顺序元数据file_offsetint \| None行组第一个页面的字节偏移total_compressed_sizeint \| None行组压缩后总字节数ordinalint \| None行组在文件内的序号sorting_columns展开为SortingColumn列表每个元素描述一列的排序信息column_idx行组内列索引、descending是否降序、nulls_firstnull 是否排在非 null 之前。部分字段file_offset、total_compressed_size、ordinal是 Parquet 规范中的可选字段读取方未写入时为None测试 test_file_metadata_row_groups_and_column_chunks 与 PyArrow 的parquet_file.metadata.row_group(rg_idx)逐一比对行数、字节数、列块数量与每列num_values、压缩/未压缩大小确保语义对齐。2. ColumnChunk列块定位信息属性类型说明file_pathstr该列块所在文件的相对路径file_offsetint已弃用的列元数据字节偏移offset_index_offset/offset_index_lengthint该列块 OffsetIndex 在文件中的偏移与字节数column_index_offset/column_index_lengthint该列块 ColumnIndex 在文件中的偏移与字节数schema_idxint在展平 schema 中的派生索引meta_dataColumnChunkMetaData该列块的元数据载荷3. ColumnChunkMetaData列块元数据载荷path_in_schema列路径的各段组件嵌套列会给出多段如[a, b]num_values该列块的值数量total_uncompressed_size/total_compressed_size未压缩 / 压缩后的页面总字节数statisticsColumnChunkStatistics对象。4. ColumnChunkStatisticsmin/max 与计数统计属性类型说明has_min_maxbool是否同时具备编码后的最小值与最大值min_encoded/max_encodedbytes \| None编码后的原始统计载荷需结合该列的物理/逻辑类型解释优先使用min_value/max_value其次回退到已弃用的min/maxnull_countint \| None列块内 null 值数量distinct_countint \| None列块内去重值数量is_min_value_exact/is_max_value_exactbool \| Nonemin_value/max_value是否为精确的列块极值测试 test_file_metadata_columnchunk_statistics 展示了编码规则int64列的 min/max 以小端 8 字节打包struct.pack(q, value)返回字符串列直接返回原始 UTF-8 字节test_file_metadata_columnchunk_statistics_without_minmax 验证未写统计时has_min_max为False、min_encoded/max_encoded/exactness 标志均为None。六、典型应用场景与注意事项1. 数据剪枝前的零数据探查read_parquet_column_chunk_bounds的输出天然适合做行组级谓词剪枝拿到文件索引 行组索引 每列 min/max 后可以在不读取任何数据页的情况下排除不可能命中过滤条件的行组。这正是混合扫描hybrid scan流水线的基础——hybrid_scan_io 示例 与 hybrid_scan.hpp 展示了如何用预物化 footer 驱动后续按需读取。2. 元数据预物化复用先用read_parquet_footers得到FileMetaData列表再将其作为parquet_metadatas参数传给read_parquet或ChunkedParquetReader可避免读取器重复解析 footer——这对反复读取同一批文件例如多轮查询收益明显。3. 与高层 cuDF API 的关系cudf.DataFrame.read_parquet_metadata实现见 cudf/io/parquet.py内部直接调用plc.io.parquet_metadata.read_parquet_metadata因此本文介绍的所有底层行为schema 提取、pandas 元数据解析、行组元数据聚合都会影响高层 API 返回的(num_rows, num_rowgroups, column_names, num_columns, rowgroup_metadata)。4. 使用边界与易错点不可直接构造ParquetMetadata、ParquetSchema、ParquetColumnSchema、FileMetaData、RowGroup、ColumnChunk等类均禁止用户直接__init__必须经由对应读取函数或工厂方法创建columns必须是序列read_parquet_column_chunk_bounds的columns传入单个str会抛TypeError且列表内元素也必须全部为strfooter 后缀问题FileMetaData.from_bytes不剥离PAR1后缀与长度字段调用前需自行切出 footer 区域不过实测传入带后缀字节也能正确解析统计语义min_encoded/max_encoded是原始编码字节而非解引用后的值exactness 标志不会被read_parquet_column_chunk_bounds解释需要精确边界语义时应自行检查is_min_value_exact/is_max_value_exact多文件一致性read_parquet_metadata聚合的是整个数据集跨文件的同名列 dtype 不一致会在统计解码阶段报错。七、进一步阅读模块实现parquet_metadata.pyx、parquet_metadata.pyi、parquet_metadata.pxdC 底层parquet_metadata.hpp、reader_impl.cpp测试用例test_parquet.py预物化元数据、from_bytes、行组/列块/统计、column chunk bounds 各专项测试、test_experimental_hybrid_scan.py文档入口pylibcudf IO API 索引、高层 cuDF 的 io.rst以上路径均可直接在当前仓库中打开结合源码与测试深入验证本文所述的每一个 API 行为。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GPU 加速数据管线pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GP数据分析数据工程机器学习Apache Arrow 统计信息 Schema 规范以 Arrow 数组标准化表达统计信息的完整指南Apache Arrow 统计信息 Schema 规范以 Arrow 数组标准化表达统计信息的完整指南 导读 本文详解 Apache Arrow 官方格式规范人工智能AI Agent工具调用Formily Vue useFieldSchema 完全指南在自定义组件中读取当前字段的 Schema 信息Formily Vue useFieldSchema 完全指南在自定义组件中读取当前字段的 Schema 信息 导读 useFieldSchema 是 For前端UI组件上一篇7个实用技巧掌握folium色彩映射从单值映射到自定义色标完全指南下一篇3个维度重构你的数字伴侣开源框架创意实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考