diff --git a/datafusion/functions-nested/src/remove.rs b/datafusion/functions-nested/src/remove.rs index 3d4076800e1e9..54dec8ca18f4f 100644 --- a/datafusion/functions-nested/src/remove.rs +++ b/datafusion/functions-nested/src/remove.rs @@ -40,13 +40,13 @@ make_udf_expr_and_func!( ArrayRemove, array_remove, array element, - "removes the first element from the array equal to the given value.", + "removes the first element from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", array_remove_udf ); #[user_doc( doc_section(label = "Array Functions"), - description = "Removes the first element from the array equal to the given value.", + description = "Removes the first element from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", syntax_example = "array_remove(array, element)", sql_example = r#"```sql > select array_remove([1, 2, 2, 3, 2, 1, 4], 2); @@ -55,6 +55,13 @@ make_udf_expr_and_func!( +----------------------------------------------+ | [1, 2, 3, 2, 1, 4] | +----------------------------------------------+ + +> select array_remove([1, 2, NULL, 2, 4], 2); ++---------------------------------------------------+ +| array_remove(List([1,2,NULL,2,4]),Int64(2)) | ++---------------------------------------------------+ +| [1, NULL, 2, 4] | ++---------------------------------------------------+ ```"#, argument( name = "array", @@ -130,14 +137,14 @@ make_udf_expr_and_func!( ArrayRemoveN, array_remove_n, array element max, - "removes the first `max` elements from the array equal to the given value.", + "removes the first `max` elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", array_remove_n_udf ); #[user_doc( doc_section(label = "Array Functions"), - description = "Removes the first `max` elements from the array equal to the given value.", - syntax_example = "array_remove_n(array, element, max))", + description = "Removes the first `max` elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", + syntax_example = "array_remove_n(array, element, max)", sql_example = r#"```sql > select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); +---------------------------------------------------------+ @@ -145,6 +152,13 @@ make_udf_expr_and_func!( +---------------------------------------------------------+ | [1, 3, 2, 1, 4] | +---------------------------------------------------------+ + +> select array_remove_n([1, 2, NULL, 2, 4], 2, 2); ++----------------------------------------------------------+ +| array_remove_n(List([1,2,NULL,2,4]),Int64(2),Int64(2)) | ++----------------------------------------------------------+ +| [1, NULL, 4] | ++----------------------------------------------------------+ ```"#, argument( name = "array", @@ -225,13 +239,13 @@ make_udf_expr_and_func!( ArrayRemoveAll, array_remove_all, array element, - "removes all elements from the array equal to the given value.", + "removes all elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", array_remove_all_udf ); #[user_doc( doc_section(label = "Array Functions"), - description = "Removes all elements from the array equal to the given value.", + description = "Removes all elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries.", syntax_example = "array_remove_all(array, element)", sql_example = r#"```sql > select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); @@ -240,6 +254,13 @@ make_udf_expr_and_func!( +--------------------------------------------------+ | [1, 3, 1, 4] | +--------------------------------------------------+ + +> select array_remove_all([1, 2, NULL, 2, 4], 2); ++-----------------------------------------------------+ +| array_remove_all(List([1,2,NULL,2,4]),Int64(2)) | ++-----------------------------------------------------+ +| [1, NULL, 4] | ++-----------------------------------------------------+ ```"#, argument( name = "array", diff --git a/docs/source/user-guide/expressions.md b/docs/source/user-guide/expressions.md index 56d78ac473f14..af9053c9919e9 100644 --- a/docs/source/user-guide/expressions.md +++ b/docs/source/user-guide/expressions.md @@ -230,9 +230,9 @@ select log(-1), log(0), sqrt(-1); | array_positions(array, element) | Searches for an element in the array, returns all occurrences. `array_positions([1, 2, 2, 3, 4], 2) -> [2, 3]` | | array_prepend(element, array) | Prepends an element to the beginning of an array. `array_prepend(1, [2, 3, 4]) -> [1, 2, 3, 4]` | | array_repeat(element, count) | Returns an array containing element `count` times. `array_repeat(1, 3) -> [1, 1, 1]` | -| array_remove(array, element) | Removes the first element from the array equal to the given value. `array_remove([1, 2, 2, 3, 2, 1, 4], 2) -> [1, 2, 3, 2, 1, 4]` | -| array_remove_n(array, element, max) | Removes the first `max` elements from the array equal to the given value. `array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2) -> [1, 3, 2, 1, 4]` | -| array_remove_all(array, element) | Removes all elements from the array equal to the given value. `array_remove_all([1, 2, 2, 3, 2, 1, 4], 2) -> [1, 3, 1, 4]` | +| array_remove(array, element) | Removes the first element from the array equal to the given value. `NULL` elements already in the array are preserved when removing a non-`NULL` value, and `array_remove(array, NULL)` returns `NULL`. `array_remove([1, 2, NULL, 2, 4], 2) -> [1, NULL, 2, 4]` | +| array_remove_n(array, element, max) | Removes the first `max` elements from the array equal to the given value. `NULL` elements already in the array are preserved when removing a non-`NULL` value, and `array_remove_n(array, NULL, max)` returns `NULL`. `array_remove_n([1, 2, NULL, 2, 4], 2, 2) -> [1, NULL, 4]` | +| array_remove_all(array, element) | Removes all elements from the array equal to the given value. `NULL` elements already in the array are preserved when removing a non-`NULL` value, and `array_remove_all(array, NULL)` returns `NULL`. `array_remove_all([1, 2, NULL, 2, 4], 2) -> [1, NULL, 4]` | | array_replace(array, from, to) | Replaces the first occurrence of the specified element with another specified element. `array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5) -> [1, 5, 2, 3, 2, 1, 4]` | | array_replace_n(array, from, to, max) | Replaces the first `max` occurrences of the specified element with another specified element. `array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2) -> [1, 5, 5, 3, 2, 1, 4]` | | array_replace_all(array, from, to) | Replaces all occurrences of the specified element with another specified element. `array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5) -> [1, 5, 5, 3, 5, 1, 4]` | diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index 254151c2c20eb..6b39ea263fea4 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -3880,7 +3880,7 @@ _Alias of [array_prepend](#array_prepend)._ ### `array_remove` -Removes the first element from the array equal to the given value. +Removes the first element from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries. ```sql array_remove(array, element) @@ -3900,6 +3900,13 @@ array_remove(array, element) +----------------------------------------------+ | [1, 2, 3, 2, 1, 4] | +----------------------------------------------+ + +> select array_remove([1, 2, NULL, 2, 4], 2); ++---------------------------------------------------+ +| array_remove(List([1,2,NULL,2,4]),Int64(2)) | ++---------------------------------------------------+ +| [1, NULL, 2, 4] | ++---------------------------------------------------+ ``` #### Aliases @@ -3908,7 +3915,7 @@ array_remove(array, element) ### `array_remove_all` -Removes all elements from the array equal to the given value. +Removes all elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries. ```sql array_remove_all(array, element) @@ -3928,6 +3935,13 @@ array_remove_all(array, element) +--------------------------------------------------+ | [1, 3, 1, 4] | +--------------------------------------------------+ + +> select array_remove_all([1, 2, NULL, 2, 4], 2); ++-----------------------------------------------------+ +| array_remove_all(List([1,2,NULL,2,4]),Int64(2)) | ++-----------------------------------------------------+ +| [1, NULL, 4] | ++-----------------------------------------------------+ ``` #### Aliases @@ -3936,10 +3950,10 @@ array_remove_all(array, element) ### `array_remove_n` -Removes the first `max` elements from the array equal to the given value. +Removes the first `max` elements from the array equal to the given value. NULL elements already in the array are preserved when removing a non-NULL value. If `element` evaluates to NULL, the result is NULL rather than removing NULL entries. ```sql -array_remove_n(array, element, max)) +array_remove_n(array, element, max) ``` #### Arguments @@ -3957,6 +3971,13 @@ array_remove_n(array, element, max)) +---------------------------------------------------------+ | [1, 3, 2, 1, 4] | +---------------------------------------------------------+ + +> select array_remove_n([1, 2, NULL, 2, 4], 2, 2); ++----------------------------------------------------------+ +| array_remove_n(List([1,2,NULL,2,4]),Int64(2),Int64(2)) | ++----------------------------------------------------------+ +| [1, NULL, 4] | ++----------------------------------------------------------+ ``` #### Aliases