feat: move and make validate_struct_compatibility public for nested struct casting

Author: kosiew

datafusion/common/src/nested_struct.rs

@@ -15,11 +15,11 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use crate::error::{DataFusionError, Result};
+use crate::error::{DataFusionError, Result, _plan_err};
 use arrow::{
     array::{new_null_array, Array, ArrayRef, StructArray},
     compute::cast,
-    datatypes::{DataType::Struct, Field},
+    datatypes::{DataType::Struct, Field, FieldRef},
 };
 use std::sync::Arc;
 
@@ -121,6 +121,81 @@ pub fn cast_column(source_col: &ArrayRef, target_field: &Field) -> Result<ArrayR
     }
 }
 
+/// Validates compatibility between source and target struct fields for casting operations.
+///
+/// This function implements comprehensive struct compatibility checking by examining:
+/// - Field name matching between source and target structs  
+/// - Type castability for each matching field (including recursive struct validation)
+/// - Proper handling of missing fields (target fields not in source are allowed - filled with nulls)
+/// - Proper handling of extra fields (source fields not in target are allowed - ignored)
+///
+/// # Compatibility Rules
+/// - **Field Matching**: Fields are matched by name (case-sensitive)
+/// - **Missing Target Fields**: Allowed - will be filled with null values during casting
+/// - **Extra Source Fields**: Allowed - will be ignored during casting  
+/// - **Type Compatibility**: Each matching field must be castable using Arrow's type system
+/// - **Nested Structs**: Recursively validates nested struct compatibility
+///
+/// # Arguments
+/// * `source_fields` - Fields from the source struct type
+/// * `target_fields` - Fields from the target struct type
+///
+/// # Returns
+/// * `Ok(true)` if the structs are compatible for casting
+/// * `Err(DataFusionError)` with detailed error message if incompatible
+///
+/// # Examples
+/// ```ignore
+/// // Compatible: source has extra field, target has missing field
+/// // Source: {a: i32, b: string, c: f64}  
+/// // Target: {a: i64, d: bool}
+/// // Result: Ok(true) - 'a' can cast i32->i64, 'b','c' ignored, 'd' filled with nulls
+///
+/// // Incompatible: matching field has incompatible types
+/// // Source: {a: string}
+/// // Target: {a: binary}
+/// // Result: Err(...) - string cannot cast to binary
+/// ```
+pub fn validate_struct_compatibility(
+    source_fields: &[FieldRef],
+    target_fields: &[FieldRef],
+) -> Result<bool> {
+    // Check compatibility for each target field
+    for target_field in target_fields {
+        // Look for matching field in source by name
+        if let Some(source_field) = source_fields
+            .iter()
+            .find(|f| f.name() == target_field.name())
+        {
+            // Check if the matching field types are compatible
+            match (source_field.data_type(), target_field.data_type()) {
+                // Recursively validate nested structs
+                (Struct(source_nested), Struct(target_nested)) => {
+                    validate_struct_compatibility(source_nested, target_nested)?;
+                }
+                // For non-struct types, use the existing castability check
+                _ => {
+                    if !arrow::compute::can_cast_types(
+                        source_field.data_type(),
+                        target_field.data_type(),
+                    ) {
+                        return _plan_err!(
+                            "Cannot cast struct field '{}' from type {:?} to type {:?}",
+                            target_field.name(),
+                            source_field.data_type(),
+                            target_field.data_type()
+                        );
+                    }
+                }
+            }
+        }
+        // Missing fields in source are OK - they'll be filled with nulls
+    }
+
+    // Extra fields in source are OK - they'll be ignored
+    Ok(true)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -202,4 +277,53 @@ mod tests {
         assert!(error_msg.contains("to struct type"));
         assert!(error_msg.contains("Source must be a struct"));
     }
+
+    #[test]
+    fn test_validate_struct_compatibility_incompatible_types() {
+        // Source struct: {field1: Binary, field2: String}
+        let source_fields = vec![
+            Arc::new(Field::new("field1", DataType::Binary, true)),
+            Arc::new(Field::new("field2", DataType::Utf8, true)),
+        ];
+
+        // Target struct: {field1: Int32}
+        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int32, true))];
+
+        let result = validate_struct_compatibility(&source_fields, &target_fields);
+        assert!(result.is_err());
+        let error_msg = result.unwrap_err().to_string();
+        assert!(error_msg.contains("Cannot cast struct field 'field1'"));
+        assert!(error_msg.contains("Binary"));
+        assert!(error_msg.contains("Int32"));
+    }
+
+    #[test]
+    fn test_validate_struct_compatibility_compatible_types() {
+        // Source struct: {field1: Int32, field2: String}
+        let source_fields = vec![
+            Arc::new(Field::new("field1", DataType::Int32, true)),
+            Arc::new(Field::new("field2", DataType::Utf8, true)),
+        ];
+
+        // Target struct: {field1: Int64} (Int32 can cast to Int64)
+        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int64, true))];
+
+        let result = validate_struct_compatibility(&source_fields, &target_fields);
+        assert!(result.is_ok());
+        assert!(result.unwrap());
+    }
+
+    #[test]
+    fn test_validate_struct_compatibility_missing_field_in_source() {
+        // Source struct: {field2: String} (missing field1)
+        let source_fields = vec![Arc::new(Field::new("field2", DataType::Utf8, true))];
+
+        // Target struct: {field1: Int32}
+        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int32, true))];
+
+        // Should be OK - missing fields will be filled with nulls
+        let result = validate_struct_compatibility(&source_fields, &target_fields);
+        assert!(result.is_ok());
+        assert!(result.unwrap());
+    }
 }

datafusion/datasource/src/nested_schema_adapter/adapter.rs

