聚合工厂#

group Aggregation Factories

枚举

enum class rank_percentage : int32_t#

返回的排名是否应为百分比，并说明百分比归一化的类型。

值

enumerator NONE#: 排名

enumerator ZERO_NORMALIZED#: rank / count

enumerator ONE_NORMALIZED#: (rank - 1) / (count - 1)

enum class udf_type : bool#

用户定义函数字符串中的代码类型。

值

enumerator CUDA#

enumerator PTX#

enum class correlation_type : int32_t#

相关性方法类型。

值

enumerator PEARSON#

enumerator KENDALL#

enumerator SPEARMAN#

enum class ewm_history : int32_t#

EWM 输入值第一个值的处理方式类型。

值

enumerator INFINITE#

enumerator FINITE#

函数

template<typename Base = aggregation> std::unique_ptr<Base> make_sum_aggregation()#

用于创建 SUM 聚合的工厂

返回:: 一个 SUM 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_product_aggregation()#

用于创建 PRODUCT 聚合的工厂

返回:: 一个 PRODUCT 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_min_aggregation()#

用于创建 MIN 聚合的工厂

返回:: 一个 MIN 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_max_aggregation()#

用于创建 MAX 聚合的工厂

返回:: 一个 MAX 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_count_aggregation(null_policy null_handling = null_policy::EXCLUDE)#

用于创建 COUNT 聚合的工厂。

参数:: null_handling – 指示是否计算空值
返回:: 一个 COUNT 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_any_aggregation()#

用于创建 ANY 聚合的工厂

返回:: 一个 ANY 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_all_aggregation()#

用于创建 ALL 聚合的工厂

返回:: 一个 ALL 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_histogram_aggregation()#

用于创建 HISTOGRAM 聚合的工厂

返回:: 一个 HISTOGRAM 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_sum_of_squares_aggregation()#

用于创建 SUM_OF_SQUARES 聚合的工厂

返回:: 一个 SUM_OF_SQUARES 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_mean_aggregation()#

用于创建 MEAN 聚合的工厂

返回:: 一个 MEAN 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_m2_aggregation()#

用于创建 M2 聚合的工厂。

M2 聚合是与均值之差的平方和。即：M2 = SUM((x - MEAN) * (x - MEAN))。

此聚合生成用于计算多个离散数据集的方差和标准差的中间值。有关更多详细信息，请参阅#Parallel_algorithm。

返回:: 一个 M2 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_variance_aggregation(size_type ddof = 1)#

用于创建 VARIANCE 聚合的工厂。

参数:: ddof – 自由度的增量。计算 variance 时使用的除数是 N - ddof，其中 N 是总体大小。
抛出:: cudf::logic_error – 如果输入类型是chrono或复合类型。
返回:: 一个 VARIANCE 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_std_aggregation(size_type ddof = 1)#

用于创建 STD 聚合的工厂。

参数:: ddof – 自由度的增量。计算 std 时使用的除数是 N - ddof，其中 N 是总体大小。
抛出:: cudf::logic_error – 如果输入类型是chrono或复合类型。
返回:: 一个 STD 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_median_aggregation()#

用于创建 MEDIAN 聚合的工厂

返回:: 一个 MEDIAN 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_quantile_aggregation(std::vector<double> const &quantiles, interpolation interp = interpolation::LINEAR)#

用于创建 QUANTILE 聚合的工厂。

参数:

quantiles – 所需的分位数
interp – 所需的插值方法

返回:

一个 QUANTILE 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_argmax_aggregation()#

用于创建 ARGMAX 聚合的工厂。

ARGMAX 返回最大元素的索引。

返回:: 一个 ARGMAX 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_argmin_aggregation()#

用于创建 ARGMIN 聚合的工厂。

argmin 返回最小元素的索引。

返回:: 一个 ARGMIN 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_nunique_aggregation(null_policy null_handling = null_policy::EXCLUDE)#

