[DOC-13215] Add COMPRESS() and UNCOMPRESS() Functions

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 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. 
+
+=== Arguments
+input_string:: A string or a valid expression that evaluates to a 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,105 @@ SELECT URLENCODE("SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;") AS
 ]
 ----
 ====
+
+[[fn-str-uncompress,UNCOMPRESS()]]
+== UNCOMPRESS(`input_string`)
+
+=== Description
+
+This function takes a `base64` encoded, compressed string as input and returns the original uncompressed string. 
+
+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
+
+input_string:: A `base64` encoded string that represents the compressed data. 
+It supports the following formats: 
+
+* `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 that represents the decoded and uncompressed data.
+
+=== Examples
+
+.Example 1: Uncompressing a `base64` encoded string
+====
+.Query
+[source,sqlpp]
+----
+SELECT UNCOMPRESS("eJwKycgsVsgsVijJSFVIzs8tKEotLk5NUSguKcrMSwcEAAD//5/2CwI=");
+----
+
+.Result
+[source,json]
+----
+[
+  {
+    "$1": "This is the compressed string"
+  }
+]
+----
+====
+
+.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 3: 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\" } 
+        ] 
+      }"
+}
+----
+====