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::{Field, SchemaRef};
22use arrow::record_batch::RecordBatch;
23use datafusion_common::Result;
24use datafusion_expr::PartitionEvaluator;
25
26use std::any::Any;
27use std::sync::Arc;
28
29/// Evaluates a window function by instantiating a
30/// `[PartitionEvaluator]` for calculating the function's output in
31/// that partition.
32///
33/// Note that unlike aggregation based window functions, some window
34/// functions such as `rank` ignore the values in the window frame,
35/// but others such as `first_value`, `last_value`, and
36/// `nth_value` need the value.
37#[allow(rustdoc::private_intra_doc_links)]
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<Field>;
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        self.expressions()
61            .iter()
62            .map(|e| {
63                e.evaluate(batch)
64                    .and_then(|v| v.into_array(batch.num_rows()))
65            })
66            .collect()
67    }
68
69    /// Create a [`PartitionEvaluator`] for evaluating the function on
70    /// a particular partition.
71    fn create_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>>;
72
73    /// Construct a new [`StandardWindowFunctionExpr`] that produces
74    /// the same result as this function on a window with reverse
75    /// order. The return value of this function is used by the
76    /// DataFusion optimizer to avoid re-sorting the data when
77    /// possible.
78    ///
79    /// Returns `None` (the default) if no reverse is known (or possible).
80    ///
81    /// For example, the reverse of `lead(10)` is `lag(10)`.
82    fn reverse_expr(&self) -> Option<Arc<dyn StandardWindowFunctionExpr>> {
83        None
84    }
85
86    /// Returns the ordering introduced by the window function, if applicable.
87    /// Most window functions don't introduce an ordering, hence the default
88    /// value is `None`. Note that this information is used to update ordering
89    /// equivalences.
90    fn get_result_ordering(&self, _schema: &SchemaRef) -> Option<PhysicalSortExpr> {
91        None
92    }
93}
datafusion_physical_expr/window/standard_window_function_expr.rs

datafusion_physical_expr/window/
standard_window_function_expr.rs