用于创建 NUNIQUE 聚合的工厂。

NUNIQUE 返回唯一元素的数量。

参数:: null_handling – 指示是否计算空值
返回:: 一个 NUNIQUE 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_nth_element_aggregation(size_type n, null_policy null_handling = null_policy::INCLUDE)#

用于创建 NTH_ELEMENT 聚合的工厂。

NTH_ELEMENT 返回组/序列的第 n 个元素。

如果 n 不在 [-group_size, group_size) 范围内，则相应组的结果将为空值。负索引 [-group_size, -1] 分别对应于 [0, group_size-1] 索引，其中 group_size 是每组的大小。

参数:

n – 每组中第 n 个元素的索引
null_handling – 指示在索引期间包含/排除空值

返回:

一个 NTH_ELEMENT 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_row_number_aggregation()#

用于创建 ROW_NUMBER 聚合的工厂

返回:: 一个 ROW_NUMBER 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_ewma_aggregation(double const center_of_mass, ewm_history history)#

用于创建 EWMA 聚合的工厂。

EWMA 返回一个不可为空的列，其类型与输入相同，其值是输入序列的指数加权移动平均值。将这些值记为 y_i。

EWMA 聚合通过质心 (com) 进行参数化，质心影响先前值 (y_0 … y_{i-1}) 在计算 y_i 中的贡献。

EWMA 聚合也通过历史记录 cudf::ewm_history 进行参数化。必须特别考虑输入序列第一个值的数学处理。对此有两种方法：一种认为序列的第一个值是某些无限数据历史的指数加权移动平均值；另一种认为第一个值是唯一已知的数据点。这些假设导致了 y_i 的两种不同公式。ewm_history 选择其中一种。

EWMA 聚合具有特殊的空值处理。空值有两个作用。第一个作用是将最后一个有效值向前传播，直到计算出。这可以视为空值对平均值没有任何影响。第二个作用改变了 y_i 的计算方式。由于移动平均线在概念上旨在根据贡献值的近期程度进行加权，因此即使空值不改变平均值，也应将其计为有效周期。例如，如果输入序列是 {1, NULL, 3}，那么在计算 y_2 时，应该将 y_0 视为发生在 y_2 之前的两个周期，而不仅仅是一个周期。

参数:

center_of_mass – 质心。
history – 关于第一个值的假设选择

返回:

一个 EWM 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_rank_aggregation(rank_method method, order column_order = order::ASCENDING, null_policy null_handling = null_policy::EXCLUDE, null_order null_precedence = null_order::AFTER, rank_percentage percentage = rank_percentage::NONE)#

用于创建 RANK 聚合的工厂。

RANK 返回一个 size_type 或 double 类型的“排名”列（有关如何确定数据类型，请参阅下面的注释 3），用于给定的排名方法和列顺序。如果排除空值，则这些行的排名将为空值，否则返回一个不可为空的列。仅当 percentage!=NONE 且排名方法为 average 时，才返回双精度列。

此聚合仅适用于“扫描”算法。组或未分组扫描的输入列是一个 orderby 列，该列按聚合函数排名行。如果行按多列排序，则 orderby 输入列应为包含排序列的结构体列。

注意

如果行按分组键和 order_by 列预排序，此方法可能会更快。尽管 groupby 对象不要求 order_by 列已排序，但如果键已排序，groupby rank scan 聚合确实要求 order_by 列已排序。
RANK 聚合与 exclusive scans 不兼容。
除 AVERAGE 方法和 percentage!=NONE 外，所有排名方法都返回 size_type 列。对于 AVERAGE 方法和 percentage!=NONE，返回类型为 double 列。

Example: Consider a motor-racing statistics dataset, containing the following columns:
  1. venue:  (STRING) Location of the race event
  2. driver: (STRING) Name of the car driver (abbreviated to 3 characters)
  3. time:   (INT32)  Time taken to complete the circuit

