Format Date32 to string given timestamp specifiers (apache#15361)

* Format Date32 to string given timestamp specifiers

* Eagerly cast Date32 to Date64 before formatting

* Remove superfluous clone

* POC for parsing format with StrftimeItems to determine if there are any time specifiers present.

* Update benchmark code

* Stage initial selective retry

* Update comments

* Keep track of consecutive Date32 failures

* Revert "Keep track of consecutive Date32 failures"

This reverts commit b379fe1.

* Updated example filename.

* Updates to reflect changes in main.

* Documentation update.

---------

Co-authored-by: Bruce Ritchie <bruce.ritchie@veeva.com>
Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>

Author: 3 people

datafusion/functions/benches/to_char.rs

@@ -33,7 +33,7 @@ use rand::prelude::IndexedRandom;
 use rand::rngs::ThreadRng;
 use rand::Rng;
 
-fn random_date_in_range(
+fn pick_date_in_range(
     rng: &mut ThreadRng,
     start_date: NaiveDate,
     end_date: NaiveDate,
@@ -43,7 +43,7 @@ fn random_date_in_range(
     start_date + TimeDelta::try_days(random_days).unwrap()
 }
 
-fn data(rng: &mut ThreadRng) -> Date32Array {
+fn generate_date32_array(rng: &mut ThreadRng) -> Date32Array {
     let mut data: Vec<i32> = vec![];
     let unix_days_from_ce = NaiveDate::from_ymd_opt(1970, 1, 1)
         .unwrap()
@@ -56,39 +56,139 @@ fn data(rng: &mut ThreadRng) -> Date32Array {
         .expect("Date should parse");
     for _ in 0..1000 {
         data.push(
-            random_date_in_range(rng, start_date, end_date).num_days_from_ce()
+            pick_date_in_range(rng, start_date, end_date).num_days_from_ce()
                 - unix_days_from_ce,
         );
     }
 
     Date32Array::from(data)
 }
 
-fn patterns(rng: &mut ThreadRng) -> StringArray {
-    let samples = [
-        "%Y:%m:%d".to_string(),
-        "%d-%m-%Y".to_string(),
-        "%d%m%Y".to_string(),
-        "%Y%m%d".to_string(),
-        "%Y...%m...%d".to_string(),
-    ];
-    let mut data: Vec<String> = vec![];
+const DATE_PATTERNS: [&str; 5] =
+    ["%Y:%m:%d", "%d-%m-%Y", "%d%m%Y", "%Y%m%d", "%Y...%m...%d"];
+
+const DATETIME_PATTERNS: [&str; 8] = [
+    "%Y:%m:%d %H:%M%S",
+    "%Y:%m:%d %_H:%M%S",
+    "%Y:%m:%d %k:%M%S",
+    "%d-%m-%Y %I%P-%M-%S %f",
+    "%d%m%Y %H",
+    "%Y%m%d %M-%S %.3f",
+    "%Y...%m...%d %T%3f",
+    "%c",
+];
+
+fn pick_date_pattern(rng: &mut ThreadRng) -> String {
+    DATE_PATTERNS
+        .choose(rng)
+        .expect("Empty list of date patterns")
+        .to_string()
+}
+
+fn pick_date_time_pattern(rng: &mut ThreadRng) -> String {
+    DATETIME_PATTERNS
+        .choose(rng)
+        .expect("Empty list of date time patterns")
+        .to_string()
+}
+
+fn pick_date_and_date_time_mixed_pattern(rng: &mut ThreadRng) -> String {
+    match rng.random_bool(0.5) {
+        true => pick_date_pattern(rng),
+        false => pick_date_time_pattern(rng),
+    }
+}
+
+fn generate_pattern_array(
+    rng: &mut ThreadRng,
+    pick_fn: impl Fn(&mut ThreadRng) -> String,
+) -> StringArray {
+    let mut data = Vec::with_capacity(1000);
+
     for _ in 0..1000 {
-        data.push(samples.choose(rng).unwrap().to_string());
+        data.push(pick_fn(rng));
     }
 
     StringArray::from(data)
 }
 
+fn generate_date_pattern_array(rng: &mut ThreadRng) -> StringArray {
+    generate_pattern_array(rng, pick_date_pattern)
+}
+
+fn generate_datetime_pattern_array(rng: &mut ThreadRng) -> StringArray {
+    generate_pattern_array(rng, pick_date_time_pattern)
+}
+
+fn generate_mixed_pattern_array(rng: &mut ThreadRng) -> StringArray {
+    generate_pattern_array(rng, pick_date_and_date_time_mixed_pattern)
+}
+
 fn criterion_benchmark(c: &mut Criterion) {
     let config_options = Arc::new(ConfigOptions::default());
 
-    c.bench_function("to_char_array_array_1000", |b| {
+    c.bench_function("to_char_array_date_only_patterns_1000", |b| {
+        let mut rng = rand::rng();
+        let data_arr = generate_date32_array(&mut rng);
+        let batch_len = data_arr.len();
+        let data = ColumnarValue::Array(Arc::new(data_arr) as ArrayRef);
+        let patterns = ColumnarValue::Array(Arc::new(generate_date_pattern_array(
+            &mut rng,
+        )) as ArrayRef);
+
+        b.iter(|| {
+            black_box(
+                to_char()
+                    .invoke_with_args(ScalarFunctionArgs {
+                        args: vec![data.clone(), patterns.clone()],
+                        arg_fields: vec![
+                            Field::new("a", data.data_type(), true).into(),
+                            Field::new("b", patterns.data_type(), true).into(),
+                        ],
+                        number_rows: batch_len,
+                        return_field: Field::new("f", DataType::Utf8, true).into(),
+                        config_options: Arc::clone(&config_options),
+                    })
+                    .expect("to_char should work on valid values"),
+            )
+        })
+    });
+
+    c.bench_function("to_char_array_datetime_patterns_1000", |b| {
+        let mut rng = rand::rng();
+        let data_arr = generate_date32_array(&mut rng);
+        let batch_len = data_arr.len();
+        let data = ColumnarValue::Array(Arc::new(data_arr) as ArrayRef);
+        let patterns = ColumnarValue::Array(Arc::new(generate_datetime_pattern_array(
+            &mut rng,
+        )) as ArrayRef);
+
+        b.iter(|| {
+            black_box(
+                to_char()
+                    .invoke_with_args(ScalarFunctionArgs {
+                        args: vec![data.clone(), patterns.clone()],
+                        arg_fields: vec![
+                            Field::new("a", data.data_type(), true).into(),
+                            Field::new("b", patterns.data_type(), true).into(),
+                        ],
+                        number_rows: batch_len,
+                        return_field: Field::new("f", DataType::Utf8, true).into(),
+                        config_options: Arc::clone(&config_options),
+                    })
+                    .expect("to_char should work on valid values"),
+            )
+        })
+    });
+
+    c.bench_function("to_char_array_mixed_patterns_1000", |b| {
         let mut rng = rand::rng();
-        let data_arr = data(&mut rng);
+        let data_arr = generate_date32_array(&mut rng);
         let batch_len = data_arr.len();
         let data = ColumnarValue::Array(Arc::new(data_arr) as ArrayRef);
-        let patterns = ColumnarValue::Array(Arc::new(patterns(&mut rng)) as ArrayRef);
+        let patterns = ColumnarValue::Array(Arc::new(generate_mixed_pattern_array(
+            &mut rng,
+        )) as ArrayRef);
 
         b.iter(|| {
             black_box(
@@ -108,13 +208,13 @@ fn criterion_benchmark(c: &mut Criterion) {
         })
     });
 
-    c.bench_function("to_char_array_scalar_1000", |b| {
+    c.bench_function("to_char_scalar_date_only_pattern_1000", |b| {
         let mut rng = rand::rng();
-        let data_arr = data(&mut rng);
+        let data_arr = generate_date32_array(&mut rng);
         let batch_len = data_arr.len();
         let data = ColumnarValue::Array(Arc::new(data_arr) as ArrayRef);
         let patterns =
-            ColumnarValue::Scalar(ScalarValue::Utf8(Some("%Y-%m-%d".to_string())));
+            ColumnarValue::Scalar(ScalarValue::Utf8(Some(pick_date_pattern(&mut rng))));
 
         b.iter(|| {
             black_box(
@@ -134,7 +234,35 @@ fn criterion_benchmark(c: &mut Criterion) {
         })
     });
 
-    c.bench_function("to_char_scalar_scalar_1000", |b| {
+    c.bench_function("to_char_scalar_datetime_pattern_1000", |b| {
+        let mut rng = rand::rng();
+        let data_arr = generate_date32_array(&mut rng);
+        let batch_len = data_arr.len();
+        let data = ColumnarValue::Array(Arc::new(data_arr) as ArrayRef);
+        let patterns = ColumnarValue::Scalar(ScalarValue::Utf8(Some(
+            pick_date_time_pattern(&mut rng),
+        )));
+
+        b.iter(|| {
+            black_box(
+                to_char()
+                    .invoke_with_args(ScalarFunctionArgs {
+                        args: vec![data.clone(), patterns.clone()],
+                        arg_fields: vec![
+                            Field::new("a", data.data_type(), true).into(),
+                            Field::new("b", patterns.data_type(), true).into(),
+                        ],
+                        number_rows: batch_len,
+                        return_field: Field::new("f", DataType::Utf8, true).into(),
+                        config_options: Arc::clone(&config_options),
+                    })
+                    .expect("to_char should work on valid values"),
+            )
+        })
+    });
+
+    c.bench_function("to_char_scalar_1000", |b| {
+        let mut rng = rand::rng();
         let timestamp = "2026-07-08T09:10:11"
             .parse::<NaiveDateTime>()
             .unwrap()
@@ -144,9 +272,8 @@ fn criterion_benchmark(c: &mut Criterion) {
             .timestamp_nanos_opt()
             .unwrap();
         let data = ColumnarValue::Scalar(TimestampNanosecond(Some(timestamp), None));
-        let pattern = ColumnarValue::Scalar(ScalarValue::Utf8(Some(
-            "%d-%m-%Y %H:%M:%S".to_string(),
-        )));
+        let pattern =
+            ColumnarValue::Scalar(ScalarValue::Utf8(Some(pick_date_pattern(&mut rng))));
 
         b.iter(|| {
             black_box(