From 69db6f19126a53d7f611817dafb33e6a5e4f8a44 Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 17:49:40 +0000
Subject: [PATCH 1/6] Docs: Cleanup arithmetic function docs

---
 .../functions/arithmetic-functions.md         | 274 +++++++++++-------
 .../functions/type-conversion-functions.md    |   4 +-
 2 files changed, 177 insertions(+), 101 deletions(-)

diff --git a/docs/en/sql-reference/functions/arithmetic-functions.md b/docs/en/sql-reference/functions/arithmetic-functions.md
index 4cfd10f40c0..164f5693e1c 100644
--- a/docs/en/sql-reference/functions/arithmetic-functions.md
+++ b/docs/en/sql-reference/functions/arithmetic-functions.md
@@ -6,7 +6,9 @@ sidebar_label: Arithmetic
 
 # Arithmetic Functions
 
-For all arithmetic functions, the result type is calculated as the smallest number type that the result fits in, if there is such a type. The minimum is taken simultaneously based on the number of bits, whether it is signed, and whether it floats. If there are not enough bits, the highest bit type is taken.
+The result type of all arithmetic functions is the smallest type which can represent all possible results. Size promotion happens for integers up to 32 bit, e.g. `UInt8 + UInt16 = UInt32`. If one of the inters has 64 or more bits, the result is of the same type as the bigger of the input integers, e.g. `UInt16 + UInt128 = UInt128`. While this introduces a risk of overflows around the value range boundary, it ensures that calculations are performed quickly using the maximum native integer width of 64 bit.
+
+The result of addition or multiplication of two integers is unsigned unless one of the integers is signed.
 
 Example:
 
