add document

docs/en/sql-reference/functions/encryption-functions.md

@@ -294,6 +294,74 @@ Result:
 
 Notice how only a portion of the data was properly decrypted, and the rest is gibberish since either `mode`, `key`, or `iv` were different upon encryption.
 
+## tryDecrypt
+
+Similar to `decrypt`, but returns NULL if decryption fail because of using wrong key.
+
+**Examples**
+
+Let's create a table with `user_id` is unique user id, `encrypted` is an encrypted string field, `iv` is intitial vector for decrypt/encrypt. Assume that users know their id and the key to decrypt the encrypted field:
+
+```sql
+CREATE TABLE decrypt_null (
+  dt DateTime,
+  user_id UInt32,
+  encrypted String,
+  iv String
+) ENGINE = Memory;
+```
+
+Insert some data:
+
+```sql
+INSERT INTO decrypt_null VALUES
+    ('2022-08-02 00:00:00', 1, encrypt('aes-256-gcm', 'value1', 'keykeykeykeykeykeykeykeykeykey01', 'iv1'), 'iv1'),
+    ('2022-09-02 00:00:00', 2, encrypt('aes-256-gcm', 'value2', 'keykeykeykeykeykeykeykeykeykey02', 'iv2'), 'iv2'),
+    ('2022-09-02 00:00:01', 3, encrypt('aes-256-gcm', 'value3', 'keykeykeykeykeykeykeykeykeykey03', 'iv3'), 'iv3');
+```
+
+Query with `decrypt`:
+
+```sql
+SELECT
+    dt,
+    user_id,
+    decrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value
+FROM decrypt_null
+ORDER BY user_id ASC
+```
+
+Result:
+
+```
+0 rows in set. Elapsed: 0.329 sec.
+
+Received exception from server (version 22.10.1):
+Code: 454. DB::Exception: Received from localhost:24071. DB::Exception: Failed to decrypt. OpenSSL error code: 0: while executing 'FUNCTION decrypt('aes-256-gcm' :: 4, encrypted :: 2, 'keykeykeykeykeykeykeykeykeykey02' :: 5, iv :: 3) -> decrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) String : 6'. (OPENSSL_ERROR)
+
+```
+
+Query with `tryDecrypt`:
+
+```sql
+SELECT
+    dt,
+    user_id,
+    tryDecrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value
+FROM decrypt_null
+ORDER BY user_id ASC
+```
+
+Result:
+
+```
+┌──────────────────dt─┬─user_id─┬─value──┐
+│ 2022-08-02 00:00:00 │       1 │ ᴺᵁᴸᴸ   │
+│ 2022-09-02 00:00:00 │       2 │ value2 │
+│ 2022-09-02 00:00:01 │       3 │ ᴺᵁᴸᴸ   │
+└─────────────────────┴─────────┴────────┘
+```
+
 ## aes_decrypt_mysql
 
 Compatible with mysql encryption and decrypts data encrypted with [AES_ENCRYPT](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_aes-encrypt) function.