Coverage Report

Created: 2024-10-13 08:39

/Users/andrewlamb/Software/datafusion/datafusion/physical-expr/src/window/built_in_window_function_expr.rs
Line
Count
Source (jump to first uncovered line)
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
18
use crate::{PhysicalExpr, PhysicalSortExpr};
19
20
use arrow::array::ArrayRef;
21
use arrow::datatypes::Field;
22
use arrow::record_batch::RecordBatch;
23
use arrow_schema::SchemaRef;
24
use datafusion_common::Result;
25
use datafusion_expr::PartitionEvaluator;
26
27
use std::any::Any;
28
use 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.
38
#[allow(rustdoc::private_intra_doc_links)]
39
pub trait BuiltInWindowFunctionExpr: Send + Sync + std::fmt::Debug {
40
    /// Returns the aggregate expression as [`Any`] so that it can be
41
    /// downcast to a specific implementation.
42
    fn as_any(&self) -> &dyn Any;
43
44
    /// The field of the final result of evaluating this window function.
45
    fn field(&self) -> Result<Field>;
46
47
    /// Expressions that are passed to the [`PartitionEvaluator`].
48
    fn expressions(&self) -> Vec<Arc<dyn PhysicalExpr>>;
49
50
    /// Human readable name such as `"MIN(c2)"` or `"RANK()"`. The default
51
    /// implementation returns placeholder text.
52
0
    fn name(&self) -> &str {
53
0
        "BuiltInWindowFunctionExpr: default name"
54
0
    }
55
56
    /// Evaluate window function's arguments against the input window
57
    /// batch and return an [`ArrayRef`].
58
    ///
59
    /// Typically, the resulting vector is a single element vector.
60
0
    fn evaluate_args(&self, batch: &RecordBatch) -> Result<Vec<ArrayRef>> {
61
0
        self.expressions()
62
0
            .iter()
63
0
            .map(|e| {
64
0
                e.evaluate(batch)
65
0
                    .and_then(|v| v.into_array(batch.num_rows()))
66
0
            })
67
0
            .collect()
68
0
    }
69
70
    /// Create a [`PartitionEvaluator`] for evaluating the function on
71
    /// a particular partition.
72
    fn create_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>>;
73
74
    /// Construct a new [`BuiltInWindowFunctionExpr`] that produces
75
    /// the same result as this function on a window with reverse
76
    /// order. The return value of this function is used by the
77
    /// DataFusion optimizer to avoid re-sorting the data when
78
    /// possible.
79
    ///
80
    /// Returns `None` (the default) if no reverse is known (or possible).
81
    ///
82
    /// For example, the reverse of `lead(10)` is `lag(10)`.
83
0
    fn reverse_expr(&self) -> Option<Arc<dyn BuiltInWindowFunctionExpr>> {
84
0
        None
85
0
    }
86
87
    /// Returns the ordering introduced by the window function, if applicable.
88
    /// Most window functions don't introduce an ordering, hence the default
89
    /// value is `None`. Note that this information is used to update ordering
90
    /// equivalences.
91
3
    fn get_result_ordering(&self, _schema: &SchemaRef) -> Option<PhysicalSortExpr> {
92
3
        None
93
3
    }
94
}