互操作 Arrow#

group Arrow

类型定义

using unique_schema_t = std::unique_ptr<ArrowSchema, void (*)(ArrowSchema*)>#

用于指向带自定义删除器的 ArrowSchema 的 unique_ptr 的类型定义

using unique_device_array_t = std::unique_ptr<ArrowDeviceArray, void (*)(ArrowDeviceArray*)>#

用于指向带自定义删除器的 ArrowDeviceArray 的 unique_ptr 的类型定义

using owned_columns_t = std::vector<std::unique_ptr<cudf::column>>#

用于拥有列向量的类型定义，用于从 ArrowDeviceArray 转换

using unique_table_view_t = std::unique_ptr<cudf::table_view, custom_view_deleter<cudf::table_view>>#

用于指向带自定义删除器的 cudf::table_view 的 unique_ptr 的类型定义

using unique_column_view_t = std::unique_ptr<cudf::column_view, custom_view_deleter<cudf::column_view>>#

用于指向带自定义删除器的 cudf::column_view 的 unique_ptr 的类型定义

函数

unique_schema_t to_arrow_schema(cudf::table_view const &input, cudf::host_span<column_metadata const> metadata)#

从 cudf 表和元数据创建 ArrowSchema。

使用表和元数据填充并返回 ArrowSchema C 结构体。

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，decimal 将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

参数:

  • input – 用于创建 schema 的表

  • metadata – 包含列和子元素的名称层次结构

返回:

从 input 生成的 ArrowSchema

