(datafusion) branch main updated: Make `create_ordering` pub and add doc for it (#14996)

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xudong963 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git


The following commit(s) were added to refs/heads/main by this push:
     new dd0fd889ea Make `create_ordering` pub and add doc for it (#14996)
dd0fd889ea is described below

commit dd0fd889ea603f929accb99002e2f99280823f5c
Author: xudong.w <wx...@gmail.com>
AuthorDate: Tue Mar 4 22:08:01 2025 +0800

    Make `create_ordering` pub and add doc for it (#14996)
    
    * Make create_ordering public and add notes
    
    * fix test
    
    * fix
    
    * Update datafusion/core/src/datasource/mod.rs
    
    Co-authored-by: Andrew Lamb <an...@nerdnetworks.org>
    
    ---------
    
    Co-authored-by: Andrew Lamb <an...@nerdnetworks.org>
---
 datafusion/core/src/datasource/listing/table.rs |  2 +-
 datafusion/core/src/datasource/mod.rs           | 52 ++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/datafusion/core/src/datasource/listing/table.rs b/datafusion/core/src/datasource/listing/table.rs
index 71e2d31ee9..4d7762784d 100644
--- a/datafusion/core/src/datasource/listing/table.rs
+++ b/datafusion/core/src/datasource/listing/table.rs
@@ -1306,7 +1306,7 @@ mod tests {
                 vec![vec![
                     col("int_col").add(lit(1)).sort(true, true),
                 ]],
-                Err("Expected single column references in output_ordering, got int_col + Int32(1)"),
+                Err("Expected single column reference in sort_order[0][0], got int_col + Int32(1)"),
             ),
             // ok with one column
             (
diff --git a/datafusion/core/src/datasource/mod.rs b/datafusion/core/src/datasource/mod.rs
index 8661def838..18a1318dd4 100644
--- a/datafusion/core/src/datasource/mod.rs
+++ b/datafusion/core/src/datasource/mod.rs
@@ -53,16 +53,55 @@ use datafusion_common::{plan_err, Result};
 use datafusion_expr::{Expr, SortExpr};
 use datafusion_physical_expr::{expressions, LexOrdering, PhysicalSortExpr};
 
-fn create_ordering(
+/// Converts logical sort expressions to physical sort expressions
+///
+/// This function transforms a collection of logical sort expressions into their physical
+/// representation that can be used during query execution.
+///
+/// # Arguments
+///
+/// * `schema` - The schema containing column definitions
+/// * `sort_order` - A collection of logical sort expressions grouped into lexicographic orderings
+///
+/// # Returns
+///
+/// A vector of lexicographic orderings for physical execution, or an error if the transformation fails
+///
+/// # Examples
+///
+/// ```
+/// // Create orderings from columns "id" and "name"
+/// # use arrow::datatypes::{Schema, Field, DataType};
+/// # use datafusion::datasource::create_ordering;
+/// # use datafusion_common::Column;
+/// # use datafusion_expr::{Expr, SortExpr};
+/// #
+/// // Create a schema with two fields
+/// let schema = Schema::new(vec![
+///     Field::new("id", DataType::Int32, false),
+///     Field::new("name", DataType::Utf8, false),
+/// ]);
+///
+/// let sort_exprs = vec![
+///     vec![
+///         SortExpr { expr: Expr::Column(Column::new(Some("t"), "id")), asc: true, nulls_first: false }
+///     ],
+///     vec![
+///         SortExpr { expr: Expr::Column(Column::new(Some("t"), "name")), asc: false, nulls_first: true }
+///     ]
+/// ];
+/// let result = create_ordering(&schema, &sort_exprs).unwrap();
+/// ```
+pub fn create_ordering(
     schema: &Schema,
     sort_order: &[Vec<SortExpr>],
 ) -> Result<Vec<LexOrdering>> {
     let mut all_sort_orders = vec![];
 
-    for exprs in sort_order {
+    for (group_idx, exprs) in sort_order.iter().enumerate() {
         // Construct PhysicalSortExpr objects from Expr objects:
         let mut sort_exprs = LexOrdering::default();
-        for sort in exprs {
+        for (expr_idx, sort) in exprs.iter().enumerate() {
             match &sort.expr {
                 Expr::Column(col) => match expressions::col(&col.name, schema) {
                     Ok(expr) => {
@@ -80,8 +119,11 @@ fn create_ordering(
                 },
                 expr => {
                     return plan_err!(
-                    "Expected single column references in output_ordering, got {expr}"
-                )
+                        "Expected single column reference in sort_order[{}][{}], got {}",
+                        group_idx,
+                        expr_idx,
+                        expr
+                    );
                 }
             }
         }


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org