adriangb commented on code in PR #19674: URL: https://github.com/apache/datafusion/pull/19674#discussion_r2713728696
########## docs/source/user-guide/sql/struct_coercion.md: ########## @@ -0,0 +1,354 @@ +<!--- + 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. +--> + +# Struct Type Coercion and Field Mapping + +DataFusion uses **name-based field mapping** when coercing struct types across different operations. This document explains how struct coercion works, when it applies, and how to handle NULL fields. + +## Overview: Name-Based vs Positional Mapping + +When combining structs from different sources (e.g., in UNION, array construction, or JOINs), DataFusion matches struct fields by **name** rather than by **position**. This provides more robust and predictable behavior compared to positional matching. + +### Example: Field Reordering is Handled Transparently + +```sql +-- These two structs have the same fields in different order +SELECT [{a: 1, b: 2}, {b: 3, a: 4}]; + +-- Result: Field names matched, values unified +-- [{"a": 1, "b": 2}, {"a": 4, "b": 3}] +``` + +## Coercion Paths Using Name-Based Matching + +The following query operations use name-based field mapping for struct coercion: + +### 1. Array Literal Construction Review Comment: This seems like more just general documentation on where casts happen, I don't think it's specific to struct coercion. That said I don't know that this exist anywhere else / there is nowhere better to put it. I suggest we keep it here for now since you've written it and it is helpful and not wrong, and we can always refactor the docs later. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
