groupby.hpp

转到此文件的文档。

/*
 * Copyright (c) 2019-2024, NVIDIA CORPORATION.
 *
 * 根据 Apache 许可证 2.0 版（“许可证”）获得许可；
 * 除非遵守许可证，否则您不得使用此文件。
 * 您可以获得许可证的副本，地址为
 *
 * https://apache.ac.cn/licenses/LICENSE-2.0
 *
 * 除非适用法律要求或书面同意，否则软件
 * 根据许可证分发是基于“按原样”的基础，
 * 不提供任何形式的担保或条件，无论是明示的还是暗示的。
 * 请参阅许可证，了解管理权限和
 * 许可证下的限制条件的特定语言。
 */

#pragma once

#include <cudf/aggregation.hpp>
#include <cudf/column/column_view.hpp>
#include <cudf/replace.hpp>
#include <cudf/table/table_view.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/export.hpp>
#include <cudf/utilities/memory_resource.hpp>
#include <cudf/utilities/span.hpp>

#include <rmm/cuda_stream_view.hpp>

#include <memory>
#include <utility>
#include <vector>

namespace CUDF_EXPORT cudf {
namespace groupby { // 按键对值进行分组并在这些组上计算聚合。
namespace detail {
namespace sort { // 基于排序的分组辅助类
struct sort_groupby_helper;

} // 命名空间 sort
} // 命名空间 detail

struct aggregation_request { // 在列上执行分组聚合的请求。
 column_view values; // 要聚合的元素。
 std::vector<std::unique_ptr<groupby_aggregation>> aggregations; // 所需的聚合操作。
};

struct scan_request { // 扫描列时执行分组聚合的请求。
 column_view values;
 std::vector<std::unique_ptr<groupby_scan_aggregation>> aggregations;
};

struct aggregation_result { // 一个 aggregation_request 的结果。
 std::vector<std::unique_ptr<column>> results{}; // 聚合结果列表
};

class groupby { // 按键对值进行分组并在这些组上计算聚合。
 public
 groupby() = delete;
 ~groupby();
 groupby(groupby const&) = delete;
 groupby(groupby&&) = delete;
 groupby& operator=(groupby const&) = delete;
 groupby& operator=(groupby&&) = delete;

 explicit groupby(table_view const& keys, // 用于分组的键。
 null_policy null_handling = null_policy::EXCLUDE, // 处理键中 null 值的策略。
 sorted keys_are_sorted = sorted::NO, // 指示键是否已排序。
 std::vector<order> const& column_order = {}, // 如果键未排序，则每个键列的排序顺序。
 std::vector<null_order> const& null_precedence = {}); // 如果键未排序，则每个键列的 null 值排序优先级。

 std::pair<std::unique_ptr<table>, std::vector<aggregation_result>> aggregate( // 对指定的值执行分组聚合。
 host_span<aggregation_request const> requests, // 聚合请求列表。
 rmm::cuda_stream_view stream = cudf::get_default_stream(), // 用于设备内存操作和内核启动的 CUDA 流。
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 用于分配返回的表/列的设备内存资源。
 std::pair<std::unique_ptr<table>, std::vector<aggregation_result>> scan( // 对指定的值执行分组扫描。
 host_span<scan_request const> requests, // 扫描请求列表。
 rmm::cuda_stream_view stream = cudf::get_default_stream(), // 用于设备内存操作和内核启动的 CUDA 流。
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 用于分配返回的表/列的设备内存资源。

 std::pair<std::unique_ptr<table>, std::unique_ptr<table>> shift( // 对指定的值执行分组位移。
 table_view const& values, // 要位移的值。
 host_span<size_type const> offsets, // 每个值列的位移量。
 std::vector<std::reference_wrapper<scalar const>> const& fill_values, // 位移位置的填充值。
 rmm::cuda_stream_view stream = cudf::get_default_stream(), // 用于设备内存操作和内核启动的 CUDA 流。
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 用于分配返回的表/列的设备内存资源。

 struct groups { // 对一组值进行 groupby 操作对应的分组数据。
 std::unique_ptr<table> keys; // 分组后的键表。
 std::vector<size_type> offsets; // 组偏移量。
 std::unique_ptr<table> values; // 分组后的值表。
 };

 groups get_groups(cudf::table_view values = {}, // 要分组的值。
 rmm::cuda_stream_view stream = cudf::get_default_stream(), // 用于设备内存操作和内核启动的 CUDA 流。
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 用于分配返回的表/列的设备内存资源。

 std::pair<std::unique_ptr<table>, std::unique_ptr<table>> replace_nulls( // 对值执行分组替换 null 值操作。
 table_view const& values, // 要在其中替换 null 值的值。
 host_span<cudf::replace_policy const> replace_policies, // 每个值列替换 null 值的策略。
 rmm::cuda_stream_view stream = cudf::get_default_stream(), // 用于设备内存操作和内核启动的 CUDA 流。
 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref()); // 用于分配返回的表/列的设备内存资源。

 private
 table_view _keys;
 null_policy _include_null_keys{null_policy::EXCLUDE}; // 处理键中 null 值的策略。
 sorted _keys_are_sorted{sorted::NO}; // 指示键是否已排序。
 std::vector<order> _column_order{};
 std::vector<null_order> _null_precedence{}; // 如果键未排序，则每个键列的 null 值排序优先级。
 std::unique_ptr<detail::sort::sort_groupby_helper>
 _helper; // 用于基于排序的分组实现的辅助类

 detail::sort::sort_groupby_helper& helper(); // 返回辅助对象，如有必要则进行初始化

 std::pair<std::unique_ptr<table>, std::vector<aggregation_result>> dispatch_aggregation( // 内部函数，用于分派到基于哈希或基于排序的分组
 host_span<aggregation_request const> requests,
 rmm::cuda_stream_view stream,
 rmm::device_async_resource_ref mr);

 // 基于排序的分组聚合
 std::pair<std::unique_ptr<table>, std::vector<aggregation_result>> sort_aggregate(
 host_span<aggregation_request const> requests,
 rmm::cuda_stream_view stream,
 rmm::device_async_resource_ref mr);

 std::pair<std::unique_ptr<table>, std::vector<aggregation_result>> sort_scan(
 host_span<scan_request const> requests,
 rmm::cuda_stream_view stream,
 rmm::device_async_resource_ref mr);
};
} // 命名空间 groupby
} // 命名空间 CUDF_EXPORT cudf