列工厂#

group Factories

函数

std::unique_ptr<column> make_empty_column(data_type type)#

创建指定 type 的空列。

空列包含零个元素且没有有效性掩码。

参数：: type – [in] 列数据类型
返回：: 具有所需类型的空列

std::unique_ptr<column> make_empty_column(type_id id)#

创建指定类型的空列。

空列包含零个元素且没有有效性掩码。

参数：: id – [in] 列类型 ID
返回：: 具有指定类型的空列

std::unique_ptr<column> make_numeric_column(data_type type, size_type size, mask_state state = mask_state::UNALLOCATED, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定数值 data_type 的 size 个元素，带可选空值掩码。

注意

null_count() 由请求的空值掩码 state 确定

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是数值类型
cudf::logic_error – 如果 size < 0

参数：

type – [in] 所需的数值元素类型
size – [in] 列中的元素数量
state – [in] 可选，控制列的空值掩码的分配/初始化。默认情况下，不分配空值掩码。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的数值列

template<typename B> std::unique_ptr<column> make_numeric_column(data_type type, size_type size, B &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定数值 data_type 的 size 个元素，带空值掩码。

注意

null_count 是可选的，如果未提供则会计算。

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是数值类型

参数：

type – [in] 所需的数值元素类型
size – [in] 列中的元素数量
null_mask – [in] 用于此列的空值掩码。
null_count – [in] null_mask 中可选的空值数量。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的数值列

std::unique_ptr<column> make_fixed_point_column(data_type type, size_type size, mask_state state = mask_state::UNALLOCATED, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定 fixed_point data_type 的 size 个元素，带可选空值掩码。

注意

列的空值数量由请求的空值掩码 state 确定。

抛出：

cudf::logic_error – 如果 type 不是 fixed_point 类型。
cudf::logic_error – 如果 size < 0

参数：

type – [in] 所需的 fixed_point 元素类型。
size – [in] 列中的元素数量。
state – [in] 可选，控制列的空值掩码的分配/初始化。默认情况下，不分配空值掩码。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源。

返回：

构造的定点数类型列

template<typename B> std::unique_ptr<column> make_fixed_point_column(data_type type, size_type size, B &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定 fixed_point data_type 的 size 个元素，带空值掩码。

注意

null_count 是可选的，如果未提供则会计算。

抛出：

cudf::logic_error – 如果 type 不是 fixed_point 类型。

参数：

type – [in] 所需的 fixed_point 元素类型。
size – [in] 列中的元素数量。
null_mask – [in] 用于此列的空值掩码。
null_count – [in] null_mask 中可选的空值数量。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源。

返回：

构造的定点数类型列

std::unique_ptr<column> make_timestamp_column(data_type type, size_type size, mask_state state = mask_state::UNALLOCATED, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定时间戳 data_type 的 size 个元素，带可选空值掩码。

注意

null_count() 由请求的空值掩码 state 确定

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是时间戳类型
cudf::logic_error – 如果 size < 0

参数：

type – [in] 所需的时间戳元素类型
size – [in] 列中的元素数量
state – [in] 可选，控制列的空值掩码的分配/初始化。默认情况下，不分配空值掩码。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的时间戳类型列

template<typename B> std::unique_ptr<column> make_timestamp_column(data_type type, size_type size, B &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定时间戳 data_type 的 size 个元素，带空值掩码。

注意

null_count 是可选的，如果未提供则会计算。

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是时间戳类型

参数：

type – [in] 所需的时间戳元素类型
size – [in] 列中的元素数量
null_mask – [in] 用于此列的空值掩码。
null_count – [in] null_mask 中可选的空值数量。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的时间戳类型列

std::unique_ptr<column> make_duration_column(data_type type, size_type size, mask_state state = mask_state::UNALLOCATED, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定持续时间 data_type 的 size 个元素，带可选空值掩码。

注意

null_count() 由请求的空值掩码 state 确定

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是持续时间类型
cudf::logic_error – 如果 size < 0

参数：

type – [in] 所需的持续时间元素类型
size – [in] 列中的元素数量
state – [in] 可选，控制列的空值掩码的分配/初始化。默认情况下，不分配空值掩码。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的持续时间类型列

template<typename B> std::unique_ptr<column> make_duration_column(data_type type, size_type size, B &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定持续时间 data_type 的 size 个元素，带空值掩码。

注意

null_count 是可选的，如果未提供则会计算。

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是持续时间类型

参数：

type – [in] 所需的持续时间元素类型
size – [in] 列中的元素数量
null_mask – [in] 用于此列的空值掩码。
null_count – [in] null_mask 中可选的空值数量。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的持续时间类型列

std::unique_ptr<column> make_fixed_width_column(data_type type, size_type size, mask_state state = mask_state::UNALLOCATED, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定固定宽度 data_type 的 size 个元素，带可选空值掩码。

注意

null_count() 由请求的空值掩码 state 确定

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是固定宽度类型
cudf::logic_error – 如果 size < 0

参数：

type – [in] 所需的固定宽度类型
size – [in] 列中的元素数量
state – [in] 可选，控制列的空值掩码的分配/初始化。默认情况下，不分配空值掩码。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的固定宽度类型列

template<typename B> std::unique_ptr<column> make_fixed_width_column(data_type type, size_type size, B &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造列，包含足够的未初始化存储空间，用于容纳指定固定宽度 data_type 的 size 个元素，带空值掩码。

注意

null_count 是可选的，如果未提供则会计算。

抛出：

std::bad_alloc – 如果设备内存分配失败
cudf::logic_error – 如果 type 不是固定宽度类型

参数：

type – [in] 所需的固定宽度元素类型
size – [in] 列中的元素数量
null_mask – [in] 用于此列的空值掩码。
null_count – [in] null_mask 中可选的空值数量。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源

返回：

构造的固定宽度类型列

std::unique_ptr<column> make_strings_column(cudf::device_span<thrust::pair<char const*, size_type> const> strings, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一个 STRING 类型列，给定一个包含指针/大小对的设备 span。

总字符字节数不得超过 size_type 的最大大小。字符串字符应为 UTF-8 编码的字节序列。使用 strings_column_view 类对此类型的列执行字符串操作。

注意

null_count() 和 null_bitmask 取决于对是否包含空字符串。也就是说，对于每一对，如果 .first 为 null，则该字符串视为空。同样，如果 .first 不为 null 且 .second 为 0，则该字符串视为空（非空值）。否则，.first 成员必须是指向 .second 连续字节的有效设备地址。

抛出：

std::bad_alloc – 如果设备内存分配失败

参数：

strings – [in] 指针/大小对的设备 span。每个指针必须是设备内存地址或 nullptr（表示空字符串）。大小必须是字节数。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配列的 null_mask 和子列设备内存的设备内存资源。

返回：

构造的字符串列

std::vector<std::unique_ptr<column>> make_strings_column_batch(std::vector<cudf::device_span<thrust::pair<char const*, size_type> const>> const &input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一批 STRING 类型列，给定一个包含指针/大小对的设备 spans 数组。

此函数的输入/输出预期类似于只接受一个包含指针/大小对的设备 span 的 make_strings_column() API。不同之处在于，此函数旨在一次创建多个字符串列，以最大限度地减少多次内核启动和流同步的开销。

参数：

input – 指针/大小对的设备 spans 数组，其中每个指针是设备内存地址或 nullptr（表示空字符串），大小是字符串长度（以字节为单位）
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于为输出列分配内存的设备内存资源

返回：

构造的字符串列数组

std::unique_ptr<column> make_strings_column(cudf::device_span<string_view const> string_views, string_view const null_placeholder, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一个 STRING 类型列，给定一个 string_view 的设备 span。

总字符字节数不得超过 size_type 的最大大小。字符串字符应为 UTF-8 编码的字节序列。使用 strings_column_view 类对此类型的列执行字符串操作。

注意

对于每个 string_view，如果 .data() 是 null_placeholder.data()，则该字符串视为空值。同样，如果 .data() 不是 null_placeholder.data() 并且 .size_bytes() 为 0，则该字符串视为空（非空值）。否则，.data() 必须是指向 .size_bytes() 连续字节的有效设备地址。输出列的 null_count() 将等于输入空 string_view 的数量。

抛出：

std::bad_alloc – 如果设备内存分配失败

参数：

string_views – [in] string_view 的 span。每个 string_view 必须指向设备内存地址或 null_placeholder（表示空字符串）。大小必须是字节数。
null_placeholder – [in] string_view，表示给定 string_views 列表中的空字符串。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配列的 null_mask 和子列设备内存的设备内存资源。

返回：

构造的字符串列

std::unique_ptr<column> make_strings_column(size_type num_strings, std::unique_ptr<column> offsets_column, rmm::device_buffer &&chars_buffer, size_type null_count, rmm::device_buffer &&null_mask)#

构造一个 STRING 类型列，给定偏移量列、字符列以及空值掩码和空值数量。

列和掩码被移入结果字符串列。

参数：

num_strings – 列表示的字符串数量。
offsets_column – 此列的偏移量值列。元素数量比字符串总数多一个，因此 offset[last] - offset[0] 是字符串向量中的总字节数。
chars_buffer – 此列所有字符串的字符字节缓冲区。各个字符串由偏移量和空值掩码标识。
null_count – 空字符串条目的数量。
null_mask – 设备内存中指定空字符串的位。使用 Arrow 格式的空值来解释此位掩码。

返回：

构造的字符串列

std::unique_ptr<cudf::column> make_lists_column(size_type num_rows, std::unique_ptr<column> offsets_column, std::unique_ptr<column> child_column, size_type null_count, rmm::device_buffer &&null_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一个 LIST 类型列，给定偏移量列、子列以及空值掩码和空值数量。

列和掩码被移入结果列表列。

列表列的结构与字符串列类似。它们包含一组表示每行列表中长度的偏移量，以及一个由偏移量引用的数据“子列”。

由于列表是嵌套类型，子列本身可以进一步嵌套。当深度 N+1 的子列本身是一个列表时，深度 N 的偏移量列引用深度 N+1 的偏移量列。当深度 N+1 的子列是叶类型（int、float 等）时，深度 N 的偏移量列引用深度 N+1 的数据。

Example:
List<int>
input:              {{1, 2}, {3, 4, 5}}
offsets (depth 0)   {0, 2, 5}
data    (depth 0)
offsets (depth 1)
data    (depth 1)   {1, 2, 3, 4, 5}

Example:
List<List<int>>
input:              { {{1, 2}}, {{3, 4, 5}, {6, 7}} }
offsets (depth 0)   {0, 1, 3}
data    (depth 0)
offsets (depth 1)   {0, 2, 5, 7}
data    (depth 1)
offsets (depth 2)
data    (depth 2)   {1, 2, 3, 4, 5, 6, 7}

参数：

num_rows – [in] 列表示的列表数量。
offsets_column – [in] 此列的偏移值列。每个值应表示子元素的起始偏移量，对应行的开头，第一行从 0 开始。可以通过减去 offsets[N+1] - offsets[N] 来确定行 N 的长度。偏移总数应比列中的行数多 1。
child_column – [in] 由 offsets_column 表示的列表引用的嵌套数据列。注意：子列本身可能进一步嵌套。
null_count – [in] 空列表条目的数量。
null_mask – [in] 指定设备内存中空列表的位。使用 Arrow 格式的 null 来解释此位掩码。
stream – [in] 用于所有内存分配和设备内核的可选流。
mr – [in] 用于分配列的 null_mask 和子级的设备内存的可选资源。

返回：

构造的列表列

std::unique_ptr<column> make_empty_lists_column(data_type child_type, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

创建一个空的 LIST 列。

列表列需要一个子类型，因此不能使用 make_empty_column 创建。

参数：

child_type – 用于空子列的类型
stream – 用于设备内存操作和内核启动的 CUDA 流
mr – 用于分配返回列的设备内存的设备内存资源

返回：

新建的空列表列

std::unique_ptr<cudf::column> make_structs_column(size_type num_rows, std::vector<std::unique_ptr<column>> &&child_columns, size_type null_count, rmm::device_buffer &&null_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

使用指定的子列作为成员构造一个 STRUCT 列。

指定的子列/成员列和 null_mask 由生成的 struct 列采用。

struct 列要求所有指定的子列具有相同的行数。struct 列的行数等于其任何/所有子列的行数。任何索引处的单个 struct 行均由相同索引处的、按子列列表中指定顺序排列的所有单个子列值组成。

指定的 null mask 控制哪个 struct 行具有 null 值。这与单个子列的 null 值是正交的。

参数：

num_rows – [in] struct 列中的 struct 值数量。
child_columns – [in] struct 包含的子级/成员列表。
null_count – [in] struct 列中的 null 值数量。
null_mask – [in] 指定列中空 struct 值的位。
stream – [in] 用于所有内存分配和设备内核的可选流。
mr – [in] 用于设备内存分配的可选资源。

返回：

构造的 structs 列

std::unique_ptr<column> make_column_from_scalar(scalar const &s, size_type size, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一个具有 size 个元素的列，所有元素都等于给定的标量。

输出列将具有与 s.type() 相同的类型。如果 s.invalid()==false，输出列将包含所有 null 行。如果 size==0，输出列将为空。对于 LIST 标量，将保留来自 s 的列层级结构。

参数：

s – [in] 用于列中值的标量。
size – [in] 输出列的行数。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源。

返回：

构造的列，其行都包含标量值

std::unique_ptr<column> make_dictionary_from_scalar(scalar const &s, size_type size, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

构造一个具有 size 个元素的字典列，所有元素都等于给定的标量。

输出列的键将具有 s.type() 类型。如果 size==0，输出列将为空。

抛出：

cudf::logic_error – 如果 s.is_valid()==false

参数：

s – [in] 用于列中值的标量。
size – [in] 输出列的行数。
stream – [in] 用于设备内存操作和内核启动的 CUDA 流。
mr – [in] 用于分配返回列的设备内存的设备内存资源。

返回：

构造的字典列

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

通过复制提供的 keys 和 indices 来构造字典列。

预期 keys_column.has_nulls() == false。假设 keys_column 中的元素是唯一的且按严格的全序排列。也就是说，对于所有 i in [0,n-1)（其中 n 是键的数量），keys_column[i] 排在 keys_column[i+1] 之前。

索引值必须在 [0,keys_column.size()) 范围内。

输出列的 null_mask 和 null count 从 indices 列复制。如果 indices_column 中索引为 i 的元素为 null，则返回的字典列中索引为 i 的元素也将为 null。

k = ["a","c","d"]
i = [1,0,null,2,2]
d = make_dictionary_column(k,i)
d is now {["a","c","d"],[1,0,undefined,2,2]} bitmask={1,1,0,1,1}

输出列的 null_mask 和 null count 从 indices 列复制。

抛出：

cudf::logic_error – 如果 keys_column 包含 null
cudf::logic_error – 如果 indices_column 类型不是 INT32

参数：

keys_column – 用作新字典列键的唯一、有序值列。
indices_column – 用于新字典列的索引。
stream – 用于设备内存操作和内核启动的 CUDA 流。
mr – 用于分配返回列的设备内存的设备内存资源。

返回：

新建的字典列。

std::unique_ptr<column> make_dictionary_column(std::unique_ptr<column> keys_column, std::unique_ptr<column> indices_column, rmm::device_buffer &&null_mask, size_type null_count, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

通过获取提供的 keys 和 indices 列的所有权来构造字典列。

keys_column 和 indices 列不得包含 null。假设 keys_column 中的元素是唯一的且按严格的全序排列。也就是说，对于所有 i in [0,n-1)（其中 n 是键的数量），keys_column[i] 排在 keys_column[i+1] 之前。

索引值必须在 [0,keys_column.size()) 范围内。

抛出：

cudf::logic_error – 如果 keys_column 或 indices_column 包含 null
cudf::logic_error – 如果 indices_column 类型不是无符号整数类型

参数：

keys_column – 用作新字典列键的唯一、有序值列。
indices_column – 用于新字典列的索引。
null_mask – 输出列的 Null mask。
null_count – 输出列的 null 数量。
stream – 用于设备内存操作和内核启动的 CUDA 流。
mr – 用于分配返回列的设备内存的设备内存资源。

返回：

新建的字典列。

std::unique_ptr<column> make_dictionary_column(std::unique_ptr<column> keys_column, std::unique_ptr<column> indices_column, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

通过获取提供的 keys 和 indices 列的所有权来构造字典列。

The keys_column 不得包含 null，并假定其元素是唯一的且按严格的全序排列。也就是说，对于所有 i in [0,n-1)（其中 n 是键的数量），keys_column[i] 排在 keys_column[i+1] 之前。

The indices_column 可以是任何整数类型，并且应包含用于输出列的 null-mask。索引值必须在 [0,keys_column.size()) 范围内。

抛出：

cudf::logic_error – 如果 keys_column 包含 null

参数：

keys_column – 用作新字典列键的唯一、有序值列。
indices_column – 用于新字典列的索引值和 null-mask。
stream – 用于设备内存操作和内核启动的 CUDA 流。
mr – 用于分配返回列的设备内存的设备内存资源。

返回：

新建的字典列。

列工厂#

本页