datafusion_functions_window/
ntile.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
18//! `ntile` window function implementation
19
20use std::any::Any;
21use std::fmt::Debug;
22use std::sync::Arc;
23
24use crate::utils::{
25    get_scalar_value_from_args, get_signed_integer, get_unsigned_integer,
26};
27use datafusion_common::arrow::array::{ArrayRef, UInt64Array};
28use datafusion_common::arrow::datatypes::{DataType, Field};
29use datafusion_common::{exec_err, DataFusionError, Result};
30use datafusion_expr::{
31    Documentation, Expr, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
32};
33use datafusion_functions_window_common::field;
34use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
35use datafusion_macros::user_doc;
36use field::WindowUDFFieldArgs;
37
38get_or_init_udwf!(
39    Ntile,
40    ntile,
41    "integer ranging from 1 to the argument value, dividing the partition as equally as possible"
42);
43
44pub fn ntile(arg: Expr) -> Expr {
45    ntile_udwf().call(vec![arg])
46}
47
48#[user_doc(
49    doc_section(label = "Ranking Functions"),
50    description = "Integer ranging from 1 to the argument value, dividing the partition as equally as possible",
51    syntax_example = "ntile(expression)",
52    argument(
53        name = "expression",
54        description = "An integer describing the number groups the partition should be split into"
55    )
56)]
57#[derive(Debug)]
58pub struct Ntile {
59    signature: Signature,
60}
61
62impl Ntile {
63    /// Create a new `ntile` function
64    pub fn new() -> Self {
65        Self {
66            signature: Signature::uniform(
67                1,
68                vec![
69                    DataType::UInt64,
70                    DataType::UInt32,
71                    DataType::UInt16,
72                    DataType::UInt8,
73                    DataType::Int64,
74                    DataType::Int32,
75                    DataType::Int16,
76                    DataType::Int8,
77                ],
78                Volatility::Immutable,
79            ),
80        }
81    }
82}
83
84impl Default for Ntile {
85    fn default() -> Self {
86        Self::new()
87    }
88}
89
90impl WindowUDFImpl for Ntile {
91    fn as_any(&self) -> &dyn Any {
92        self
93    }
94
95    fn name(&self) -> &str {
96        "ntile"
97    }
98
99    fn signature(&self) -> &Signature {
100        &self.signature
101    }
102
103    fn partition_evaluator(
104        &self,
105        partition_evaluator_args: PartitionEvaluatorArgs,
106    ) -> Result<Box<dyn PartitionEvaluator>> {
107        let scalar_n =
108            get_scalar_value_from_args(partition_evaluator_args.input_exprs(), 0)?
109                .ok_or_else(|| {
110                    DataFusionError::Execution(
111                        "NTILE requires a positive integer".to_string(),
112                    )
113                })?;
114
115        if scalar_n.is_null() {
116            return exec_err!("NTILE requires a positive integer, but finds NULL");
117        }
118
119        if scalar_n.is_unsigned() {
120            let n = get_unsigned_integer(scalar_n)?;
121            Ok(Box::new(NtileEvaluator { n }))
122        } else {
123            let n: i64 = get_signed_integer(scalar_n)?;
124            if n <= 0 {
125                return exec_err!("NTILE requires a positive integer");
126            }
127            Ok(Box::new(NtileEvaluator { n: n as u64 }))
128        }
129    }
130    fn field(&self, field_args: WindowUDFFieldArgs) -> Result<Field> {
131        let nullable = false;
132
133        Ok(Field::new(field_args.name(), DataType::UInt64, nullable))
134    }
135
136    fn documentation(&self) -> Option<&Documentation> {
137        self.doc()
138    }
139}
140
141#[derive(Debug)]
142struct NtileEvaluator {
143    n: u64,
144}
145
146impl PartitionEvaluator for NtileEvaluator {
147    fn evaluate_all(
148        &mut self,
149        _values: &[ArrayRef],
150        num_rows: usize,
151    ) -> Result<ArrayRef> {
152        let num_rows = num_rows as u64;
153        let mut vec: Vec<u64> = Vec::new();
154        let n = u64::min(self.n, num_rows);
155        for i in 0..num_rows {
156            let res = i * n / num_rows;
157            vec.push(res + 1)
158        }
159        Ok(Arc::new(UInt64Array::from(vec)))
160    }
161}
datafusion_functions_window/ntile.rs

datafusion_functions_window/
ntile.rs
