From 3b94d58c9667f5df78e00f3d4644cfbec6cf76c1 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 13 Mar 2025 09:29:32 +0530 Subject: [PATCH 1/4] add hashbytes function --- .../n1ql-language-reference/metafun.adoc | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc index d1d88c04..af2ff374 100644 --- a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc @@ -703,6 +703,73 @@ FROM system:completed_requests; ---- ==== +== HASHBYTES(`input`, [ `options` ]) + +=== Description + +This function returns a binary hash value for a given input using a specified hashing algorithm. It accepts both binary and JSON data as inputs and supports various hashing algorithms. + +=== Arguments + +input:: A binary object to hash. ++ +For non-binary data, you must provide the JSON marshalled value. + +options:: An object that includes a string that specifies the algorithm to use. ++ +Supported algorithms are: `crc32`, `md4`, `md5`, `sha224`, `sha256`, `sha384`, `sha512`, `sha512/224`, and `sha512/256`. ++ +Depending on the algorithm you choose, you can have additional fields. ++ +For example, with `crc32`, you need to add an additional `polynomial` field which can have one of the following values: +* "ieee" (the default if not specified) +* "castagnoli" +* "koopman" +* A valid 32-bit integer, provided either as JSON number (limited to decimal) or as a string that can be parsed as the numeric value (hexadecimal can be used with a "0x" prefix) + +=== Return Value + +A binary hash value. + +=== Examples +==== +Example 1: Use the `sha256` algorithm to hash. + +[source,sqlpp] +---- +SELECT HASHBYTES('Hello World', {"algorithm":"sha256"}); +---- + +.Results +[source,json] +---- +[ + { + "$1": "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e" + } +] +---- +==== + +==== +Example 2: Use the `crc32` algorithm to hash. + +[source,sqlpp] +---- +SELECT HASHBYTES("hello world", {"algorithm":"crc32", "polynomial":"koopman"}); +---- + +.Results +[source,json] +---- +[ + { + "$1": "df373d3c" + } +] +---- +==== + [[len,LEN()]] == LEN(`expression`) From 7beef420d7312563894ec68134175f0f806aaa4d Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 14 Mar 2025 10:50:40 +0530 Subject: [PATCH 2/4] add more content --- .../n1ql-language-reference/metafun.adoc | 45 ++++++++++++------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc index af2ff374..5b725b1f 100644 --- a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc @@ -703,43 +703,53 @@ FROM system:completed_requests; ---- ==== +[[hashbytes,HASHBYTES()]] + == HASHBYTES(`input`, [ `options` ]) === Description -This function returns a binary hash value for a given input using a specified hashing algorithm. It accepts both binary and JSON data as inputs and supports various hashing algorithms. +This function returns a binary hash value for a given input using a specified hashing algorithm. +By using this function, you can protect your data by masking its original form while still allowing verification or comparison. === Arguments -input:: A binary object to hash. +input:: The data to be hashed, represented as a binary object. + -For non-binary data, you must provide the JSON marshalled value. +If the data is not in the binary form, you must convert it to a JSON marshalled value (JSON string) before it can be hashed. +You can use the ENCODE_JSON() function to do this conversion. +For more information, see xref:n1ql-language-reference/jsonfun.adoc[JSON Functions]. -options:: An object that includes a string that specifies the algorithm to use. +options:: An object that specifies the hashing algorithm (string) to be used. + Supported algorithms are: `crc32`, `md4`, `md5`, `sha224`, `sha256`, `sha384`, `sha512`, `sha512/224`, and `sha512/256`. + -Depending on the algorithm you choose, you can have additional fields. -+ -For example, with `crc32`, you need to add an additional `polynomial` field which can have one of the following values: -* "ieee" (the default if not specified) -* "castagnoli" -* "koopman" -* A valid 32-bit integer, provided either as JSON number (limited to decimal) or as a string that can be parsed as the numeric value (hexadecimal can be used with a "0x" prefix) +Some of the algorithms require additional configuration fields. +For example, for `crc32`, you need to add a `polynomial` field which can have one of the following values: ++ +-- +* `ieee` (the default value) +* `castagnoli` +* `koopman` +* A valid 32-bit integer, provided either as a JSON number (decimal) or a string that can be parsed as a numeric value (supports hexadecimal with a "0x" prefix) +-- === Return Value A binary hash value. +The size or length of the value depends on the algorithm you choose. === Examples -==== -Example 1: Use the `sha256` algorithm to hash. +[[hashbytes-ex1,HASHBYTES() Example 1]] + +.Find the hash value using the `sha256` algorithm +==== +.Query [source,sqlpp] ---- SELECT HASHBYTES('Hello World', {"algorithm":"sha256"}); ---- - .Results [source,json] ---- @@ -751,14 +761,15 @@ SELECT HASHBYTES('Hello World', {"algorithm":"sha256"}); ---- ==== -==== -Example 2: Use the `crc32` algorithm to hash. +[[hashbytes-ex2,HASHBYTES() Example 2]] +.Find the hash value using the `crc32` algorithm +==== +.Query [source,sqlpp] ---- SELECT HASHBYTES("hello world", {"algorithm":"crc32", "polynomial":"koopman"}); ---- - .Results [source,json] ---- From 9f8313c89db45fe5ef2d5818955bb535ed1e0367 Mon Sep 17 00:00:00 2001 From: rakhi-prathap Date: Mon, 17 Mar 2025 16:07:21 +0530 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- .../n1ql-language-reference/metafun.adoc | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc index 5b725b1f..36eab71c 100644 --- a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc @@ -710,7 +710,7 @@ FROM system:completed_requests; === Description This function returns a binary hash value for a given input using a specified hashing algorithm. -By using this function, you can protect your data by masking its original form while still allowing verification or comparison. +By using this function, you can verify or compare data quickly, or protect your data by masking its original form while still allowing verification or comparison. === Arguments @@ -720,19 +720,37 @@ If the data is not in the binary form, you must convert it to a JSON marshalled You can use the ENCODE_JSON() function to do this conversion. For more information, see xref:n1ql-language-reference/jsonfun.adoc[JSON Functions]. -options:: An object that specifies the hashing algorithm (string) to be used. -+ +options:: [Optional] +An object that specifies the hashing algorithm and other options for the function. +If omitted, the default hashing algorithm is `sha256`. + +=== Options + +[options="header", cols="1a,3a,1a"] +|=== +| Name | Description | Schema + +| **algorithm** + +__required__ +| Specifies the hashing algorithm to be used. + Supported algorithms are: `crc32`, `md4`, `md5`, `sha224`, `sha256`, `sha384`, `sha512`, `sha512/224`, and `sha512/256`. -+ -Some of the algorithms require additional configuration fields. -For example, for `crc32`, you need to add a `polynomial` field which can have one of the following values: -+ --- +| String + +| **polynomial** + +__optional__ +| The polynomial to use. +This only applies if the algorithm is `crc32`. +This property may have one of the following values: + * `ieee` (the default value) * `castagnoli` * `koopman` * A valid 32-bit integer, provided either as a JSON number (decimal) or a string that can be parsed as a numeric value (supports hexadecimal with a "0x" prefix) --- + +*Default:* `ieee` +| String or integer +|=== === Return Value From bf829449f47dc3a10c5ef768bd4e7bbde45d7b54 Mon Sep 17 00:00:00 2001 From: rakhi-prathap Date: Mon, 17 Mar 2025 16:49:05 +0530 Subject: [PATCH 4/4] Update modules/n1ql/pages/n1ql-language-reference/metafun.adoc Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- modules/n1ql/pages/n1ql-language-reference/metafun.adoc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc index 36eab71c..12565b86 100644 --- a/modules/n1ql/pages/n1ql-language-reference/metafun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/metafun.adoc @@ -714,11 +714,8 @@ By using this function, you can verify or compare data quickly, or protect your === Arguments -input:: The data to be hashed, represented as a binary object. -+ -If the data is not in the binary form, you must convert it to a JSON marshalled value (JSON string) before it can be hashed. -You can use the ENCODE_JSON() function to do this conversion. -For more information, see xref:n1ql-language-reference/jsonfun.adoc[JSON Functions]. +input:: A binary object or any {sqlpp} data type. +The JSON marshalled value of the data is used as the input. options:: [Optional] An object that specifies the hashing algorithm and other options for the function.