@@ -20,36 +22,74 @@ SELECT toTypeName(0), toTypeName(0 + 0), toTypeName(0 + 0 + 0), toTypeName(0 + 0
 └───────────────┴────────────────────────┴─────────────────────────────────┴──────────────────────────────────────────┘
 ```
 
-Arithmetic functions work for any pair of types from UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, Float32, or Float64.
+Arithmetic functions work for any pair of `UInt8`, `UInt16`, `UInt32`, `UInt64`, `Int8`, `Int16`, `Int32`, `Int64`, `Float32`, or `Float64` values.
 
-Overflow is produced the same way as in C++.
+Overflows are produced the same way as in C++.
 
-## plus(a, b), a + b operator
+## plus
 
-Calculates the sum of the numbers.
-You can also add integer numbers with a date or date and time. In the case of a date, adding an integer means adding the corresponding number of days. For a date with time, it means adding the corresponding number of seconds.
+**Syntax**
 
-## minus(a, b), a - b operator
+```sql
+plus(a, b)
+```
 
-Calculates the difference. The result is always signed.
+Calculates the sum of `a` and `b`.
 
-You can also calculate integer numbers from a date or date with time. The idea is the same – see above for ‘plus’.
+It is possible to add an integer and a date or date with time. The former operation increments the number of days in the date, the latter operation increments the number of seconds.
 
-## multiply(a, b), a \* b operator
+Alias: `a + b` (operator)
 
-Calculates the product of the numbers.
+## minus
 
-## divide(a, b), a / b operator
+**Syntax**
 
-Calculates the quotient of the numbers. The result type is always a floating-point type.
-It is not integer division. For integer division, use the ‘intDiv’ function.
-When dividing by zero you get ‘inf’, ‘-inf’, or ‘nan’.
+```sql
+minus(a, b)
+```
+Calculates the difference of `a` and `b`. The result is always signed.
 
-## intDiv(a, b)
+Similar to `plus`, it is possible to subtract an integer from a date or date with time.
 
-Calculates the quotient of the numbers. Divides into integers, rounding down (by the absolute value).
+Alias: `a - b` (operator)
 
-Returns an integer of the type of the dividend (the first parameter).
+## multiply
+
+**Syntax**
+
+```sql
+multiply(a, b)
+```
+
+Calculates the product of `a` and `b`.
+
+Alias: `a \* b` (operator)
+
+## divide
+
+**Syntax**
+
+```sql
+divide(a, b)
+```
+
+Calculates the quotient of `a` and `b`. The result is always a floating-point value. If you need integer division, you can use the `intDiv` function.
+
+Division by 0 returns `inf`, `-inf`, or `nan`.
+
+Alias: `a / b` (operator)
+
+## intDiv
+
+**Syntax**
+
+```sql
+intDiv(a, b)
+```
+
+Performs an integer division of `a` by `b`, i.e. computes the quotient rounded down to the next smallest integer.
+
+The result has the same type as the dividend (the first parameter).
 
 An exception is thrown when dividing by zero, when the quotient does not fit in the range of the dividend, or when dividing a minimal negative number by minus one.
 
@@ -62,6 +102,7 @@ SELECT
     intDiv(toFloat64(1), 0.001) AS res,
     toTypeName(res)
 ```
+
 ```response
 ┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
 │ 1000 │ Int64                                   │
@@ -73,30 +114,64 @@ SELECT
     intDiv(1, 0.001) AS res,
     toTypeName(res)
 ```
+
 ```response
 Received exception from server (version 23.2.1):
 Code: 153. DB::Exception: Received from localhost:9000. DB::Exception: Cannot perform integer division, because it will produce infinite or too large number: While processing intDiv(1, 0.001) AS res, toTypeName(res). (ILLEGAL_DIVISION)
 ```
 
-## intDivOrZero(a, b)
+## intDivOrZero
 
-Differs from ‘intDiv’ in that it returns zero when dividing by zero or when dividing a minimal negative number by minus one.
+**Syntax**
 
-## modulo(a, b), a % b operator
+```sql
+intDivOrZero(a, b)
+```
+
+Same as `intDiv` but returns zero when dividing by zero or when dividing a minimal negative number by minus one.
+
+## modulo
+
+**Syntax**
+
+```sql
+modulo(a, b)
+```
+Calculates the remainder of the division of `a` by `b`.
 
-Calculates the remainder when dividing `a` by `b`.
 The result type is an integer if both inputs are integers. If one of the inputs is a floating-point number, the result is a floating-point number.
+
 The remainder is computed like in C++. Truncated division is used for negative numbers.
+
 An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
 
-## moduloOrZero(a, b)
+Alias: `a % b` (operator)
 
-Differs from [modulo](#modulo) in that it returns zero when the divisor is zero.
+## moduloOrZero
 
-## positiveModulo(a, b), positive_modulo(a, b), pmod(a, b)
-Calculates the remainder when dividing `a` by `b`. Similar to the function `modulo` except that `positive_modulo` always returns a non-negative number.
+**Syntax**
 
-Notice that `positive_modulo` is 4-5 times slower than `modulo`. You should not use `positive_modulo` unless you want to get a positive result and don't care about performance too much.
+```sql
+moduloOrZero(a, b)
+```
+
+Like [modulo](#modulo) but returns zero when the divisor is zero.
+
+## positiveModulo(a, b)
+
+**Syntax**
+
+```sql
+positiveModulo(a, b)
+```
+
+Like [modulo](#modulo) but always returns a non-negative number.
+
+This function is 4-5 times slower than `modulo`.
+
+Alias:
+- `positive_modulo(a, b)`
+- `pmod(a, b)`
 
 **Example**
 
@@ -108,51 +183,67 @@ SELECT positiveModulo(-1, 10)
 
 Result:
 
-```text
-
+```result
 ┌─positiveModulo(-1, 10)─┐
 │                      9 │
 └────────────────────────┘
 ```
 
-## negate(a), -a operator
-
-Calculates a number with the reverse sign. The result is always signed.
-
-## abs(a)
-
-Calculates the absolute value of the number (a). That is, if a \< 0, it returns -a. For unsigned types it does not do anything. For signed integer types, it returns an unsigned number.
-
-## gcd(a, b)
-
-Returns the greatest common divisor of the numbers.
-An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
-
-## lcm(a, b)
-
-Returns the least common multiple of the numbers.
-An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
-
-## max2
-
-Compares two values and returns the maximum. The returned value is converted to [Float64](../../sql-reference/data-types/float.md).
+## negate
 
 **Syntax**
 
 ```sql
-max2(value1, value2)
+negate(a)
 ```
 
-**Arguments**
+Negates `a`. The result is always signed.
 
-- `value1` — First value. [Int/UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
-- `value2` — Second value. [Int/UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
+Alias: `-a`
 
-**Returned value**
+## abs
 
-- The maximum of two values.
+**Syntax**
 
-Type: [Float](../../sql-reference/data-types/float.md).
+```sql
+abs(a)
+```
+
+Calculates the absolute value of `a`. Has no effect if `a` is of an unsigned type. If `a` is of a signed type, it returns an unsigned number.
+
+## gcd
+
+**Syntax**
+
+```sql
+gcd(a, b)
+```
+
+Returns the greatest common divisor of `a` and `b`.
+
+An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
+
+## lcm(a, b)
+
+Returns the least common multiple of `a` and `b`.
+
+An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
+
+**Syntax**
+
+```sql
+lcm(a, b)
+```
+
+## max2
+
+**Syntax**
+
+```sql
+max2(a, b)
+```
+
+Returns the bigger of `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
 
 **Example**
 
@@ -164,7 +255,7 @@ SELECT max2(-1, 2);
 
 Result:
 
-```text
+```result
 ┌─max2(-1, 2)─┐
 │           2 │
 └─────────────┘
@@ -172,24 +263,13 @@ Result:
 
 ## min2
 
-Compares two values and returns the minimum. The returned value is converted to [Float64](../../sql-reference/data-types/float.md).
-
 **Syntax**
 
 ```sql
-min2(value1, value2)
+min2(a, b)
 ```
 
-**Arguments**
-
-- `value1` — First value. [Int/UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
-- `value2` — Second value. [Int/UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
-
-**Returned value**
-
-- The minimum of two values.
-
-Type: [Float](../../sql-reference/data-types/float.md).
+Returns the smaller of `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
 
 **Example**
 
@@ -201,21 +281,13 @@ SELECT min2(-1, 2);
 
 Result:
 
-```text
+```result
 ┌─min2(-1, 2)─┐
 │          -1 │
 └─────────────┘
 ```
 
-## multiplyDecimal(a, b[, result_scale])
-
-Performs multiplication on two decimals. Result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
-Result scale can be explicitly specified by `result_scale` argument (const Integer in range `[0, 76]`). If not specified, the result scale is the max scale of given arguments.
-
-:::note    
-These functions work significantly slower than usual `multiply`.
-In case you don't really need controlled precision and/or need fast computation, consider using [multiply](#multiply)
-:::
+## multiplyDecimal
 
 **Syntax**
 
@@ -223,6 +295,12 @@ In case you don't really need controlled precision and/or need fast computation,
 multiplyDecimal(a, b[, result_scale])
 ```
 
+Multiplies decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+
+The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
+
+This function work significantly slower than usual `multiply`. In case no control over the result precision is needed and/or fast computation is desired, consider using `multiply`.
+
 **Arguments**
 
 - `a` — First value: [Decimal](../../sql-reference/data-types/decimal.md).
@@ -237,19 +315,20 @@ Type: [Decimal256](../../sql-reference/data-types/decimal.md).
 
 **Example**
 
-```text
+```result
 ┌─multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)─┐
 │                                                           25.2 │
 └────────────────────────────────────────────────────────────────┘
 ```
 
-**Difference from regular multiplication:**
+**Differences compared to regular multiplication:**
+
 ```sql
 SELECT toDecimal64(-12.647, 3) * toDecimal32(2.1239, 4);
 SELECT toDecimal64(-12.647, 3) as a, toDecimal32(2.1239, 4) as b, multiplyDecimal(a, b);
 ```
 
-```text
+```result
 ┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
 │                                               -26.8609633 │
 └───────────────────────────────────────────────────────────┘
@@ -270,7 +349,7 @@ SELECT
     a * b;
 ```
 
-```text
+```result
 ┌─────────────a─┬─────────────b─┬─multiplyDecimal(toDecimal64(-12.647987876, 9), toDecimal64(123.967645643, 9))─┐
 │ -12.647987876 │ 123.967645643 │                                                               -1567.941279108 │
 └───────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────┘
@@ -279,15 +358,7 @@ Received exception from server (version 22.11.1):
 Code: 407. DB::Exception: Received from localhost:9000. DB::Exception: Decimal math overflow: While processing toDecimal64(-12.647987876, 9) AS a, toDecimal64(123.967645643, 9) AS b, a * b. (DECIMAL_OVERFLOW)
 ```
 
-## divideDecimal(a, b[, result_scale])
-
-Performs division on two decimals. Result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
-Result scale can be explicitly specified by `result_scale` argument (const Integer in range `[0, 76]`). If not specified, the result scale is the max scale of given arguments.
-
-:::note    
-These function work significantly slower than usual `divide`.
-In case you don't really need controlled precision and/or need fast computation, consider using [divide](#divide).
-:::
+## divideDecimal
 
 **Syntax**
 
@@ -295,6 +366,12 @@ In case you don't really need controlled precision and/or need fast computation,
 divideDecimal(a, b[, result_scale])
 ```
 
+Divides two decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+
+The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
+
+This function work significantly slower than usual `divide`. In case no control over the result precision is needed and/or fast computation is desired, consider using `divide`.
+
 **Arguments**
 
 - `a` — First value: [Decimal](../../sql-reference/data-types/decimal.md).
@@ -309,19 +386,20 @@ Type: [Decimal256](../../sql-reference/data-types/decimal.md).
 
 **Example**
 
-```text
+```result
 ┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
 │                                                -5.7142857142 │
 └──────────────────────────────────────────────────────────────┘
 ```
 
-**Difference from regular division:**
+**Differences compared to regular division:**
+
 ```sql
 SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
 SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
 ```
 
-```text
+```result
 ┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
 │                                             -5.7 │
 └──────────────────────────────────────────────────┘
@@ -336,7 +414,7 @@ SELECT toDecimal64(-12, 0) / toDecimal32(2.1, 1);
 SELECT toDecimal64(-12, 0) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
 ```
 
-```text
+```result
 DB::Exception: Decimal result's scale is less than argument's one: While processing toDecimal64(-12, 0) / toDecimal32(2.1, 1). (ARGUMENT_OUT_OF_BOUND)
 
 ┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 5)─┐
diff --git a/docs/en/sql-reference/functions/type-conversion-functions.md b/docs/en/sql-reference/functions/type-conversion-functions.md
index ff2288abac8..c7c66cc771f 100644
--- a/docs/en/sql-reference/functions/type-conversion-functions.md
+++ b/docs/en/sql-reference/functions/type-conversion-functions.md
@@ -8,9 +8,7 @@ sidebar_label: Type Conversion
 
 ## Common Issues with Data Conversion
 
-ClickHouse generally uses the [same behavior as C++ programs](https://en.cppreference.com/w/cpp/language/implicit_conversion). In particular,
-- the result of addition or multiplication of two integers is unsigned unless one of the integers is signed,
-- the result of addition or multiplication of two integers is of the next bigger integer type such that every possible result can be represented (e.g. `UInt8 + UInt16 = UInt32`). Size promotion only happens for integers up to 32 bit. If one of the integers has 64 or more bits, the result of addition or multiplication is of the same type as the bigger of the input integers (e.g. `UInt16 + UInt128 = UInt128`) - while this introduces a risk of overflows around the value range boundary it ensures that calculations are performed quickly using the maximum native integer width of 64 bit.
+ClickHouse generally uses the [same behavior as C++ programs](https://en.cppreference.com/w/cpp/language/implicit_conversion).
 
 `to<type>` functions and [cast](#castx-t) behave differently in some cases, for example in case of [LowCardinality](../data-types/lowcardinality.md): [cast](#castx-t) removes [LowCardinality](../data-types/lowcardinality.md) trait `to<type>` functions don't. The same with [Nullable](../data-types/nullable.md), this behaviour is not compatible with SQL standard, and it can be changed using [cast_keep_nullable](../../operations/settings/settings.md/#cast_keep_nullable) setting.
 

From 9e13e5a52ade6efeee3984b60150a2781f11c952 Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 18:09:20 +0000
Subject: [PATCH 2/6] Some fixes

---
 .../functions/arithmetic-functions.md         | 123 ++++++++++--------
 1 file changed, 67 insertions(+), 56 deletions(-)

diff --git a/docs/en/sql-reference/functions/arithmetic-functions.md b/docs/en/sql-reference/functions/arithmetic-functions.md
index 164f5693e1c..790598196ce 100644
--- a/docs/en/sql-reference/functions/arithmetic-functions.md
+++ b/docs/en/sql-reference/functions/arithmetic-functions.md
@@ -28,71 +28,72 @@ Overflows are produced the same way as in C++.
 
 ## plus
 
+Calculates the sum of two values `a` and `b`.
+
 **Syntax**
 
 ```sql
 plus(a, b)
 ```
 
-Calculates the sum of `a` and `b`.
-
 It is possible to add an integer and a date or date with time. The former operation increments the number of days in the date, the latter operation increments the number of seconds.
 
 Alias: `a + b` (operator)
 
 ## minus
 
+Calculates the difference of two values `a` and `b`. The result is always signed.
+
+Similar to `plus`, it is possible to subtract an integer from a date or date with time.
+
 **Syntax**
 
 ```sql
 minus(a, b)
 ```
-Calculates the difference of `a` and `b`. The result is always signed.
-
-Similar to `plus`, it is possible to subtract an integer from a date or date with time.
 
 Alias: `a - b` (operator)
 
 ## multiply
 
+Calculates the product of two values `a` and `b`.
+
 **Syntax**
 
 ```sql
 multiply(a, b)
 ```
 
-Calculates the product of `a` and `b`.
-
 Alias: `a \* b` (operator)
 
 ## divide
 
+Calculates the quotient of two values `a` and `b`. The result is always a floating-point value. If you need integer division, you can use the `intDiv` function.
+
+Division by 0 returns `inf`, `-inf`, or `nan`.
+
 **Syntax**
 
 ```sql
 divide(a, b)
 ```
 
-Calculates the quotient of `a` and `b`. The result is always a floating-point value. If you need integer division, you can use the `intDiv` function.
-
-Division by 0 returns `inf`, `-inf`, or `nan`.
-
 Alias: `a / b` (operator)
 
 ## intDiv
 
+Performs an integer division of two values `a` by `b`, i.e. computes the quotient rounded down to the next smallest integer.
+
+The result has the same type as the dividend (the first parameter).
+
+An exception is thrown when dividing by zero, when the quotient does not fit in the range of the dividend, or when dividing a minimal negative number by minus one.
+
 **Syntax**
 
 ```sql
 intDiv(a, b)
 ```
 
-Performs an integer division of `a` by `b`, i.e. computes the quotient rounded down to the next smallest integer.
-
-The result has the same type as the dividend (the first parameter).
-
-An exception is thrown when dividing by zero, when the quotient does not fit in the range of the dividend, or when dividing a minimal negative number by minus one.
-
 **Example**
 
 Query:
@@ -122,22 +123,17 @@ Code: 153. DB::Exception: Received from localhost:9000. DB::Exception: Cannot pe
 
 ## intDivOrZero
 
+Same as `intDiv` but returns zero when dividing by zero or when dividing a minimal negative number by minus one.
+
 **Syntax**
 
 ```sql
 intDivOrZero(a, b)
 ```
 
-Same as `intDiv` but returns zero when dividing by zero or when dividing a minimal negative number by minus one.
-
 ## modulo
 
-**Syntax**
-
-```sql
-modulo(a, b)
-```
-Calculates the remainder of the division of `a` by `b`.
+Calculates the remainder of the division of two values `a` by `b`.
 
 The result type is an integer if both inputs are integers. If one of the inputs is a floating-point number, the result is a floating-point number.
 
@@ -145,30 +141,36 @@ The remainder is computed like in C++. Truncated division is used for negative n
 
 An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
 
+**Syntax**
+
+```sql
+modulo(a, b)
+```
+
 Alias: `a % b` (operator)
 
 ## moduloOrZero
 
+Like [modulo](#modulo) but returns zero when the divisor is zero.
+
 **Syntax**
 
 ```sql
 moduloOrZero(a, b)
 ```
 
-Like [modulo](#modulo) but returns zero when the divisor is zero.
-
 ## positiveModulo(a, b)
 
+Like [modulo](#modulo) but always returns a non-negative number.
+
+This function is 4-5 times slower than `modulo`.
+
 **Syntax**
 
 ```sql
 positiveModulo(a, b)
 ```
 
-Like [modulo](#modulo) but always returns a non-negative number.
-
-This function is 4-5 times slower than `modulo`.
-
 Alias:
 - `positive_modulo(a, b)`
 - `pmod(a, b)`
@@ -191,41 +193,41 @@ Result:
 
 ## negate
 
+Negates a value `a`. The result is always signed.
+
 **Syntax**
 
 ```sql
 negate(a)
 ```
 
-Negates `a`. The result is always signed.
-
 Alias: `-a`
 
 ## abs
 
+Calculates the absolute value of `a`. Has no effect if `a` is of an unsigned type. If `a` is of a signed type, it returns an unsigned number.
+
 **Syntax**
 
 ```sql
 abs(a)
 ```
 
-Calculates the absolute value of `a`. Has no effect if `a` is of an unsigned type. If `a` is of a signed type, it returns an unsigned number.
-
 ## gcd
 
+Returns the greatest common divisor of two values `a` and `b`.
+
+An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
+
 **Syntax**
 
 ```sql
 gcd(a, b)
 ```
 
-Returns the greatest common divisor of `a` and `b`.
-
-An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
-
 ## lcm(a, b)
 
-Returns the least common multiple of `a` and `b`.
+Returns the least common multiple of two values `a` and `b`.
 
 An exception is thrown when dividing by zero or when dividing a minimal negative number by minus one.
 
@@ -237,14 +239,14 @@ lcm(a, b)
 
 ## max2
 
+Returns the bigger of two values `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
+
 **Syntax**
 
 ```sql
 max2(a, b)
 ```
 
-Returns the bigger of `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
-
 **Example**
 
 Query:
@@ -263,14 +265,14 @@ Result:
 
 ## min2
 
+Returns the smaller of two values `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
+
 **Syntax**
 
 ```sql
 min2(a, b)
 ```
 
-Returns the smaller of `a` and `b`. The returned value is of type [Float64](../../sql-reference/data-types/float.md).
-
 **Example**
 
 Query:
@@ -289,18 +291,18 @@ Result:
 
 ## multiplyDecimal
 
+Multiplies decimals two values `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+
+The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
+
+This function work significantly slower than usual `multiply`. In case no control over the result precision is needed and/or fast computation is desired, consider using `multiply`.
+
 **Syntax**
 
 ```sql
 multiplyDecimal(a, b[, result_scale])
 ```
 
-Multiplies decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
-
-The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
-
-This function work significantly slower than usual `multiply`. In case no control over the result precision is needed and/or fast computation is desired, consider using `multiply`.
-
 **Arguments**
 
 - `a` — First value: [Decimal](../../sql-reference/data-types/decimal.md).
@@ -328,6 +330,8 @@ SELECT toDecimal64(-12.647, 3) * toDecimal32(2.1239, 4);
 SELECT toDecimal64(-12.647, 3) as a, toDecimal32(2.1239, 4) as b, multiplyDecimal(a, b);
 ```
 
+Result:
+
 ```result
 ┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
 │                                               -26.8609633 │
@@ -349,6 +353,8 @@ SELECT
     a * b;
 ```
 
+Result:
+
 ```result
 ┌─────────────a─┬─────────────b─┬─multiplyDecimal(toDecimal64(-12.647987876, 9), toDecimal64(123.967645643, 9))─┐
 │ -12.647987876 │ 123.967645643 │                                                               -1567.941279108 │
@@ -360,18 +366,19 @@ Code: 407. DB::Exception: Received from localhost:9000. DB::Exception: Decimal m
 
 ## divideDecimal
 
+
+Divides two decimals two values `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+
+The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
+
+This function work significantly slower than usual `divide`. In case no control over the result precision is needed and/or fast computation is desired, consider using `divide`.
+
 **Syntax**
 
 ```sql
 divideDecimal(a, b[, result_scale])
 ```
 
-Divides two decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
-
-The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
-
-This function work significantly slower than usual `divide`. In case no control over the result precision is needed and/or fast computation is desired, consider using `divide`.
-
 **Arguments**
 
 - `a` — First value: [Decimal](../../sql-reference/data-types/decimal.md).
@@ -399,6 +406,8 @@ SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
 SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
 ```
 
+Result:
+
 ```result
 ┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
 │                                             -5.7 │
@@ -414,6 +423,8 @@ SELECT toDecimal64(-12, 0) / toDecimal32(2.1, 1);
 SELECT toDecimal64(-12, 0) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
 ```
 
+Result:
+
 ```result
 DB::Exception: Decimal result's scale is less than argument's one: While processing toDecimal64(-12, 0) / toDecimal32(2.1, 1). (ARGUMENT_OUT_OF_BOUND)
 

From bb0573cd56a05d1cfec561b16c7ccfb24d02bfe1 Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 18:11:50 +0000
Subject: [PATCH 3/6] More fixes

---
 docs/en/sql-reference/functions/arithmetic-functions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/en/sql-reference/functions/arithmetic-functions.md b/docs/en/sql-reference/functions/arithmetic-functions.md
index 790598196ce..64fae0e82f0 100644
--- a/docs/en/sql-reference/functions/arithmetic-functions.md
+++ b/docs/en/sql-reference/functions/arithmetic-functions.md
@@ -36,7 +36,7 @@ Calculates the sum of two values `a` and `b`.
 plus(a, b)
 ```
 
-It is possible to add an integer and a date or date with time. The former operation increments the number of days in the date, the latter operation increments the number of seconds.
+It is possible to add an integer and a date or date with time. The former operation increments the number of days in the date, the latter operation increments the number of seconds in the date with time.
 
 Alias: `a + b` (operator)
 
@@ -291,7 +291,7 @@ Result:
 
 ## multiplyDecimal
 
-Multiplies decimals two values `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+Multiplies two decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
 
 The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
 
@@ -367,7 +367,7 @@ Code: 407. DB::Exception: Received from localhost:9000. DB::Exception: Decimal m
 ## divideDecimal
 
 
-Divides two decimals two values `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+Divides two decimals `a` and `b`. The result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
 
 The scale of the result can be explicitly specified by `result_scale`. If `result_scale` is not specified, it is assumed to be the maximum scale of the input values.
 

From eca1ca31d148263060f4dd06a367cac9a6351d1b Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 18:03:01 +0000
Subject: [PATCH 4/6] Cleanup random function docs

---
 .../functions/random-functions.md             | 251 +++++++-----------
 1 file changed, 95 insertions(+), 156 deletions(-)

diff --git a/docs/en/sql-reference/functions/random-functions.md b/docs/en/sql-reference/functions/random-functions.md
index 879cf376028..e0d7b7dea5b 100644
--- a/docs/en/sql-reference/functions/random-functions.md
+++ b/docs/en/sql-reference/functions/random-functions.md
@@ -6,53 +6,39 @@ sidebar_label: Random Numbers
 
 # Functions for Generating Random Numbers
 
-All the functions accept zero arguments or one argument. If an argument is passed, it can be any type, and its value is not used for anything. The only purpose of this argument is to prevent common subexpression elimination, so that two different instances of the same function return different columns with different random numbers.
+All functions in this section accept zero or one arguments. The only use of the argument (if provided) is to prevent prevent [common subexpression
+elimination](../../sql-reference/functions/index.md#common-subexpression-elimination) such that two different execution of the same random
+function in a query return different random values.
 
-:::note    
-Non-cryptographic generators of random numbers are used.
+Related content
+- Blog: [Generating random data in ClickHouse](https://clickhouse.com/blog/generating-random-test-distribution-data-for-clickhouse)
+
+:::note
+The random numbers are generated by non-cryptographic algorithms.
 :::
 
 ## rand, rand32
 
-Returns a random UInt32 number, evenly distributed among all UInt32-type numbers.
+Returns a random UInt32 number, evenly distributed accross the range of all possible UInt32 numbers.
 
 Uses a linear congruential generator.
 
 ## rand64
 
-Returns a random UInt64 number, evenly distributed among all UInt64-type numbers.
+Returns a random UInt64 number, evenly distributed accross the range of all possible UInt64 numbers.
 
 Uses a linear congruential generator.
 
 ## randCanonical
-The function generates results with independent and identically distributed uniformly distributed values in [0, 1).
 
-Non-deterministic. Return type is Float64.
+Returns a Float64 value, evenly distributed in [0, 1).
 
 ## randConstant
 
-Produces a constant column with a random value.
-
-**Syntax**
-
-``` sql
-randConstant([x])
-```
-
-**Arguments**
-
-- `x` — [Expression](../../sql-reference/syntax.md#syntax-expressions) resulting in any of the [supported data types](../../sql-reference/data-types/index.md#data_types). The resulting value is discarded, but the expression itself if used for bypassing [common subexpression elimination](../../sql-reference/functions/index.md#common-subexpression-elimination) if the function is called multiple times in one query. Optional parameter.
-
-**Returned value**
-
-- Random number.
-
-Type: [UInt32](../../sql-reference/data-types/int-uint.md).
+Like `rand` but produces a constant column with a random value.
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT rand(), rand(1), rand(number), randConstant(), randConstant(1), randConstant(number)
 FROM numbers(3)
@@ -60,7 +46,7 @@ FROM numbers(3)
 
 Result:
 
-``` text
+``` result
 ┌─────rand()─┬────rand(1)─┬─rand(number)─┬─randConstant()─┬─randConstant(1)─┬─randConstant(number)─┐
 │ 3047369878 │ 4132449925 │   4044508545 │     2740811946 │      4229401477 │           1924032898 │
 │ 2938880146 │ 1267722397 │   4154983056 │     2740811946 │      4229401477 │           1924032898 │
@@ -68,17 +54,11 @@ Result:
 └────────────┴────────────┴──────────────┴────────────────┴─────────────────┴──────────────────────┘
 ```
 
-# Functions for Generating Random Numbers based on Distributions
-
-:::note    
-These functions are available starting from 22.10.
-:::
-
-
+# Functions for Generating Random Numbers based on a Distribution
 
 ## randUniform
 
-Return random number based on [continuous uniform distribution](https://en.wikipedia.org/wiki/Continuous_uniform_distribution) in a specified range from `min` to `max`.
+Returns a Float64 drawn uniformly from the interval between `min` and `max` ([continuous uniform distribution](https://en.wikipedia.org/wiki/Continuous_uniform_distribution)).
 
 **Syntax**
 
@@ -93,21 +73,17 @@ randUniform(min, max)
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randUniform(5.5, 10) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randUniform(5.5, 10)─┐
 │    8.094978491443102 │
 │   7.3181248914450885 │
@@ -117,40 +93,34 @@ Result:
 └──────────────────────┘
 ```
 
-
-
 ## randNormal
 
-Return random number based on [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution).
+Returns a Float64 drawn from a [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution).
 
 **Syntax**
 
 ``` sql
-randNormal(meam, variance)
+randNormal(mean, variance)
 ```
 
 **Arguments**
 
-- `meam` - `Float64` mean value of distribution,
+- `mean` - `Float64` - mean value of distribution,
 - `variance` - `Float64` - [variance](https://en.wikipedia.org/wiki/Variance).
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randNormal(10, 2) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌──randNormal(10, 2)─┐
 │ 13.389228911709653 │
 │  8.622949707401295 │
@@ -160,40 +130,34 @@ Result:
 └────────────────────┘
 ```
 
-
-
 ## randLogNormal
 
-Return random number based on [log-normal distribution](https://en.wikipedia.org/wiki/Log-normal_distribution).
+Returns a Float64 drawn from a [log-normal distribution](https://en.wikipedia.org/wiki/Log-normal_distribution).
 
 **Syntax**
 
 ``` sql
-randLogNormal(meam, variance)
+randLogNormal(mean, variance)
 ```
 
 **Arguments**
 
-- `meam` - `Float64` mean value of distribution,
+- `mean` - `Float64` - mean value of distribution,
 - `variance` - `Float64` - [variance](https://en.wikipedia.org/wiki/Variance).
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randLogNormal(100, 5) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randLogNormal(100, 5)─┐
 │  1.295699673937363e48 │
 │  9.719869109186684e39 │
@@ -203,11 +167,9 @@ Result:
 └───────────────────────┘
 ```
 
-
-
 ## randBinomial
 
-Return random number based on [binomial distribution](https://en.wikipedia.org/wiki/Binomial_distribution).
+Returns a UInt64 drawn from a [binomial distribution](https://en.wikipedia.org/wiki/Binomial_distribution).
 
 **Syntax**
 
@@ -217,26 +179,22 @@ randBinomial(experiments, probability)
 
 **Arguments**
 
-- `experiments` - `UInt64` number of experiments,
+- `experiments` - `UInt64` - number of experiments,
 - `probability` - `Float64` - probability of success in each experiment (values in `0...1` range only).
 
 **Returned value**
 
-- Random number.
-
-Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
+- Random number. Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randBinomial(100, .75) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randBinomial(100, 0.75)─┐
 │                      74 │
 │                      78 │
@@ -246,11 +204,9 @@ Result:
 └─────────────────────────┘
 ```
 
-
-
 ## randNegativeBinomial
 
-Return random number based on [negative binomial distribution](https://en.wikipedia.org/wiki/Negative_binomial_distribution).
+Returns a UInt64 drawn from a [negative binomial distribution](https://en.wikipedia.org/wiki/Negative_binomial_distribution).
 
 **Syntax**
 
@@ -260,26 +216,22 @@ randNegativeBinomial(experiments, probability)
 
 **Arguments**
 
-- `experiments` - `UInt64` number of experiments,
+- `experiments` - `UInt64` - number of experiments,
 - `probability` - `Float64` - probability of failure in each experiment (values in `0...1` range only).
 
 **Returned value**
 
-- Random number.
-
-Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
+- Random number. Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randNegativeBinomial(100, .75) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randNegativeBinomial(100, 0.75)─┐
 │                              33 │
 │                              32 │
@@ -289,11 +241,9 @@ Result:
 └─────────────────────────────────┘
 ```
 
-
-
 ## randPoisson
 
-Return random number based on [Poisson distribution](https://en.wikipedia.org/wiki/Poisson_distribution).
+Returns a UInt64 drawn from a [Poisson distribution](https://en.wikipedia.org/wiki/Poisson_distribution).
 
 **Syntax**
 
@@ -303,25 +253,21 @@ randPoisson(n)
 
 **Arguments**
 
-- `n` - `UInt64` mean number of occurrences.
+- `n` - `UInt64` - mean number of occurrences.
 
 **Returned value**
 
-- Random number.
-
-Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
+- Random number. Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randPoisson(10) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randPoisson(10)─┐
 │               8 │
 │               8 │
@@ -331,11 +277,9 @@ Result:
 └─────────────────┘
 ```
 
-
-
 ## randBernoulli
 
-Return random number based on [Bernoulli distribution](https://en.wikipedia.org/wiki/Bernoulli_distribution).
+Returns a UInt64 drawn from a [Bernoulli distribution](https://en.wikipedia.org/wiki/Bernoulli_distribution).
 
 **Syntax**
 
@@ -349,21 +293,17 @@ randBernoulli(probability)
 
 **Returned value**
 
-- Random number.
-
-Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
+- Random number. Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randBernoulli(.75) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randBernoulli(0.75)─┐
 │                   1 │
 │                   1 │
@@ -373,11 +313,9 @@ Result:
 └─────────────────────┘
 ```
 
-
-
 ## randExponential
 
-Return random number based on [exponential distribution](https://en.wikipedia.org/wiki/Exponential_distribution).
+Returns a Float64 drawn from a [exponential distribution](https://en.wikipedia.org/wiki/Exponential_distribution).
 
 **Syntax**
 
@@ -387,25 +325,21 @@ randExponential(lambda)
 
 **Arguments**
 
-- `lambda` - `Float64` lambda value.
+- `lambda` - `Float64` - lambda value.
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randExponential(1/10) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randExponential(divide(1, 10))─┐
 │              44.71628934340778 │
 │              4.211013337903262 │
@@ -415,11 +349,9 @@ Result:
 └────────────────────────────────┘
 ```
 
-
-
 ## randChiSquared
 
-Return random number based on [Chi-square distribution](https://en.wikipedia.org/wiki/Chi-squared_distribution) - a distribution of a sum of the squares of k independent standard normal random variables.
+Returns a Float64 drawn from a [Chi-square distribution](https://en.wikipedia.org/wiki/Chi-squared_distribution) - a distribution of a sum of the squares of k independent standard normal random variables.
 
 **Syntax**
 
@@ -429,25 +361,21 @@ randChiSquared(degree_of_freedom)
 
 **Arguments**
 
-- `degree_of_freedom` - `Float64` degree of freedom.
+- `degree_of_freedom` - `Float64` - degree of freedom.
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randChiSquared(10) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─randChiSquared(10)─┐
 │ 10.015463656521543 │
 │  9.621799919882768 │
@@ -457,11 +385,9 @@ Result:
 └────────────────────┘
 ```
 
-
-
 ## randStudentT
 
-Return random number based on [Student's t-distribution](https://en.wikipedia.org/wiki/Student%27s_t-distribution).
+Returns a Float64 drawn from a [Student's t-distribution](https://en.wikipedia.org/wiki/Student%27s_t-distribution).
 
 **Syntax**
 
@@ -471,25 +397,21 @@ randStudentT(degree_of_freedom)
 
 **Arguments**
 
-- `degree_of_freedom` - `Float64` degree of freedom.
+- `degree_of_freedom` - `Float64` - degree of freedom.
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randStudentT(10) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌─────randStudentT(10)─┐
 │   1.2217309938538725 │
 │   1.7941971681200541 │
@@ -499,11 +421,9 @@ Result:
 └──────────────────────┘
 ```
 
-
-
 ## randFisherF
 
-Return random number based on [F-distribution](https://en.wikipedia.org/wiki/F-distribution).
+Returns a Float64 drawn from a [F-distribution](https://en.wikipedia.org/wiki/F-distribution).
 
 **Syntax**
 
@@ -513,26 +433,22 @@ randFisherF(d1, d2)
 
 **Arguments**
 
-- `d1` - `Float64` d1 degree of freedom in `X = (S1 / d1) / (S2 / d2)`,
-- `d2` - `Float64` d2 degree of freedom in `X = (S1 / d1) / (S2 / d2)`,
+- `d1` - `Float64` - d1 degree of freedom in `X = (S1 / d1) / (S2 / d2)`,
+- `d2` - `Float64` - d2 degree of freedom in `X = (S1 / d1) / (S2 / d2)`,
 
 **Returned value**
 
-- Random number.
-
-Type: [Float64](/docs/en/sql-reference/data-types/float.md).
+- Random number. Type: [Float64](/docs/en/sql-reference/data-types/float.md).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT randFisherF(10, 3) FROM numbers(5)
 ```
 
 Result:
 
-``` text
+``` result
 ┌──randFisherF(10, 3)─┐
 │   7.286287504216609 │
 │ 0.26590779413050386 │
@@ -542,35 +458,61 @@ Result:
 └─────────────────────┘
 ```
 
-
-
-
-# Random Functions for Working with Strings
+# Functions for Generating Random Strings
 
 ## randomString
 
+Returns a random String of specified `length`. Not all characters may be printable.
+
+**Syntax**
+
+```sql
+randomString(length)
+```
+
 ## randomFixedString
 
+Like `randomString` but returns a FixedString.
+
 ## randomPrintableASCII
 
+Returns a random String of specified `length`. All characters are printable.
+
+**Syntax**
+
+```sql
+randomPrintableASCII(length)
+```
+
 ## randomStringUTF8
 
+Returns a random String containing `length` many UTF8 codepoints. Not all characters may be printable
+
+**Syntax**
+
+```sql
+randomStringUTF8(length)
+```
+
 ## fuzzBits
 
 **Syntax**
 
-``` sql
-fuzzBits([s], [prob])
-```
+Inverts the bits of String or FixedString `s`, each with probability `prob`.
 
-Inverts bits of `s`, each with probability `prob`.
+**Syntax**
+
+``` sql
+fuzzBits(s, prob)
+```
 
 **Arguments**
 - `s` - `String` or `FixedString`
 - `prob` - constant `Float32/64`
 
 **Returned value**
-Fuzzed string with same as s type.
+
+Fuzzed string with same type as `s`.
 
 **Example**
 
@@ -581,13 +523,10 @@ FROM numbers(3)
 
 Result:
 
-``` text
+``` result
 ┌─fuzzBits(materialize('abacaba'), 0.1)─┐
 │ abaaaja                               │
 │ a*cjab+                               │
 │ aeca2A                                │
 └───────────────────────────────────────┘
 ```
-
-## Related content
-- Blog: [Generating random data in ClickHouse](https://clickhouse.com/blog/generating-random-test-distribution-data-for-clickhouse)

From 74c21bbc5d451ecfdba7be1d7d3a9ce834c72def Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 18:36:10 +0000
Subject: [PATCH 5/6] UUID --> UUIDs

---
 docs/en/sql-reference/functions/uuid-functions.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/en/sql-reference/functions/uuid-functions.md b/docs/en/sql-reference/functions/uuid-functions.md
index 7322603c88c..c338add3a57 100644
--- a/docs/en/sql-reference/functions/uuid-functions.md
+++ b/docs/en/sql-reference/functions/uuid-functions.md
@@ -1,12 +1,10 @@
 ---
 slug: /en/sql-reference/functions/uuid-functions
 sidebar_position: 205
-sidebar_label: UUID
+sidebar_label: UUIDs
 ---
 
-# Functions for Working with UUID
-
-The functions for working with UUID are listed below.
+# Functions for Working with UUIDs
 
 ## generateUUIDv4
 

From 92890f4e089ac1f13be57036c9eb6155abd43a45 Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 19 Apr 2023 18:51:38 +0000
Subject: [PATCH 6/6] Cleanup logical function docs

---
 .../functions/logical-functions.md            | 52 +++++++++----------
 1 file changed, 25 insertions(+), 27 deletions(-)

diff --git a/docs/en/sql-reference/functions/logical-functions.md b/docs/en/sql-reference/functions/logical-functions.md
index 36777d4e67f..1c45994605a 100644
--- a/docs/en/sql-reference/functions/logical-functions.md
+++ b/docs/en/sql-reference/functions/logical-functions.md
@@ -6,13 +6,13 @@ sidebar_label: Logical
 
 # Logical Functions
 
-Performs logical operations on arguments of any numeric types, but returns a [UInt8](../../sql-reference/data-types/int-uint.md) number equal to 0, 1 or `NULL` in some cases.
+Below functions perform logical operations on arguments of arbitrary numeric types. They return either 0 or 1 as [UInt8](../../sql-reference/data-types/int-uint.md) or in some cases `NULL`.
 
-Zero as an argument is considered `false`, while any non-zero value is considered `true`.
+Zero as an argument is considered `false`, non-zero values are considered `true`.
 
 ## and
 
-Calculates the result of the logical conjunction between two or more values. Corresponds to [Logical AND Operator](../../sql-reference/operators/index.md#logical-and-operator).
+Calculates the logical conjunction between two or more values. 
 
 **Syntax**
 
@@ -20,7 +20,9 @@ Calculates the result of the logical conjunction between two or more values. Cor
 and(val1, val2...)
 ```
 
-You can use the [short_circuit_function_evaluation](../../operations/settings/settings.md#short-circuit-function-evaluation) setting to calculate the `and` function according to a short scheme. If this setting is enabled, `vali` is evaluated only on rows where `(val1 AND val2 AND ... AND val{i-1})` is true. For example, an exception about division by zero is not thrown when executing the query `SELECT and(number = 2, intDiv(1, number)) FROM numbers(10)`.
+Setting [short_circuit_function_evaluation](../../operations/settings/settings.md#short-circuit-function-evaluation) controls whether short-circuit evaluation is used. If enabled, `val_i` is evaluated only if `(val_1 AND val_2 AND ... AND val_{i-1})` is `true`. For example, with short-circuit evaluation, no division-by-zero exception is thrown when executing the query `SELECT and(number = 2, intDiv(1, number)) FROM numbers(5)`.
+
+Alias: The [AND Operator](../../sql-reference/operators/index.md#logical-and-operator).
 
 **Arguments**
 
@@ -28,16 +30,14 @@ You can use the [short_circuit_function_evaluation](../../operations/settings/se
 
 **Returned value**
 
-- `0`, if there is at least one zero value argument.
-- `NULL`, if there are no zero values arguments and there is at least one `NULL` argument.
+- `0`, if there at least one argument evaluates to `false`,
+- `NULL`, if no argumetn evaluates to `false` and at least one argument is `NULL`,
 - `1`, otherwise.
 
 Type: [UInt8](../../sql-reference/data-types/int-uint.md) or [Nullable](../../sql-reference/data-types/nullable.md)([UInt8](../../sql-reference/data-types/int-uint.md)).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT and(0, 1, -2);
 ```
@@ -66,7 +66,7 @@ Result:
 
 ## or
 
-Calculates the result of the logical disjunction between two or more values. Corresponds to [Logical OR Operator](../../sql-reference/operators/index.md#logical-or-operator).
+Calculates the logical disjunction between two or more values.
 
 **Syntax**
 
@@ -74,7 +74,9 @@ Calculates the result of the logical disjunction between two or more values. Cor
 or(val1, val2...)
 ```
 
-You can use the [short_circuit_function_evaluation](../../operations/settings/settings.md#short-circuit-function-evaluation) setting to calculate the `or` function according to a short scheme. If this setting is enabled, `vali` is evaluated only on rows where `((NOT val1) AND (NOT val2) AND ... AND (NOT val{i-1}))` is true. For example, an exception about division by zero is not thrown when executing the query `SELECT or(number = 0, intDiv(1, number) != 0) FROM numbers(10)`.
+Setting [short_circuit_function_evaluation](../../operations/settings/settings.md#short-circuit-function-evaluation) controls whether short-circuit evaluation is used. If enabled, `val_i` is evaluated only if `((NOT val_1) AND (NOT val_2) AND ... AND (NOT val_{i-1}))` is `true`. For example, with short-circuit evaluation, no division-by-zero exception is thrown when executing the query `SELECT or(number = 0, intDiv(1, number) != 0) FROM numbers(5)`.
+
+Alias: The [OR Operator](../../sql-reference/operators/index.md#logical-or-operator).
 
 **Arguments**
 
@@ -82,16 +84,14 @@ You can use the [short_circuit_function_evaluation](../../operations/settings/se
 
 **Returned value**
 
-- `1`, if there is at least one non-zero value.
-- `0`, if there are only zero values.
-- `NULL`, if there are only zero values and `NULL`.
+- `1`, if at least one argument evalutes to `true`,
+- `0`, if all arguments evaluate to `false`,
+- `NULL`, if all arguments evaluate to `false` and at least one argument is `NULL`.
 
 Type: [UInt8](../../sql-reference/data-types/int-uint.md) or [Nullable](../../sql-reference/data-types/nullable.md)([UInt8](../../sql-reference/data-types/int-uint.md)).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT or(1, 0, 0, 2, NULL);
 ```
@@ -120,7 +120,7 @@ Result:
 
 ## not
 
-Calculates the result of the logical negation of the value. Corresponds to [Logical Negation Operator](../../sql-reference/operators/index.md#logical-negation-operator).
+Calculates logical negation of a value.
 
 **Syntax**
 
@@ -128,22 +128,22 @@ Calculates the result of the logical negation of the value. Corresponds to [Logi
 not(val);
 ```
 
+Alias: The [Negation Operator](../../sql-reference/operators/index.md#logical-negation-operator).
+
 **Arguments**
 
 - `val` — The value. [Int](../../sql-reference/data-types/int-uint.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md) or [Nullable](../../sql-reference/data-types/nullable.md).
 
 **Returned value**
 
-- `1`, if the `val` is `0`.
-- `0`, if the `val` is a non-zero value.
-- `NULL`, if the `val` is a `NULL` value.
+- `1`, if `val` evaluates to `false`,
+- `0`, if `val` evaluates to `true`,
+- `NULL`, if `val` is `NULL`.
 
 Type: [UInt8](../../sql-reference/data-types/int-uint.md) or [Nullable](../../sql-reference/data-types/nullable.md)([UInt8](../../sql-reference/data-types/int-uint.md)).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT NOT(1);
 ```
@@ -158,7 +158,7 @@ Result:
 
 ## xor
 
-Calculates the result of the logical exclusive disjunction between two or more values. For more than two values the function works as if it calculates `XOR` of the first two values and then uses the result with the next value to calculate `XOR` and so on.
+Calculates the logical exclusive disjunction between two or more values. For more than two values the function first xor-s the first two values, then xor-s the result with the third value etc.
 
 **Syntax**
 
@@ -172,16 +172,14 @@ xor(val1, val2...)
 
 **Returned value**
 
-- `1`, for two values: if one of the values is zero and other is not.
-- `0`, for two values: if both values are zero or non-zero at the same time.
-- `NULL`, if there is at least one `NULL` value.
+- `1`, for two values: if one of the values evaluates to `false` and other does not,
+- `0`, for two values: if both values evalute to `false` or to both `true`,
+- `NULL`, if at least one of the inputs is `NULL`
 
 Type: [UInt8](../../sql-reference/data-types/int-uint.md) or [Nullable](../../sql-reference/data-types/nullable.md)([UInt8](../../sql-reference/data-types/int-uint.md)).
 
 **Example**
 
-Query:
-
 ``` sql
 SELECT xor(0, 1, 1);
 ```