Apache DataFusion SQL Query Engine
perf: Optimize `array_sort()` (#21083)
Neil Conwaye5c69a433e63
diff --git a/datafusion/functions-nested/Cargo.toml b/datafusion/functions-nested/Cargo.tomlindex 5fce3e854e..2ce9532a22 100644--- a/datafusion/functions-nested/Cargo.toml+++ b/datafusion/functions-nested/Cargo.toml@@ -109,3 +109,7 @@ name = "array_to_string"[[bench]]harness = falsename = "array_position"++[[bench]]+harness = false+name = "array_sort"diff --git a/datafusion/functions-nested/benches/array_sort.rs b/datafusion/functions-nested/benches/array_sort.rsnew file mode 100644index 0000000000..940c0396cb--- /dev/null+++ b/datafusion/functions-nested/benches/array_sort.rs@@ -0,0 +1,195 @@+// 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.++use std::hint::black_box;+use std::sync::Arc;++use arrow::array::{ArrayRef, BooleanBufferBuilder, Int32Array, ListArray, StringArray};+use arrow::buffer::{NullBuffer, OffsetBuffer};+use arrow::datatypes::{DataType, Field};+use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};+use datafusion_common::config::ConfigOptions;+use datafusion_expr::{ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl};+use datafusion_functions_nested::sort::ArraySort;+use rand::SeedableRng;+use rand::rngs::StdRng;+use rand::seq::SliceRandom;++const SEED: u64 = 42;+const NUM_ROWS: usize = 8192;++fn create_int32_list_array(+ num_rows: usize,+ elements_per_row: usize,+ with_nulls: bool,+) -> ArrayRef {+ let mut rng = StdRng::seed_from_u64(SEED);+ let total_values = num_rows * elements_per_row;++ let mut values: Vec<i32> = (0..total_values as i32).collect();+ values.shuffle(&mut rng);++ let values = Arc::new(Int32Array::from(values));+ let offsets: Vec<i32> = (0..=num_rows)+ .map(|i| (i * elements_per_row) as i32)+ .collect();++ let nulls = if with_nulls {+ // Every 10th row is null+ Some(NullBuffer::from(+ (0..num_rows).map(|i| i % 10 != 0).collect::<Vec<bool>>(),+ ))+ } else {+ None+ };++ Arc::new(ListArray::new(+ Arc::new(Field::new("item", DataType::Int32, true)),+ OffsetBuffer::new(offsets.into()),+ values,+ nulls,+ ))+}++/// Creates a ListArray where ~10% of elements within each row are null.+fn create_int32_list_array_with_null_elements(+ num_rows: usize,+ elements_per_row: usize,+) -> ArrayRef {+ let mut rng = StdRng::seed_from_u64(SEED);+ let total_values = num_rows * elements_per_row;++ let mut values: Vec<i32> = (0..total_values as i32).collect();+ values.shuffle(&mut rng);++ // ~10% of elements are null+ let mut validity = BooleanBufferBuilder::new(total_values);+ for i in 0..total_values {+ validity.append(i % 10 != 0);+ }+ let null_buffer = NullBuffer::from(validity.finish());++ let values = Arc::new(Int32Array::new(values.into(), Some(null_buffer)));+ let offsets: Vec<i32> = (0..=num_rows)+ .map(|i| (i * elements_per_row) as i32)+ .collect();++ Arc::new(ListArray::new(+ Arc::new(Field::new("item", DataType::Int32, true)),+ OffsetBuffer::new(offsets.into()),+ values,+ None,+ ))+}++fn create_string_list_array(num_rows: usize, elements_per_row: usize) -> ArrayRef {+ let mut rng = StdRng::seed_from_u64(SEED);+ let total_values = num_rows * elements_per_row;++ let mut indices: Vec<usize> = (0..total_values).collect();+ indices.shuffle(&mut rng);+ let string_values: Vec<String> =+ indices.iter().map(|i| format!("value_{i:06}")).collect();+ let values = Arc::new(StringArray::from(string_values));++ let offsets: Vec<i32> = (0..=num_rows)+ .map(|i| (i * elements_per_row) as i32)+ .collect();++ Arc::new(ListArray::new(+ Arc::new(Field::new("item", DataType::Utf8, true)),+ OffsetBuffer::new(offsets.into()),+ values,+ None,+ ))+}++fn invoke_array_sort(udf: &ArraySort, array: &ArrayRef) -> ColumnarValue {+ udf.invoke_with_args(ScalarFunctionArgs {+ args: vec![ColumnarValue::Array(Arc::clone(array))],+ arg_fields: vec![Field::new("arr", array.data_type().clone(), true).into()],+ number_rows: array.len(),+ return_field: Field::new("result", array.data_type().clone(), true).into(),+ config_options: Arc::new(ConfigOptions::default()),+ })+ .unwrap()+}++/// Vary elements_per_row over [5, 20, 100, 1000]: for small arrays, per-row+/// overhead dominates, whereas for larger arrays the sort kernel dominates.+fn bench_array_sort(c: &mut Criterion) {+ let mut group = c.benchmark_group("array_sort");+ let udf = ArraySort::new();++ // Int32 arrays+ for &elements_per_row in &[5, 20, 100, 1000] {+ let array = create_int32_list_array(NUM_ROWS, elements_per_row, false);+ group.bench_with_input(+ BenchmarkId::new("int32", elements_per_row),+ &elements_per_row,+ |b, _| {+ b.iter(|| {+ black_box(invoke_array_sort(&udf, &array));+ });+ },+ );+ }++ // Int32 with nulls in the outer list (10% null rows), single size+ {+ let array = create_int32_list_array(NUM_ROWS, 50, true);+ group.bench_function("int32_with_nulls", |b| {+ b.iter(|| {+ black_box(invoke_array_sort(&udf, &array));+ });+ });+ }++ // Int32 with null elements (~10% of elements within rows are null)+ for &elements_per_row in &[5, 20, 100, 1000] {+ let array =+ create_int32_list_array_with_null_elements(NUM_ROWS, elements_per_row);+ group.bench_with_input(+ BenchmarkId::new("int32_null_elements", elements_per_row),+ &elements_per_row,+ |b, _| {+ b.iter(|| {+ black_box(invoke_array_sort(&udf, &array));+ });+ },+ );+ }++ // String arrays+ for &elements_per_row in &[5, 20, 100, 1000] {+ let array = create_string_list_array(NUM_ROWS, elements_per_row);+ group.bench_with_input(+ BenchmarkId::new("string", elements_per_row),+ &elements_per_row,+ |b, _| {+ b.iter(|| {+ black_box(invoke_array_sort(&udf, &array));+ });+ },+ );+ }++ group.finish();+}++criterion_group!(benches, bench_array_sort);+criterion_main!(benches);diff --git a/datafusion/functions-nested/src/sort.rs b/datafusion/functions-nested/src/sort.rsindex 2562931691..8678c68099 100644--- a/datafusion/functions-nested/src/sort.rs+++ b/datafusion/functions-nested/src/sort.rs@@ -18,14 +18,18 @@//! [`ScalarUDFImpl`] definitions for array_sort function.use crate::utils::make_scalar_function;-use arrow::array::{Array, ArrayRef, GenericListArray, OffsetSizeTrait, new_null_array};-use arrow::buffer::OffsetBuffer;-use arrow::compute::SortColumn;-use arrow::datatypes::{DataType, FieldRef};-use arrow::{compute, compute::SortOptions};+use arrow::array::BooleanBufferBuilder;+use arrow::array::{+ Array, ArrayRef, ArrowPrimitiveType, GenericListArray, OffsetSizeTrait,+ PrimitiveArray, UInt32Array, UInt64Array, new_empty_array, new_null_array,+};+use arrow::buffer::{NullBuffer, OffsetBuffer};+use arrow::datatypes::{ArrowNativeTypeOp, DataType, FieldRef};+use arrow::row::{RowConverter, SortField};+use arrow::{compute, compute::SortOptions, downcast_primitive_array};use datafusion_common::cast::{as_large_list_array, as_list_array, as_string_array};use datafusion_common::utils::ListCoercion;-use datafusion_common::{Result, exec_err};+use datafusion_common::{Result, exec_err, internal_datafusion_err};use datafusion_expr::{ArrayFunctionArgument, ArrayFunctionSignature, ColumnarValue, Documentation,ScalarFunctionArgs, ScalarUDFImpl, Signature, TypeSignature, Volatility,@@ -67,11 +71,11 @@ make_udf_expr_and_func!(),argument(name = "desc",- description = "Whether to sort in descending order(`ASC` or `DESC`)."+ description = "Whether to sort in ascending (`ASC`) or descending (`DESC`) order. The default is `ASC`."),argument(name = "nulls_first",- description = "Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`)."+ description = "Whether to sort nulls first (`NULLS FIRST`) or last (`NULLS LAST`). The default is `NULLS FIRST`."))]#[derive(Debug, PartialEq, Eq, Hash)]@@ -161,25 +165,20 @@ fn array_sort_inner(args: &[ArrayRef]) -> Result<ArrayRef> {return Ok(new_null_array(args[0].data_type(), args[0].len()));}- let sort_options = match args.len() {- 1 => None,- 2 => {- let sort = as_string_array(&args[1])?.value(0);- Some(SortOptions {- descending: order_desc(sort)?,- nulls_first: true,- })- }- 3 => {- let sort = as_string_array(&args[1])?.value(0);- let nulls_first = as_string_array(&args[2])?.value(0);- Some(SortOptions {- descending: order_desc(sort)?,- nulls_first: order_nulls_first(nulls_first)?,- })- }- // We guard at the top- _ => unreachable!(),+ let sort_options = if args.len() >= 2 {+ let order = as_string_array(&args[1])?.value(0);+ let descending = order_desc(order)?;+ let nulls_first = if args.len() >= 3 {+ order_nulls_first(as_string_array(&args[2])?.value(0))?+ } else {+ true+ };+ Some(SortOptions {+ descending,+ nulls_first,+ })+ } else {+ None};match args[0].data_type() {@@ -206,54 +205,283 @@ fn array_sort_generic<OffsetSize: OffsetSizeTrait>(field: FieldRef,sort_options: Option<SortOptions>,) -> Result<ArrayRef> {+ let values = list_array.values();++ if values.data_type().is_primitive() {+ array_sort_primitive(list_array, field, sort_options)+ } else {+ array_sort_non_primitive(list_array, field, sort_options)+ }+}++/// Sort each row of a primitive-typed ListArray using a custom in-place sort+/// kernel.+fn array_sort_primitive<OffsetSize: OffsetSizeTrait>(+ list_array: &GenericListArray<OffsetSize>,+ field: FieldRef,+ sort_options: Option<SortOptions>,+) -> Result<ArrayRef> {+ let values = list_array.values().as_ref();+ downcast_primitive_array! {+ values => sort_primitive_list(values, list_array, field, sort_options),+ _ => exec_err!("array_sort: unsupported primitive type")+ }+}++fn sort_primitive_list<T: ArrowPrimitiveType, OffsetSize: OffsetSizeTrait>(+ prim_values: &PrimitiveArray<T>,+ list_array: &GenericListArray<OffsetSize>,+ field: FieldRef,+ sort_options: Option<SortOptions>,+) -> Result<ArrayRef>+where+ T::Native: ArrowNativeTypeOp,+{+ if prim_values.null_count() > 0 {+ sort_list_with_nulls(prim_values, list_array, field, sort_options)+ } else {+ sort_list_no_nulls(prim_values, list_array, field, sort_options)+ }+}++/// Fast path for primitive values with no element-level nulls. Copies all+/// values into a single `Vec` and sorts each row's slice in-place.+fn sort_list_no_nulls<T: ArrowPrimitiveType, OffsetSize: OffsetSizeTrait>(+ prim_values: &PrimitiveArray<T>,+ list_array: &GenericListArray<OffsetSize>,+ field: FieldRef,+ sort_options: Option<SortOptions>,+) -> Result<ArrayRef>+where+ T::Native: ArrowNativeTypeOp,+{let row_count = list_array.len();+ let offsets = list_array.offsets();+ let values_start = offsets[0].as_usize();+ let values_end = offsets[row_count].as_usize();++ let descending = sort_options.is_some_and(|o| o.descending);- let mut array_lengths = vec![];- let mut arrays = vec![];- for i in 0..row_count {- if list_array.is_null(i) {- array_lengths.push(0);+ // Copy all values into a mutable buffer+ let mut values: Vec<T::Native> =+ prim_values.values()[values_start..values_end].to_vec();++ for (row_index, window) in offsets.windows(2).enumerate() {+ if list_array.is_null(row_index) {+ continue;+ }+ let start = window[0].as_usize() - values_start;+ let end = window[1].as_usize() - values_start;+ let slice = &mut values[start..end];+ if descending {+ slice.sort_unstable_by(|a, b| b.compare(*a));} else {- let arr_ref = list_array.value(i);-- // arrow sort kernel does not support Structs, so use- // lexsort_to_indices instead:- // https://github.com/apache/arrow-rs/issues/6911#issuecomment-2562928843- let sorted_array = match arr_ref.data_type() {- DataType::Struct(_) => {- let sort_columns: Vec<SortColumn> = vec![SortColumn {- values: Arc::clone(&arr_ref),- options: sort_options,- }];- let indices = compute::lexsort_to_indices(&sort_columns, None)?;- compute::take(arr_ref.as_ref(), &indices, None)?- }- _ => {- let arr_ref = arr_ref.as_ref();- compute::sort(arr_ref, sort_options)?- }- };- array_lengths.push(sorted_array.len());- arrays.push(sorted_array);+ slice.sort_unstable_by(|a, b| a.compare(*b));}}- let elements = arrays- .iter()- .map(|a| a.as_ref())- .collect::<Vec<&dyn Array>>();+ let new_offsets = rebase_offsets(offsets);+ let sorted_values = Arc::new(+ PrimitiveArray::<T>::new(values.into(), None)+ .with_data_type(prim_values.data_type().clone()),+ );- let list_arr = if elements.is_empty() {- GenericListArray::<OffsetSize>::new_null(field, row_count)- } else {- GenericListArray::<OffsetSize>::new(- field,- OffsetBuffer::from_lengths(array_lengths),- Arc::new(compute::concat(elements.as_slice())?),- list_array.nulls().cloned(),+ Ok(Arc::new(GenericListArray::<OffsetSize>::try_new(+ field,+ new_offsets,+ sorted_values,+ list_array.nulls().cloned(),+ )?))+}++/// Slow path for primitive values with element-level nulls.+fn sort_list_with_nulls<T: ArrowPrimitiveType, OffsetSize: OffsetSizeTrait>(+ prim_values: &PrimitiveArray<T>,+ list_array: &GenericListArray<OffsetSize>,+ field: FieldRef,+ sort_options: Option<SortOptions>,+) -> Result<ArrayRef>+where+ T::Native: ArrowNativeTypeOp,+{+ let row_count = list_array.len();+ let offsets = list_array.offsets();+ let values_start = offsets[0].as_usize();+ let values_end = offsets[row_count].as_usize();+ let total_values = values_end - values_start;++ let descending = sort_options.is_some_and(|o| o.descending);+ let nulls_first = sort_options.is_none_or(|o| o.nulls_first);++ let mut out_values: Vec<T::Native> = vec![T::Native::default(); total_values];+ let mut validity = BooleanBufferBuilder::new(total_values);++ let src_nulls = prim_values.nulls().ok_or_else(|| {+ internal_datafusion_err!(+ "sort_list_with_nulls called but values have no null buffer")+ })?;+ let src_values = prim_values.values();++ for (row_index, window) in offsets.windows(2).enumerate() {+ let start = window[0].as_usize();+ let end = window[1].as_usize();+ let row_len = end - start;+ let out_start = start - values_start;++ if list_array.is_null(row_index) || row_len == 0 {+ validity.append_n(row_len, false);+ continue;+ }++ let null_count = src_nulls.slice(start, row_len).null_count();+ let valid_count = row_len - null_count;++ // Compact valid values directly into the target region of the output+ // buffer: after nulls (if nulls_first) or at the start (if nulls_last).+ let valid_offset = if nulls_first { null_count } else { 0 };+ let mut write_pos = out_start + valid_offset;+ for i in start..end {+ if src_nulls.is_valid(i) {+ out_values[write_pos] = src_values[i];+ write_pos += 1;+ }+ }++ let valid_slice = &mut out_values+ [out_start + valid_offset..out_start + valid_offset + valid_count];+ if descending {+ valid_slice.sort_unstable_by(|a, b| b.compare(*a));+ } else {+ valid_slice.sort_unstable_by(|a, b| a.compare(*b));+ }++ // Build validity bits+ if nulls_first {+ validity.append_n(null_count, false);+ validity.append_n(valid_count, true);+ } else {+ validity.append_n(valid_count, true);+ validity.append_n(null_count, false);+ }+ }++ let new_offsets = rebase_offsets(offsets);++ let null_buffer = NullBuffer::from(validity.finish());+ let sorted_values = Arc::new(+ PrimitiveArray::<T>::new(out_values.into(), Some(null_buffer))+ .with_data_type(prim_values.data_type().clone()),+ );++ Ok(Arc::new(GenericListArray::<OffsetSize>::try_new(+ field,+ new_offsets,+ sorted_values,+ list_array.nulls().cloned(),+ )?))+}++/// Sort a non-pritive-typed ListArray by converting all rows at once using+/// `RowConverter`, and then sort row indices by comparing encoded bytes (sort+/// direction and null ordering are baked into the encoding), and materialize+/// the result with a single `take()`.+fn array_sort_non_primitive<OffsetSize: OffsetSizeTrait>(+ list_array: &GenericListArray<OffsetSize>,+ field: FieldRef,+ sort_options: Option<SortOptions>,+) -> Result<ArrayRef> {+ let row_count = list_array.len();+ let values = list_array.values();+ let offsets = list_array.offsets();+ let values_start = offsets[0].as_usize();+ let total_values = offsets[row_count].as_usize() - values_start;++ let converter = RowConverter::new(vec![SortField::new_with_options(+ values.data_type().clone(),+ sort_options.unwrap_or_default(),+ )])?;+ let values_sliced = values.slice(values_start, total_values);+ let rows = converter.convert_columns(&[Arc::clone(&values_sliced)])?;++ let mut indices: Vec<OffsetSize> = Vec::with_capacity(total_values);+ let mut new_offsets = Vec::with_capacity(row_count + 1);+ new_offsets.push(OffsetSize::usize_as(0));++ let mut sort_scratch: Vec<usize> = Vec::new();++ for (row_index, window) in offsets.windows(2).enumerate() {+ let start = window[0];+ let end = window[1];++ if list_array.is_null(row_index) {+ new_offsets.push(new_offsets[row_index]);+ continue;+ }++ let len = (end - start).as_usize();+ let local_start = start.as_usize() - values_start;++ if len <= 1 {+ indices.extend((local_start..local_start + len).map(OffsetSize::usize_as));+ } else {+ sort_scratch.clear();+ sort_scratch.extend(local_start..local_start + len);+ sort_scratch.sort_unstable_by(|&a, &b| rows.row(a).cmp(&rows.row(b)));+ indices.extend(sort_scratch.iter().map(|&i| OffsetSize::usize_as(i)));+ }++ new_offsets.push(new_offsets[row_index] + (end - start));+ }++ let sorted_values = if indices.is_empty() {+ new_empty_array(values.data_type())+ } else {+ take_by_indices(&values_sliced, indices)?};- Ok(Arc::new(list_arr))++ Ok(Arc::new(GenericListArray::<OffsetSize>::try_new(+ field,+ OffsetBuffer::<OffsetSize>::new(new_offsets.into()),+ sorted_values,+ list_array.nulls().cloned(),+ )?))+}++/// Select elements from `values` at the given `indices` using `compute::take`.+/// We consume `indices` in order to avoid an intermediate copy.+fn take_by_indices<OffsetSize: OffsetSizeTrait>(+ values: &ArrayRef,+ indices: Vec<OffsetSize>,+) -> Result<ArrayRef> {+ let len = indices.len();+ let buffer = arrow::buffer::Buffer::from_vec(indices);+ let indices_array: ArrayRef = if OffsetSize::IS_LARGE {+ Arc::new(UInt64Array::new(+ arrow::buffer::ScalarBuffer::new(buffer, 0, len),+ None,+ ))+ } else {+ Arc::new(UInt32Array::new(+ arrow::buffer::ScalarBuffer::new(buffer, 0, len),+ None,+ ))+ };+ Ok(compute::take(values.as_ref(), &indices_array, None)?)+}++/// Rebase offsets so they start at 0. For non-sliced ListArrays (the common+/// case) offsets already start at 0 and we can clone the Arc-backed buffer+/// cheaply instead of allocating a new Vec.+fn rebase_offsets<OffsetSize: OffsetSizeTrait>(+ offsets: &OffsetBuffer<OffsetSize>,+) -> OffsetBuffer<OffsetSize> {+ if offsets[0].as_usize() == 0 {+ offsets.clone()+ } else {+ let rebased: Vec<OffsetSize> = offsets.iter().map(|o| *o - offsets[0]).collect();+ OffsetBuffer::new(rebased.into())+ }}fn order_desc(modifier: &str) -> Result<bool> {diff --git a/datafusion/sqllogictest/test_files/array.slt b/datafusion/sqllogictest/test_files/array.sltindex 91efdd63a7..6e0d7a882e 100644--- a/datafusion/sqllogictest/test_files/array.slt+++ b/datafusion/sqllogictest/test_files/array.slt@@ -2535,6 +2535,14 @@ select array_sort([]);----[]+# empty-but-non-null string arrays should remain non-null, not become null+query ?B+select array_sort(column1), array_sort(column1) is null+from (values (arrow_cast(make_array('b', 'a'), 'List(Utf8)')), (arrow_cast([], 'List(Utf8)'))) as t(column1);+----+[a, b] false+[] false+# test with null argumentsquery ?select array_sort(NULL);@@ -2602,6 +2610,14 @@ from values (array_sort(arrow_cast([1, 3, 5, -5], 'FixedSizeList(4 x non-null In----[-5, 1, 3, 5] List(non-null Int32)+# arrays of strings+query ???+select array_sort(make_array('banana', 'apple', null, 'cherry')),+ array_sort(make_array('banana', 'apple', null, 'cherry'), 'DESC', 'NULLS LAST'),+ array_sort(make_array('banana', 'apple', null, 'cherry'), 'ASC', 'NULLS LAST');+----+[NULL, apple, banana, cherry] [cherry, banana, apple, NULL] [apple, banana, cherry, NULL]+query ?select array_sort([struct('foo', 3), struct('foo', 1), struct('bar', 1)])----@@ -2625,6 +2641,76 @@ select array_sort([sum(a)]) from t1 where a > 100 group by b;statement okdrop table t1;+# float arrays with NaN and Infinity (NaN sorts after Infinity per IEEE totalOrder)+query ???+select array_sort(make_array(1.0, 'NaN'::double, -1.0, 'Infinity'::double, '-Infinity'::double, null)),+ array_sort(make_array(1.0, 'NaN'::double, -1.0, 'Infinity'::double, '-Infinity'::double, null), 'DESC', 'NULLS LAST'),+ array_sort(make_array('NaN'::double, 'NaN'::double, 1.0));+----+[NULL, -inf, -1.0, 1.0, inf, NaN] [NaN, inf, 1.0, -1.0, -inf, NULL] [1.0, NaN, NaN]++# float32 arrays+query ??+select array_sort(arrow_cast(make_array(3.0, 1.0, 'NaN'::double, null, 2.0), 'List(Float32)')),+ array_sort(arrow_cast(make_array(3.0, 1.0, 'NaN'::double, null, 2.0), 'List(Float32)'), 'DESC', 'NULLS LAST');+----+[NULL, 1.0, 2.0, 3.0, NaN] [NaN, 3.0, 2.0, 1.0, NULL]++# element-level nulls with all sort option combinations+query ????+select array_sort(make_array(3, null, 1, null, 2), 'ASC', 'NULLS FIRST'),+ array_sort(make_array(3, null, 1, null, 2), 'ASC', 'NULLS LAST'),+ array_sort(make_array(3, null, 1, null, 2), 'DESC', 'NULLS FIRST'),+ array_sort(make_array(3, null, 1, null, 2), 'DESC', 'NULLS LAST');+----+[NULL, NULL, 1, 2, 3] [1, 2, 3, NULL, NULL] [NULL, NULL, 3, 2, 1] [3, 2, 1, NULL, NULL]++# timestamp arrays+query ??+select array_sort(make_array(arrow_cast('2024-01-15T10:00:00', 'Timestamp(Nanosecond, None)'),+ arrow_cast('2024-01-01T00:00:00', 'Timestamp(Nanosecond, None)'),+ null,+ arrow_cast('2024-06-15T12:00:00', 'Timestamp(Nanosecond, None)'))),+ array_sort(make_array(arrow_cast('2024-01-15T10:00:00', 'Timestamp(Nanosecond, None)'),+ arrow_cast('2024-01-01T00:00:00', 'Timestamp(Nanosecond, None)'),+ null,+ arrow_cast('2024-06-15T12:00:00', 'Timestamp(Nanosecond, None)')), 'DESC', 'NULLS LAST');+----+[NULL, 2024-01-01T00:00:00, 2024-01-15T10:00:00, 2024-06-15T12:00:00] [2024-06-15T12:00:00, 2024-01-15T10:00:00, 2024-01-01T00:00:00, NULL]++# date arrays+query ??+select array_sort(make_array('2024-03-01'::date, '2024-01-01'::date, null, '2024-02-01'::date)),+ array_sort(make_array('2024-03-01'::date, '2024-01-01'::date, null, '2024-02-01'::date), 'DESC', 'NULLS LAST');+----+[NULL, 2024-01-01, 2024-02-01, 2024-03-01] [2024-03-01, 2024-02-01, 2024-01-01, NULL]++# struct arrays with nulls and DESC+query ??+select array_sort([struct('b', 2), struct('a', 1), null, struct('a', 3)]),+ array_sort([struct('b', 2), struct('a', 1), null, struct('a', 3)], 'DESC', 'NULLS LAST');+----+[NULL, {c0: a, c1: 1}, {c0: a, c1: 3}, {c0: b, c1: 2}] [{c0: b, c1: 2}, {c0: a, c1: 3}, {c0: a, c1: 1}, NULL]++# boolean arrays+query ??+select array_sort(make_array(true, false, null, true, false)),+ array_sort(make_array(true, false, null, true, false), 'DESC', 'NULLS LAST');+----+[NULL, false, false, true, true] [true, true, false, false, NULL]++# all-null array+query ?+select array_sort(make_array(null, null, null));+----+[NULL, NULL, NULL]++# single-element arrays+query ??+select array_sort(make_array(42)), array_sort(make_array(null::int));+----+[42] [NULL]+## list_sort (aliases: `array_sort`)query ???select list_sort(make_array(1, 3, null, 5, NULL, -5)), list_sort(make_array(1, 3, null, 2), 'ASC'), list_sort(make_array(1, 3, null, 2), 'desc', 'NULLS FIRST');diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.mdindex ae5dbd5bee..d347e36d27 100644--- a/docs/source/user-guide/sql/scalar_functions.md+++ b/docs/source/user-guide/sql/scalar_functions.md@@ -4182,8 +4182,8 @@ array_sort(array, desc, nulls_first)#### Arguments- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators.-- **desc**: Whether to sort in descending order(`ASC` or `DESC`).-- **nulls_first**: Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`).+- **desc**: Whether to sort in ascending (`ASC`) or descending (`DESC`) order. The default is `ASC`.+- **nulls_first**: Whether to sort nulls first (`NULLS FIRST`) or last (`NULLS LAST`). The default is `NULLS FIRST`.#### Example