Initial draft

2024-11-22 23:52:03 +00:00 · 2021-10-20 01:42:05 +03:00 · 2021-10-20 01:42:05 +03:00 · c1d24037a4
commit c1d24037a4
parent d1138a8a25
3 changed files with 886 additions and 0 deletions
--- a/docs/en/sql-reference/functions/arithmetic-functions.md
+++ b/docs/en/sql-reference/functions/arithmetic-functions.md
@ -82,3 +82,76 @@ An exception is thrown when dividing by zero or when dividing a minimal negative
 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 {#max2}
+
+Compares two values and returns the maximum. The returned value is converted to [Float64](../../sql-reference/data-types/float.md).
+
+**Syntax**
+
+```sql
+max2(value1, value2)
+```
+
+**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 maximum of 2 values.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT max2(-1, 2);
+```
+
+Result:
+
+```text
+┌─max2(-1, 2)─┐
+│           2 │
+└─────────────┘
+```
+
+# min2 {#min2}
+
+Compares two values and returns the minimum. The returned value is converted to [Float64](../../sql-reference/data-types/float.md).
+
+**Syntax**
+
+```sql
+max2(value1, value2)
+```
+
+**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 2 values.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT max2(-1, 2);
+```
+
+Result:
+
+```text
+┌─max2(-1, 2)─┐
+│           2 │
+└─────────────┘
+```
--- a/docs/en/sql-reference/functions/tuple-functions.md
+++ b/docs/en/sql-reference/functions/tuple-functions.md
@ -165,3 +165,806 @@ Result:
 │               2 │
 └─────────────────┘
 ```
+
+## tuplePlus {#tupleplus}
+
+Calculates the sum of corresponding values of two tuples of the same size.
+
+**Syntax**
+
+```sql
+tuplePlus(tuple1, tuple2)
+```
+
+Alias: `vectorSum`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple2` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Tuple with the sum.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tuplePlus((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─tuplePlus((1, 2), (2, 3))─┐
+│ (3,5)                     │
+└───────────────────────────┘
+```
+
+## tupleMinus {#tupleminus}
+
+Calculates the subtraction of corresponding values of two tuples of the same size.
+
+**Syntax**
+
+```sql
+tupleMinus(tuple1, tuple2)
+```
+
+Alias: `vectorDifference`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple2` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Tuple with the result of subtraction.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleMinus((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─tupleMinus((1, 2), (2, 3))─┐
+│ (-1,-1)                    │
+└────────────────────────────┘
+```
+
+## tupleMultiply {#tuplemultiply}
+
+Calculates the multiplication of corresponding values of two tuples of the same size.
+
+**Syntax**
+
+```sql
+tupleMultiply(tuple1, tuple2)
+```
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple2` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Tuple with the multiplication.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleMultiply((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─tupleMultiply((1, 2), (2, 3))─┐
+│ (2,6)                         │
+└───────────────────────────────┘
+```
+
+## tupleDivide {#tupledivide}
+
+Calculates the division of corresponding values of two tuples of the same size. Note that division by zero will return `inf`.
+
+**Syntax**
+
+```sql
+tupleDivide(tuple1, tuple2)
+```
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple2` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Tuple with the result of division.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleDivide((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─tupleDivide((1, 2), (2, 3))─┐
+│ (0.5,0.6666666666666666)    │
+└─────────────────────────────┘
+```
+
+## tupleNegate {#tuplenegate}
+
+Calculates the negation of the tuple values.
+
+**Syntax**
+
+```sql
+tupleNegate(tuple)
+```
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Tuple with the result of negation.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleDivide((1, 2));
+```
+
+Result:
+
+```text
+┌─tupleNegate((1, 2))─┐
+│ (-1,-2)             │
+└─────────────────────┘
+```
+
+## tupleMultiplyByNumber {#tuplemultiplybynumber}
+
+Returns a tuple with all values multiplied by a number.
+
+**Syntax**
+
+```sql
+tupleMultiplyByNumber(tuple, number)
+```
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+-   `number` — Multiplier. [Int/UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md) or [Decimal](../../sql-reference/data-types/decimal.md).
+
+**Returned value**
+
+-   Tuple with multiplied values.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleMultiplyByNumber((1, 2), -2.1);
+```
+
+Result:
+
+```text
+┌─tupleMultiplyByNumber((1, 2), -2.1)─┐
+│ (-2.1,-4.2)                         │
+└─────────────────────────────────────┘
+```
+
+## tupleDivideByNumber {#tupledividebynumber}
+
+Returns a tuple with all values divided by a number. Note that division by zero will return `inf`.
+
+**Syntax**
+
+```sql
+tupleDivideByNumber(tuple, number)
+```
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+-   `number` — Divider. [Int/UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md) or [Decimal](../../sql-reference/data-types/decimal.md).
+
+**Returned value**
+
+-   Tuple with divided values.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT tupleDivideByNumber((1, 2), 0.5);
+```
+
+Result:
+
+```text
+┌─tupleDivideByNumber((1, 2), 0.5)─┐
+│ (2,4)                            │
+└──────────────────────────────────┘
+```
+
+## dotProduct {#dotproduct}
+
+Calculates the scalar product of two tuples of the same size.
+
+**Syntax**
+
+```sql
+dotProduct(tuple1, tuple2)
+```
+
+Alias: `scalarProduct`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple2` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Scalar product.
+
+Type: [Int/UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md) or [Decimal](../../sql-reference/data-types/decimal.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT dotProduct((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─dotProduct((1, 2), (2, 3))─┐
+│                          8 │
+└────────────────────────────┘
+```
+
+## L1Norm {#l1norm}
+
+Calculates the sum of absolute values of a tuple.
+
+**Syntax**
+
+```sql
+L1Norm(tuple)
+```
+
+Alias: `normL1`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   L1 norm or [taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry) distance.
+
+Type: [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md) or [Decimal](../../sql-reference/data-types/decimal.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L1Norm((1, 2));
+```
+
+Result:
+
+```text
+┌─L1Norm((1, 2))─┐
+│              3 │
+└────────────────┘
+```
+
+## L2Norm {#l2norm}
+
+Calculates the square root of the sum of the squares of the tuple values.
+
+**Syntax**
+
+```sql
+L1Norm(tuple)
+```
+
+Alias: `normL2`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   L2 norm or [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance).
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L2Norm((1, 2));
+```
+
+Result:
+
+```text
+┌───L2Norm((1, 2))─┐
+│ 2.23606797749979 │
+└──────────────────┘
+```
+
+## LinfNorm {#linfnorm}
+
+Calculates the maximum of absolute values of a tuple.
+
+**Syntax**
+
+```sql
+LinfNorm(tuple)
+```
+
+Alias: `normLinf`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   The maximum absolute value.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LinfNorm((1, -2));
+```
+
+Result:
+
+```text
+┌─LinfNorm((1, -2))─┐
+│                 2 │
+└───────────────────┘
+```
+
+## LpNorm {#lpnorm}
+
+Calculates the root of `p`-th power of the sum of the absolute values of a tuple in the power of `p`.
+
+**Syntax**
+
+```sql
+LpNorm(tuple, p)
+```
+
+Alias: `normLp`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+-   `p` — The power. Possible values: any number from [1;inf). [UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
+
+**Returned value**
+
+-   [Lp-norm](https://en.wikipedia.org/wiki/Norm_(mathematics)#p-norm)
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LpNorm((1, -2),2);
+```
+
+Result:
+
+```text
+┌─LpNorm((1, -2), 2)─┐
+│   2.23606797749979 │
+└────────────────────┘
+```
+
+## L1Distance {#l1distance}
+
+Calculates the distance between two points (the values of the tuples are the coordinates) in 1-norm ([taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry) distance).
+
+**Syntax**
+
+```sql
+L1Distance(tuple1, tuple2)
+```
+
+Alias: `distanceL1`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple1` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   1-norm distance.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L1Distance((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─L1Distance((1, 2), (2, 3))─┐
+│                          2 │
+└────────────────────────────┘
+```
+
+## L2Distance {#l2distance}
+
+Calculates the distance between two points (the values of the tuples are the coordinates) in 2-norm ([Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance)).
+
+**Syntax**
+
+```sql
+L2Distance(tuple1, tuple2)
+```
+
+Alias: `distanceL2`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple1` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   2-norm distance.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L2Distance((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─L2Distance((1, 2), (2, 3))─┐
+│         1.4142135623730951 │
+└────────────────────────────┘
+```
+
+## LinfDistance {#linfdistance}
+
+Calculates the distance between two points (the values of the tuples are the coordinates) in [infinity-norm distance](https://en.wikipedia.org/wiki/Norm_(mathematics)#Maximum_norm_(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm)).
+
+**Syntax**
+
+```sql
+LinfDistance(tuple1, tuple2)
+```
+
+Alias: `distanceLinf`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple1` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Infinity-norm distance.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LinfDistance((1, 2), (2, 3));
+```
+
+Result:
+
+```text
+┌─LinfDistance((1, 2), (2, 3))─┐
+│                            1 │
+└──────────────────────────────┘
+```
+
+## LpDistance {#LpDistance}
+
+Calculates the distance between two points (the values of the tuples are the coordinates) in [p-norm distance](https://en.wikipedia.org/wiki/Norm_(mathematics)#p-norm).
+
+**Syntax**
+
+```sql
+LpDistance(tuple1, tuple2, p)
+```
+
+Alias: `distanceLp`.
+
+**Arguments**
+
+-   `tuple1` — First tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple1` — Second tuple. [Tuple](../../sql-reference/data-types/tuple.md).
+-   `p` — The power. Possible values: any number from [1;inf). [UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
+
+**Returned value**
+
+-   Lp-norm distance.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LpDistance((1, 2), (2, 3), 3);
+```
+
+Result:
+
+```text
+┌─LpDistance((1, 2), (2, 3), 3)─┐
+│            1.2599210498948732 │
+└───────────────────────────────┘
+```
+
+## L1Normalize {#l1normalize}
+
+Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in 1-norm ([taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry)).
+
+**Syntax**
+
+```sql
+L1Normalize(tuple)
+```
+
+Alias: `normalizeL1`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Unit vector.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md) of [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L1Normalize((1, 2));
+```
+
+Result:
+
+```text
+┌─L1Normalize((1, 2))─────────────────────┐
+│ (0.3333333333333333,0.6666666666666666) │
+└─────────────────────────────────────────┘
+```
+
+## L2Normalize {#l2normalize}
+
+Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in 2-norm ([Euclidean geometry](https://en.wikipedia.org/wiki/Euclidean_space).
+
+**Syntax**
+
+```sql
+L2Normalize(tuple)
+```
+
+Alias: `normalizeL1`.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Unit vector.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md) of [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT L2Normalize((3, 4));
+```
+
+Result:
+
+```text
+┌─L2Normalize((3, 4))─┐
+│ (0.6,0.8)           │
+└─────────────────────┘
+```
+
+## LinfNormalize {#linfnormalize}
+
+Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in [infinity-norm](https://en.wikipedia.org/wiki/Norm_(mathematics)#Maximum_norm_(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm)).
+
+**Syntax**
+
+```sql
+LinfNormalize(tuple)
+```
+
+Alias: `normalizeLinf `.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Unit vector.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md) of [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LinfNormalize((3, 4));
+```
+
+Result:
+
+```text
+┌─LinfNormalize((3, 4))─┐
+│ (0.75,1)              │
+└───────────────────────┘
+```
+
+## LpNormalize {#lpnormalize}
+
+Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in [p-norm](https://en.wikipedia.org/wiki/Norm_(mathematics)#p-norm).
+
+**Syntax**
+
+```sql
+LpNormalize(tuple, p)
+```
+
+Alias: `normalizeLp `.
+
+**Arguments**
+
+-   `tuple` — [Tuple](../../sql-reference/data-types/tuple.md).
+-   `p` — The power. Possible values: any number from [1;inf). [UInt](../../sql-reference/data-types/int-uint.md) or [Float](../../sql-reference/data-types/float.md).
+
+**Returned value**
+
+-   Unit vector.
+
+Type: [Tuple](../../sql-reference/data-types/tuple.md) of [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT LpNormalize((3, 4),5);
+```
+
+Result:
+
+```text
+┌─LpNormalize((3, 4), 5)──────────────────┐
+│ (0.7187302630182624,0.9583070173576831) │
+└─────────────────────────────────────────┘
+```
+
+cosineDistance 
+
+## cosineDistance {#cosinedistance}
+
+Calculates the cosine distance between two vectors (the values of the tuples are the coordinates). The less the returned value is, the more similar are the vectors.
+
+**Syntax**
+
+```sql
+cosineDistance(tuple1, tuple2)
+```
+
+**Arguments**
+
+-   `tuple1` — [Tuple](../../sql-reference/data-types/tuple.md).
+-   `tuple1` — [Tuple](../../sql-reference/data-types/tuple.md).
+
+**Returned value**
+
+-   Cosine of the angle between two vectors substracted from one.
+
+Type: [Float](../../sql-reference/data-types/float.md).
+
+**Example**
+
+Query:
+
+```sql
+SELECT cosineDistance((1, 2),(2,3));
+```
+
+Result:
+
+```text
+┌─cosineDistance((1, 2), (2, 3))─┐
+│           0.007722123286332261 │
+└────────────────────────────────┘
+```
--- a/docs/en/sql-reference/operators/index.md
+++ b/docs/en/sql-reference/operators/index.md
@ -17,20 +17,30 @@ ClickHouse transforms operators to their corresponding functions at the query pa

 `-a` – The `negate (a)` function.

+For tuple negation: [tupleNegate](../../sql-reference/functions/tuple-functions.md#tuplenegate).
+
 ## Multiplication and Division Operators {#multiplication-and-division-operators}

 `a * b` – The `multiply (a, b)` function.

+For multiplying tuple by number: [tupleMultiplyByNumber](../../sql-reference/functions/tuple-functions.md#tuplemultiplybynumber), for scalar profuct: [dotProduct](../../sql-reference/functions/tuple-functions.md#dotproduct).
+
 `a / b` – The `divide(a, b)` function.

+For dividing tuple by number: [tupleDivideByNumber](../../sql-reference/functions/tuple-functions.md#tupledividebynumber).
+
 `a % b` – The `modulo(a, b)` function.

 ## Addition and Subtraction Operators {#addition-and-subtraction-operators}

 `a + b` – The `plus(a, b)` function.

+For tuple addiction: [tuplePlus](../../sql-reference/functions/tuple-functions.md#tupleplus).
+
 `a - b` – The `minus(a, b)` function.

+For tuple subtraction: [tupleMinus](../../sql-reference/functions/tuple-functions.md#tupleminus).
+
 ## Comparison Operators {#comparison-operators}

 `a = b` – The `equals(a, b)` function.