From 26508e787a3d49b9311196fd47d543bd342c674b Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 23 Sep 2025 08:53:01 +0530 Subject: [PATCH 1/4] Add the array_replace_equivalent function --- .../n1ql-language-reference/arrayfun.adoc | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc index 30423e54b..1388b16ee 100644 --- a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc @@ -1310,6 +1310,77 @@ LIMIT 1; ---- ==== +[[fn-array-replace-equivalent,ARRAY_REPLACE_EQUIVALENT()]] +== ARRAY_REPLACE_EQUIVALENT([.var]`expr`, [.var]`val1`, [.var]`val2` [, [.var]`max_int` ]) + +=== Description + +This function is similar to the <> function and returns a new array with all occurrences of [.in]`value1` replaced with [.in]`value2`. +However, it determines matches using the equivalence operator instead of the equality operator. +This enables you to replace `NULL` values and composite object values with `NULL` attributes, which is not possible with <>. + +If [.var]`max_int` is specified, the function performs no more than [.var]`max_int` replacements. + +=== Arguments + +expr:: [Required] The input array you want to replace [.var]`val1` with [.var]`val2`. + +val1:: [Required] The existing value in the input [.var]`expr` you want to replace. + +val2:: [Required] The new value you want to take the place of [.var]`val1` in the input [.var]`expr`. + +max_int:: +[Optional. Default is no maximum] The number of maximum replacements to perform. + +=== Return Values +A new array with all or [.var]`max_int` occurrences of [.in]`val1` replaced with [.in]`val2`. + +If any of the arguments are `MISSING`, then it returns `MISSING`. + +If the first argument is not an array, then it returns `NULL`. + +=== Example +==== + +[source,sqlpp] +---- +SELECT +ARRAY_REPLACE([{"name":"Brian"},{"name":null}], + {"name":null}, + {"name":"Unknown User"}) + AS replace_result, +ARRAY_REPLACE_EQUIVALENT([{"name":"Brian"},{"name":null}], + {"name":null}, + {"name":"Unknown User"}) + AS replace_equiv_result; +---- + +.Results +[source,json] +---- +[ + { + "replace_result": [ + { + "name": "Brian" + }, + { + "name": null + } + ], + "replace_equiv_result": [ + { + "name": "Brian" + }, + { + "name": "Unknown User" + } + ] + } +] +---- +==== + [[fn-array-reverse,ARRAY_REVERSE()]] == ARRAY_REVERSE([.var]`expr`) From c4fe02bcf6702518d53f800699b17adce6d225b3 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 24 Sep 2025 09:33:54 +0530 Subject: [PATCH 2/4] Update content --- .../pages/n1ql-language-reference/arrayfun.adoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc index 1388b16ee..163cde8dc 100644 --- a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc @@ -1258,7 +1258,7 @@ SELECT ARRAY_REPEAT("Vallie Ryan", 3) AS repeat_val; === Description This function returns a new array with all occurrences of [.in]`value1` replaced with [.in]`value2`. -If [.var]`max_int` is specified, than no more than [.var]`max_int` replacements will be performed. +If [.var]`max_int` is specified, the function performs no more than [.var]`max_int` replacements. === Arguments expr:: [Required] The input array you want to replace [.var]`val1` with [.var]`val2`. @@ -1311,29 +1311,29 @@ LIMIT 1; ==== [[fn-array-replace-equivalent,ARRAY_REPLACE_EQUIVALENT()]] -== ARRAY_REPLACE_EQUIVALENT([.var]`expr`, [.var]`val1`, [.var]`val2` [, [.var]`max_int` ]) +== ARRAY_REPLACE_EQUIVALENT(`expr`, `val1`, `val2` [, `max_int`]) === Description -This function is similar to the <> function and returns a new array with all occurrences of [.in]`value1` replaced with [.in]`value2`. +This function is similar to the <> function and returns a new array with all occurrences of `val1` replaced with `val2`. However, it determines matches using the equivalence operator instead of the equality operator. This enables you to replace `NULL` values and composite object values with `NULL` attributes, which is not possible with <>. -If [.var]`max_int` is specified, the function performs no more than [.var]`max_int` replacements. +If `max_int` is specified, the function performs no more than `max_int` replacements. === Arguments -expr:: [Required] The input array you want to replace [.var]`val1` with [.var]`val2`. +expr:: [Required] The input array you want to replace `val1` with `val2`. -val1:: [Required] The existing value in the input [.var]`expr` you want to replace. +val1:: [Required] The existing value in the input `expr` you want to replace. -val2:: [Required] The new value you want to take the place of [.var]`val1` in the input [.var]`expr`. +val2:: [Required] The new value you want to take the place of `val1` in the input `expr`. max_int:: [Optional. Default is no maximum] The number of maximum replacements to perform. === Return Values -A new array with all or [.var]`max_int` occurrences of [.in]`val1` replaced with [.in]`val2`. +A new array with all or `max_int` occurrences of `val1` replaced with `val2`. If any of the arguments are `MISSING`, then it returns `MISSING`. @@ -1341,6 +1341,7 @@ If the first argument is not an array, then it returns `NULL`. === Example ==== +The following example shows how the ARRAY_REPLACE_EQUIVALENT function can replace `NULL` values, while the ARRAY_REPLACE function cannot. [source,sqlpp] ---- From 22f555e92545229bd2af92cd6f24659b7372723f Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 24 Sep 2025 09:49:56 +0530 Subject: [PATCH 3/4] Minor language fix --- modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc index 163cde8dc..eba7a199e 100644 --- a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc @@ -1330,7 +1330,8 @@ val1:: [Required] The existing value in the input `expr` you want to replace. val2:: [Required] The new value you want to take the place of `val1` in the input `expr`. max_int:: -[Optional. Default is no maximum] The number of maximum replacements to perform. +[Optional] The maximum number of replacements to perform. +By default, you can perform any number of replacements. === Return Values A new array with all or `max_int` occurrences of `val1` replaced with `val2`. From e1f34c5e7ba254ee1bd6c4f996eeba16b5e89f36 Mon Sep 17 00:00:00 2001 From: rakhi-prathap Date: Tue, 7 Oct 2025 10:14:47 +0530 Subject: [PATCH 4/4] Apply suggestion from code review Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc index eba7a199e..446a567b2 100644 --- a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc @@ -1253,7 +1253,7 @@ SELECT ARRAY_REPEAT("Vallie Ryan", 3) AS repeat_val; ==== [[fn-array-replace,ARRAY_REPLACE()]] -== ARRAY_REPLACE([.var]`expr`, [.var]`val1`, [.var]`val2` [, [.var]`max_int` ]) +== ARRAY_REPLACE(`expr`, `val1`, `val2` [, `max_int`]) === Description This function returns a new array with all occurrences of [.in]`value1` replaced with [.in]`value2`.