For the following presorted data:

 [ //      venue,           driver,           time
   {   "silverstone",  "HAM" ("hamilton"),   15823},
   {   "silverstone",  "LEC" ("leclerc"),    15827},
   {   "silverstone",  "BOT" ("bottas"),     15834},  // <-- Tied for 3rd place.
   {   "silverstone",  "NOR" ("norris"),     15834},  // <-- Tied for 3rd place.
   {   "silverstone",  "RIC" ("ricciardo"),  15905},
   {      "monza",     "RIC" ("ricciardo"),  12154},
   {      "monza",     "NOR" ("norris"),     12156},  // <-- Tied for 2nd place.
   {      "monza",     "BOT" ("bottas"),     12156},  // <-- Tied for 2nd place.
   {      "monza",     "LEC" ("leclerc"),    12201},
   {      "monza",     "PER" ("perez"),      12203}
 ]

A grouped rank aggregation scan with:
  groupby column      : venue
  input orderby column: time
Produces the following rank column for each methods:
first:   {   1,     2,     3,     4,     5,      1,     2,     3,     4,     5}
average: {   1,     2,   3.5,   3.5,     5,      1,   2.5,   2.5,     4,     5}
min:     {   1,     2,     3,     3,     5,      1,     2,     2,     4,     5}
max:     {   1,     2,     4,     4,     5,      1,     3,     3,     4,     5}
dense:   {   1,     2,     3,     3,     4,      1,     2,     2,     3,     4}
This corresponds to the following grouping and `driver` rows:
         { "HAM", "LEC", "BOT", "NOR", "RIC",  "RIC", "NOR", "BOT", "LEC", "PER" }
           <----------silverstone----------->|<-------------monza-------------->

min rank for each percentage types:
NONE:             {   1,      2,     3,     3,     5,      1,     2,     2,     4,     5 }
ZERO_NORMALIZED : { 0.16,  0.33,  0.50,  0.50,  0.83,   0.16,  0.33,  0.33,  0.66,  0.83 }
ONE_NORMALIZED:   { 0.00,  0.25,  0.50,  0.50,  1.00,   0.00,  0.25,  0.25,  0.75,  1.00 }
where count corresponds to the number of rows in the group. @see cudf::rank_percentage

参数:

method – 用于打破平局（相同值）的排名方法
column_order – 排名所需的排序顺序
null_handling – 在排名期间包含空值的标志。如果未包含空值，则相应的排名将为空值。
null_precedence – 列中空值与其他元素相比的所需顺序
percentage – 枚举，表示将排名转换为范围 (0,1] 内百分比的类型

返回:

一个 RANK 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_collect_list_aggregation(null_policy null_handling = null_policy::INCLUDE)#

用于创建 COLLECT_LIST 聚合的工厂。

COLLECT_LIST 返回组/序列中所有包含元素的列表列。

如果 null_handling 设置为 EXCLUDE，则从每个列表行中删除空元素。

参数:: null_handling – 指示是否在列表元素中包含/排除空值
返回:: 一个 COLLECT_LIST 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_collect_set_aggregation(null_policy null_handling = null_policy::INCLUDE, null_equality nulls_equal = null_equality::EQUAL, nan_equality nans_equal = nan_equality::ALL_EQUAL)#

用于创建 COLLECT_SET 聚合的工厂。

COLLECT_SET 返回组/序列中所有包含元素的列表列。在每个列表中，重复的条目将被删除，以使每个条目只出现一次。

如果 null_handling 设置为 EXCLUDE，则从每个列表行中删除空元素。

参数:

null_handling – 指示在收集期间是否包含/排除空值
nulls_equal – 标志，指定每个列表中的空条目是否应视为相等。
nans_equal – 标志，指定浮点列中的 NaN 值是否应视为相等。

返回:

一个 COLLECT_SET 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_lag_aggregation(size_type offset)#

