Apache DataFusion SQL Query Engine
feat: Add Spark-compatible `monthname` function to datafusion-spark (#21639)
Zeel Rajodiya626da1eafdee
diff --git a/datafusion/spark/src/function/datetime/mod.rs b/datafusion/spark/src/function/datetime/mod.rsindex 3133ed7337..98afa91ddc 100644--- a/datafusion/spark/src/function/datetime/mod.rs+++ b/datafusion/spark/src/function/datetime/mod.rs@@ -26,6 +26,7 @@ pub mod from_utc_timestamp;pub mod last_day;pub mod make_dt_interval;pub mod make_interval;+pub mod monthname;pub mod next_day;pub mod time_trunc;pub mod to_utc_timestamp;@@ -52,6 +53,7 @@ make_udf_function!(extract::SparkSecond, second);make_udf_function!(last_day::SparkLastDay, last_day);make_udf_function!(make_dt_interval::SparkMakeDtInterval, make_dt_interval);make_udf_function!(make_interval::SparkMakeInterval, make_interval);+make_udf_function!(monthname::SparkMonthName, monthname);make_udf_function!(next_day::SparkNextDay, next_day);make_udf_function!(time_trunc::SparkTimeTrunc, time_trunc);make_udf_function!(to_utc_timestamp::SparkToUtcTimestamp, to_utc_timestamp);@@ -117,6 +119,11 @@ pub mod expr_fn {"Make interval from years, months, weeks, days, hours, mins and secs.",years months weeks days hours mins secs));+ export_functions!((+ monthname,+ "Returns the three-letter abbreviated month name from a date or timestamp.",+ arg1+ ));// TODO: add once ANSI support is added:// "When both of the input parameters are not NULL and day_of_week is an invalid input, the function throws SparkIllegalArgumentException if spark.sql.ansi.enabled is set to true, otherwise NULL."export_functions!((@@ -195,6 +202,7 @@ pub fn functions() -> Vec<Arc<ScalarUDF>> {make_dt_interval(),make_interval(),minute(),+ monthname(),next_day(),second(),time_trunc(),diff --git a/datafusion/spark/src/function/datetime/monthname.rs b/datafusion/spark/src/function/datetime/monthname.rsnew file mode 100644index 0000000000..6cfa9c0a92--- /dev/null+++ b/datafusion/spark/src/function/datetime/monthname.rs@@ -0,0 +1,115 @@+// 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::sync::Arc;++use arrow::array::{AsArray, StringArray};+use arrow::compute::{DatePart, date_part};+use arrow::datatypes::{DataType, Field, FieldRef};+use datafusion_common::types::{NativeType, logical_date};+use datafusion_common::utils::take_function_args;+use datafusion_common::{Result, ScalarValue, internal_err};+use datafusion_expr::{+ Coercion, ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl,+ Signature, TypeSignatureClass, Volatility,+};++const MONTH_NAMES: [&str; 12] = [+ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",+];++fn month_number_to_name(month: i32) -> Option<&'static str> {+ MONTH_NAMES.get((month - 1) as usize).copied()+}++/// Spark-compatible `monthname` expression.+/// Returns the three-letter abbreviated month name from a date or timestamp.+///+/// <https://spark.apache.org/docs/latest/api/sql/index.html#monthname>+#[derive(Debug, PartialEq, Eq, Hash)]+pub struct SparkMonthName {+ signature: Signature,+}++impl Default for SparkMonthName {+ fn default() -> Self {+ Self::new()+ }+}++impl SparkMonthName {+ pub fn new() -> Self {+ Self {+ signature: Signature::coercible(+ vec![Coercion::new_implicit(+ TypeSignatureClass::Native(logical_date()),+ vec![TypeSignatureClass::Timestamp],+ NativeType::Date,+ )],+ Volatility::Immutable,+ ),+ }+ }+}++impl ScalarUDFImpl for SparkMonthName {+ fn name(&self) -> &str {+ "monthname"+ }++ fn signature(&self) -> &Signature {+ &self.signature+ }++ fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {+ internal_err!("return_field_from_args should be used instead")+ }++ fn return_field_from_args(&self, args: ReturnFieldArgs) -> Result<FieldRef> {+ let nullable = args.arg_fields.iter().any(|f| f.is_nullable());+ Ok(Arc::new(Field::new(self.name(), DataType::Utf8, nullable)))+ }++ fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {+ let [arg] = take_function_args(self.name(), args.args)?;+ match arg {+ ColumnarValue::Scalar(scalar) => {+ if scalar.is_null() {+ return Ok(ColumnarValue::Scalar(ScalarValue::Utf8(None)));+ }+ let arr = scalar.to_array_of_size(1)?;+ let month_arr = date_part(&arr, DatePart::Month)?;+ let month_val = month_arr+ .as_primitive::<arrow::datatypes::Int32Type>()+ .value(0);+ let name = month_number_to_name(month_val).map(|s| s.to_string());+ Ok(ColumnarValue::Scalar(ScalarValue::Utf8(name)))+ }+ ColumnarValue::Array(arr) => {+ let month_arr = date_part(&arr, DatePart::Month)?;+ let int_arr = month_arr.as_primitive::<arrow::datatypes::Int32Type>();++ let result: StringArray = int_arr+ .iter()+ .map(|maybe_month| maybe_month.and_then(month_number_to_name))+ .collect();++ Ok(ColumnarValue::Array(Arc::new(result)))+ }+ }+ }+}diff --git a/datafusion/sqllogictest/test_files/spark/datetime/monthname.slt b/datafusion/sqllogictest/test_files/spark/datetime/monthname.sltnew file mode 100644index 0000000000..5927d79526--- /dev/null+++ b/datafusion/sqllogictest/test_files/spark/datetime/monthname.slt@@ -0,0 +1,175 @@+# 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.++# Scalar date input+query T+SELECT monthname('2024-03-15'::DATE);+----+Mar++# All 12 months+query T+SELECT monthname('2024-01-15'::DATE);+----+Jan++query T+SELECT monthname('2024-02-15'::DATE);+----+Feb++query T+SELECT monthname('2024-03-15'::DATE);+----+Mar++query T+SELECT monthname('2024-04-15'::DATE);+----+Apr++query T+SELECT monthname('2024-05-15'::DATE);+----+May++query T+SELECT monthname('2024-06-15'::DATE);+----+Jun++query T+SELECT monthname('2024-07-15'::DATE);+----+Jul++query T+SELECT monthname('2024-08-15'::DATE);+----+Aug++query T+SELECT monthname('2024-09-15'::DATE);+----+Sep++query T+SELECT monthname('2024-10-15'::DATE);+----+Oct++query T+SELECT monthname('2024-11-15'::DATE);+----+Nov++query T+SELECT monthname('2024-12-15'::DATE);+----+Dec++# NULL handling+query T+SELECT monthname(NULL::DATE);+----+NULL++# Array input+query T+SELECT monthname(d) FROM (VALUES ('2024-01-01'::DATE), ('2024-06-15'::DATE), ('2024-12-31'::DATE), (NULL::DATE)) AS t(d);+----+Jan+Jun+Dec+NULL++# Timestamp input: Spark coerces TIMESTAMP/TIMESTAMP_NTZ to DATE before evaluation+query T+SELECT monthname('2024-03-15 12:34:56'::TIMESTAMP);+----+Mar++query T+SELECT monthname('2024-07-04 00:00:00'::TIMESTAMP);+----+Jul++query T+SELECT monthname(NULL::TIMESTAMP);+----+NULL++# Timestamp array input+query T+SELECT monthname(ts) FROM (VALUES+ ('2024-01-15 01:02:03'::TIMESTAMP),+ ('2024-08-20 10:20:30'::TIMESTAMP),+ ('2024-11-30 23:59:59'::TIMESTAMP),+ (NULL::TIMESTAMP)+) AS t(ts);+----+Jan+Aug+Nov+NULL++# TIMESTAMP_NTZ (Timestamp without timezone) — explicit Microsecond precision+query T+SELECT monthname(arrow_cast('2024-04-10 09:15:00', 'Timestamp(Microsecond, None)'));+----+Apr++# TIMESTAMP_NTZ — explicit Millisecond precision+query T+SELECT monthname(arrow_cast('2024-09-05 18:45:30', 'Timestamp(Millisecond, None)'));+----+Sep++# TIMESTAMP_NTZ — explicit Second precision+query T+SELECT monthname(arrow_cast('2024-02-29 00:00:00', 'Timestamp(Second, None)'));+----+Feb++# TIMESTAMP_NTZ — NULL handling+query T+SELECT monthname(arrow_cast(NULL, 'Timestamp(Microsecond, None)'));+----+NULL++# TIMESTAMP with timezone (Spark TIMESTAMP / LTZ) — coerces to Date32+query T+SELECT monthname(arrow_cast('2024-05-20 03:00:00', 'Timestamp(Nanosecond, Some("UTC"))'));+----+May++query T+SELECT monthname(arrow_cast('2024-10-31 23:59:59', 'Timestamp(Microsecond, Some("America/New_York"))'));+----+Oct++# Error: wrong argument type (string without cast)+statement error Function 'monthname' requires Date, but received String+SELECT monthname('not-a-date');++# Error: wrong argument type (integer)+statement error Function 'monthname' requires Date, but received Int64+SELECT monthname(123);++# Error: no arguments+statement error 'monthname' does not support zero arguments+SELECT monthname();