数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载本文是 libcudf C API 文档体系中Table Classes表类模块的深度技术指南。该模块是 cuDFGPU DataFrame LibraryC 层的核心抽象之一定义了以cudf::table拥有型数据容器与cudf::table_view/cudf::mutable_table_view非拥有型轻量视图为代表的一整套表对象模型。阅读本文后你将掌握 libcudf 中表对象的构建方式、所有权语义、行列元数据访问、列子集选取select、视图与容器互转以及表级空值/可空性检测等工具函数的真实用法并理解其底层实现与测试验证方式。一、Table Classes 在 libcudf API 文档体系中的位置libcudf 的公开 API 文档由 Sphinx Breathe 驱动 Doxygen 自动生成。核心类被组织为若干个 Doxygen 组group定义于 cpp/include/doxygen_groups.h顶层组cudf_classesClasses下包含column_classesColumn、table_classesTable、scalar_classesScalar、fixed_point_classesFixed Point等子组其中table_classes组正是本文主题其 RST 入口为 docs/cudf/source/libcudf/api_docs/table_classes.rst通过.. doxygengroup:: table_classes指令把组内所有带ingroup table_classes标记的类与函数的 Doxygen 注释自动展开为 API 页面该页面作为子页面挂接在 docs/cudf/source/libcudf/api_docs/cudf_classes.rst 的toctree中与column_classes、scalar_classes、fixed_point_classes并列。从源码看ingroup table_classes标记出现在 cpp/include/cudf/table/table.hpp、cpp/include/cudf/table/table_view.hpp、cpp/include/cudf/table/table_view.hpp 与 cpp/include/cudf/table/equality.hpp因此该组实际由三大类 API 组成拥有型容器cudf::table、非拥有视图(mutable_)table_view以及表级相等比较函数tables_equal。二、核心对象模型拥有型容器与非拥有视图libcudf 表对象遵循与column/column_view完全一致的两层设计哲学类型所有权拷贝成本典型用途cudf::table拥有持有unique_ptrcolumn深拷贝设备内存数据的真正持有者运算结果、读入数据cudf::table_view非拥有持有column_view按值传递、trivially copyable只读传入各类 compute APIcudf::mutable_table_view非拥有持有mutable_column_view按值传递需要对列内容就地修改的场景两类视图的共同基类是cudf::detail::table_view_baseColumnView模板参数只能是column_view或mutable_column_view通过static_assert强制约束见 cpp/include/cudf/table/table_view.hpp。视图非拥有、可平凡拷贝文档明确要求按值传递cpp/include/cudf/table/table_view.hpp。一个值得注意的语义细节无论是table还是table_view都允许零列但有行数的表——当列集合为空时行数依然可以非零见 cpp/include/cudf/table/table.hpp 与 cpp/include/cudf/table/table_view.hpp。这服务于将零列但非零长度的 Arrow 数组转换为 libcudf 表的场景需要借助显式行数构造器完成。三、cudf::table拥有型表容器cudf::table的内部存储是一个std::vectorstd::unique_ptrcolumn并显式记录_num_rowscpp/include/cudf/table/table.hpp。其构造、复制、视图转换等成员在 cpp/src/table/table.cpp 中实现。3.1 构造函数cudf::table共提供四种构造途径cpp/include/cudf/table/table.hpp1. 深拷贝构造——从另一张表完整复制列数据可显式指定 CUDA 流与设备内存资源explicit table(table const other, cuda::stream_ref stream cudf::get_default_stream(), rmm::device_async_resource_ref mr cudf::get_current_device_resource_ref());实现中逐列调用std::make_uniquecolumn(*c, stream, mr)完成拷贝cpp/src/table/table.cpp并包裹CUDF_FUNC_RANGE()用于 NVTX 性能分析。2. 移动构造——从std::vectorstd::unique_ptrcolumn转移列所有权table(std::vectorstd::unique_ptrcolumn columns);实现会校验每个列指针非空且大小一致行数取自首列cpp/src/table/table.cpp。若columns为空则_num_rows置 0。3. 显式行数构造——用于零列表场景table(std::vectorstd::unique_ptrcolumn columns, size_type num_rows);当columns非空时要求num_rows与每个列的大小严格相等否则抛出std::invalid_argumentnum_rows为负同样抛错cpp/src/table/table.cpp。4. 从视图拷贝构造——把table_view的内容物化为拥有型表table(table_view view, cuda::stream_ref stream cudf::get_default_stream(), rmm::device_async_resource_ref mr cudf::get_current_device_resource_ref());实现遍历视图逐列构造columncpp/src/table/table.cpp。注意该类的拷贝赋值与移动赋值均被deletecpp/include/cudf/table/table.hpp所有权的转移必须通过构造或release()完成。3.2 常用成员方法方法签名简化行为num_columns()size_type num_columns() const noexcept返回列数即_columns.size()table.hppnum_rows()size_type num_rows() const noexcept返回行数table.hppalloc_size()std::size_t alloc_size() const所有列设备分配总字节数内部对每列alloc_size()做transform_reduce求和table.cppview()table_view view() const生成不可变非拥有视图table.cppmutable_view()mutable_table_view mutable_view()生成可变非拥有视图table.cpprelease()std::vectorstd::unique_ptrcolumn release()移交列所有权随后num_columns()0且num_rows()0table.cppselect(begin, end)/select(indices)模板 / 向量版本按列索引区间或索引集合选取子表视图table.hppget_column(i)column/column const返回第 i 列的引用越界抛std::out_of_rangetable.hpp此外还提供了到table_view与mutable_table_view的隐式转换运算符table.hpp、table.hpp因此在调用接受视图的 API 时table可以直接隐式转换无需显式调用view()。四、table_view 与 mutable_table_view轻量非拥有视图table_view_baseColumnView是两类视图的公共实现cpp/include/cudf/table/table_view.hpp提供如下能力迭代器begin()/end()返回对内部列视图向量的迭代器支持范围 for 遍历各列table_view.hpp列访问column(column_index)返回指定列的ColumnView const越界抛std::out_of_rangetable_view.hpp元数据num_columns()、num_rows()、is_empty()判断num_columns()0table_view.hpp。4.1 构造与行数校验视图构造时对列大小一致性有严格校验实现在 cpp/src/table/table_view.cpp由std::vectorColumnView构造若列数大于 0逐个断言每列size()与首列一致不一致抛Column size mismatch.逻辑错误行数取首列大小空列时行数为 0由std::vectorColumnView 显式num_rows构造校验num_rows 0且每列大小等于num_rows否则抛std::invalid_argument。由于std::vector可以由std::initializer_list构造官方推荐直接使用花括号初始化例如column_view c0, c1, c2; table_view t{{c0, c1, c2}}; // 由三列构造视图该写法在 table_view.hpp 的注释中明确给出。此外table_view与mutable_table_view还支持从向量列表拼接构造table_view(std::vectortable_view const views)会把多个视图的列横向拼接到一张表中并要求所有视图行数一致否则抛logic_errortable_view.hpp。其实现先concatenate_column_views合并列、再由concatenated_table_num_rows校验行数一致table_view.cpp、table_view.cpp。4.2 select按列索引选取子表table_view::select提供两个重载迭代器区间版本模板与std::vectorsize_type版本table_view.hpp后者委托给前者table_view.cpp。其行为为返回由指定列索引组成的新视图不拷贝数据任一索引越出[0, num_columns())抛std::out_of_range允许结果为空视图但行数被保留。测试用例 cpp/tests/table/table_view_tests.cu 验证了t.select({2, 3})得到的视图第 0 列与原始表第 2 列相等、第 1 列与原始表第 3 列相等table_view_tests.cu 则验证select({2, 3, 4})对只有两列的表抛出std::out_of_range。4.3 mutable_table_view 的特殊行为mutable_table_view继承table_view_basemutable_column_view额外提供column(i)返回mutable_column_view通过const_cast放宽只读限制table_view.hpp到不可变table_view的转换运算符实现为构造{begin(), end()}的列视图向量并携带行数table_view.cpp由std::vectormutable_table_view拼接构造table_view.hpp。五、表级工具函数与相等比较table_view.hpp与equality.hpp还提供一组作用在整表上的工具函数多数实现在 cpp/src/table/table_view.cpp函数语义实现位置has_nested_columns(view)是否存在嵌套类型列LIST/STRUCT 等按is_nested(col.type())判断table_view.cppnullable(view)任一列可空不深入子层级table_view.cpphas_nulls(view)任一列含空值不深入子层级table_view.cpphas_nested_nulls(input)递归检查整棵列层级中的空值table_view.cpphas_nested_nullable_columns(input)递归检查整棵层级中的可空列table_view.cppget_nullable_columns(table)收集所有嵌套层级的可空列返回vectorcolumn_viewtable_view.cppscatter_columns(source, map, target)按列索引映射把source的列视图散落到target的副本中语义为out[map[i]] source[i]table_view.cppdetail::is_relationally_comparable(lhs, rhs)逐列检查类型可关系比较且类型相同table_view.cpp5.1 tables_equal表相等比较cpp/include/cudf/table/equality.hpp 定义的tables_equal是table_classes组内的核心计算 APIbool tables_equal(table_view const left, table_view const right, null_equality nulls_equal null_equality::EQUAL, cuda::stream_ref stream cudf::get_default_stream());返回true当且仅当行数相同、列数相同、列类型匹配且left每一行与right同索引行比较相等。空值是否相等由nulls_equal默认null_equality::EQUAL控制浮点 NaN 视为相等若表中含EMPTY类型则抛cudf::logic_error。其设备端实现在 cpp/src/table/table_equal.cu。六、实战示例组合使用表对象综合以上 API一个典型的构造 → 视图 → 选取 → 比较流程如下写法参照测试用例 cpp/tests/table/table_view_tests.cu 与头文件注释#include cudf/table/table.hpp #include cudf/table/table_view.hpp #include cudf/table/equality.hpp // 1. 用列包装器构造列测试框架场景实际生产环境列来自 IO 或算子结果 cudf::test::fixed_width_column_wrapperint8_t col1{{1, 2, 3, 4}}; cudf::test::fixed_width_column_wrapperint16_t col2{{1, 2, 3, 4}}; cudf::test::fixed_width_column_wrapperint32_t col3{{4, 5, 6, 7}}; cudf::test::fixed_width_column_wrapperint64_t col4{{4, 5, 6, 7}}; // 2. 通过 initializer_list 构造视图 cudf::table_view t{{col1, col2, col3, col4}}; assert(t.num_columns() 4 t.num_rows() 4); // 3. 选取列子集零拷贝 cudf::table_view selected t.select({2, 3}); assert(selected.num_columns() 2); // 4. 空列表视图仍携带行数 cudf::table_view empty_cols(std::vectorcudf::column_view{}); assert(empty_cols.num_columns() 0); // 5. 视图 → 拥有型表深拷贝并可用隐式转换直接比较 cudf::table owned(selected); bool equal cudf::tables_equal(selected, owned.view());生产环境非测试框架中列通常由cudf::make_fixed_width_column等工厂函数创建或由cudf::io读入后获得视图构造与select、tables_equal的使用方式保持一致。需要迭代列时可直接使用范围 forfor (auto const col : t) { // col 为 cudf::column_view }对表做字典序逐行比较等高级操作可参考 cpp/tests/table/table_view_tests.cu 中通过cudf::detail::row::lexicographic::two_table_comparator配合thrust::transform实现的样例。七、关联文档与进一步阅读Table Classes API 页面入口docs/cudf/source/libcudf/api_docs/table_classes.rst类总览页docs/cudf/source/libcudf/api_docs/cudf_classes.rst头文件权威 API 文档cpp/include/cudf/table/table.hpp、cpp/include/cudf/table/table_view.hpp、cpp/include/cudf/table/equality.hpp实现列级基础见 cpp/include/cudf/column/column.hpp 与 cpp/include/cudf/column/column_view.hpp表实现见 cpp/src/table/table.cpp、cpp/src/table/table_view.cpp、cpp/src/table/table_equal.cu测试表容器行为见 cpp/tests/table/table_tests.cpp视图行为见 cpp/tests/table/table_view_tests.cuPython 侧对应抽象cudf.DataFrame 的底层即由这些 C 表对象支撑相关用法可参考 python/cudf/cudf 目录下的实现。掌握table/table_view/mutable_table_view三者之间的所有权与视图语义是正确、高效地调用 libcudf 全部计算与 IO API 的前提——几乎所有算子都接收table_view作为入参并以std::unique_ptrtable作为返回值理解本组类即可顺畅阅读与使用整个 libcudf API 面。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐libcudf GPU DataFrame 核心数据结构完全指南column 与 table 解析libcudf GPU DataFrame 核心数据结构完全指南column 与 table 解析 libcudf 是 cuDF 项目的 C GPU Da数据分析数据工程机器学习TBB concurrent_set 相等性比较语义解析operator 与 operator! 的规范、源码实现与陷阱TBB concurrent_set 相等性比较语义解析operator 与 operator! 的规范、源码实现与陷阱 本文解析 Intel oneA数据分析数据工程机器学习cuDF Column Nullmask 完全指南libcudf 有效性位掩码 API 剖析与实战cuDF Column Nullmask 完全指南libcudf 有效性位掩码 API 剖析与实战 导读 在 GPU DataFrame 库 cuDFlib数据分析数据工程机器学习上一篇性能基准测试MiniCPM-V在不同硬件配置下的完整评测下一篇解决90%用户痛点MiniCPM-V模型实战问题与高效解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