用于创建 LAG 聚合的工厂。

参数:: offset – 输入的滞后行数
返回:: 一个 LAG 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_lead_aggregation(size_type offset)#

用于创建 LEAD 聚合的工厂。

参数:: offset – 输入的超前行数
返回:: 一个 LEAD 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_udf_aggregation(udf_type type, std::string const &user_defined_aggregator, data_type output_type)#

用于创建基于 PTX 或 CUDA 的 UDF 聚合的工厂。

参数:

type – [in] udf_type::PTX 或 udf_type::CUDA
user_defined_aggregator – [in] 包含聚合器代码的字符串
output_type – [in] 预期的输出类型

返回:

包含用户定义聚合器字符串的聚合

template<typename Base = aggregation> std::unique_ptr<Base> make_host_udf_aggregation(std::unique_ptr<host_udf_base> host_udf)#

用于创建 HOST_UDF 聚合的工厂。

参数:: host_udf – 派生自 host_udf_base 的类实例，用于执行聚合
返回:: 一个 HOST_UDF 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_merge_lists_aggregation()#

用于创建 MERGE_LISTS 聚合的工厂。

给定一个列表列，此聚合将所有对应于相同键值的列表合并为一个列表。它专门用于将多个（分布式）groupby COLLECT_LIST 聚合的中间结果合并为最终的 COLLECT_LIST 结果。因此，它要求输入列表列不可为空（包含列表项的子列不受此限制）。

返回:: 一个 MERGE_LISTS 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_merge_sets_aggregation(null_equality nulls_equal = null_equality::EQUAL, nan_equality nans_equal = nan_equality::ALL_EQUAL)#

用于创建 MERGE_SETS 聚合的工厂。

给定一个列表列，此聚合首先将所有对应于相同键值的列表合并为一个列表，然后删除每个列表中的所有重复条目，生成一个包含不重复条目的列表列。

此聚合专门用于将多个（分布式）groupby COLLECT_LIST 或 COLLECT_SET 聚合的中间结果合并为最终的 COLLECT_SET 结果。因此，它要求输入列表列不可为空（包含列表项的子列不受此限制）。

实际上，此聚合的输入（中间结果）应由（分布式）COLLECT_LIST 聚合生成，而不是 COLLECT_SET，以避免不必要地删除中间结果中的重复条目。

参数:

nulls_equal – 标志，用于指定在删除重复列表条目时，是否应将每个列表中的 null 视为相等。
nans_equal – 标志，用于指定在删除重复列表条目时，浮点列中的 NaN 值是否应被视为相等。

返回:

一个 MERGE_SETS 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_merge_m2_aggregation()#

用于创建 MERGE_M2 聚合的工厂。

将独立集合上 M2 聚合的结果合并为一个新的 M2 值，该值等同于一次性对所有集合执行单个 M2 聚合的结果。此聚合仅对 struct 有效，其成员是同一集合上 COUNT_VALID、MEAN 和 M2 聚合的结果。此聚合的输出是一个包含合并后的 COUNT_VALID、MEAN 和 M2 聚合的 struct。

输入 M2 聚合值应全部为非负数，因为它们是从 M2 聚合输出的。

返回:: 一个 MERGE_M2 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_merge_histogram_aggregation()#

用于创建 MERGE_HISTOGRAM 聚合的工厂。

将独立集合上 HISTOGRAM 聚合的结果合并为一个新的 HISTOGRAM 值，该值等同于一次性对所有集合执行单个 HISTOGRAM 聚合的结果。

返回:: 一个 MERGE_HISTOGRAM 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_covariance_aggregation(size_type min_periods = 1, size_type ddof = 1)#

用于创建 COVARIANCE 聚合的工厂。

计算两列之间的协方差。输入列是不可为空的 struct 列的子列。

参数:

min_periods – 生成结果所需的最小非 null 观测值数量
ddof – 自由度的 delta。计算中使用的除数是 N - ddof，其中 N 是非 null 观测值的数量。

