聚合规约#

group 规约

枚举

enum class scan_type : bool#

描述扫描操作类型的枚举。

值

enumerator INCLUSIVE#
enumerator EXCLUSIVE#

函数

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

计算列中所有行的值规约。

此函数不检测规约中的溢出。当 output_dtype 与 col.type() 不匹配时，在计算聚合时其值可能被提升为 int64_t 或 double，然后在返回前转换为 output_dtype。

对于非算术类型（例如时间戳或字符串）的规约，仅支持 min 和 max 操作。

操作会跳过任何空值。

如果列为空或包含所有空条目 col.size()==col.null_count()，则对于规约类型 any，输出标量值为 false；对于规约类型 all，输出标量值为 true。对于所有其他规约，输出标量返回时 is_valid()==false。

如果输入列是算术类型，output_dtype 可以是任何算术类型。如果输入列是非算术类型（例如时间戳或字符串），output_dtype 必须与 col.type() 匹配。如果规约类型是 any 或 all，output_dtype 必须是 BOOL8 类型。

如果规约失败，输出标量返回时 is_valid()==false。

抛出:

  • cudf::logic_error – 如果对非算术输出类型且操作符不是 min 和 max 时调用规约。

  • cudf::logic_error – 如果输入列数据类型不可转换为 output_dtype。

  • cudf::logic_error – 如果调用 min 或 max 规约且输出类型与输入列数据类型不匹配。

  • cudf::logic_error – 如果调用 any 或 all 规约且输出类型不是 BOOL8。

  • cudf::logic_error – 如果调用 mean、var 或 std 规约且 output_dtype 不是浮点类型。

参数:

  • col – 输入列视图

  • agg – 规约应用的聚合操作符

  • output_dtype – 输出标量类型

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配返回标量设备内存的设备内存资源

返回:

包含规约结果的输出标量

std::unique_ptr<scalar> reduce(column_view const &col, reduce_aggregation const &agg, data_type output_dtype, 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())#

计算列中所有行的值规约，带有一个初始值。

仅支持 sum、product、min、max、any 和 all 规约。

抛出:

cudf::logic_error – 如果规约不是 sum、product、min、max、any 或 all 且指定了 init。

参数:

  • col – 输入列视图

  • agg – 规约应用的聚合操作符

  • output_dtype – 输出标量类型

  • init – 规约的初始值

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配返回标量设备内存的设备内存资源

返回:

包含规约结果的输出标量

std::unique_ptr<column> segmented_reduce(column_view const &segmented_values, device_span<size_type const> offsets, segmented_reduce_aggregation const &agg, data_type output_dtype, null_policy null_handling, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

计算输入列中每个段的规约。

此函数不检测规约中的溢出。当 output_dtype 与 segmented_values.type() 不匹配时，在计算聚合时其值可能被提升为 int64_t 或 double，然后在返回前转换为 output_dtype。

在规约期间，空值被视为恒等元。

如果段为空，则与该段结果对应的行为空。

如果 offsets 中的任何索引超出 segmented_values 的边界，则行为未定义。

如果输入列是算术类型，output_dtype 可以是任何算术类型。如果输入列是非算术类型（例如时间戳），则必须指定相同的输出类型。

如果输入非空，则结果始终可空。

抛出:

  • cudf::logic_error – 如果对非算术输出类型且操作符不是 min 和 max 时调用规约。

  • cudf::logic_error – 如果输入列数据类型不可转换为 output_dtype 类型。

  • cudf::logic_error – 如果调用 min 或 max 规约且 output_dtype 与输入列数据类型不匹配。

  • cudf::logic_error – 如果调用 any 或 all 规约且 output_dtype 不是 BOOL8。

参数:

  • segmented_values – 分段输入的列视图

  • offsets – segmented_values 中每个段的偏移量。一个包含 num_segments + 1 个偏移量的列表。第 i 个段的大小是 offsets[i+1] - offsets[i]。

  • agg – 规约应用的聚合操作符

  • output_dtype – 输出列类型

  • null_handling – 如果是 INCLUDE，如果段中的所有元素都有效，则规约有效，否则为空。如果是 EXCLUDE，如果段中的任何元素有效，则规约有效，否则为空。

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配返回标量设备内存的设备内存资源

返回:

包含分段规约结果的输出列

std::unique_ptr<column> segmented_reduce(column_view const &segmented_values, device_span<size_type const> offsets, segmented_reduce_aggregation const &agg, data_type output_dtype, null_policy null_handling, 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())#

计算输入列中每个段的规约，带有一个初始值。仅支持 SUM、PRODUCT、MIN、MAX、ANY 和 ALL 聚合。

参数:

  • segmented_values – 分段输入的列视图

  • offsets – segmented_values 中每个段的偏移量。一个包含 num_segments + 1 个偏移量的列表。第 i 个段的大小是 offsets[i+1] - offsets[i]。

  • agg – 规约应用的聚合操作符

  • output_dtype – 输出列类型

  • null_handling – 如果是 INCLUDE，如果段中的所有元素都有效，则规约有效，否则为空。如果是 EXCLUDE，如果段中的任何元素有效，则规约有效，否则为空。

  • init – 规约的初始值

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配返回标量设备内存的设备内存资源

返回:

包含分段规约结果的输出列。

std::unique_ptr<column> scan(column_view const &input, scan_aggregation const &agg, scan_type inclusive, null_policy null_handling = null_policy::EXCLUDE, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

计算列的扫描。

操作会跳过空值，并且如果输入元素在 i 处为空，则输出元素在 i 处也将为空。

抛出:

cudf::logic_error – 如果列数据类型不是数值类型。

参数:

  • input – [in] 用于扫描的输入列视图

  • agg – [in] scan 应用的聚合操作符的 unique_ptr

  • inclusive – [in] 标志，如果 scan_type::INCLUSIVE 则应用包含式扫描，如果 scan_type::EXCLUSIVE 则应用排除式扫描。

  • null_handling – [in] 如果 null_policy::EXCLUDE，则在计算结果时排除空值。如果 null_policy::INCLUDE，则包含空值。任何涉及空值的操作结果都为空。

  • stream – [in] 用于设备内存操作和内核启动的 CUDA 流

  • mr – [in] 用于分配返回标量设备内存的设备内存资源

返回:

扫描后的输出列

std::pair<std::unique_ptr<scalar>, std::unique_ptr<scalar>> minmax(column_view const &col, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

确定列的最小值和最大值。

参数:

  • col – 计算最小值/最大值的列

  • stream – 用于设备内存操作和内核启动的 CUDA 流

  • mr – 用于分配返回列设备内存的设备内存资源

返回:

一个 std::pair 标量，其中第一个标量是输入列的最小值，第二个标量是输入列的最大值。