rolling.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-2025, NVIDIA CORPORATION.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #include <cudf/aggregation.hpp>
21 #include <cudf/types.hpp>
23 #include <cudf/utilities/export.hpp>
25 
26 #include <rmm/resource_ref.hpp>
27 
28 #include <memory>
29 #include <optional>
30 #include <variant>
31 
32 namespace CUDF_EXPORT cudf {
52 
59  bounded_closed(cudf::scalar const& delta) : delta_{delta} {}
64  [[nodiscard]] cudf::scalar const* delta() const noexcept { return &delta_; }
65 };
66 
77 struct bounded_open {
80 
87  bounded_open(cudf::scalar const& delta) : delta_{delta} {}
88 
93  [[nodiscard]] cudf::scalar const* delta() const noexcept { return &delta_; }
94 };
95 
101 struct unbounded {
106  [[nodiscard]] constexpr cudf::scalar const* delta() const noexcept { return nullptr; }
107 };
113 struct current_row {
118  [[nodiscard]] constexpr cudf::scalar const* delta() const noexcept { return nullptr; }
119 };
120 
124 using range_window_type = std::variant<unbounded, current_row, bounded_closed, bounded_open>;
125 
132  std::unique_ptr<rolling_aggregation> aggregation;
133 };
134 
151 std::pair<std::unique_ptr<column>, std::unique_ptr<column>> make_range_windows(
152  table_view const& group_keys,
153  column_view const& orderby,
154  order order,
156  range_window_type preceding,
157  range_window_type following,
160 
194 std::unique_ptr<column> rolling_window(
195  column_view const& input,
196  size_type preceding_window,
197  size_type following_window,
198  size_type min_periods,
199  rolling_aggregation const& agg,
202 
218 std::unique_ptr<column> rolling_window(
219  column_view const& input,
220  column_view const& default_outputs,
221  size_type preceding_window,
222  size_type following_window,
223  size_type min_periods,
224  rolling_aggregation const& agg,
227 
232  public:
239  static window_bounds get(size_type value) { return window_bounds(false, value); }
240 
247  {
248  return window_bounds(true, std::numeric_limits<cudf::size_type>::max());
249  }
250 
257  [[nodiscard]] bool is_unbounded() const { return _is_unbounded; }
258 
264  [[nodiscard]] size_type value() const { return _value; }
265 
266  private:
267  explicit window_bounds(bool is_unbounded_, size_type value_ = 0)
268  : _is_unbounded{is_unbounded_}, _value{value_}
269  {
270  }
271 
272  bool const _is_unbounded;
273  size_type const _value;
274 };
275 
368 std::unique_ptr<column> grouped_rolling_window(
369  table_view const& group_keys,
370  column_view const& input,
371  size_type preceding_window,
372  size_type following_window,
373  size_type min_periods,
374  rolling_aggregation const& aggr,
377 
390 std::unique_ptr<column> grouped_rolling_window(
391  table_view const& group_keys,
392  column_view const& input,
393  window_bounds preceding_window,
394  window_bounds following_window,
395  size_type min_periods,
396  rolling_aggregation const& aggr,
399 
416 std::unique_ptr<column> grouped_rolling_window(
417  table_view const& group_keys,
418  column_view const& input,
419  column_view const& default_outputs,
420  size_type preceding_window,
421  size_type following_window,
422  size_type min_periods,
423  rolling_aggregation const& aggr,
426 
440 std::unique_ptr<column> grouped_rolling_window(
441  table_view const& group_keys,
442  column_view const& input,
443  column_view const& default_outputs,
444  window_bounds preceding_window,
445  window_bounds following_window,
446  size_type min_periods,
447  rolling_aggregation const& aggr,
450 
561 std::unique_ptr<column> grouped_range_rolling_window(
562  table_view const& group_keys,
563  column_view const& orderby_column,
564  cudf::order const& order,
565  column_view const& input,
566  range_window_bounds const& preceding,
567  range_window_bounds const& following,
568  size_type min_periods,
569  rolling_aggregation const& aggr,
572 
588 std::unique_ptr<table> grouped_range_rolling_window(
589  table_view const& group_keys,
590  column_view const& orderby,
591  order order,
593  range_window_type preceding,
594  range_window_type following,
598 
640 std::unique_ptr<column> rolling_window(
641  column_view const& input,
642  column_view const& preceding_window,
643  column_view const& following_window,
644  size_type min_periods,
645  rolling_aggregation const& agg,
648 
656 bool is_valid_rolling_aggregation(data_type source, aggregation::Kind kind); // end of group
658 } // namespace CUDF_EXPORT cudf
Representation for specifying desired aggregations from aggregation-based APIs, e....
Kind
Possible aggregation operations.
Definition: aggregation.hpp:95
A non-owning, immutable view of device data as a column of elements, some of which may be null as ind...
Indicator for the logical data type of an element in a column.
Definition: types.hpp:243
Derived class intended for rolling_window specific aggregation usage.
An owning class to represent a singular value.
Definition: scalar.hpp:51
A set of cudf::column_view's of the same size.
Definition: table_view.hpp:200
std::pair< std::unique_ptr< column >, std::unique_ptr< column > > make_range_windows(table_view const &group_keys, column_view const &orderby, order order, null_order null_order, range_window_type preceding, range_window_type following, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Constructs preceding and following columns given window range specifications.
std::unique_ptr< table > grouped_range_rolling_window(table_view const &group_keys, column_view const &orderby, order order, null_order null_order, range_window_type preceding, range_window_type following, host_span< rolling_request const > requests, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Apply a grouping-aware range-based rolling window function to a sequence of columns.
std::unique_ptr< column > grouped_rolling_window(table_view const &group_keys, column_view const &input, column_view const &default_outputs, window_bounds preceding_window, window_bounds following_window, size_type min_periods, rolling_aggregation const &aggr, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Applies a grouping-aware, fixed-size rolling window function to the values in a column.
bool is_valid_rolling_aggregation(data_type source, aggregation::Kind kind)
Indicate if a rolling aggregation is supported for a source datatype.
std::variant< unbounded, current_row, bounded_closed, bounded_open > range_window_type
The type of the range-based rolling window endpoint.
Definition: rolling.hpp:124
std::unique_ptr< column > rolling_window(column_view const &input, column_view const &preceding_window, column_view const &following_window, size_type min_periods, rolling_aggregation const &agg, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
Applies a variable-size rolling window function to the values in a column.
rmm::cuda_stream_view const get_default_stream()
Get the current default stream.
rmm::device_async_resource_ref get_current_device_resource_ref()
Get the current device memory resource reference.
cuda::mr::async_resource_ref< cuda::mr::device_accessible > device_async_resource_ref
null_order
Indicates how null values compare against all other values.
Definition: types.hpp:159
int32_t size_type
Row index type for columns and tables.
Definition: types.hpp:95
order
Indicates the order in which elements should be sorted.
Definition: types.hpp:118
cuDF interfaces
Definition: host_udf.hpp:37
Strongly typed wrapper for bounded closed rolling windows.
Definition: rolling.hpp:49
cudf::scalar const * delta() const noexcept
Return pointer to the row delta scalar.
Definition: rolling.hpp:64
bounded_closed(cudf::scalar const &delta)
Construct a bounded closed rolling window.
Definition: rolling.hpp:59
cudf::scalar const & delta_
Definition: rolling.hpp:50
Strongly typed wrapper for bounded open rolling windows.
Definition: rolling.hpp:77
cudf::scalar const & delta_
Definition: rolling.hpp:78
bounded_open(cudf::scalar const &delta)
Construct a bounded open rolling window.
Definition: rolling.hpp:87
cudf::scalar const * delta() const noexcept
Return pointer to the row delta scalar.
Definition: rolling.hpp:93
Strongly typed wrapper for current_row rolling windows.
Definition: rolling.hpp:113
constexpr cudf::scalar const * delta() const noexcept
Return a null row delta.
Definition: rolling.hpp:118
C++20 std::span with reduced feature set.
Definition: span.hpp:194
Abstraction for window boundary sizes, to be used with grouped_range_rolling_window().
A request for a rolling aggregation on a column.
Definition: rolling.hpp:129
std::unique_ptr< rolling_aggregation > aggregation
Desired aggregation.
Definition: rolling.hpp:132
column_view values
Elements to aggregate.
Definition: rolling.hpp:130
size_type min_periods
Minimum number of observations required for the window to be valid.
Definition: rolling.hpp:131
Strongly typed wrapper for unbounded rolling windows.
Definition: rolling.hpp:101
constexpr cudf::scalar const * delta() const noexcept
Return a null row delta.
Definition: rolling.hpp:106
Abstraction for window boundary sizes.
Definition: rolling.hpp:231
static window_bounds unbounded()
Construct unbounded window boundary.
Definition: rolling.hpp:246
size_type value() const
Gets the row-boundary for this window_bounds.
Definition: rolling.hpp:264
bool is_unbounded() const
Definition: rolling.hpp:257
static window_bounds get(size_type value)
Construct bounded window boundary.
Definition: rolling.hpp:239
Type declarations for libcudf.