返回:

一个 COVARIANCE 聚合对象

template<typename Base = aggregation> std::unique_ptr<Base> make_correlation_aggregation(correlation_type type, size_type min_periods = 1)#

用于创建 CORRELATION 聚合的工厂。

计算两列之间的相关系数。输入列是不可为空的 struct 列的子列。

参数:

type – correlation_type
min_periods – 生成结果所需的最小非 null 观测值数量

返回:

一个 CORRELATION 聚合对象

template<typename Base> std::unique_ptr<Base> make_tdigest_aggregation(int max_centroids = 1000)#

用于创建 TDIGEST 聚合的工厂。

从输入值生成一个 tdigest（https://arxiv.org/pdf/1902.04023.pdf）列。输入聚合值应为固定宽度的数值类型。

生成的 tdigest 列结构如下

struct { // 摘要列表的中心点 { struct { double // 均值 double // 权重 }, … } // 这些来自输入流，而不是中心点。它们用于 // 在计算近似分位数时，在开头或 // 结尾附近。 double // 最小值 double // 最大值 }

每个输出行是一个单独的 tdigest。行的长度是 tdigest 的“大小”，其中每个元素代表一个加权质心（均值，权重）。

参数:: max_centroids – 控制压缩级别和对输出 tdigest 数据进行后续查询时的准确度的参数。max_centroids 为计算出的 tdigest 的大小设定了一个上限：值为 1000 将导致 tdigest 包含不超过 1000 个质心（每个 32 字节）。值越高，tdigest 信息越准确。
返回:: 一个 TDIGEST 聚合对象

template<typename Base> std::unique_ptr<Base> make_merge_tdigest_aggregation(int max_centroids = 1000)#

用于创建 MERGE_TDIGEST 聚合的工厂。

合并来自先前通过 make_tdigest_aggregation 或 make_merge_tdigest_aggregation 生成的聚合结果，以生成一个新的 tdigest（https://arxiv.org/pdf/1902.04023.pdf）列。

生成的 tdigest 列结构如下

每个输出行是一个单独的 tdigest。行的长度是 tdigest 的“大小”，其中每个元素代表一个加权质心（均值，权重）。

参数:: max_centroids – 控制压缩级别和对输出 tdigest 数据进行后续查询时的准确度的参数。max_centroids 为计算出的 tdigest 的大小设定了一个上限：值为 1000 将导致 tdigest 包含不超过 1000 个质心（每个 32 字节）。值越高，tdigest 信息越准确。
返回:: 一个 MERGE_TDIGEST 聚合对象

class host_udf_base#

#include <host_udf.hpp>

基于主机的 UDF 实现的基本接口。

此类声明了用户 UDF 实现中必须定义的函数 do_hash、is_equal 和 clone。 libcudf 聚合框架需要这些函数来执行其操作。

派生类包括 cudf::groupby_host_udf, cudf::reduce_host_udf, cudf::segmented_reduce_host_udf

公有函数

virtual ~host_udf_base() = default#: 默认析构函数。

inline virtual std::size_t do_hash() const#

计算实例的哈希值。

当派生类具有数据成员，使得每个实例需要彼此区分时，覆盖此函数是可选的。

返回:: 实例的哈希值

virtual bool is_equal(host_udf_base const &other) const = 0#

比较派生类的两个实例是否相等。

参数:: other – 要与之比较的另一个实例
返回:: 如果两个实例相等，则为 True

virtual std::unique_ptr<host_udf_base> clone() const = 0#

克隆实例。

派生类的实例应轻量级，以便高效克隆。

返回:: 从此实例克隆出的新实例

struct reduce_host_udf : public cudf::host_udf_base #

#include <host_udf.hpp>

用于 reduction 上下文的基于主机的 UDF 实现接口。

用于 reduction 的基于主机的 UDF 实现需要从此类派生。除了实现基类 host_udf_base 中声明的虚函数外，此类派生类还必须定义 operator() 函数来执行 reduction 操作。

示例

struct my_udf_aggregation : cudf::reduce_host_udf {
  my_udf_aggregation() = default;

