chore: tidy up comments in sort alias fix

Clarify what the algorithm does and why, remove example-specific
column names from the implementation comments.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: yonatan-sevenai

datafusion/sql/src/unparser/rewrite.rs

@@ -254,12 +254,13 @@ pub(super) fn rewrite_plan_for_sort_on_non_projected_fields(
             .map(|e| map.get(e).unwrap_or(e).clone())
             .collect::<Vec<_>>();
 
-        // Build a reverse map from alias name → underlying expression for
-        // sort columns that are dropped from the outer projection.  When
-        // the inner Projection is trimmed to `new_exprs` below, any alias
-        // that only existed in the inner Projection disappears, so ORDER BY
-        // references to it become dangling.  We inline the physical
-        // expression instead (e.g. ORDER BY "c" → ORDER BY "Z").
+        // The inner Projection may define aliases that the Sort references
+        // but the outer Projection does not include.  Since we are about to
+        // replace the inner Projection's expressions with `new_exprs` (which
+        // only contains the outer Projection's columns), those alias
+        // definitions will be lost.  To keep the Sort valid, rewrite any
+        // sort expression that references a dropped alias so that it uses
+        // the alias's underlying expression instead.
         let projected_aliases: HashSet<&str> = new_exprs
             .iter()
             .filter_map(|e| match e {
@@ -268,7 +269,7 @@ pub(super) fn rewrite_plan_for_sort_on_non_projected_fields(
             })
             .collect();
 
-        let alias_to_underlying: HashMap<String, Expr> = inner_p
+        let dropped_aliases: HashMap<String, Expr> = inner_p
             .expr
             .iter()
             .filter_map(|e| match e {
@@ -279,15 +280,14 @@ pub(super) fn rewrite_plan_for_sort_on_non_projected_fields(
             })
             .collect();
 
-        if !alias_to_underlying.is_empty() {
+        if !dropped_aliases.is_empty() {
             for sort_expr in &mut sort.expr {
                 let mut expr = sort_expr.expr.clone();
                 while let Expr::Alias(alias) = expr {
                     expr = *alias.expr;
                 }
                 if let Expr::Column(ref col) = expr {
-                    let name = col.name();
-                    if let Some(underlying) = alias_to_underlying.get(name) {
+                    if let Some(underlying) = dropped_aliases.get(col.name()) {
                         sort_expr.expr = underlying.clone();
                     }
                 }

datafusion/sql/tests/cases/plan_to_sql.rs

@@ -2974,12 +2974,12 @@ fn test_unparse_manual_join_with_subquery_aggregate() -> Result<()> {
     Ok(())
 }
 
-/// Regression test: when the outer Projection excludes a Sort column that was
-/// defined as an alias in the inner Projection (through a SubqueryAlias), the
-/// Unparser must either preserve the subquery boundary or inline the physical
-/// column name into the ORDER BY clause.
+/// Regression test for https://github.com/apache/datafusion/issues/21490
 ///
-/// See: https://github.com/apache/datafusion/issues/XXXX
+/// When the outer Projection excludes a Sort column whose definition only
+/// exists as an alias in the inner Projection, the Unparser must inline the
+/// underlying expression into ORDER BY rather than emitting the now-missing
+/// alias name.
 #[test]
 fn test_sort_on_aliased_column_dropped_by_outer_projection() -> Result<()> {
     let schema = Schema::new(vec![
@@ -3017,9 +3017,7 @@ fn test_sort_on_aliased_column_dropped_by_outer_projection() -> Result<()> {
     let unparser = Unparser::default();
     let sql = unparser.plan_to_sql(&plan)?;
 
-    // The sort column "c" (aliased from "Z" in the inner Projection) must be
-    // inlined to the physical column in ORDER BY, since the outer Projection
-    // excludes it from the SELECT list.
+    // ORDER BY must reference the physical column, not the dropped alias.
     assert_snapshot!(
         sql,
         @r#"SELECT t."X" AS a, t."Y" AS b FROM phys_table AS t ORDER BY t."Z" DESC NULLS FIRST LIMIT 1"#