互操作箭头#

group interop_arrow

类型定义

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

typedef 用于带有自定义删除器的 ArrowSchema 的 unique_ptr

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

typedef 用于具有自定义删除器的 ArrowDeviceArray 的 unique_ptr

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

typedef 用于拥有列的向量，用于从 ArrowDeviceArray 转换

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

typedef 用于指向 cudf::table_view 的 unique_ptr，带有自定义删除器

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

typedef 用于指向 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结构体。

注意

对于小数，由于libcudf中未存储其精度，小数将被转换为具有cudf小数类型支持的最宽精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

Parameters:

  • input – 用于创建模式的表

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

Returns:

从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上的释放回调以清理内存。

注意

对于小数，由于libcudf中未存储其精度，它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

注意

在cudf与Arrow不同的情况下，例如布尔值的表示（Arrow使用位图，cudf每个值使用1字节），将执行复制。

Parameters:

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

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

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

Returns:

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上的释放回调以清理内存。

注意

对于小数，由于libcudf中未存储其精度，因此它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

注意

在cudf与Arrow不同的情况下，例如布尔值的表示（Arrow使用位图，cudf每个值使用1字节），将执行复制。

Parameters:

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

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

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

Returns:

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())#

从表视图创建 ArrowDeviceArray。

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

调用此函数后，必须调用返回的ArrowDeviceArray上的释放回调，以清理转换过程中创建的任何内存。

在cudf与Arrow不同的情况下，将执行复制操作：

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

  • DECIMAL32 和 DECIMAL64：转换为 Arrow decimal128

  • STRING: Arrow 期望为空的字符串列提供一个单一的 int32 偏移子数组

注意

对于小数，由于libcudf中未存储其精度，它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

Parameters:

  • table – 输入表

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

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

Returns:

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())#

从列视图创建 ArrowDeviceArray。

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

调用此函数后，必须调用返回的ArrowDeviceArray上的释放回调，以清理转换过程中创建的任何内存。

在cudf与Arrow不同的情况下，将执行复制操作：

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

  • DECIMAL32 和 DECIMAL64：转换为 Arrow decimal128

  • STRING: Arrow 期望为空字符串列提供一个单值的 int32 偏移子数组

注意

对于小数，由于libcudf中未存储其精度，因此它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

Parameters:

  • col – 输入列

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

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

Returns:

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())#

将表格视图数据复制到主机并为其创建ArrowDeviceArray。

填充C结构体ArrowDeviceArray，将cudf数据复制到主机。返回的ArrowDeviceArray将具有CPU的设备类型，并且与传入的表视图所引用的内存没有关联。返回的unique_ptr的删除器将自动调用ArrowDeviceArray上的释放回调。

注意

对于小数，由于libcudf中未存储其精度，它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

Parameters:

  • table – 输入表

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

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

Returns:

从输入表生成的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())#

将列视图数据复制到主机并为其创建ArrowDeviceArray。

填充C结构体ArrowDeviceArray，将cudf数据复制到主机。返回的ArrowDeviceArray将具有CPU的设备类型，并且与传入的列视图所引用的内存没有关联。返回的unique_ptr的删除器将自动调用ArrowDeviceArray上的释放回调。

注意

对于小数，由于libcudf中没有存储它们的精度，它们将被转换为具有cudf小数类型支持的最大精度的Arrow decimal128。例如，numeric::decimal32将被转换为精度为9的Arrow decimal128，这是32位类型的最大精度。同样，numeric::decimal128将被转换为精度为38的Arrow decimal128。

Parameters:

  • col – 输入列

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

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

Returns:

从输入列生成的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。

转换不会在输入的数组上调用 release。

Throws:

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

  • cudf::data_type_error – 如果输入数组不是结构体数组。

Parameters:

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

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

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

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

Returns:

从给定的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。

转换不会在输入的数组上调用 release。

Throws:

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

Parameters:

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

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

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

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

Returns:

从给定的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。

转换不会在输入的数组上调用 release。

Throws:

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

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

  • cudf::data_type_error – 如果输入数组不是结构体数组，非结构体数组应传递给 from_arrow_host_column。

Parameters:

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

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

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

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

Returns:

从给定的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及其组成的数组或模式，因为Arrow流不适合多次读取。

Throws:

std::invalid_argument – 如果输入为NULL

Parameters:

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

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

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

Returns:

从给定的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。

转换不会在输入的数组上调用 release。

Throws:

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

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

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

Parameters:

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

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

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

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

Returns:

从给定的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 后调用其释放回调，并且在此之后不再访问 cudf::table_view。

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

注意

用于table_view的unique_ptr的自定义删除器负责维护任何已分配内存的所有权，例如将布尔列从Arrow使用的位图转换为cudf的每个值1字节。

注意

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

Throws:

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

  • cudf::data_type_error – 如果输入数组不是结构体数组，非结构体数组应传递给 from_arrow_device_column 代替。

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

Parameters:

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

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

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

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

Returns:

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

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 构造一个非拥有的 cudf::column_view，数据必须对 CUDA 设备可访问。由于生成的 cudf::column_view 不会拥有数据，因此 ArrowDeviceArray 必须在结果的整个生命周期内保持活动状态。调用者有责任确保在不再需要 ArrowDeviceArray 后调用其释放回调，并且在此之后不再访问 cudf::column_view。

注意

用于table_view的unique_ptr的自定义删除器负责维护任何已分配内存的所有权，例如将布尔列从Arrow使用的位图转换为cudf的每个值1字节。

注意

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

Throws:

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

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

Parameters:

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

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

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

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

Returns:

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

struct column_metadata#
#include <interop.hpp>

箭头数组的详细元数据信息。

截至目前，这仅包含cudf列子层次结构中的名称，但未来可以根据需求进行更新。

公共函数

inline column_metadata(std::string _name)#

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

Parameters:

_name – 列的名称

公共成员

std::string name#

列的名称。

std::vector<column_metadata> children_meta#

列的子元素的元数据。

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

用于自定义删除器的函数对象，适用于table_view的unique_ptr

从ArrowDeviceArray转换时，存在数据无法零拷贝的情况（例如布尔值或非UINT32字典索引）。此自定义删除器用于维护对分配数据的所有权，因为cudf::table_view不持有所有权。

公共函数

inline explicit custom_view_deleter(owned_columns_t &&owned)#

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

Parameters:

owned – 拥有列的向量

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

用于删除 unique_ptr 的操作符

Parameters:

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

公共成员

owned_columns_t owned_mem_#

必须删除的拥有列。