implement date_diff for logical layer

datafusion/functions/src/datetime/date_diff.rs

@@ -0,0 +1,122 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use std::{any::Any, sync::Arc};
+
+use arrow::datatypes::{DataType, Field, FieldRef};
+use datafusion_common::{
+    internal_err, not_impl_err,
+    types::{logical_date, logical_string},
+    Result,
+};
+use datafusion_doc::Documentation;
+use datafusion_expr::{
+    Coercion, ColumnarValue, ReturnFieldArgs, ScalarUDFImpl, Signature, TypeSignature,
+    TypeSignatureClass,
+};
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Time and Date Functions"),
+    description = "Returns the difference between two dates or timestamps.",
+    syntax_example = "date_diff(expression1, expression2, unit)",
+    argument(
+        name = "expression1",
+        description = "Time expression to operate on. Can be a constant, column, or function."
+    ),
+    argument(
+        name = "expression2",
+        description = "Time expression to operate on. Can be a constant, column, or function."
+    ),
+    argument(
+        name = "unit",
+        description = r#"The unit of time to use for the difference calculation. Supported units are:
+
+    - year
+    - quarter (emits value in inclusive range [1, 4] based on which quartile of the year the date is in)
+    - month
+    - week (week of the year)
+    - day (day of the month)
+"#
+    )
+)]
+#[derive(Debug)]
+pub struct DateDiffFunc {
+    signature: Signature,
+    aliases: Vec<String>,
+    return_field: FieldRef,
+}
+
+impl Default for DateDiffFunc {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl DateDiffFunc {
+    pub fn new() -> Self {
+        Self {
+            signature: Signature::one_of(
+                vec![TypeSignature::Coercible(vec![
+                    Coercion::new_exact(TypeSignatureClass::Native(logical_date())),
+                    Coercion::new_exact(TypeSignatureClass::Native(logical_date())),
+                    Coercion::new_exact(TypeSignatureClass::Native(logical_string())),
+                ])],
+                datafusion_expr::Volatility::Immutable,
+            ),
+            aliases: vec![String::from("datediff")],
+            return_field: Arc::new(Field::new("date_diff", DataType::Int32, true)),
+        }
+    }
+}
+
+impl ScalarUDFImpl for DateDiffFunc {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "date_diff"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        internal_err!("return_field_from_args should be called instead")
+    }
+
+    fn return_field_from_args(&self, _args: ReturnFieldArgs) -> Result<FieldRef> {
+        Ok(Arc::clone(&self.return_field))
+    }
+
+    fn invoke_with_args(
+        &self,
+        _args: datafusion_expr::ScalarFunctionArgs,
+    ) -> Result<ColumnarValue> {
+        not_impl_err!("date_diff isn't implemented for the execution")
+    }
+
+    fn aliases(&self) -> &[String] {
+        &self.aliases
+    }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        self.doc()
+    }
+}

datafusion/functions/src/datetime/mod.rs

@@ -25,6 +25,7 @@ pub mod common;
 pub mod current_date;
 pub mod current_time;
 pub mod date_bin;
+pub mod date_diff;
 pub mod date_part;
 pub mod date_trunc;
 pub mod from_unixtime;
@@ -42,6 +43,7 @@ make_udf_function!(current_time::CurrentTimeFunc, current_time);
 make_udf_function!(date_bin::DateBinFunc, date_bin);
 make_udf_function!(date_part::DatePartFunc, date_part);
 make_udf_function!(date_trunc::DateTruncFunc, date_trunc);
+make_udf_function!(date_diff::DateDiffFunc, date_diff);
 make_udf_function!(make_date::MakeDateFunc, make_date);
 make_udf_function!(from_unixtime::FromUnixtimeFunc, from_unixtime);
 make_udf_function!(now::NowFunc, now);
