From 37c4196555802d65d7e2fefc59f200642b337096 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 2 Jul 2025 18:55:29 +0530 Subject: [PATCH 1/3] Add a new object function --- .../n1ql-language-reference/objectfun.adoc | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc index df694f6d8..2a89c3e43 100644 --- a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc @@ -281,6 +281,110 @@ LIMIT 1; ---- ==== + +[[fn-obj-filter,OBJECT_FILTER()]] +== OBJECT_FILTER(`expression` [, `options`]) + +=== Description +This function extracts and returns nested fields from an input object that match a specified pattern, while retaining their original hierarchical path structure in the output. +The function is particularly useful when working with complex objects, as it allows you to filter fields based patterns using either regular expressions or exact matches. + +=== Arguments +expression:: An expression representing an object. + +options:: [Optional] A JSON object specifying options for the function. + +=== Options + +[options="header", cols="1a,3a,1a"] +|=== +| Name | Description | Schema + +| **pattern** + +| The pattern to match. +This can be a regular expression or a simple string, depending on the `regex` parameter. +| String + +| **regex** + +| If `TRUE`, the pattern is treated as a regular expression. + +If `FALSE`, the pattern is treated as a simple string. + +*Default:* `TRUE` +| Boolean + +| **arraysubscript** + +| Specifies whether array subscripts are included in field names before applying the filter. + +If `TRUE`, array subscripts are included. +If `FALSE`, array subscripts are replaced by `*`. + +*Default:* `TRUE` + +| Boolean + +| **composites** + +| Specifies whether the pattern should match field names that contain values requiring further processing, such as nested objects or arrays. + +If `TRUE`, the pattern is matched against every level of nested fields. +If `FALSE`, the pattern is matched only against the deepest level of nested fields. + +*Default:* `TRUE` +| Boolean + +| **patternspace** + +| A string literal with two possible values. + +"field":: The pattern is matched against individual field names. + +"path":: The pattern is matched against composite path names. + +*Default:* `"path"` +| String +|=== + +=== Return Value +An object containing only the fields that match the specified pattern. +Non-matching fields are excluded from the output. + +=== Examples + +[[obj-filter-ex1,OBJECT_FILTER() Example 1]] +.Example 1 +==== +.Query +[source,sqlpp] +---- +SELECT OBJECT_FILTER(t, {"pattern":"Business service"}) +FROM `travel-sample`.`inventory`.`hotel` t +WHERE type = 'hotel' +LIMIT 2; +---- +.Results +[source,json] +---- +[ + { + "$1": { + "reviews": [ + { + "ratings": { + "Business service (e.g., internet access)": 4 + } + } + ] + } + }, + { + "$1": null + } +] +---- +==== + +[[obj-filter-ex2,OBJECT_FILTER() Example 2]] + + [[fn-obj-inner-pairs,OBJECT_INNER_PAIRS()]] == OBJECT_INNER_PAIRS(`expression`) From c7af828bdba36f88706b1d09f4b4edd68af7dd0d Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 3 Jul 2025 10:10:24 +0530 Subject: [PATCH 2/3] examples + formatting fixes --- .../n1ql-language-reference/objectfun.adoc | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc index 2a89c3e43..d2e032a9e 100644 --- a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc @@ -287,7 +287,7 @@ LIMIT 1; === Description This function extracts and returns nested fields from an input object that match a specified pattern, while retaining their original hierarchical path structure in the output. -The function is particularly useful when working with complex objects, as it allows you to filter fields based patterns using either regular expressions or exact matches. +This is particularly useful when working with complex objects, as it allows you to filter fields based patterns using either regular expressions or exact matches. === Arguments expression:: An expression representing an object. @@ -317,6 +317,7 @@ If `FALSE`, the pattern is treated as a simple string. | Specifies whether array subscripts are included in field names before applying the filter. If `TRUE`, array subscripts are included. + If `FALSE`, array subscripts are replaced by `*`. *Default:* `TRUE` @@ -327,6 +328,7 @@ If `FALSE`, array subscripts are replaced by `*`. | Specifies whether the pattern should match field names that contain values requiring further processing, such as nested objects or arrays. If `TRUE`, the pattern is matched against every level of nested fields. + If `FALSE`, the pattern is matched only against the deepest level of nested fields. *Default:* `TRUE` @@ -335,9 +337,9 @@ If `FALSE`, the pattern is matched only against the deepest level of nested fiel | **patternspace** + | A string literal with two possible values. -"field":: The pattern is matched against individual field names. +`"field"`: The pattern is matched against individual field names. -"path":: The pattern is matched against composite path names. +`"path"`: The pattern is matched against composite path names. *Default:* `"path"` | String @@ -350,7 +352,7 @@ Non-matching fields are excluded from the output. === Examples [[obj-filter-ex1,OBJECT_FILTER() Example 1]] -.Example 1 +.Filtering by field name ==== .Query [source,sqlpp] @@ -383,6 +385,35 @@ LIMIT 2; ==== [[obj-filter-ex2,OBJECT_FILTER() Example 2]] +.Filtering by full path +You can use <> to generate the full path to a field, and then use that path in the `pattern` parameter. +==== +.Query +[source,sqlpp] +---- +SELECT OBJECT_FILTER(t, { "pattern": "reviews[1].ratings.Service", "regex": false }) +FROM `travel-sample`.`inventory`.`hotel` t +WHERE type = 'hotel' +LIMIT 1; +---- +.Results +[source,json] +---- +[ + { + "$1": { + "reviews": [ + { + "ratings": { + "Service": 3 + } + } + ] + } + } +] +---- +==== [[fn-obj-inner-pairs,OBJECT_INNER_PAIRS()]] From 770b86956136f8700ce4335995397c77f7cedf24 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 3 Jul 2025 10:19:07 +0530 Subject: [PATCH 3/3] Minor fix --- modules/n1ql/pages/n1ql-language-reference/objectfun.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc index d2e032a9e..abfc2e224 100644 --- a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc @@ -287,7 +287,7 @@ LIMIT 1; === Description This function extracts and returns nested fields from an input object that match a specified pattern, while retaining their original hierarchical path structure in the output. -This is particularly useful when working with complex objects, as it allows you to filter fields based patterns using either regular expressions or exact matches. +This is particularly useful when working with complex objects, as it allows you to filter fields based on patterns using either regular expressions or exact matches. === Arguments expression:: An expression representing an object.