Add apply_retention_mask and deprecate apply_boolean_mask

cpp/CMakeLists.txt

@@ -899,7 +899,7 @@ add_library(
   src/lists/segmented_sort.cu
   src/lists/sequences.cu
   src/lists/set_operations.cu
-  src/lists/stream_compaction/apply_boolean_mask.cu
+  src/lists/stream_compaction/apply_mask.cu
   src/lists/stream_compaction/distinct.cu
   src/lists/utilities.cu
   src/merge/merge.cu
@@ -998,7 +998,7 @@ add_library(
   src/sort/stable_sort_column.cu
   src/sort/stable_sort.cu
   src/sort/top_k.cu
-  src/stream_compaction/apply_boolean_mask.cu
+  src/stream_compaction/apply_mask.cu
   src/stream_compaction/distinct.cu
   src/stream_compaction/distinct_helpers.cu
   src/stream_compaction/distinct_helpers_flat_nan_equal_any.cu

cpp/benchmarks/CMakeLists.txt

@@ -138,7 +138,7 @@ ConfigureNVBench(FILTER_NVBENCH filter/minmax_filter.cpp)
 # * stream_compaction benchmark -------------------------------------------------------------------
 ConfigureNVBench(
   STREAM_COMPACTION_NVBENCH
-  stream_compaction/apply_boolean_mask.cpp
+  stream_compaction/apply_mask.cpp
   stream_compaction/distinct.cpp
   stream_compaction/stable_distinct.cpp
   stream_compaction/stream_compaction_common.cpp

cpp/benchmarks/filter/minmax_filter.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -131,7 +131,7 @@ void BM_filter_min_max(nvbench::state& state)
         auto filter_table         = cudf::table_view{filter_column_views};
         auto const filter_boolean = cudf::compute_column(predicate_table, tree.back(), stream, mr);
         auto const result =
-          cudf::apply_boolean_mask(filter_table, filter_boolean->view(), stream, mr);
+          cudf::apply_retention_mask(filter_table, filter_boolean->view(), stream, mr);
       } break;
       case engine_type::JIT: {
         cudf::filter_input predicate_inputs[] = {

cpp/benchmarks/ndsh/utilities.cpp

@@ -218,15 +218,15 @@ std::unique_ptr<table_with_names> apply_filter(std::unique_ptr<table_with_names>
 {
   CUDF_BENCHMARK_RANGE();
   auto const boolean_mask = cudf::compute_column(table->table(), predicate);
-  auto result_table       = cudf::apply_boolean_mask(table->table(), boolean_mask->view());
+  auto result_table       = cudf::apply_retention_mask(table->table(), boolean_mask->view());
   return std::make_unique<table_with_names>(std::move(result_table), table->column_names());
 }
 
 std::unique_ptr<table_with_names> apply_mask(std::unique_ptr<table_with_names> const& table,
                                              std::unique_ptr<cudf::column> const& mask)
 {
   CUDF_BENCHMARK_RANGE();
-  auto result_table = cudf::apply_boolean_mask(table->table(), mask->view());
+  auto result_table = cudf::apply_retention_mask(table->table(), mask->view());
   return std::make_unique<table_with_names>(std::move(result_table), table->column_names());
 }
 

cpp/benchmarks/stream_compaction/apply_boolean_mask.cpp → cpp/benchmarks/stream_compaction/apply_mask.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2019-2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2019-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -70,7 +70,7 @@ void apply_mask_benchmark(nvbench::state& state, nvbench::type_list<DataType>)
   state.exec(nvbench::exec_tag::sync,
              [&source_table, &mask, is_retention](nvbench::launch& launch) {
                if (is_retention) {
-                 cudf::apply_boolean_mask(*source_table, mask->view());
+                 cudf::apply_retention_mask(*source_table, mask->view());
                } else {
                  cudf::apply_deletion_mask(*source_table, mask->view());
                }

cpp/include/cudf/detail/stream_compaction.hpp

@@ -46,9 +46,14 @@ enum class mask_type : bool {
 };
 
 /**
- * @copydoc cudf::apply_boolean_mask
+ * @brief Filters @p input using @p boolean_mask.
  *
+ * @param input The input table to filter
+ * @param boolean_mask A nullable BOOL8 column used to filter @p input
  * @param mask_kind Specifies how the boolean mask is treated (retentions or deletions)
+ * @param stream CUDA stream used for device memory operations and kernel launches
+ * @param mr Device memory resource used to allocate the returned table's device memory
+ * @return A table containing the rows of @p input selected by @p boolean_mask and @p mask_kind
  */
 std::unique_ptr<table> apply_mask(table_view const& input,
                                   column_view const& boolean_mask,

cpp/include/cudf/lists/detail/stream_compaction.hpp

@@ -14,9 +14,14 @@ namespace cudf {
 namespace lists::detail {
 
 /**
- * @copydoc cudf::lists::apply_boolean_mask
+ * @brief Filters elements in each row of @p input using @p boolean_mask.
  *
+ * @param input The input lists column to filter
+ * @param boolean_mask A nullable lists-of-bools column used to filter @p input
  * @param mask_kind Specifies how the boolean mask is treated (retentions or deletions)
+ * @param stream CUDA stream used for device memory operations and kernel launches
+ * @param mr Device memory resource used to allocate the returned column's device memory
+ * @return A lists column containing the elements selected by @p boolean_mask and @p mask_kind
  */
 std::unique_ptr<column> apply_mask(lists_column_view const& input,
                                    lists_column_view const& boolean_mask,

cpp/include/cudf/lists/stream_compaction.hpp

@@ -24,35 +24,55 @@ namespace lists {
  */
 
 /**
- * @brief Filters elements in each row of `input` LIST column using `boolean_mask`
+ * @brief 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 `boolean_mask` is non-null and `true`.
+ * from the input row *only* if the corresponding `retention_mask` is non-null and `true`.
  *
  * E.g.
  * @code{.pseudo}
- * input        = { {0,1,2}, {3,4}, {5,6,7}, {8,9} };
- * boolean_mask = { {0,1,1}, {1,0}, {1,1,1}, {0,0} };
- * results      = { {1,2},   {3},   {5,6,7}, {} };
+ * 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}, {} };
  * @endcode
  *
- * `input` and `boolean_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 *only* if the corresponding boolean_mask element is `true`.
+ * An element is copied to an output row *only* if the corresponding @p retention_mask element is
+ * `true`.
  * An output row is invalid only if the input row is invalid.
  *
- * @throws cudf::logic_error if `boolean_mask` is not a "lists of bools" column
- * @throws cudf::logic_error if `input` and `boolean_mask` have different number of rows
+ * @note @p input and @p retention_mask must have the same number of rows. The output column has the
+ * same number of rows as the input column.
+ *
+ * @throws cudf::logic_error if @p retention_mask is not a "lists of bools" column
+ * @throws cudf::logic_error if @p input and @p retention_mask have different number of rows
  *
  * @param input The input list column view to be filtered
- * @param boolean_mask A nullable list of bools column used to filter `input` elements
+ * @param retention_mask A nullable list of bools column used to filter `input` elements
  * @param stream CUDA stream used for device memory operations and kernel launches
- * @param mr Device memory resource used to allocate the returned table's device memory
+ * @param mr Device memory resource used to allocate the returned column's device memory
  * @return List column of the same type as `input`, containing filtered list rows
  */
-std::unique_ptr<column> apply_boolean_mask(
+std::unique_ptr<column> 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());
+
+/**
+ * @brief 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.
+ *
+ * @param input The input list column view to be filtered.
+ * @param boolean_mask A nullable list of bools column used to filter `input` elements.
+ * @param stream CUDA stream used for device memory operations and kernel launches.
+ * @param mr Device memory resource used to allocate the returned column's device memory.
+ * @return List column of the same type as `input`, containing filtered list rows.
+ */
+[[deprecated("Use apply_retention_mask() instead")]] std::unique_ptr<column> apply_boolean_mask(
   lists_column_view const& input,
   lists_column_view const& boolean_mask,
   cuda::stream_ref stream           = cudf::get_default_stream(),

cpp/include/cudf/stream_compaction.hpp

@@ -190,28 +190,47 @@ std::unique_ptr<table> drop_nans(
   rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
 /**
- * @brief Filters `input` using `boolean_mask` of boolean values as a mask.
+ * @brief Filters `input` using `retention_mask` of boolean values as a mask.
  *
  * Given an input `table_view` and a mask `column_view`, an element `i` from
  * each column_view of the `input` is copied to the corresponding output column
  * if the corresponding element `i` in the mask is non-null and `true`.
  * This operation is stable: the input order is preserved.
  *
- * @note if @p input.num_rows() is zero, there is no error, and an empty table
- * is returned.
+ * @note If @p retention_mask is empty, or @p input has zero rows, an empty table is returned.
  *
- * @throws cudf::logic_error if `input.num_rows() != boolean_mask.size()`.
- * @throws cudf::logic_error if `boolean_mask` is not `type_id::BOOL8` type.
+ * @throws cudf::logic_error if non-empty @p input has different number of rows than @p
+ * retention_mask.
+ * @throws cudf::logic_error if @p retention_mask is not `type_id::BOOL8` type.
  *
  * @param[in] input The input table_view to filter
- * @param[in] boolean_mask A nullable column_view of type type_id::BOOL8 used
+ * @param[in] retention_mask A nullable column_view of type type_id::BOOL8 used
  * as a mask to filter the `input`.
  * @param[in] stream CUDA stream used for device memory operations and kernel launches
  * @param[in] mr Device memory resource used to allocate the returned table's device memory
- * @return Table containing copy of all rows of @p input passing
- * the filter defined by @p boolean_mask.
+ * @return Table containing copy of all rows of @p input passing the filter defined by
+ * @p retention_mask.
+ */
+std::unique_ptr<table> apply_retention_mask(
+  table_view const& input,
+  column_view const& retention_mask,
+  rmm::cuda_stream_view stream      = cudf::get_default_stream(),
+  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
+
+/**
+ * @brief Filters `input` using `boolean_mask` of boolean values as a mask.
+ *
+ * @deprecated in release 26.10. Use `apply_retention_mask` instead.
+ *
+ * @param[in] input The input table_view to filter.
+ * @param[in] boolean_mask A nullable column_view of type type_id::BOOL8 used
+ * as a mask to filter `input`.
+ * @param[in] stream CUDA stream used for device memory operations and kernel launches.
+ * @param[in] mr Device memory resource used to allocate the returned table's device memory.
+ * @return Table containing copies of all rows of @p input passing the filter defined by
+ * @p boolean_mask.
  */
-std::unique_ptr<table> apply_boolean_mask(
+[[deprecated("Use apply_retention_mask() instead")]] std::unique_ptr<table> apply_boolean_mask(
   table_view const& input,
   column_view const& boolean_mask,
   cuda::stream_ref stream           = cudf::get_default_stream(),
@@ -236,8 +255,8 @@ std::unique_ptr<table> apply_boolean_mask(
  * as a mask to filter the `input`.
  * @param[in] stream CUDA stream used for device memory operations and kernel launches
  * @param[in] mr Device memory resource used to allocate the returned table's device memory
- * @return Table containing copy of all rows of @p input that are not marked
- * for deletion by @p deletion_mask.
+ * @return Table containing copy of all rows of @p input that are not marked for deletion
+ * by @p deletion_mask.
  */
 std::unique_ptr<table> apply_deletion_mask(
   table_view const& input,

cpp/libcudf_streaming/benchmarks/streaming/ndsh/q04.cpp

@@ -148,7 +148,7 @@ rapidsmpf::streaming::Actor filter_lineitem(std::shared_ptr<rapidsmpf::streaming
                                        chunk_stream,
                                        mr);
     auto filtered_table =
-      cudf::apply_boolean_mask(table.select({2}), mask->view(), chunk_stream, mr);
+      cudf::apply_retention_mask(table.select({2}), mask->view(), chunk_stream, mr);
     co_await ch_out->send(cudf_streaming::to_message(
       msg.sequence_number(),
       std::make_unique<cudf_streaming::table_chunk>(std::move(filtered_table), chunk_stream)));

cpp/libcudf_streaming/benchmarks/streaming/ndsh/q09.cpp

@@ -168,7 +168,7 @@ rapidsmpf::streaming::Actor filter_part(std::shared_ptr<rapidsmpf::streaming::Co
     co_await ch_out->send(cudf_streaming::to_message(
       msg.sequence_number(),
       std::make_unique<cudf_streaming::table_chunk>(
-        cudf::apply_boolean_mask(table.select({0}), mask->view(), chunk_stream, mr),
+        cudf::apply_retention_mask(table.select({0}), mask->view(), chunk_stream, mr),
         chunk_stream)));
   }
   co_await ch_out->drain(ctx->executor());

cpp/libcudf_streaming/benchmarks/streaming/ndsh/q21.cpp

@@ -211,7 +211,7 @@ rapidsmpf::streaming::Actor filter_lineitem(std::shared_ptr<rapidsmpf::streaming
     co_await ch_out->send(cudf_streaming::to_message(
       msg.sequence_number(),
       std::make_unique<cudf_streaming::table_chunk>(
-        cudf::apply_boolean_mask(
+        cudf::apply_retention_mask(
           chunk.table_view().select({0, 1}), mask->view(), chunk.stream(), ctx->br()->device_mr()),
         chunk.stream())));
   }
@@ -243,7 +243,7 @@ rapidsmpf::streaming::Actor filter_grouped_greater(
     co_await ch_out->send(cudf_streaming::to_message(
       msg.sequence_number(),
       std::make_unique<cudf_streaming::table_chunk>(
-        cudf::apply_boolean_mask(
+        cudf::apply_retention_mask(
           chunk.table_view().select({0}), mask->view(), chunk.stream(), ctx->br()->device_mr()),
         chunk.stream())));
     if (!released_lineitem_read) {
@@ -278,7 +278,7 @@ rapidsmpf::streaming::Actor filter_grouped_equal(
     co_await ch_out->send(cudf_streaming::to_message(
       msg.sequence_number(),
       std::make_unique<cudf_streaming::table_chunk>(
-        cudf::apply_boolean_mask(
+        cudf::apply_retention_mask(
           chunk.table_view().select({0}), mask->view(), chunk.stream(), ctx->br()->device_mr()),
         chunk.stream())));
   }

cpp/libcudf_streaming/src/bloom_filter.cpp

@@ -150,7 +150,7 @@ rapidsmpf::streaming::Actor bloom_filter::apply(
                                        mask.data(),
                                        {},
                                        0};
-    auto result    = cudf::apply_boolean_mask(
+    auto result    = cudf::apply_retention_mask(
       chunk.table_view(), mask_view, chunk_stream, ctx_->br()->device_mr());
     std::ignore = std::move(chunk);
     std::ignore = std::move(res);

cpp/src/io/parquet/experimental/hybrid_scan_impl.hpp

@@ -590,7 +590,7 @@ class hybrid_scan_reader_impl : public parquet::detail::reader_impl {
    * and only if in_row_mask[i] is valid and true
    *
    * Updates the output row mask to reflect the final valid and surviving rows from the input row
-   * mask. This is inline with the masking behavior of cudf::detail::apply_boolean_mask
+   * mask. This is inline with the masking behavior of cudf::apply_retention_mask.
    *
    * @param in_row_mask Input row mask column
    * @param out_row_mask Output row mask column

cpp/src/io/parquet/experimental/hybrid_scan_preprocess.cu

@@ -366,7 +366,7 @@ namespace {
 
 /**
  * @brief Computes the updated row mask value such that out_row_mask[i] = true, iff in_row_mask[i]
- * is valid and true. This is inline with the masking behavior of cudf::apply_boolean_mask.
+ * is valid and true. This is inline with the masking behavior of cudf::apply_retention_mask.
  */
 struct row_mask_update_fn {
   bool is_nullable;

cpp/src/join/sort_merge_join.cu

@@ -14,12 +14,12 @@
 #include <cudf/detail/nvtx/ranges.hpp>
 #include <cudf/detail/row_operator/lexicographic.cuh>
 #include <cudf/detail/sizes_to_offsets_iterator.cuh>
+#include <cudf/detail/stream_compaction.hpp>
 #include <cudf/join/join.hpp>
 #include <cudf/join/sort_merge_join.hpp>
 #include <cudf/lists/lists_column_view.hpp>
 #include <cudf/null_mask.hpp>
 #include <cudf/sorting.hpp>
-#include <cudf/stream_compaction.hpp>
 #include <cudf/table/table_view.hpp>
 #include <cudf/types.hpp>
 #include <cudf/utilities/error.hpp>
@@ -648,7 +648,8 @@ void sort_merge_join::preprocessed_table::apply_nonnull_filter(cuda::stream_ref
                "Something went wrong while dropping nulls in the unprocessed tables");
   bool_mask->set_null_mask(_validity_mask.value(), _num_nulls.value(), stream);
 
-  _null_processed_table      = apply_boolean_mask(_table_view, *bool_mask, stream, temp_mr);
+  _null_processed_table =
+    detail::apply_mask(_table_view, *bool_mask, detail::mask_type::RETENTION, stream, temp_mr);
   _null_processed_table_view = _null_processed_table.value()->view();
 }
 

cpp/src/lists/stream_compaction/apply_boolean_mask.cu → cpp/src/lists/stream_compaction/apply_mask.cu

@@ -103,6 +103,15 @@ std::unique_ptr<column> apply_mask(lists_column_view const& input,
 }
 }  // namespace detail
 
+std::unique_ptr<column> apply_retention_mask(lists_column_view const& input,
+                                             lists_column_view const& retention_mask,
+                                             cuda::stream_ref stream,
+                                             rmm::device_async_resource_ref mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::apply_mask(input, retention_mask, cudf::detail::mask_type::RETENTION, stream, mr);
+}
+
 std::unique_ptr<column> apply_boolean_mask(lists_column_view const& input,
                                            lists_column_view const& boolean_mask,
                                            cuda::stream_ref stream,

cpp/src/stream_compaction/apply_boolean_mask.cu → cpp/src/stream_compaction/apply_mask.cu

@@ -96,6 +96,15 @@ std::unique_ptr<table> apply_mask(table_view const& input,
 /*
  * Filters a table_view using a column_view of boolean values as a mask.
  */
+std::unique_ptr<table> apply_retention_mask(table_view const& input,
+                                            column_view const& retention_mask,
+                                            rmm::cuda_stream_view stream,
+                                            rmm::device_async_resource_ref mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::apply_mask(input, retention_mask, detail::mask_type::RETENTION, stream, mr);
+}
+
 std::unique_ptr<table> apply_boolean_mask(table_view const& input,
                                           column_view const& boolean_mask,
                                           cuda::stream_ref stream,

cpp/tests/CMakeLists.txt

@@ -513,7 +513,7 @@ ConfigureTest(
 # * stream compaction tests -----------------------------------------------------------------------
 ConfigureTest(
   STREAM_COMPACTION_TEST
-  stream_compaction/apply_boolean_mask_tests.cpp
+  stream_compaction/apply_mask_tests.cpp
   stream_compaction/distinct_tests.cpp
   stream_compaction/drop_nans_tests.cpp
   stream_compaction/drop_nulls_tests.cpp
@@ -738,7 +738,7 @@ ConfigureTest(
   lists/set_operations/intersect_distinct_tests.cpp
   lists/set_operations/union_distinct_tests.cpp
   lists/sort_lists_tests.cpp
-  lists/stream_compaction/apply_boolean_mask_tests.cpp
+  lists/stream_compaction/apply_mask_tests.cpp
   lists/stream_compaction/distinct_tests.cpp
   GPUS 1
   PERCENT 70