@@ -87,6 +89,10 @@ pub mod expr_fn {
         make_date,
         "make a date from year, month and day component parts",
         year month day
+    ),(
+        date_diff,
+        "returns the difference between two dates or timestamps.",
+        args,
     ),(
         now,
         "returns the current timestamp in nanoseconds, using the same value for all instances of now() in same statement",
@@ -260,6 +266,7 @@ pub fn functions() -> Vec<Arc<ScalarUDF>> {
         date_bin(),
         date_part(),
         date_trunc(),
+        date_diff(),
         from_unixtime(),
         make_date(),
         now(),

datafusion/sql/src/expr/function.rs

@@ -15,22 +15,25 @@
 // specific language governing permissions and limitations
 // under the License.
 
+use std::sync::Arc;
+
 use crate::planner::{ContextProvider, PlannerContext, SqlToRel};
 
 use arrow::datatypes::DataType;
 use datafusion_common::{
     internal_datafusion_err, internal_err, not_impl_err, plan_datafusion_err, plan_err,
-    DFSchema, Dependency, Diagnostic, Result, Span,
+    DFSchema, Dependency, Diagnostic, Result, ScalarValue, Span,
 };
 use datafusion_expr::expr::{ScalarFunction, Unnest, WildcardOptions};
 use datafusion_expr::planner::{PlannerResult, RawAggregateExpr, RawWindowExpr};
 use datafusion_expr::{
-    expr, Expr, ExprFunctionExt, ExprSchemable, WindowFrame, WindowFunctionDefinition,
+    expr, Expr, ExprFunctionExt, ExprSchemable, ScalarUDF, WindowFrame,
+    WindowFunctionDefinition,
 };
 use sqlparser::ast::{
     DuplicateTreatment, Expr as SQLExpr, Function as SQLFunction, FunctionArg,
     FunctionArgExpr, FunctionArgumentClause, FunctionArgumentList, FunctionArguments,
-    NullTreatment, ObjectName, OrderByExpr, Spanned, WindowType,
+    Ident, NullTreatment, ObjectName, OrderByExpr, Spanned, ValueWithSpan, WindowType,
 };
 
 /// Suggest a valid function based on an invalid input function name
@@ -267,8 +270,17 @@ impl<S: ContextProvider> SqlToRel<'_, S> {
                 }
             }
         }
+
         // User-defined function (UDF) should have precedence
         if let Some(fm) = self.context_provider.get_function_meta(&name) {
+            if fm.name().eq("date_diff") {
+                return self.sql_datediff_to_logical_expr(
+                    args,
+                    fm,
+                    schema,
+                    planner_context,
+                );
+            }
             let args = self.function_args_to_expr(args, schema, planner_context)?;
             return Ok(Expr::ScalarFunction(ScalarFunction::new_udf(fm, args)));
         }
@@ -289,6 +301,7 @@ impl<S: ContextProvider> SqlToRel<'_, S> {
                 "Aggregate ORDER BY is not implemented for window functions"
             );
         }
+
         // Then, window function
         if let Some(WindowType::WindowSpec(window)) = over {
             let partition_by = window
@@ -629,4 +642,60 @@ impl<S: ContextProvider> SqlToRel<'_, S> {
             }
         }
     }
+
+    pub(crate) fn sql_datediff_to_logical_expr(
+        &self,
+        args: Vec<FunctionArg>,
+        fm: Arc<ScalarUDF>,
+        schema: &DFSchema,
+        planner_context: &mut PlannerContext,
+    ) -> Result<Expr> {
+        if args.len() != 3 {
+            return plan_err!("date_diff() requires exactly three arguments: start_date, end_date, granularity");
+        }
+        let mut args_iter = args.into_iter();
+        let Some(start_date) = args_iter.next() else {
+            return plan_err!("date_diff() requires exactly three arguments: start_date, end_date, granularity");
+        };
+        let Some(end_date) = args_iter.next() else {
+            return plan_err!("date_diff() requires exactly three arguments: start_date, end_date, granularity");
+        };
+        let Some(granularity) = args_iter.next() else {
+            return plan_err!("date_diff() requires exactly three arguments: start_date, end_date, granularity");
+        };
+
+        let start_date =
+            self.sql_fn_arg_to_logical_expr(start_date, schema, planner_context)?;
+        let end_date =
+            self.sql_fn_arg_to_logical_expr(end_date, schema, planner_context)?;
+        let granularity = self.sql_datetime_field_to_logical_expr(granularity)?;
+
+        Ok(Expr::ScalarFunction(ScalarFunction::new_udf(
+            fm,
+            vec![start_date, end_date, granularity],
+        )))
+    }
+
+    pub(crate) fn sql_datetime_field_to_logical_expr(
+        &self,
+        arg: FunctionArg,
+    ) -> Result<Expr> {
+        match arg {
+            FunctionArg::Unnamed(FunctionArgExpr::Expr(expr)) => {
+                match expr {
+                    SQLExpr::Identifier(Ident { value, .. }) => {
+                        let s = value.to_lowercase();
+                        Ok(Expr::Literal(ScalarValue::Utf8(Some(s)), None))
+                    }
+                    SQLExpr::Value(ValueWithSpan { value: sqlparser::ast::Value::SingleQuotedString(value), .. }) => {
+                        Ok(Expr::Literal(ScalarValue::Utf8(Some(value)), None))
+                    }
+                    _ => plan_err!(
+                        "Invalid argument for date part: {expr}. It must be a single quoted string or datetime field"
+                    )
+                }
+            },
+            _ => plan_err!("Invalid argument for date part: {arg}. It must be a single quoted string or datetime field"),
+        }
+    }
 }

