数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载本篇技术指南以 cuDF 仓库中 pylibcudf 的 ORCOptimized Row Columnar格式 I/O 模块 API 文档为核心系统讲解 pylibcudf 提供的 ORC 读取、写入、统计信息解析与分块chunked写入的完整接口。读者读完本文将掌握如何用OrcReaderOptions精确控制读取范围与列投影、如何用OrcWriterOptions调优 stripe 与压缩参数、如何解析 ORC 文件级与 stripe 级列统计以及在大数据量场景下如何使用OrcChunkedWriter分批写出数据。pylibcudf.io.orc 模块概览在 cuDF 仓库中pylibcudf 的 ORC I/O 能力集中在 pylibcudf.io.orc 模块内对应的 API 文档入口即 docs/cudf/source/pylibcudf/api_docs/io/orc.rst通过 Sphinx 的automodule指令自动收集该模块的全部公开成员。模块导出的完整符号清单见 orc.pyx 中的__all__包括读取read_orc、read_parsed_orc_statistics读取配置OrcReaderOptions、OrcReaderOptionsBuilder写入write_orc写入配置OrcWriterOptions、OrcWriterOptionsBuilder分块写入OrcChunkedWriter、ChunkedOrcWriterOptions、ChunkedOrcWriterOptionsBuilder统计对象OrcColumnStatistics、ParsedOrcStatistics能力探测is_supported_read_orc、is_supported_write_orc该模块底层直接绑定 libcudf 的 C 实现cudf::io::orc_reader_options、cudf::io::read_orc、cudf::io::write_orc等见 cpp/include/cudf/io/orc.hpp因此所有 GPU 加速的解析、解压、编码与列裁剪都在设备端完成Python 侧仅负责传递配置与接收结果。读取 ORC 文件OrcReaderOptions 与 read_orc从构建器开始读取 ORC 的第一步是构造OrcReaderOptions。与大多数 pylibcudf I/O 接口一致推荐通过OrcReaderOptions.builder(source)创建OrcReaderOptionsBuilder再用链式方法配置行为最后调用build()生成选项对象。source是SourceInfo可以指向文件路径、主机字节缓冲区HostBuffer或设备缓冲区DeviceBuffer。import pylibcudf as plc source_info plc.io.types.SourceInfo([dataset.orc]) options plc.io.orc.OrcReaderOptions.builder(source_info).build() result plc.io.orc.read_orc(options) # result 是 TableWithMetadata包含 GPU 上的 Table 与列名等元数据read_orc的完整签名还支持显式传入 CUDA 流与内存资源见 orc.pyxread_orc(options, streamNone, mrNone)stream用于设备内存操作与 kernel 启动的 CUDA 流不传则使用默认流mrDeviceMemoryResource控制返回表设备内存的分配来源如使用池化内存资源。读取选项全解OrcReaderOptions提供一组 setter 方法覆盖行范围、列投影、stripe 选择、类型转换等维度。下表汇总各选项的含义与约束对应 C 侧实现见 orc.hpp 与 orc.pyx方法参数说明约束set_num_rows(nrows)int64_t从读取起点开始读取的行数不设置则读到文件末尾不能为负与set_stripes互斥set_skip_rows(skip_rows)int64_t从文件开头跳过的行数不能为负与set_stripes互斥set_stripes(stripes)list[list[int]]每个输入源要读取的 stripe 编号列表外层列表与输入源一一对应非空时不允许再设置skip_rows/num_rowsset_columns(col_names)list[str]只读取指定名称的列列投影列名必须是字符串set_decimal128_columns(val)list[str]将指定列使用完全限定名读为 128 位 Decimal 类型列名必须是字符串set_timestamp_type(type_)DataType将时间戳列统一转换为指定时间戳类型—set_source(src)SourceInfo覆盖已有数据源—use_index(use)builder 方法bool是否使用 ORC 行索引row index加速读取默认开启—典型的分页读取示例options plc.io.orc.OrcReaderOptions.builder(source_info).build() options.set_skip_rows(1000) # 跳过前 1000 行 options.set_num_rows(500) # 只读接下来的 500 行 options.set_columns([a, b]) # 只取 a、b 两列 options.set_timestamp_type(plc.DataType(plc.TypeId.TIMESTAMP_MICROSECONDS)) result plc.io.orc.read_orc(options)几点源码级注意见 orc.hppset_stripes、set_skip_rows、set_num_rows之间存在互斥校验stripes非空时C 侧会通过CUDF_EXPECTS抛出cudf::logic_error如 Cant set stripes along with skip_rowsskip_rows、num_rows传入负值会直接抛错底层 C 还有enable_use_np_dtypesnumpy 兼容 dtype、enable_ignore_timezone_in_stripe_footer忽略 stripe footer 中的写入方时区等选项pylibcudf 目前暴露的是上表中的核心子集。返回值 TableWithMetadataread_orc返回TableWithMetadata定义见 types.pyi同时携带tblGPU 上的Table与column_names含嵌套子列名的列名规格。可通过result.tbl取表用result.columns取列元组或调用column_names(...)获取扁平或含子列的列名列表。解析 ORC 统计信息read_parsed_orc_statisticsORC 格式天然在文件 footer 与各 stripe 中携带列级统计最小值、最大值、总和、空值信息等。pylibcudf 提供read_parsed_orc_statistics(source_info, streamNone)直接读取并解析这些统计见 orc.pyx返回ParsedOrcStatistics对象stats plc.io.orc.read_parsed_orc_statistics(plc.io.types.SourceInfo([dataset.orc])) print(stats.column_names) # 每列的列名 for col_stats in stats.file_stats: # 文件级统计每列一个 print(col_stats.number_of_values) # 非空值数量 print(col_stats.has_null) # 是否含空值 print(col_stats.get(minimum)) # 按类型安全取值ParsedOrcStatistics的三个属性对应见 orc.pyxcolumn_nameslist[str]每列的列名file_statslist[OrcColumnStatistics]文件级每列一条统计stripes_statslist[list[OrcColumnStatistics]]外层按 stripe、内层按列组织。OrcColumnStatistics提供统一的字典式访问__getitem__、__contains__、get(item, default)以及number_of_values、has_null属性可能为None表示该统计缺失。类型特定统计会按列类型填充不同键解析逻辑见 orc.pyxC 结构定义见 cpp/include/cudf/io/orc_metadata.hpp列类型可用键说明整数integerminimum/maximum/sumint64 范围与求和浮点doubleminimum/maximum/sumdouble 范围与求和字符串stringminimum/maximum/sum字典序最小/最大字符串sum为总字符长度布尔buckettrue_count/false_count通过true_count与number_of_values推算得到Decimalminimum/maximum/sum以字符串形式保存日期dateminimum/maximumUTC 时区的datetime.datetime二进制binarysum总字节数时间戳timestampminimum/maximum依据 ORC-135 规范读取minimumUtc/maximumUtc并转为 UTCdatetime毫秒精度写入 ORC 文件OrcWriterOptions 与 write_orc基本写入流程写入同样采用 builder 模式OrcWriterOptions.builder(sink, table)同时接收目标SinkInfo文件路径或缓冲区与要写出的Table构建完成后调用plc.io.orc.write_orc(options, streamNone)执行见 orc.pyximport pylibcudf as plc import pyarrow as pa pa_table pa.table({a: [1.0, 2.0, None], b: [True, None, False]}) plc_table plc.Table.from_arrow(pa_table) sink plc.io.types.SinkInfo([output.orc]) # 可选的列级元数据与 footer 键值元数据 tbl_meta plc.io.types.TableInputMetadata(plc_table) user_data {source: pylibcudf-demo} options ( plc.io.orc.OrcWriterOptions.builder(sink, plc_table) .metadata(tbl_meta) .key_value_metadata(user_data) .compression(plc.io.types.CompressionType.SNAPPY) .enable_statistics(plc.io.types.StatisticsFreq.STATISTICS_ROWGROUP) .build() ) plc.io.orc.write_orc(options)写入选项与默认值OrcWriterOptions的 setter 与 builder 方法对应关系及默认值如下默认值常量见 orc.hpp成员初始化见 orc.hppbuilder 方法setter默认值说明compression(comp)set_compressionSNAPPY压缩算法传入AUTO会被归一化为SNAPPYenable_statistics(val)enable_statisticsORC_STATISTICS_ROW_GROUP统计收集粒度见下文stripe_size_bytes(val)set_stripe_size_bytes64 MiB64 * 1024 * 1024单个 stripe 最大字节数stripe_size_rows(val)set_stripe_size_rows1,000,000 行单个 stripe 最大行数row_index_stride(val)set_row_index_stride10,000 行行索引row index跨度即每个 row group 的最大行数metadata(meta)set_metadata无TableInputMetadata写入列级元数据key_value_metadata(kvm)set_key_value_metadata空footer 的键值元数据dict[str, str]统计粒度取值来自StatisticsFreq枚举见 types.pyiSTATISTICS_NONE不收集、STATISTICS_ROWGROUP/STATISTICS_PAGE/STATISTICS_COLUMN。为消除术语歧义libcudf 专门定义了ORC_STATISTICS_STRIPE STATISTICS_ROWGROUP与ORC_STATISTICS_ROW_GROUP STATISTICS_PAGE两个常量——ORC 的 stripe 对应 Parquet 的 row groupORC 的 row group 对应 Parquet 的 page见 orc.hpp。关键取值约束写配置并非任意取值C 侧有硬性校验见 orc.hppset_stripe_size_bytes最小值 64 KiB64 10否则抛logic_error64KB is the minimum stripe sizeset_stripe_size_rows最小值 512 行Maximum stripe size cannot be smaller than 512set_row_index_stride最小值 512且实际生效时向下取整到 8 的倍数get_row_index_stride中unaligned_stride - unaligned_stride % 8当 stripe 行数小于 row group 行数时row group 大小会被自动缩减以适配 stripe 大小。分块写入OrcChunkedWriter 与 ChunkedOrcWriterOptions当数据无法一次性整体驻留 GPU 内存、或需要流式地分批写出大量数据时使用OrcChunkedWriter。流程为先构造ChunkedOrcWriterOptions.builder(sink)配置压缩与统计等参数并build()再通过OrcChunkedWriter.from_options(options, streamNone)创建写入器之后循环调用writer.write(table)最后必须调用writer.close()收尾见 orc.pyxsink plc.io.types.SinkInfo([chunked.orc]) chunked_options ( plc.io.orc.ChunkedOrcWriterOptions.builder(sink) .compression(plc.io.types.CompressionType.SNAPPY) .enable_statistics(plc.io.types.StatisticsFreq.STATISTICS_ROWGROUP) .build() ) writer plc.io.orc.OrcChunkedWriter.from_options(chunked_options) for chunk_table in chunk_iterator: # 分批产出 pylibcudf Table writer.write(chunk_table) writer.close()ChunkedOrcWriterOptions与OrcWriterOptions共享同一组调优参数set_stripe_size_bytes、set_stripe_size_rows、set_row_index_stride及 builder 的compression/enable_statistics/key_value_metadata/metadata默认值与校验规则完全一致。区别在于普通写入要求构造时传入完整Table而分块写入只需SinkInfoTable在每次write调用时才提供。说明在底层 C 中读取侧同样存在chunked_orc_reader见 orc.hpp用于把超大 ORC 文件按chunk_read_limit输出字节上限、pass_read_limit临时内存上限与output_row_granularity行粒度分块读回pylibcudf 目前暴露的是写入方向的分块能力。压缩支持探测is_supported_read_orc / is_supported_write_orcORC 压缩算法是否可用取决于当前系统构建配置例如某些压缩库未静态链接或运行时缺失。CompressionType枚举提供NONE、AUTO、SNAPPY、GZIP、BZIP2、BROTLI、ZIP、XZ、ZLIB、LZ4、LZO、ZSTD等取值见 types.pyi但并非每种都必然可用。pylibcudf 提供两个运行时探测函数见 orc.pyxif plc.io.orc.is_supported_write_orc(plc.io.types.CompressionType.ZSTD): # 仅在支持时才使用 ZSTD 写入 options plc.io.orc.OrcWriterOptions.builder(sink, table) \ .compression(plc.io.types.CompressionType.ZSTD) \ .build() plc.io.orc.write_orc(options)is_supported_read_orc(compression)与is_supported_write_orc(compression)分别检查读写方向的支持情况C 侧文档明确标注这是运行时检查runtime check因此最佳实践是在选用非默认压缩算法前先探测。测试验证与注意事项pylibcudf 的 ORC 功能在 python/pylibcudf/tests/io/test_orc.py 中有系统性覆盖可作为使用范式的参考test_read_orc_basic参数化验证nrows/skiprows/columns组合并通过set_source覆盖数据源最终与 PyArrow 期望结果逐表比对test_read_orc_from_device_buffers验证从DeviceBuffer构造SourceInfo直接读取test_roundtrip_pa_table覆盖NONE/SNAPPY压缩、STATISTICS_NONE/STATISTICS_COLUMN统计粒度、以及 64 KiB stripe 与 512 行级参数的回环round-trip读写。此外有几个写入侧事实值得留意见 orc.hpp若编码或压缩过程中抛出异常则不会向 sink 写入任何数据非部分写入UNIX 纪元前最后 999 毫秒内的时间戳在 ORC 中不可精确表示读回时会晚一秒与 Apache ORC 写入器行为一致对应 ORC-763 / ORC-771时间戳写入默认按 UTC 记录writer_timezone默认UTC如需与 Hive / Spark 等记录本地时区的写入器互操作应显式设置写入方时区空字符串或无法解析的时区名会在写入时被拒绝。小结pylibcudf.io.orc 是一套以 builder 模式贯穿读写两侧、参数语义与 libcudf C 实现一一对应的 GPU 加速 ORC 接口。读取侧通过OrcReaderOptions控制行范围、列投影、stripe 选择与 Decimal128 / 时间戳转换统计侧用read_parsed_orc_statistics拿到文件级与 stripe 级列统计写入侧用OrcWriterOptions调优压缩、stripe 与行索引参数数据量超出单次内存承载时OrcChunkedWriter提供分批写出方案。所有参数默认值与合法性校验均能在 cpp/include/cudf/io/orc.hpp 中找到源码级依据建议在自定义压缩算法或极小 stripe 配置前对照上文约束表并优先使用is_supported_write_orc做运行时探测。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GPU 加速数据管线pylibcudf Parquet 读写 API 完全指南从 ParquetReaderOptions 到 ChunkedParquetWriter 的 GP数据分析数据工程机器学习PyArrow 读写 Apache ORC 格式完全指南从单文件到云存储PyArrow 读写 Apache ORC 格式完全指南从单文件到云存储 Apache ORCOptimized Row Columnar是一种开源的列式数据工程大数据序列化数据分析scrcpy 安卓投屏35ms 延迟、1 秒出首帧、手机零 App 安装scrcpy 安卓投屏35ms 延迟、1 秒出首帧、手机零 App 安装 敲一行 scrcpy 约 1 秒后手机屏幕出现在电脑窗口键盘输入、鼠标点击直接落音视频上一篇COLMAP三维重建实战5种安装方案深度解析与性能优化下一篇Wasp 单命令自动化部署Wasp Deploy完整指南从 wasp deploy 到 Fly.io 与 Railway 的生产落地创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
