datafusion_physical_expr/window/
standard_window_function_expr.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use crate::{PhysicalExpr, PhysicalSortExpr};
19
20use arrow::array::ArrayRef;
21use arrow::datatypes::{FieldRef, SchemaRef};
22use arrow::record_batch::RecordBatch;
23use datafusion_common::Result;
24use datafusion_expr::{LimitEffect, PartitionEvaluator};
25
26use datafusion_physical_expr_common::utils::evaluate_expressions_to_arrays;
27use std::any::Any;
28use std::sync::Arc;
29
30/// Evaluates a window function by instantiating a
31/// [`PartitionEvaluator`] for calculating the function's output in
32/// that partition.
33///
34/// Note that unlike aggregation based window functions, some window
35/// functions such as `rank` ignore the values in the window frame,
36/// but others such as `first_value`, `last_value`, and
37/// `nth_value` need the value.
38pub trait StandardWindowFunctionExpr: Send + Sync + std::fmt::Debug {
39    /// Returns the aggregate expression as [`Any`] so that it can be
40    /// downcast to a specific implementation.
41    fn as_any(&self) -> &dyn Any;
42
43    /// The field of the final result of evaluating this window function.
44    fn field(&self) -> Result<FieldRef>;
45
46    /// Expressions that are passed to the [`PartitionEvaluator`].
47    fn expressions(&self) -> Vec<Arc<dyn PhysicalExpr>>;
48
49    /// Human readable name such as `"MIN(c2)"` or `"RANK()"`. The default
50    /// implementation returns placeholder text.
51    fn name(&self) -> &str {
52        "StandardWindowFunctionExpr: default name"
53    }
54
55    /// Evaluate window function's arguments against the input window
56    /// batch and return an [`ArrayRef`].
57    ///
58    /// Typically, the resulting vector is a single element vector.
59    fn evaluate_args(&self, batch: &RecordBatch) -> Result<Vec<ArrayRef>> {
60        evaluate_expressions_to_arrays(&self.expressions(), batch)
61    }
62
63    /// Create a [`PartitionEvaluator`] for evaluating the function on
64    /// a particular partition.
65    fn create_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>>;
66
67    /// Construct a new [`StandardWindowFunctionExpr`] that produces
68    /// the same result as this function on a window with reverse
69    /// order. The return value of this function is used by the
70    /// DataFusion optimizer to avoid re-sorting the data when
71    /// possible.
72    ///
73    /// Returns `None` (the default) if no reverse is known (or possible).
74    ///
75    /// For example, the reverse of `lead(10)` is `lag(10)`.
76    fn reverse_expr(&self) -> Option<Arc<dyn StandardWindowFunctionExpr>> {
77        None
78    }
79
80    /// Returns the ordering introduced by the window function, if applicable.
81    /// Most window functions don't introduce an ordering, hence the default
82    /// value is `None`. Note that this information is used to update ordering
83    /// equivalences.
84    fn get_result_ordering(&self, _schema: &SchemaRef) -> Option<PhysicalSortExpr> {
85        None
86    }
87
88    fn limit_effect(&self) -> LimitEffect;
89}
datafusion_physical_expr/window/standard_window_function_expr.rs

datafusion_physical_expr/window/
standard_window_function_expr.rs
