doc: Add documentation explaining the behavior of null values ​​in struct comparisons (#21226)

## Which issue does this PR close?

- Closes #.

## Rationale for this change

DataFusion already supports tuple-like and `STRUCT` comparisons, but the
user-facing documentation did not clearly describe the current
comparison semantics, especially around lexicographical ordering and
`NULL` handling. The `IN` documentation also did not explain tuple-like
values.

## What changes are included in this PR?

- Added a short `STRUCT` comparison note to
[struct_coercion.md](/Users/jensen/code/datafusion/docs/source/user-guide/sql/struct_coercion.md),
documenting that:
  - `STRUCT` values support standard comparison operators
  - comparisons are lexicographical by field order
  - `NULL` is ordered before non-`NULL`
- Added minimal examples for `STRUCT` comparisons, including a `NULL`
example
- Added a short note to
[subqueries.md](/Users/jensen/code/datafusion/docs/source/user-guide/sql/subqueries.md)
explaining that tuple-like `IN` uses DataFusion's struct equality
semantics
- Added a concrete example:
  - `SELECT (7521, 30) IN ((7521, NULL));`
  - result: `false`

## Are these changes tested?

No new tests were added. This PR only updates documentation for existing
behavior, and the documented behavior is already covered by existing
tuple/struct comparison and `IN` tests.

## Are there any user-facing changes?

Yes. This PR updates the SQL user documentation to clarify the current
semantics of `STRUCT` comparisons and tuple-like `IN` expressions.

Author: xiedeyantu

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 with

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 with
 a struct type of fields `field_a` and `c1`:

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).
 
 ```sql
 named_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).
 
 ```sql
 struct(expression1[, ..., expression_n])

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 Matching
 
 If you have existing code that relied on **positional** struct field matching, you may need to update it.

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