Apache DataFusion SQL Query Engine
doc: Add documentation explaining the behavior of `null` values in struct comparisons (#21226)
Zhen Chen1e68674705b3
diff --git a/datafusion/functions/src/core/named_struct.rs b/datafusion/functions/src/core/named_struct.rsindex 6ae17f055e..8973e836d3 100644--- a/datafusion/functions/src/core/named_struct.rs+++ b/datafusion/functions/src/core/named_struct.rs@@ -27,7 +27,9 @@ use std::sync::Arc;#[user_doc(doc_section(label = "Struct Functions"),- description = "Returns an Arrow struct using the specified name and input expressions pairs.",+ description = "Returns an Arrow struct using the specified name and input expressions pairs.+For information on comparing and ordering struct values (including `NULL` handling),+see [Comparison and Ordering](struct_coercion.md#comparison-and-ordering).",syntax_example = "named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input])",sql_example = r#"For example, this query converts two columns `a` and `b` to a single column withdiff --git a/datafusion/functions/src/core/struct.rs b/datafusion/functions/src/core/struct.rsindex 476da39a5a..2697cb46b0 100644--- a/datafusion/functions/src/core/struct.rs+++ b/datafusion/functions/src/core/struct.rs@@ -27,7 +27,9 @@ use std::sync::Arc;doc_section(label = "Struct Functions"),description = "Returns an Arrow struct using the specified input expressions optionally named.Fields in the returned struct use the optional name or the `cN` naming convention.-For example: `c0`, `c1`, `c2`, etc.",+For example: `c0`, `c1`, `c2`, etc.+For information on comparing and ordering struct values (including `NULL` handling),+see [Comparison and Ordering](struct_coercion.md#comparison-and-ordering).",syntax_example = "struct(expression1[, ..., expression_n])",sql_example = r#"For example, this query converts two columns `a` and `b` to a single column witha struct type of fields `field_a` and `c1`:diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.mdindex 5a8ef4db3d..022b0f9dae 100644--- a/docs/source/user-guide/sql/scalar_functions.md+++ b/docs/source/user-guide/sql/scalar_functions.md@@ -4709,6 +4709,8 @@ _Alias of [string_to_array](#string_to_array)._### `named_struct`Returns an Arrow struct using the specified name and input expressions pairs.+For information on comparing and ordering struct values (including `NULL` handling),+see [Comparison and Ordering](struct_coercion.md#comparison-and-ordering).```sqlnamed_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input])@@ -4750,6 +4752,8 @@ _Alias of [struct](#struct)._Returns an Arrow struct using the specified input expressions optionally named.Fields in the returned struct use the optional name or the `cN` naming convention.For example: `c0`, `c1`, `c2`, etc.+For information on comparing and ordering struct values (including `NULL` handling),+see [Comparison and Ordering](struct_coercion.md#comparison-and-ordering).```sqlstruct(expression1[, ..., expression_n])diff --git a/docs/source/user-guide/sql/struct_coercion.md b/docs/source/user-guide/sql/struct_coercion.mdindex d2a32fcee2..059f9fd009 100644--- a/docs/source/user-guide/sql/struct_coercion.md+++ b/docs/source/user-guide/sql/struct_coercion.md@@ -208,6 +208,26 @@ SELECT [] FROM t_left JOIN t_right;```+## Comparison and Ordering++DataFusion supports comparing `STRUCT` values with standard comparison operators+(`=`, `!=`, `<`, `<=`, `>`, `>=`). Ordering comparisons are lexicographical and+follow DataFusion's default ascending comparison behavior, where `NULL` sorts+before non-`NULL` values.++### Examples++```sql+SELECT {x: 1, y: 2} < {x: 1, y: 3};+-- true++SELECT {x: 1, y: NULL} < {x: 1, y: 2};+-- true++SELECT {x: 1, y: NULL} = {x: 1, y: NULL};+--true+```+## Migration Guide: From Positional to Name-Based MatchingIf you have existing code that relied on **positional** struct field matching, you may need to update it.diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.mdindex 692d1c4020..7533bd49d5 100644--- a/docs/source/user-guide/sql/subqueries.md+++ b/docs/source/user-guide/sql/subqueries.md@@ -102,6 +102,18 @@ SELECT * FROM x WHERE column_1 NOT IN (1,3);+----------+----------+```+#### `IN` with tuple-like values and `NULL`++For tuple-like values, `IN` uses DataFusion's struct equality semantics:++```sql+SELECT (1, 1) IN ((1, NULL));+-- false++SELECT (1, NULL) IN ((1, NULL));+-- true+```+## SELECT clause subqueries`SELECT` clause subqueries use values returned from the inner query as part