Filtering

Functions
std::unique_ptr< column >	cudf::lists::apply_retention_mask (lists_column_view const &input, lists_column_view const &retention_mask, cuda::stream_ref stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Filters elements in each row of input LIST column using retention_mask LIST of booleans as a mask. More...
std::unique_ptr< column >	cudf::lists::apply_boolean_mask (lists_column_view const &input, lists_column_view const &boolean_mask, cuda::stream_ref stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Filters elements in each row of input LIST column using boolean_mask LIST of booleans as a mask. More...
std::unique_ptr< column >	cudf::lists::apply_deletion_mask (lists_column_view const &input, lists_column_view const &deletion_mask, cuda::stream_ref stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Filters elements in each row of input LIST column using deletion_mask LIST of booleans as a mask. More...
std::unique_ptr< column >	cudf::lists::distinct (lists_column_view const &input, null_equality nulls_equal=null_equality::EQUAL, nan_equality nans_equal=nan_equality::ALL_EQUAL, duplicate_keep_option keep_option=duplicate_keep_option::KEEP_ANY, cuda::stream_ref stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Create a new list column without duplicate elements in each list. More...

Detailed Description

Function Documentation

apply_boolean_mask()

std::unique_ptr<column> cudf::lists::apply_boolean_mask	(	lists_column_view const &	input,
		lists_column_view const &	boolean_mask,
		cuda::stream_ref	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

#include <cudf/lists/stream_compaction.hpp>

Filters elements in each row of input LIST column using boolean_mask LIST of booleans as a mask.

Deprecated:

in release 26.10. Use apply_retention_mask instead.

Parameters

input	The input list column view to be filtered.
boolean_mask	A nullable list of bools column used to filter input elements.
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

List column of the same type as input, containing filtered list rows.

apply_deletion_mask()

std::unique_ptr<column> cudf::lists::apply_deletion_mask	(	lists_column_view const &	input,
		lists_column_view const &	deletion_mask,
		cuda::stream_ref	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

#include <cudf/lists/stream_compaction.hpp>

Filters elements in each row of input LIST column using deletion_mask LIST of booleans as a mask.

Given an input LIST column and a list-of-bools column, the function produces a new LIST column of the same type as input, where each element is deleted from the input row if the corresponding deletion_mask is non-null and true.

E.g.

input          = { {0,1,2}, {3,4}, {5,6,7}, {8,9} };
deletion_mask  = { {0,1,1}, {1,0}, {1,1,1}, {0,0} };
results        = { {0},     {4},   {},      {8,9} };

input and deletion_mask must have the same number of rows. The output column has the same number of rows as the input column. An element is copied to an output row if the corresponding deletion_mask element is non-null and false. An output row is invalid only if the input row is invalid.

Exceptions

cudf::logic_error	if deletion_mask is not a "lists of bools" column
cudf::logic_error	if input and deletion_mask have different number of rows

Parameters

input	The input list column view to be filtered
deletion_mask	A nullable list of bools column used to filter input elements
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned table's device memory

Returns

List column of the same type as input, containing list rows with deleted elements removed

apply_retention_mask()

std::unique_ptr<column> cudf::lists::apply_retention_mask	(	lists_column_view const &	input,
		lists_column_view const &	retention_mask,
		cuda::stream_ref	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

#include <cudf/lists/stream_compaction.hpp>

Filters elements in each row of input LIST column using retention_mask LIST of booleans as a mask.

Given an input LIST column and a list-of-bools column, the function produces a new LIST column of the same type as input, where each element is copied from the input row only if the corresponding retention_mask is non-null and true.

E.g.

input          = { {0,1,2}, {3,4}, {5,6,7}, {8,9} };
retention_mask = { {0,1,1}, {1,0}, {1,1,1}, {0,0} };
results        = { {1,2},   {3},   {5,6,7}, {} };

An element is copied to an output row only if the corresponding retention_mask element is true. An output row is invalid only if the input row is invalid.

Note

input and retention_mask must have the same number of rows. The output column has the same number of rows as the input column.

Exceptions

cudf::logic_error	if retention_mask is not a "lists of bools" column
cudf::logic_error	if input and retention_mask have different number of rows

Parameters

input	The input list column view to be filtered
retention_mask	A nullable list of bools column used to filter input elements
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

List column of the same type as input, containing filtered list rows

distinct()

std::unique_ptr<column> cudf::lists::distinct	(	lists_column_view const &	input,
		null_equality	nulls_equal = null_equality::EQUAL,
		nan_equality	nans_equal = nan_equality::ALL_EQUAL,
		duplicate_keep_option	keep_option = duplicate_keep_option::KEEP_ANY,
		cuda::stream_ref	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

#include <cudf/lists/stream_compaction.hpp>

Create a new list column without duplicate elements in each list.

Given a lists column input, distinct elements of each list are copied to the corresponding output list. The order of lists is preserved while the order of elements within each list is not guaranteed.

Example:

input  = { {0, 1, 2, 3, 2}, {3, 1, 2}, null, {4, null, null, 5} }
result = { {0, 1, 2, 3}, {3, 1, 2}, null, {4, null, 5} }

Parameters

input	The input lists column
nulls_equal	Flag to specify whether null elements should be considered as equal
nans_equal	Flag to specify whether floating-point NaNs should be considered as equal
keep_option	Flag to specify which element to keep (first, last, any)
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned object

Returns

The resulting lists column containing lists without duplicates