datafusion/sqllogictest/test_files/joins.slt

@@ -725,24 +725,24 @@ SELECT t1_id, t1_name, t2_name FROM t1, t2 WHERE 1=1 ORDER BY t1_id, t1_name, t2
 44 d z
 
 query ITT nosort
-SELECT t1_id, t1_name, t2_name FROM t1 CROSS JOIN t2 ORDER BY t1_id
+SELECT t1_id, t1_name, t2_name FROM t1 CROSS JOIN t2 ORDER BY t1_id, t1_name, t2_name
 ----
-11 a z
-11 a y
-11 a x
 11 a w
-22 b z
-22 b y
-22 b x
+11 a x
+11 a y
+11 a z
 22 b w
-33 c z
-33 c y
-33 c x
+22 b x
+22 b y
+22 b z
 33 c w
-44 d z
-44 d y
-44 d x
+33 c x
+33 c y
+33 c z
 44 d w
+44 d x
+44 d y
+44 d z
 
 query ITITI rowsort
 SELECT * FROM (SELECT t1_id, t1_name FROM t1 UNION ALL SELECT t1_id, t1_name FROM t1) AS t1 CROSS JOIN t2

docs/source/user-guide/sql/scalar_functions.md

@@ -1986,9 +1986,11 @@ Additional examples can be found [here](https://github.com/apache/datafusion/blo
 - [current_time](#current_time)
 - [current_timestamp](#current_timestamp)
 - [date_bin](#date_bin)
+- [date_diff](#date_diff)
 - [date_format](#date_format)
 - [date_part](#date_part)
 - [date_trunc](#date_trunc)
+- [datediff](#datediff)
 - [datepart](#datepart)
 - [datetrunc](#datetrunc)
 - [from_unixtime](#from_unixtime)
@@ -2087,6 +2089,30 @@ FROM VALUES ('2023-01-01T18:18:18Z'), ('2023-01-03T19:00:03Z')  t(time);
 2 row(s) fetched.
 ```
 
+### `date_diff`
+
+Returns the difference between two dates or timestamps.
+
+```sql
+date_diff(expression1, expression2, unit)
+```
+
+#### Arguments
+
+- **expression1**: Time expression to operate on. Can be a constant, column, or function.
+- **expression2**: Time expression to operate on. Can be a constant, column, or function.
+- **unit**: The unit of time to use for the difference calculation. Supported units are:
+
+  - year
+  - quarter (emits value in inclusive range [1, 4] based on which quartile of the year the date is in)
+  - month
+  - week (week of the year)
+  - day (day of the month)
+
+#### Aliases
+
+- datediff
+
 ### `date_format`
 
 _Alias of [to_char](#to_char)._
@@ -2157,6 +2183,10 @@ date_trunc(precision, expression)
 
 - datetrunc
 
+### `datediff`
+
+_Alias of [date_diff](#date_diff)._
+
 ### `datepart`
 
 _Alias of [date_part](#date_part)._