From 810186571f0206ed73f17125805d018077734285 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 28 Apr 2025 16:07:39 +0530 Subject: [PATCH 1/7] Add compress and uncompress functions --- .../n1ql-language-reference/stringfun.adoc | 138 ++++++++++++++++++ ...arams.adoc => .search-request-params.adoc} | 0 2 files changed, 138 insertions(+) rename modules/search/pages/{search-request-params.adoc => .search-request-params.adoc} (100%) diff --git a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc index 5903b3a02..9112d1c6a 100644 --- a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc @@ -8,6 +8,62 @@ NOTE: If any arguments to any of the following functions are [.out]`MISSING` then the result is also [.out]`MISSING` -- that is, no result is returned. Similarly, if any of the arguments passed to the functions are `NULL` or are of the wrong type, such as an integer instead of a string, then `NULL` is returned as the result. +[[fn-str-compress,COMPRESS()]] +== COMPRESS(`input_string`) + +=== Description + +This function compresses a string using `zlib` compression and encodes the compressed data into `base64` format. +It returns an encoded string that can be easily transmitted or stored. + +TIP: To convert a compressed string to the original format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-uncompress[UNCOMPRESS()] function. + +=== Arguments +input_string:: A string or a valid expression which evaluates to string. + +=== Return Value +A base64-encoded string. + +=== Examples + +.Example 1: Using a string argument +==== +.Query +[source,sqlpp] +---- +SELECT COMPRESS("This is the string to compress"); +---- + +.Result +[source,json] +---- +[ + { + "$1": "eJwKycgsVsgsVijJSFUoLinKzEtXKMlXSM7PLShKLS4GBAAA//+ouQs8" + } +] +---- +==== + +.Example 2: Using an expression that evaluates to a string as the argument +==== +.Query +[source,sqlpp] +---- +SELECT COMPRESS(REPEAT("Hell0",10)); +---- + +.Result +[source,json] +---- +[ + { + "$1": "eJzySM3JMSCJAAQAAP//tSYREw==" + } +] +---- +==== + [[fn-str-concat,CONCAT()]] == CONCAT([.var]`string1`, [.var]`string2`, …) @@ -1583,3 +1639,85 @@ SELECT URLENCODE("SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;") AS ] ---- ==== + +[[fn-str-uncompress,UNCOMPRESS()]] +== UNCOMPRESS(`compressed_string`) + +=== Description + +This function takes a `base64` encoded compressed string and returns the original uncompressed string. + +TIP: To compress and encode a string to `base64` format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-compress[COMPRESS()] function. + +=== Arguments + +compressed_string:: A string that can be one of the following: + +* `zlib` compressed string that is `base64` encoded. +* `gzip` compressed string that is `base64` encoded. +* `base64` encoded and compressed execution plan strings stored in the `pln` array of AWR documents. +//TODO: Add link to the AWR documentation. + +=== Return Value +A string. + +=== Examples + +.Example 1: Uncompressing a string +==== +.Query +[source,sqlpp] +---- +SELECT UNCOMPRESS("eJwKycgsVsgsVijJSFVIzs8tKEotLk5NUSguKcrMSwcEAAD//5/2CwI="); +---- + +.Result +[source,json] +---- +[ + { + "$1": "This is the compressed string" + } +] +---- +==== + +.Example 2: Uncompressing execution plan strings in AWR documents +==== +Consider a workload document with `pln` array as follows: + +[source,json] +---- +"pln": [ + "0NM7AjQyYjVjNDMwZjIwNTFmNmIAX2RlZmF1bHQAE3RyYXZlbC1zYW1wbGUAJTA9AA==", + "0NM7AjQyYjVjNDMwZjIwNTFmNmIAX2RlZmF1bHQAE3RyYXZlbC1zYW1wbGUAJTA9AA==" + ] +---- + +.Query +[source,sqlpp] +---- +SELECT UNCOMPRESS("0NM7AjQyYjVjNDMwZjIwNTFmNmIAX2RlZmF1bHQAE3RyYXZlbC1zYW1wbGUAJTA9AA=="); +---- +.Result +[source,json] +---- +{ + "$1": + "{ \"#operator\": \"Sequence\", + \"~children\": [ + { \"#operator\": \"PrimaryScan3\", + \"index_id\": \"42b5c430f2051f6b\", + \"keyspace\": \"_default\" + }, + { \"#operator\": \"Fetch\", + \"keyspace\": \"travel-sample\" + }, + { \"#operator\": \"InitialProject\" }, + { \"#operator\": \"Limit\" }, + { \"#operator\": \"Stream\" } + ] + }" +} +---- +==== \ No newline at end of file diff --git a/modules/search/pages/search-request-params.adoc b/modules/search/pages/.search-request-params.adoc similarity index 100% rename from modules/search/pages/search-request-params.adoc rename to modules/search/pages/.search-request-params.adoc From a1829a4b6b93113d71257d261de7d67c126cbcbc Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 28 Apr 2025 16:08:31 +0530 Subject: [PATCH 2/7] Revert a change --- .../{.search-request-params.adoc => search-request-params.adoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename modules/search/pages/{.search-request-params.adoc => search-request-params.adoc} (100%) diff --git a/modules/search/pages/.search-request-params.adoc b/modules/search/pages/search-request-params.adoc similarity index 100% rename from modules/search/pages/.search-request-params.adoc rename to modules/search/pages/search-request-params.adoc From 670586560d07b6463e65f1b879c12dfc1f53ca14 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 29 Apr 2025 11:10:55 +0530 Subject: [PATCH 3/7] temp commit for building preview --- .../{search-request-params.adoc => .search-request-params.adoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename modules/search/pages/{search-request-params.adoc => .search-request-params.adoc} (100%) diff --git a/modules/search/pages/search-request-params.adoc b/modules/search/pages/.search-request-params.adoc similarity index 100% rename from modules/search/pages/search-request-params.adoc rename to modules/search/pages/.search-request-params.adoc From 5a72a4cbb8b3646942ff60c3231c22bd5be8c32c Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 2 May 2025 10:00:57 +0530 Subject: [PATCH 4/7] More updates --- .../n1ql-language-reference/stringfun.adoc | 46 +++++++++++++------ 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc index 9112d1c6a..7222d30f6 100644 --- a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc @@ -16,13 +16,13 @@ Similarly, if any of the arguments passed to the functions are `NULL` or are of This function compresses a string using `zlib` compression and encodes the compressed data into `base64` format. It returns an encoded string that can be easily transmitted or stored. -TIP: To convert a compressed string to the original format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-uncompress[UNCOMPRESS()] function. +NOTE: To convert a compressed string back to its original format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-uncompress[UNCOMPRESS()] function. === Arguments -input_string:: A string or a valid expression which evaluates to string. +input_string:: A string or a valid expression that evaluates to a string. === Return Value -A base64-encoded string. +A `base64` encoded string. === Examples @@ -1641,29 +1641,30 @@ SELECT URLENCODE("SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;") AS ==== [[fn-str-uncompress,UNCOMPRESS()]] -== UNCOMPRESS(`compressed_string`) +== UNCOMPRESS(`input_string`) === Description -This function takes a `base64` encoded compressed string and returns the original uncompressed string. +This function takes a `base64` encoded, compressed string as input and returns the original uncompressed string. -TIP: To compress and encode a string to `base64` format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-compress[COMPRESS()] function. +NOTE: This function is often used together with the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-compress[COMPRESS()] function, which compresses and encodes strings to `base64` format. === Arguments -compressed_string:: A string that can be one of the following: +input_string:: A `base64` encoded string that represents the compressed data. +It supports the following formats: -* `zlib` compressed string that is `base64` encoded. -* `gzip` compressed string that is `base64` encoded. -* `base64` encoded and compressed execution plan strings stored in the `pln` array of AWR documents. -//TODO: Add link to the AWR documentation. +* `zlib` compressed and `base64` encoded strings. +* `gzip` compressed and `base64` encoded strings. +* Execution plan strings stored in the `pln` array of AWR documents that are compressed and `base64` encoded. +//TODO: Add link to the AWR documentation, when it is ready. === Return Value -A string. +A string that represents the decoded and uncompressed data. === Examples -.Example 1: Uncompressing a string +.Example 1: Uncompressing a `base64` encoded string ==== .Query [source,sqlpp] @@ -1682,6 +1683,25 @@ SELECT UNCOMPRESS("eJwKycgsVsgsVijJSFVIzs8tKEotLk5NUSguKcrMSwcEAAD//5/2CwI="); ---- ==== +.Example 2: Using UNCOMPRESS() and COMPRESS() together +==== +.Query +[source,sqlpp] +---- +SELECT UNCOMPRESS(COMPRESS("This is the compressed string")); +---- + +.Result +[source,json] +---- +[ + { + "$1": "This is the compressed string" + } +] +---- +==== + .Example 2: Uncompressing execution plan strings in AWR documents ==== Consider a workload document with `pln` array as follows: From e8a129becec1d15fe14b152e3675e19b6b79b6cb Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 2 May 2025 10:26:41 +0530 Subject: [PATCH 5/7] A minor edit --- modules/n1ql/pages/n1ql-language-reference/stringfun.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc index 7222d30f6..8189a3c12 100644 --- a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc @@ -14,7 +14,7 @@ Similarly, if any of the arguments passed to the functions are `NULL` or are of === Description This function compresses a string using `zlib` compression and encodes the compressed data into `base64` format. -It returns an encoded string that can be easily transmitted or stored. +It returns a compact, encoded string that can be easily transmitted or stored. NOTE: To convert a compressed string back to its original format, use the xref:n1ql:n1ql-language-reference/stringfun.adoc#fn-str-uncompress[UNCOMPRESS()] function. From 1ba33f9113d6df4cd05de7a869a3c24792ba2640 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 2 May 2025 10:28:01 +0530 Subject: [PATCH 6/7] Revert a commit --- .../{.search-request-params.adoc => search-request-params.adoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename modules/search/pages/{.search-request-params.adoc => search-request-params.adoc} (100%) diff --git a/modules/search/pages/.search-request-params.adoc b/modules/search/pages/search-request-params.adoc similarity index 100% rename from modules/search/pages/.search-request-params.adoc rename to modules/search/pages/search-request-params.adoc From 3c2f462cc33a5d9c9af786a5a16e11afb40c102a Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 5 May 2025 12:06:59 +0530 Subject: [PATCH 7/7] Fix numbering --- modules/n1ql/pages/n1ql-language-reference/stringfun.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc index 8189a3c12..d0df982c7 100644 --- a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc @@ -1702,7 +1702,7 @@ SELECT UNCOMPRESS(COMPRESS("This is the compressed string")); ---- ==== -.Example 2: Uncompressing execution plan strings in AWR documents +.Example 3: Uncompressing execution plan strings in AWR documents ==== Consider a workload document with `pln` array as follows: