Aggregation Reduction#

group Reduction

Enums

enum class scan_type : bool#

Enum to describe scan operation type.

Values:

enumerator INCLUSIVE#

enumerator EXCLUSIVE#

Functions

std::unique_ptr<scalar> reduce(column_view const &col, reduce_aggregation const &agg, data_type output_type, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

Computes the reduction of the values in all rows of a column.

This function does not detect overflows in reductions except for the SUM_WITH_OVERFLOW aggregation. When output_type does not match the col.type(), their values may be promoted to int64_t or double for computing aggregations and then cast to output_type before returning.

The SUM_WITH_OVERFLOW aggregation is a special case that detects integer overflow during summation of int64_t values and returns a struct containing both the sum result and an overflow flag.

Only min and max ops are supported for reduction of non-arithmetic types (e.g. timestamp or string).

Any null values are skipped for the operation. If the reduction fails, the output scalar returns with is_valid()==false.

For empty or all-null input, the result is generally an invalid scalar except for specific aggregations where the aggregation has a well-defined output.

If the input column is an arithmetic type, the output_type can be any arithmetic type. If the input column is a non-arithmetic type (e.g. timestamp or string) the output_type must match the col.type(). If the reduction type is any or all, the output_type must be type BOOL8.

Aggregation	Output Type	Init Value	Empty Input	Comments
SUM/PRODUCT	output_type	yes	NA	Input accumulated into output_type variable
SUM_WITH_OVERFLOW	STRUCT{INT64,BOOL8}	yes	{null,false}	{sum, overflow_flag}, input must be INT64
SUM_OF_SQUARES	output_type	no	NA	Input accumulated into output_type variable
MIN/MAX	col.type	yes	NA	Supports arithmetic, timestamp, duration, string types only
ANY/ALL	BOOL8	yes	True for ALL only	Checks for non-zero elements
MEAN/VARIANCE/STD	FLOAT32/FLOAT64	no	NA	output_type must be a float type
MEDIAN/QUANTILE	output_type	no	NA	Exact value if output_type is FLOAT64. See cudf::quantile
NUNIQUE	output_type	no	1 if all-nulls	May process null rows
NTH_ELEMENT	col.type	no	NA
BITWISE_AGG	col.type	no	NA	Supports only integral types
HISTOGRAM/MERGE_HISTOGRAM	LIST of col.type	no	empty list returned
COLLECT_LIST/COLLECT_SET	LIST of col.type	no	empty list returned
TDIGEST/MERGE_TDIGEST	STRUCT	no	empty struct returned	tdigest scalar is returned
HOST_UDF	output_type	yes	NA	Custom UDF could ignore output_type

The NA in the table indicates an output scalar with is_valid()==false

Throws:

std::invalid_argument – if reduction is called for non-arithmetic output type and operator other than min and max.
std::invalid_argument – if input column data type is not convertible to output_type.
std::invalid_argument – if min or max reduction is called and the output type does not match the input column data type.
std::invalid_argument – if any or all reduction is called and the output type is not BOOL8.
std::invalid_argument – if mean, var, or std reduction is called and the output_type is not floating point.
std::invalid_argument – if sum_with_overflow reduction is called and the input column type is not INT64 or the output_dtype is not STRUCT.

Parameters:

col – Input column view
agg – Aggregation operator applied by the reduction
output_type – The output scalar type
stream – CUDA stream used for device memory operations and kernel launches
mr – Device memory resource used to allocate the returned scalar’s device memory

Returns:

Output scalar with reduce result

std::unique_ptr<scalar> reduce(column_view const &col, reduce_aggregation const &agg, data_type output_type, std::optional<std::reference_wrapper<scalar const>> init, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

Computes the reduction of the values in all rows of a column with an initial value.

Only sum, product, min, max, any, all, and sum_with_overflow reductions are supported. For sum_with_overflow, the initial value is added to the sum and overflow detection is performed throughout the entire computation.

Aggregation Reduction#

This Page