列复制#

组复制

枚举

enum class out_of_bounds_policy : bool#

处理可能越界索引的策略。

NULLIFY 表示将对应于越界 gather_map 值的输出值设为空值。DONT_CHECK 表示不检查索引是否越界，以获得更好的性能。

值

enumerator NULLIFY#: 对应于越界索引的输出值为空值。

enumerator DONT_CHECK#: 不执行边界检查，性能更好。

enum class mask_allocation_policy : int32_t#

指示何时根据现有掩码分配掩码。

值

enumerator NEVER#: 无论输入如何，都不分配空值掩码。

enumerator RETAIN#: 如果输入包含空值掩码，则分配一个。

enumerator ALWAYS#: 无论输入如何，都分配空值掩码。

enum class sample_with_replacement : bool#

指示一行是否可以多次采样。

值

enumerator FALSE#: 一行只能采样一次。

enumerator TRUE#: 一行可以多次采样。

函数

std::unique_ptr<table> reverse(table_view const &source_table, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

反转表中的行。

创建一个与 source_table 相反的新表。示例

source = [[4,5,6], [7,8,9], [10,11,12]]
return = [[6,5,4], [9,8,7], [12,11,10]]

参数：

source_table – 将被反转的表
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回表的设备内存的设备内存资源

返回：

反转后的表

std::unique_ptr<column> reverse(column_view const &source_column, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

反转列的元素。

创建一个与 source_column 相反的新列。示例

source = [4,5,6]
return = [6,5,4]

参数：

source_column – 将被反转的列
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回表的设备内存的设备内存资源

返回：

反转后的列

std::unique_ptr<column> empty_like(column_view const &input)#

初始化并返回一个与 input 类型相同的空列。

参数：: input – [输入] 要模拟的输入列的不可变视图
返回：: 与 input 类型相同的空列

std::unique_ptr<column> empty_like(scalar const &input)#

初始化并返回一个与 input 类型相同的空列。

参数：: input – [输入] 要模拟的标量
返回：: 与 input 类型相同的空列

std::unique_ptr<column> allocate_like(column_view const &input, mask_allocation_policy mask_alloc = mask_allocation_policy::RETAIN, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

创建一个与 input 大小和类型相同、但未初始化的新列。

仅支持固定宽度类型。

如果 mask_alloc 分配了一个有效性掩码，该掩码也未初始化，有效位和空值计数应由调用者设置。

抛出：

cudf::data_type_error – 如果输入类型不是固定宽度类型。

参数：

input – 要模拟的输入列的不可变视图
mask_alloc – 可选，空值掩码分配策略。默认为 RETAIN
mr – 用于分配返回列的设备内存的设备内存资源
stream – 用于设备内存操作和内核启动的 CUDA 流

返回：

一个具有足够未初始化容量的列，其元素数量与 input 相同，类型与 input.type() 相同

std::unique_ptr<column> allocate_like(column_view const &input, size_type size, mask_allocation_policy mask_alloc = mask_allocation_policy::RETAIN, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

创建一个具有指定大小、类型与 input 相同、但未初始化的新列。

仅支持固定宽度类型。

如果 mask_alloc 分配了一个有效性掩码，该掩码也未初始化，有效位和空值计数应由调用者设置。

参数：

input – 要模拟的输入列的不可变视图
size – 新列所需的元素容量
mask_alloc – 可选，空值掩码分配策略。默认为 RETAIN
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

一个具有足够未初始化容量的列，其元素数量为指定大小，类型与 input.type() 相同

std::unique_ptr<table> empty_like(table_view const &input_table)#

创建一个由空列组成的表，其列类型与 input_table 相同

创建 cudf::column 对象，但不为列的数据或位掩码分配任何底层设备内存。

参数：: input_table – [输入] 要模拟的输入表的不可变视图
返回：: 一个由空列组成的表，其列类型与 input_table 中的列类型相同

void copy_range_in_place(column_view const &source, mutable_column_view &target, size_type source_begin, size_type source_end, size_type target_begin, rmm::cuda_stream_view stream = cudf::get_default_stream())#

将一个列中的一段元素就地复制到另一个列中。

将 `target` 中由索引 [`target_begin`, `target_begin` + N) 指定的元素范围，用 `source` 中由索引 [`source_begin`, `source_end`) 指定的元素替换（其中 N = (`source_end` - `source_begin`)）。对于需要重新分配内存的用例，例如字符串列和其他变长类型，请使用返回 std::unique_ptr<column> 的非就地复制函数。

如果 source 和 target 指向相同的元素且范围重叠，则行为未定义。

抛出：

cudf::data_type_error – 如果需要重新分配内存（例如对于变长类型）。
std::out_of_range – 对于无效范围（如果 source_begin > source_end，source_begin < 0，source_begin >= source.size()，source_end > source.size()，target_begin < 0，target_begin >= target.size()，或 target_begin + (source_end - source_begin) > target.size()）。
cudf::data_type_error – 如果 target 和 source 类型不同。
std::invalid_argument – 如果 source 包含空值且 target 不可为空。

参数：

source – 要从中复制的列
target – 要复制到的预分配列
source_begin – 源范围的起始索引（包含）
source_end – 源范围中最后一个元素的索引（不包含）
target_begin – 目标范围的起始索引（包含）
stream – 用于设备内存操作和内核启动的 CUDA 流

std::unique_ptr<column> copy_range(column_view const &source, column_view const &target, size_type source_begin, size_type source_end, size_type target_begin, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将一个列中的一段元素非就地复制到另一个列中。

创建一个新列，就像在 target 中执行了就地复制一样。首先创建 target 的副本，然后将 source 中由索引 [`source_begin`, `source_end`) 指定的元素（其中 N = (`source_end` - `source_begin`)）复制到由索引 [`target_begin`, `target_begin` + N) 指定的元素位置。范围之外的元素从 target 复制到返回的新列中。

如果 source 和 target 指向相同的元素且范围重叠，则行为未定义。

以下情况被视为无效范围

起始或结束索引超出相应列的范围
源或目标的起始索引大于结束索引
源范围的大小从 target_begin 开始会超出目标列的容量

抛出：

std::out_of_range – 对于任何无效范围。
cudf::data_type_error – 如果 target 和 source 类型不同。
cudf::data_type_error – 如果数据类型不是固定宽度、字符串或字典类型

参数：

source – 要从范围内部复制的列
target – 要从范围外部复制的列
source_begin – 源范围的起始索引（包含）
source_end – 源范围中最后一个元素的索引（不包含）
target_begin – 目标范围的起始索引（包含）
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

结果目标列

std::unique_ptr<column> copy_if_else(column_view const &lhs, column_view const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据 boolean_mask 中对应元素的值从 lhs 或 rhs 中选择。

根据以下规则从 rhs 或 lhs 中选择输出列中的每个元素 i：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs[i] : rhs[i]

抛出：

cudf::data_type_error – 如果 lhs 和 rhs 类型不同
std::invalid_argument – 如果 lhs 和 rhs 长度不同
cudf::data_type_error – 如果布尔掩码不是布尔类型
std::invalid_argument – 如果布尔掩码与 lhs 和 rhs 长度不同

参数：

lhs – 左侧 column_view
rhs – 右侧 column_view
boolean_mask – 一个 type_id::BOOL8 类型的列，表示每个元素的“左侧（真）/右侧（假）”布尔值。空值元素表示假。
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

包含所选元素的新列

std::unique_ptr<column> copy_if_else(scalar const &lhs, column_view const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据 boolean_mask 中对应元素的值从 lhs 或 rhs 中选择。

根据以下规则从 rhs 或 lhs 中选择输出列中的每个元素 i：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs : rhs[i]

抛出：

cudf::data_type_error – 如果 lhs 和 rhs 类型不同
cudf::data_type_error – 如果布尔掩码不是布尔类型
std::invalid_argument – 如果布尔掩码与 lhs 和 rhs 长度不同

参数：

lhs – 左侧标量
rhs – 右侧 column_view
boolean_mask – 一个 type_id::BOOL8 类型的列，表示每个元素的“左侧（真）/右侧（假）”布尔值。空值元素表示假。
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

包含所选元素的新列

std::unique_ptr<column> copy_if_else(column_view const &lhs, scalar const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据 boolean_mask 中对应元素的值从 lhs 或 rhs 中选择。

根据以下规则从 rhs 或 lhs 中选择输出列中的每个元素 i：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs[i] : rhs

抛出：

cudf::data_type_error – 如果 lhs 和 rhs 类型不同
cudf::data_type_error – 如果布尔掩码不是布尔类型
std::invalid_argument – 如果布尔掩码与 lhs 和 rhs 长度不同

参数：

lhs – 左侧 column_view
rhs – 右侧标量
boolean_mask – 一个 type_id::BOOL8 类型的列，表示每个元素的“左侧（真）/右侧（假）”布尔值。空值元素表示假。
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

包含所选元素的新列

std::unique_ptr<column> copy_if_else(scalar const &lhs, scalar const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据 boolean_mask 中对应元素的值从 lhs 或 rhs 中选择。

根据以下规则从 rhs 或 lhs 中选择输出列中的每个元素 i：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs : rhs

抛出：

cudf::logic_error – 如果布尔掩码不是布尔类型

参数：

lhs – 左侧标量
rhs – 右侧标量
boolean_mask – 一个 type_id::BOOL8 类型的列，表示每个元素的“左侧（真）/右侧（假）”布尔值。空值元素表示假。
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

包含所选元素的新列

std::unique_ptr<scalar> get_element(column_view const &input, size_type index, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从列中获取指定索引处的元素。

警告

此函数开销较大（会调用内核启动）。因此，不建议在性能敏感的代码或循环中使用它。

抛出：

std::out_of_range – 如果 index 不在范围 [0, input.size()) 内

参数：

input – 要从中获取元素的列视图
index – 要获取元素的 input 中的索引
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回标量的设备内存的设备内存资源

返回：

包含单个值的标量

std::unique_ptr<table> sample(table_view const &input, size_type const n, sample_with_replacement replacement = sample_with_replacement::FALSE, int64_t const seed = 0, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的 input 中随机收集 n 个样本。

Example:
input: {col1: {1, 2, 3, 4, 5}, col2: {6, 7, 8, 9, 10}}
n: 3
replacement: false

output:       {col1: {3, 1, 4}, col2: {8, 6, 9}}

replacement: true

output:       {col1: {3, 1, 1}, col2: {8, 6, 6}}

抛出：

cudf::logic_error – 如果 n > input.num_rows() 且 replacement == FALSE。
cudf::logic_error – 如果 n < 0。

参数：

input – 要采样的表视图
n – 期望从 input 中获得的非负样本数
replacement – 允许或不允许对同一行进行多次采样
seed – 用于初始化随机数生成器的种子值
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回表的设备内存的设备内存资源

返回：

包含从 input 中提取的样本的表

bool has_nonempty_nulls(column_view const &input, rmm::cuda_stream_view stream = cudf::get_default_stream())#

检查列或其后代是否包含非空的空行。

LIST 或 STRING 列可能包含被标记为空值的非空行。STRUCT 或 LIST 列可能包含具有非空空行的子列。其他类型的列被认为不可能包含非空空行。例如，固定宽度列没有“空”行的概念。

注意

此函数是精确的。如果返回 true，则存在一个或多个非空的空元素。

参数：

input – 要检查（及其后代）是否包含非空空行的列。
stream – 用于设备内存操作和内核启动的 CUDA 流

返回：

true 如果列或其后代包含非空空行

返回：

false 如果列及其后代都不包含非空空行

bool may_have_nonempty_nulls(column_view const &input)#

近似判断列或其后代可能是否包含非空空元素。

可能存在误报，但不会存在漏报。

与精确的 has_nonempty_nulls() 函数相比，此函数通常更高效。

复杂度

最佳情况：O(count_descendants(input))
最坏情况：O(count_descendants(input)) * m，其中 m 是最大后代中的行数

注意

此函数为近似判断。

true：可能存在非空空元素
false：肯定不存在非空空元素

参数：: input – 要检查（及其后代）是否包含非空空行的列
返回：: true 如果列或其后代包含空行
返回：: false 如果列及其后代都不包含空行

std::unique_ptr<column> purge_nonempty_nulls(column_view const &input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将 input 复制到输出中，同时清除列或其后代中的任何非空 null 行。

如果输入列不是复合类型 (LIST/STRING/STRUCT/DICTIONARY)，则输出将与 `input` 相同。

清除操作仅直接应用于 LIST 和 STRING 列，但它也间接应用于 STRUCT/DICTIONARY 列，因为这些列可能包含 LIST 或 STRING 类型的子列。

示例

auto const lists   = lists_column_wrapper<int32_t>{ {0,1}, {2,3}, {4,5} }.release();
cudf::set_null_mask(lists->null_mask(), 1, 2, false);

lists[1] is now null, but the lists child column still stores `{2,3}`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [0, 1, 2, 3, 4, 5]

After purging the contents of the list's null rows, the column's contents will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [0, 1, 4, 5]

auto const strings = strings_column_wrapper{ "AB", "CD", "EF" }.release();
cudf::set_null_mask(strings->null_mask(), 1, 2, false);

strings[1] is now null, but the strings column still stores `"CD"`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [A, B, C, D, E, F]

After purging the contents of the list's null rows, the column's contents
will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [A, B, E, F]

auto const lists   = lists_column_wrapper<int32_t>{ {0,1}, {2,3}, {4,5} };
auto const structs = structs_column_wrapper{ {lists}, null_at(1) };

structs[1].child is now null, but the lists column still stores `{2,3}`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [0, 1, 2, 3, 4, 5]

After purging the contents of the list's null rows, the column's contents
will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [0, 1, 4, 5]

参数：

input – 需要检查和清除其 null 行的列
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

一个新列，其内容等同于 input，但已清除 null 行

列复制#

本页