Lists Combine

group lists_combine

Enums

enum class concatenate_null_policy

Flag to specify whether a null list element will be ignored from concatenation, or the entire concatenation result involving null list elements will be a null element.

Values:

enumerator IGNORE

enumerator NULLIFY_OUTPUT_ROW

Functions

std::unique_ptr<column> concatenate_rows(table_view const &input, concatenate_null_policy null_policy = concatenate_null_policy::IGNORE, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())

Row-wise concatenating multiple lists columns into a single lists column.

The output column is generated by concatenating the elements within each row of the input table. If any row of the input table contains null elements, the concatenation process will either ignore those null elements, or will simply set the entire resulting row to be a null element.

s1 = [{0, 1}, {2, 3, 4}, {5}, {}, {6, 7}]
s2 = [{8}, {9}, {}, {10, 11, 12}, {13, 14, 15, 16}]
r = lists::concatenate_rows(s1, s2)
r is now [{0, 1, 8}, {2, 3, 4, 9}, {5}, {10, 11, 12}, {6, 7, 13, 14, 15, 16}]

Throws:

• cudf::logic_error – if any column of the input table is not a lists column.

• cudf::logic_error – if all lists columns do not have the same type.

Parameters:

• input – Table of lists to be concatenated.

• null_policy – The parameter to specify whether a null list element will be ignored from concatenation, or any concatenation involving a null element will result in a null list.

• stream – CUDA stream used for device memory operations and kernel launches.

• mr – Device memory resource used to allocate the returned column’s device memory.

Returns:

A new column in which each row is a list resulted from concatenating all list elements in the corresponding row of the input table.

std::unique_ptr<column> concatenate_list_elements(column_view const &input, concatenate_null_policy null_policy = concatenate_null_policy::IGNORE, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())

Concatenating multiple lists on the same row of a lists column into a single list.

Given a lists column where each row in the column is a list of lists of entries, an output lists column is generated by concatenating all the list elements at the same row together. If any row contains null list elements, the concatenation process will either ignore those null elements, or will simply set the entire resulting row to be a null element.

l = [ [{1, 2}, {3, 4}, {5}], [{6}, {}, {7, 8, 9}] ]
r = lists::concatenate_list_elements(l);
r is [ {1, 2, 3, 4, 5}, {6, 7, 8, 9} ]

Throws:

std::invalid_argument – if the input column is not at least two-level depth lists column (i.e., each row must be a list of lists).

Parameters:

• input – The lists column containing lists of list elements to concatenate.

• null_policy – The parameter to specify whether a null list element will be ignored from concatenation, or any concatenation involving a null element will result in a null list.

• stream – CUDA stream used for device memory operations and kernel launches.

• mr – Device memory resource used to allocate the returned column’s device memory.

Returns:

A new column in which each row is a list resulted from concatenating all list elements in the corresponding row of the input lists column.