  [[nodiscard]] std::unique_ptr<scalar> operator()(
    column_view const& input,
    data_type output_dtype,
    std::optional<std::reference_wrapper<scalar const>> init,
    rmm::cuda_stream_view stream,
    rmm::device_async_resource_ref mr) const override
  {
    // Perform reduction computation using the input data and return the reduction result.
    // This is where the actual reduction logic is implemented.
  }

  [[nodiscard]] bool is_equal(host_udf_base const& other) const override
  {
    // Check if the other object is also instance of this class.
    // If there are internal state variables, they may need to be checked for equality as well.
    return dynamic_cast<my_udf_aggregation const*>(&other) != nullptr;
  }

  [[nodiscard]] std::unique_ptr<host_udf_base> clone() const override
  {
    return std::make_unique<my_udf_aggregation>();
  }
};

公有函数

virtual std::unique_ptr<scalar> operator()(column_view const &input, data_type output_dtype, std::optional<std::reference_wrapper<scalar const>> init, rmm::cuda_stream_view stream, rmm::device_async_resource_ref mr) const = 0#

执行 reduction 操作。

参数:

input – 用于 reduction 的输入列
output_dtype – 最终输出标量的数据类型
init – reduction 的初始值
stream – 用于任何内核启动的 CUDA 流
mr – 用于任何分配的设备内存资源

返回:

聚合的输出结果

struct segmented_reduce_host_udf : public cudf::host_udf_base #

#include <host_udf.hpp>

用于分段 reduction 上下文的基于主机的 UDF 实现接口。

用于分段 reduction 的基于主机的 UDF 实现需要从此类派生。除了实现基类 host_udf_base 中声明的虚函数外，此类派生类还必须定义 operator() 函数来执行分段 reduction。

示例

struct my_udf_aggregation : cudf::segmented_reduce_host_udf {
  my_udf_aggregation() = default;

  [[nodiscard]] std::unique_ptr<column> operator()(
    column_view const& input,
    device_span<size_type const> offsets,
    data_type output_dtype,
    null_policy null_handling,
    std::optional<std::reference_wrapper<scalar const>> init,
    rmm::cuda_stream_view stream,
    rmm::device_async_resource_ref mr) const override
  {
    // Perform computation using the input data and return the result.
    // This is where the actual segmented reduction logic is implemented.
  }

  [[nodiscard]] bool is_equal(host_udf_base const& other) const override
  {
    // Check if the other object is also instance of this class.
    // If there are internal state variables, they may need to be checked for equality as well.
    return dynamic_cast<my_udf_aggregation const*>(&other) != nullptr;
  }

  [[nodiscard]] std::unique_ptr<host_udf_base> clone() const override
  {
    return std::make_unique<my_udf_aggregation>();
  }
};

公有函数

virtual std::unique_ptr<column> operator()(column_view const &input, device_span<size_type const> offsets, data_type output_dtype, null_policy null_handling, std::optional<std::reference_wrapper<scalar const>> init, rmm::cuda_stream_view stream, rmm::device_async_resource_ref mr) const = 0#

执行分段 reduction 操作。

参数:

input – 用于 reduction 的输入列
offsets – 定义 reduction 段的偏移量列表
output_dtype – 最终输出列的数据类型
null_handling – 如果为 INCLUDE，则仅当段中所有元素都有效时，reduction 结果才有效；如果为 EXCLUDE，则只要段中任意元素有效，reduction 结果就有效
init – reduction 的初始值
stream – 用于任何内核启动的 CUDA 流
mr – 用于任何分配的设备内存资源

返回:

聚合的输出结果

struct groupby_host_udf : public cudf::host_udf_base #

#include <host_udf.hpp>

用于 groupby 聚合上下文的基于主机的 UDF 实现接口。

用于 groupby 的基于主机的 UDF 实现需要从此类派生。除了实现基类 host_udf_base 中声明的虚函数外，此类派生类还必须定义函数 get_empty_output()（用于在输入为空时返回结果）以及 operator()（用于执行其 groupby 操作）。

执行期间，派生类可以通过一组 get* 访问器访问 libcudf groupby 框架提供的内部数据，以及通过 compute_aggregation 函数调用其他内置 groupby 聚合。

示例

struct my_udf_aggregation : cudf::groupby_host_udf {
  my_udf_aggregation() = default;

