Modified the argument of DATE_DIFF

datafusion/functions/src/datetime/date_diff.rs

@@ -33,15 +33,7 @@ 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."
-    ),
+    syntax_example = "date_diff(unit, expression1, expression2)",
     argument(
         name = "unit",
         description = r#"The unit of time to use for the difference calculation. Supported units are:
@@ -51,7 +43,20 @@ use datafusion_macros::user_doc;
     - month
     - week (week of the year)
     - day (day of the month)
+    - hour
+    - minute
+    - second
+    - millisecond
+    - microsecond
 "#
+    ),
+    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."
     )
 )]
 #[derive(Debug)]
@@ -71,11 +76,18 @@ 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())),
-                ])],
+                vec![
+                    TypeSignature::Coercible(vec![
+                        Coercion::new_exact(TypeSignatureClass::Native(logical_string())),
+                        Coercion::new_exact(TypeSignatureClass::Native(logical_date())),
+                        Coercion::new_exact(TypeSignatureClass::Native(logical_date())),
+                    ]),
+                    TypeSignature::Coercible(vec![
+                        Coercion::new_exact(TypeSignatureClass::Native(logical_string())),
+                        Coercion::new_exact(TypeSignatureClass::Timestamp),
+                        Coercion::new_exact(TypeSignatureClass::Timestamp),
+                    ]),
+                ],
                 datafusion_expr::Volatility::Immutable,
             ),
             aliases: vec![String::from("datediff")],

datafusion/sql/src/expr/function.rs

@@ -654,13 +654,13 @@ impl<S: ContextProvider> SqlToRel<'_, S> {
             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 {
+        let Some(granularity) = 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 {
+        let Some(start_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 {
+        let Some(end_date) = args_iter.next() else {
             return plan_err!("date_diff() requires exactly three arguments: start_date, end_date, granularity");
         };
 
@@ -672,7 +672,7 @@ impl<S: ContextProvider> SqlToRel<'_, S> {
 
         Ok(Expr::ScalarFunction(ScalarFunction::new_udf(
             fm,
-            vec![start_date, end_date, granularity],
+            vec![granularity, start_date, end_date],
         )))
     }
 

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

@@ -2094,20 +2094,26 @@ FROM VALUES ('2023-01-01T18:18:18Z'), ('2023-01-03T19:00:03Z')  t(time);
 Returns the difference between two dates or timestamps.
 
 ```sql
-date_diff(expression1, expression2, unit)
+date_diff(unit, expression1, expression2)
 ```
 
 #### 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)
+  - hour
+  - minute
+  - second
+  - millisecond
+  - microsecond
+
+- **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.
 
 #### Aliases