diff --git a/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc b/modules/n1ql/pages/n1ql-language-reference/stringfun.adoc index 5903b3a02..d0df982c7 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 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\" } + ] + }" +} +---- +==== \ No newline at end of file