unique_device_array_t to_arrow_device(cudf::table &&table, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从 cudf 表和元数据创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，如果可能则不执行复制。这会在 GPU 设备上保留数据，并将表及其缓冲区的所有权转移给 ArrowDeviceArray 结构体。

调用此函数后，必须调用返回的 ArrowDeviceArray 上的 release 回调函数以清理内存。

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

注意

在 cudf 与 Arrow 表示方式不同的情况下（例如 bool 类型：Arrow 使用位图，cudf 每值使用 1 字节），将执行复制。

参数:

  • table – 输入表，数据的所有权将转移给结果

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

ArrowDeviceArray，它将拥有 GPU 数据的所有权，使用者必须调用 release 函数

unique_device_array_t to_arrow_device(cudf::column &&col, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从 cudf 列和元数据创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，如果可能则不执行复制。这会在 GPU 设备上保留数据，并将表及其缓冲区的所有权转移给 ArrowDeviceArray 结构体。

调用此函数后，必须调用返回的 ArrowDeviceArray 上的 release 回调函数以清理内存。

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它们将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

注意

在 cudf 与 Arrow 表示方式不同的情况下（例如 bool 类型：Arrow 使用位图，cudf 每值使用 1 字节），将执行复制。

参数:

  • col – 输入列，数据的所有权将转移给结果

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

ArrowDeviceArray，它将拥有 GPU 数据的所有权

unique_device_array_t to_arrow_device(cudf::table_view const &table, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从 table view 创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，仅在必要时执行复制。这会封装 GPU 设备上的数据，并将表数据的视图提供给 ArrowDeviceArray 结构体。如果调用者释放 table_view 引用的数据，则使用返回的对象会导致未定义行为。

调用此函数后，必须调用返回的 ArrowDeviceArray 上的 release 回调函数以清理转换期间创建的任何内存。

在 cudf 与 Arrow 表示方式不同的情况下，将执行复制

  • BOOL8: Arrow 使用位图，cudf 每值使用 1 字节

  • DECIMAL32 和 DECIMAL64: 转换为 Arrow decimal128

  • STRING: 对于空字符串列，Arrow 期望有一个单值 int32 偏移量子数组

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

参数:

  • table – 输入表

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

ArrowDeviceArray，它将拥有任何已复制数据的所有权

unique_device_array_t to_arrow_device(cudf::column_view const &col, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从 column view 创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，仅在必要时执行复制。这会封装 GPU 设备上的数据，并将列数据的视图提供给 ArrowDeviceArray 结构体。如果调用者释放 column_view 引用的数据，则使用返回的对象会导致未定义行为。

调用此函数后，必须调用返回的 ArrowDeviceArray 上的 release 回调函数以清理转换期间创建的任何内存。

在 cudf 与 Arrow 表示方式不同的情况下，将执行复制

  • BOOL8: Arrow 使用位图，cudf 每值使用 1 字节

  • DECIMAL32 和 DECIMAL64: 转换为 Arrow decimal128

  • STRING: 对于空字符串列，Arrow 期望有一个单值 int32 偏移量子数组

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它们将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

参数:

  • col – 输入列

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

ArrowDeviceArray，它将拥有任何已复制数据的所有权

unique_device_array_t to_arrow_host(cudf::table_view const &table, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将 table view 数据复制到主机并为其创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，将 cudf 数据复制到主机。返回的 ArrowDeviceArray 的 device_type 将为 CPU，并且与传入的 table view 引用的内存没有关联。返回的 unique_ptr 的删除器将自动调用 ArrowDeviceArray 上的 release 回调函数。

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

参数:

  • table – 输入表

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

从输入表生成的 ArrowDeviceArray

unique_device_array_t to_arrow_host(cudf::column_view const &col, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将 column view 数据复制到主机并为其创建 ArrowDeviceArray。

填充 C 结构体 ArrowDeviceArray，将 cudf 数据复制到主机。返回的 ArrowDeviceArray 的 device_type 将为 CPU，并且与传入的 column view 引用的内存没有关联。返回的 unique_ptr 的删除器将自动调用 ArrowDeviceArray 上的 release 回调函数。

注意

对于 decimal 类型，由于 libcudf 中不存储它们的精度，它将被转换为 Arrow decimal128，该类型具有 cudf decimal 类型支持的最宽精度。例如，numeric::decimal32 将被转换为精度为 9 的 Arrow decimal128，这是 32 位类型的最大精度。类似地，numeric::decimal128 将被转换为精度为 38 的 Arrow decimal128。

参数:

  • col – 输入列

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 转换期间用于任何分配的设备内存资源

返回:

从输入列生成的 ArrowDeviceArray

std::unique_ptr<cudf::table> from_arrow(ArrowSchema const *schema, ArrowArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowArray 和 ArrowSchema 输入创建 cudf::table。

转换不会对输入的 Array 调用 release。

抛出:

  • std::invalid_argument – 如果 schema 或 input 为 NULL

  • cudf::data_type_error – 如果输入 array 不是 struct array。

  • std::overflow_error – 如果输入的 arrow 对象超出列大小限制。

参数:

  • schema – ArrowSchema 指针，用于描述数据的类型

  • input – 需要转换为 cudf::table 的 ArrowArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配 cudf::table 的设备内存资源

返回:

从给定的 arrow 数据生成的 cudf 表

std::unique_ptr<cudf::column> from_arrow_column(ArrowSchema const *schema, ArrowArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowArray 和 ArrowSchema 输入创建 cudf::column。

转换不会对输入的 Array 调用 release。

抛出:

std::invalid_argument – 如果 schema 或 input 为 NULL

参数:

  • schema – ArrowSchema 指针，用于描述数据的类型

  • input – 需要转换为 cudf::column 的 ArrowArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配 cudf::column 的设备内存资源

返回:

从给定的 arrow 数据生成的 cudf 列

std::unique_ptr<table> from_arrow_host(ArrowSchema const *schema, ArrowDeviceArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowDeviceArray 输入创建 cudf::table。

转换不会对输入的 Array 调用 release。

抛出:

  • std::invalid_argument – 如果 schema 或 input 为 NULL

  • std::invalid_argument – 如果 device_type 不是 ARROW_DEVICE_CPU

  • std::overflow_error – 如果输入的 arrow 对象超出列大小限制。

  • cudf::data_type_error – 如果输入的 array 不是 struct array，非 struct array 应该传递给 from_arrow_host_column。

参数:

  • schema – ArrowSchema 指针，用于描述数据的类型

  • input – 指向拥有 Arrow 数据的对象 的 ArrowDeviceArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于执行 cuda 分配的设备内存资源

返回:

从给定的 Arrow 数据生成的 cudf 表

std::unique_ptr<table> from_arrow_stream(ArrowArrayStream *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowArrayStream 输入创建 cudf::table。

转换将会释放输入的 ArrayArrayStream 及其组成 array 或 schema，因为 Arrow 流不适合多次读取。

抛出:

std::invalid_argument – 如果 input 为 NULL

参数:

  • input – 指向将生成 ArrowArray 数据对象的 ArrowArrayStream 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于执行 cuda 分配的设备内存资源

返回:

从给定的 Arrow 数据生成的 cudf 表

std::unique_ptr<column> from_arrow_host_column(ArrowSchema const *schema, ArrowDeviceArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowDeviceArray 输入创建 cudf::column。

转换不会对输入的 Array 调用 release。

抛出:

  • std::invalid_argument – 如果 schema 或 input 为 NULL

  • std::invalid_argument – 如果 device_type 不是 ARROW_DEVICE_CPU

  • cudf::data_type_error – 如果输入的 arrow 数据类型在 cudf 中不受支持。

  • std::overflow_error – 如果输入的 arrow 对象超出列大小限制。

参数:

  • schema – ArrowSchema 指针，用于描述数据的类型

  • input – 指向拥有 Arrow 数据的对象 的 ArrowDeviceArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于执行 cuda 分配的设备内存资源

返回:

从给定的 Arrow 数据生成的 cudf 列

unique_table_view_t from_arrow_device(ArrowSchema const *schema, ArrowDeviceArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowDeviceArray 和 ArrowSchema 创建 cudf::table_view

使用 ArrowDeviceArray 和 ArrowSchema 构造一个非拥有型 cudf::table_view，数据必须可由 CUDA 设备访问。由于生成的 cudf::table_view 不拥有数据，ArrowDeviceArray 在结果的生命周期内必须保持活动状态。调用者有责任确保在不再需要 ArrowDeviceArray 后对其调用 release 回调函数，并且在此之后不再访问 cudf::table_view。

输入 struct 的每个子元素将成为结果 table_view 的列。

注意

用于指向 table_view 的 unique_ptr 的自定义删除器会保留对分配的任何内存的所有权，例如将 boolean 列从 Arrow 使用的位图转换为 cudf 每值使用的 1 字节。

注意

如果输入的 ArrowDeviceArray 包含非空的 sync_event，则假定它是一个 cudaEvent_t*，并且传入的流将对其调用 cudaStreamWaitEvent 并带有该事件。然而，此函数不会在流上显式同步。

抛出:

  • std::invalid_argument – 如果 device_type 不是 ARROW_DEVICE_CUDA、ARROW_DEVICE_CUDA_HOST 或 ARROW_DEVICE_CUDA_MANAGED

  • cudf::data_type_error – 如果输入数组不是结构体数组 (struct array)，非结构体数组 (non-struct arrays) 应该改为传递给 from_arrow_device_column。

  • cudf::data_type_error – 如果输入的 arrow 数据类型不受支持。

  • std::overflow_error – 如果输入的 arrow 对象超出列大小限制。

参数:

  • schema – 指向描述设备数组类型的对象的 ArrowSchema 指针

  • input – 指向拥有 Arrow 数据的对象 的 ArrowDeviceArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于执行任何分配的设备内存资源

返回:

从给定的 Arrow 数据生成的 cudf::table_view

unique_column_view_t from_arrow_device_column(ArrowSchema const *schema, ArrowDeviceArray const *input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 ArrowDeviceArray 和 ArrowSchema 创建 cudf::column_view

使用 ArrowDeviceArray 和 ArrowSchema 构造一个非拥有的 (non-owning) cudf::column_view，数据必须可由 CUDA 设备访问。由于生成的 cudf::column_view 不拥有数据，因此 ArrowDeviceArray 必须在其结果的生命周期内保持存活。调用方有责任确保在不再需要 ArrowDeviceArray 后对其调用释放回调 (release callback)，并且在此之后不再访问 cudf::column_view。

注意

用于指向 table_view 的 unique_ptr 的自定义删除器会保留对分配的任何内存的所有权，例如将 boolean 列从 Arrow 使用的位图转换为 cudf 每值使用的 1 字节。

注意

如果输入的 ArrowDeviceArray 包含非空的 sync_event，则假定它是一个 cudaEvent_t*，并且传入的流将对其调用 cudaStreamWaitEvent 并带有该事件。然而，此函数不会在流上显式同步。

抛出:

  • std::invalid_argument – 如果 device_type 不是 ARROW_DEVICE_CUDA、ARROW_DEVICE_CUDA_HOST 或 ARROW_DEVICE_CUDA_MANAGED

  • cudf::data_type_error – 输入的 arrow 数据类型不受支持。

  • std::overflow_error – 如果输入的 arrow 对象超出列大小限制。

参数:

  • schema – 指向描述设备数组类型的对象的 ArrowSchema 指针

  • input – 指向拥有 Arrow 数据的对象 的 ArrowDeviceArray 指针

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于执行任何分配的设备内存资源

返回:

从给定的 Arrow 数据生成的 cudf::column_view

struct column_metadata#
#include <interop.hpp>

arrow 数组的详细元数据信息。

目前，这仅包含 cudf 列的子列层次结构中的名称，但将来可以根据需要更新。

公有函数

inline column_metadata(std::string _name)#

构造一个新的列元数据对象。

参数:

_name – 列的名称

公有成员

std::string name#

列的名称。

std::vector<column_metadata> children_meta#

列的子列的元数据。

template<typename ViewType>
struct custom_view_deleter#
#include <interop.hpp>

用于 `table_view` 的 `unique_ptr` 的自定义删除器 (deleter) 的 functor

当从 ArrowDeviceArray 转换时，存在数据无法实现零拷贝 (zero-copy) 的情况（例如布尔值或非 UINT32 字典索引）。由于 cudf::table_view 不拥有数据，因此使用此自定义删除器 (custom deleter) 来维护对所分配数据的所有权 (ownership)。

公有函数

inline explicit custom_view_deleter(owned_columns_t &&owned)#

构造一个新的自定义视图删除器对象。

参数:

owned – 拥有列 (owning columns) 的向量

inline void operator()(ViewType *ptr) const#

删除 unique_ptr 的运算符

参数:

ptr – 指向要删除的对象的指针

公有成员

owned_columns_t owned_mem_#

必须删除的拥有列 (Owned columns)。