  [[nodiscard]] std::unique_ptr<column> get_empty_output(
    rmm::cuda_stream_view stream,
    rmm::device_async_resource_ref mr) const override
  {
    // Return a column corresponding to the result when the input values column is empty.
  }

  [[nodiscard]] std::unique_ptr<column> operator()(
    rmm::cuda_stream_view stream,
    rmm::device_async_resource_ref mr) const override
  {
    // Perform UDF computation using the input data and return the result.
  }

  [[nodiscard]] bool is_equal(host_udf_base const& other) const override
  {
    // Check if the other object is also instance of this class.
    // If there are internal state variables, they may need to be checked for equality as well.
    return dynamic_cast<my_udf_aggregation const*>(&other) != nullptr;
  }

  [[nodiscard]] std::unique_ptr<host_udf_base> clone() const override
  {
    return std::make_unique<my_udf_aggregation>();
  }
};

注意

派生类只能执行基于排序的 groupby 聚合。基于哈希的 groupby 聚合需要更复杂的数据结构，尚未支持。

公有函数

virtual std::unique_ptr<column> get_empty_output(rmm::cuda_stream_view stream, rmm::device_async_resource_ref mr) const = 0#

在输入值列为空时获取输出。

当输入值列为空时，libcudf 会调用此函数。在这种情况下，libcudf 会尝试直接生成输出，避免不必要地评估中间数据。

参数:

stream – 用于任何内核启动的 CUDA 流
mr – 用于任何分配的设备内存资源

返回:

当输入值列为空时聚合的输出结果

virtual std::unique_ptr<column> operator()(rmm::cuda_stream_view stream, rmm::device_async_resource_ref mr) const = 0#

为基于主机的 UDF 执行主要的 groupby 计算。

参数:

stream – 用于任何内核启动的 CUDA 流
mr – 用于任何分配的设备内存资源

返回:

聚合的输出结果

class aggregation#

#include <aggregation.hpp>

在 aggregation_request 中指定所需聚合的抽象基类。

所有聚合都必须从此类派生，以实现纯虚函数，并可能封装计算聚合所需的附加信息。

派生类包括 cudf::groupby_aggregation, cudf::groupby_scan_aggregation, cudf::reduce_aggregation, cudf::rolling_aggregation, cudf::scan_aggregation, cudf::segmented_reduce_aggregation

公有类型

enum Kind#

可能的聚合操作。

值

enumerator SUM#: 求和 reduction

enumerator PRODUCT#: 乘积 reduction

enumerator MIN#: 最小值 reduction

enumerator MAX#: 最大值 reduction

enumerator COUNT_VALID#: 统计有效元素数量

enumerator COUNT_ALL#: 统计元素数量

enumerator ANY#: 任意 reduction

enumerator ALL#: 全部 reduction

enumerator SUM_OF_SQUARES#: 平方和 reduction

enumerator MEAN#: 算术平均值 reduction

enumerator M2#: 与均值之差的平方和

enumerator VARIANCE#: 方差

enumerator STD#: 标准差

enumerator MEDIAN#: 中位数 reduction

enumerator QUANTILE#: 计算指定的分位数

enumerator ARGMAX#: 最大元素的索引。

enumerator ARGMIN#: 最小元素的索引。

enumerator NUNIQUE#: 统计唯一元素数量

enumerator NTH_ELEMENT#: 获取第 n 个元素

enumerator ROW_NUMBER#: 获取当前索引的行号（相对于滚动窗口）

enumerator EWMA#: 获取当前索引处的指数加权移动平均

enumerator RANK#: 获取当前索引的排名

enumerator COLLECT_LIST#: 将值收集到列表中

enumerator COLLECT_SET#: 将值收集到不含重复条目的列表中

enumerator LEAD#: 窗口函数，访问当前行之后指定偏移量的行

enumerator LAG#: 窗口函数，访问当前行之前指定偏移量的行

enumerator PTX#: 基于 PTX 的 UDF 聚合。

enumerator CUDA#: 基于 CUDA 的 UDF 聚合。

enumerator HOST_UDF#: 基于主机的 UDF 聚合

enumerator MERGE_LISTS#: 将多个列表值合并到一个列表中

enumerator MERGE_SETS#: 将多个列表值合并到一个列表中，然后删除重复条目

enumerator MERGE_M2#: 合并 M2 聚合的中间值，

enumerator COVARIANCE#: 两组元素之间的协方差

enumerator CORRELATION#: 两组元素之间的相关性

enumerator TDIGEST#: 从一组输入值创建 tdigest

enumerator MERGE_TDIGEST#: 通过合并多个 tdigest 来创建一个 tdigest

enumerator HISTOGRAM#: 计算每个元素的频率

enumerator MERGE_HISTOGRAM#: 合并 HISTOGRAM 聚合的中间值

公有函数

inline aggregation(aggregation::Kind a)#

构造一个新的 aggregation 对象。

参数:: a – aggregation::Kind 枚举值

inline virtual bool is_equal(aggregation const &other) const#

比较两个 aggregation 对象是否相等。

参数:: other – 要与之比较的另一个 aggregation
返回:: 如果两个 aggregation 相等，则为 True

inline virtual size_t do_hash() const#

计算 aggregation 的哈希值。

返回:: aggregation 的哈希值

virtual std::unique_ptr<aggregation> clone() const = 0#

克隆 aggregation 对象。

返回:: aggregation 对象的副本

virtual std::vector<std::unique_ptr<aggregation>> get_simple_aggregations(data_type col_type, cudf::detail::simple_aggregations_collector &collector) const = 0#

获取此聚合计算所需的简单聚合。

参数:

col_type – 要聚合的列的类型
collector – 用于收集简单聚合的收集器访问者模式

返回:

前提简单聚合的向量

virtual void finalize(cudf::detail::aggregation_finalizer &finalizer) const = 0#

计算前提简单聚合计算完成后所需的聚合。

参数:: finalizer – 用于计算聚合的终结器访问者模式

公有成员

Kind kind#: 要执行的聚合。

class rolling_aggregation : public virtual cudf::aggregation #

#include <aggregation.hpp>

用于 rolling_window 特定聚合用法的派生类。

例如，rolling_window 只接受 rolling_aggregation 输入，而适当的派生类（sum_aggregation、mean_aggregation 等）从该接口派生以表示这些有效选项。

class groupby_aggregation : public virtual cudf::aggregation #: #include <aggregation.hpp>

用于 groupby 特定聚合用法的派生类。

class groupby_scan_aggregation : public virtual cudf::aggregation #: #include <aggregation.hpp>

用于 groupby 特定 scan 用法的派生类。

class reduce_aggregation : public virtual cudf::aggregation #: #include <aggregation.hpp>

用于 reduction 用法的派生类。

class scan_aggregation : public virtual cudf::aggregation #: #include <aggregation.hpp>

用于 scan 用法的派生类。

class segmented_reduce_aggregation : public virtual cudf::aggregation #: #include <aggregation.hpp>

派生类，用于分段规约。

聚合工厂#

本页