@@ -20,10 +20,10 @@ use crate::schema_adapter::{
 };
 use arrow::{
     array::ArrayRef,
-    datatypes::{DataType::Struct, Field, FieldRef, Schema, SchemaRef},
+    datatypes::{DataType::Struct, Field, Schema, SchemaRef},
 };
-use datafusion_common::nested_struct::cast_column;
-use datafusion_common::{plan_err, Result};
+use datafusion_common::nested_struct::{cast_column, validate_struct_compatibility};
+use datafusion_common::Result;
 use std::sync::Arc;
 
 /// A SchemaAdapter that handles schema evolution for nested struct types
@@ -92,133 +92,3 @@ impl SchemaAdapter for NestedStructSchemaAdapter {
         ))
     }
 }
-
-/// Validates compatibility between source and target struct fields for casting operations.
-///
-/// This function implements comprehensive struct compatibility checking by examining:
-/// - Field name matching between source and target structs  
-/// - Type castability for each matching field (including recursive struct validation)
-/// - Proper handling of missing fields (target fields not in source are allowed - filled with nulls)
-/// - Proper handling of extra fields (source fields not in target are allowed - ignored)
-///
-/// # Compatibility Rules
-/// - **Field Matching**: Fields are matched by name (case-sensitive)
-/// - **Missing Target Fields**: Allowed - will be filled with null values during casting
-/// - **Extra Source Fields**: Allowed - will be ignored during casting  
-/// - **Type Compatibility**: Each matching field must be castable using Arrow's type system
-/// - **Nested Structs**: Recursively validates nested struct compatibility
-///
-/// # Arguments
-/// * `source_fields` - Fields from the source struct type
-/// * `target_fields` - Fields from the target struct type
-///
-/// # Returns
-/// * `Ok(true)` if the structs are compatible for casting
-/// * `Err(DataFusionError)` with detailed error message if incompatible
-///
-/// # Examples
-/// ```ignore
-/// // Compatible: source has extra field, target has missing field
-/// // Source: {a: i32, b: string, c: f64}  
-/// // Target: {a: i64, d: bool}
-/// // Result: Ok(true) - 'a' can cast i32->i64, 'b','c' ignored, 'd' filled with nulls
-///
-/// // Incompatible: matching field has incompatible types
-/// // Source: {a: string}
-/// // Target: {a: binary}
-/// // Result: Err(...) - string cannot cast to binary
-/// ```
-fn validate_struct_compatibility(
-    source_fields: &[FieldRef],
-    target_fields: &[FieldRef],
-) -> Result<bool> {
-    // Check compatibility for each target field
-    for target_field in target_fields {
-        // Look for matching field in source by name
-        if let Some(source_field) = source_fields
-            .iter()
-            .find(|f| f.name() == target_field.name())
-        {
-            // Check if the matching field types are compatible
-            match (source_field.data_type(), target_field.data_type()) {
-                // Recursively validate nested structs
-                (Struct(source_nested), Struct(target_nested)) => {
-                    validate_struct_compatibility(source_nested, target_nested)?;
-                }
-                // For non-struct types, use the existing castability check
-                _ => {
-                    if !arrow::compute::can_cast_types(
-                        source_field.data_type(),
-                        target_field.data_type(),
-                    ) {
-                        return plan_err!(
-                            "Cannot cast struct field '{}' from type {:?} to type {:?}",
-                            target_field.name(),
-                            source_field.data_type(),
-                            target_field.data_type()
-                        );
-                    }
-                }
-            }
-        }
-        // Missing fields in source are OK - they'll be filled with nulls
-    }
-
-    // Extra fields in source are OK - they'll be ignored
-    Ok(true)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use arrow::datatypes::{DataType, Field};
-
-    #[test]
-    fn test_validate_struct_compatibility_incompatible_types() {
-        // Source struct: {field1: Binary, field2: String}
-        let source_fields = vec![
-            Arc::new(Field::new("field1", DataType::Binary, true)),
-            Arc::new(Field::new("field2", DataType::Utf8, true)),
-        ];
-
-        // Target struct: {field1: Int32}
-        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int32, true))];
-
-        let result = validate_struct_compatibility(&source_fields, &target_fields);
-        assert!(result.is_err());
-        let error_msg = result.unwrap_err().to_string();
-        assert!(error_msg.contains("Cannot cast struct field 'field1'"));
-        assert!(error_msg.contains("Binary"));
-        assert!(error_msg.contains("Int32"));
-    }
-
-    #[test]
-    fn test_validate_struct_compatibility_compatible_types() {
-        // Source struct: {field1: Int32, field2: String}
-        let source_fields = vec![
-            Arc::new(Field::new("field1", DataType::Int32, true)),
-            Arc::new(Field::new("field2", DataType::Utf8, true)),
-        ];
-
-        // Target struct: {field1: Int64} (Int32 can cast to Int64)
-        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int64, true))];
-
-        let result = validate_struct_compatibility(&source_fields, &target_fields);
-        assert!(result.is_ok());
-        assert!(result.unwrap());
-    }
-
-    #[test]
-    fn test_validate_struct_compatibility_missing_field_in_source() {
-        // Source struct: {field2: String} (missing field1)
-        let source_fields = vec![Arc::new(Field::new("field2", DataType::Utf8, true))];
-
-        // Target struct: {field1: Int32}
-        let target_fields = vec![Arc::new(Field::new("field1", DataType::Int32, true))];
-
-        // Should be OK - missing fields will be filled with nulls
-        let result = validate_struct_compatibility(&source_fields, &target_fields);
-        assert!(result.is_ok());
-        assert!(result.unwrap());
-    }
-}