> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по функциям расстояния

# Функции расстояния

{/*AUTOGENERATED_START*/}

<div id="L1Distance">
  ## L1Distance
</div>

Добавленный в: v21.11.0

Вычисляет расстояние между двумя точками (элементы векторов представляют собой координаты) в пространстве `L1` (1-норма — [таксомоторная геометрия](https://en.wikipedia.org/wiki/Taxicab_geometry)).

**Синтаксис**

```sql theme={null}
L1Distance(vector1, vector2)
```

**Псевдонимы**: `distanceL1`

**Аргументы**

* `vector1` — Первый вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает расстояние по 1-норме. Для входных данных типа `Array` возвращает `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, в противном случае — `Float64`. Для входных данных типа `Tuple` возвращаемый тип соответствует арифметическому типу результата поэлементных операций (целочисленные типы сохраняются). [`(U)Int*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L1Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L1Distance((1, 2), (2, 3))─┐
│                          2 │
└────────────────────────────┘
```

<div id="L1Norm">
  ## L1Norm
</div>

Добавленный в: v21.11.0

Вычисляет сумму модулей элементов вектора.

**Синтаксис**

```sql theme={null}
L1Norm(vector)
```

**Псевдонимы**: `normL1`

**Аргументы**

* `vector` — Вектор или кортеж числовых значений. [`Array(T)`](/docs/ru/reference/data-types/array) или [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает L1-норму или расстояние в [таксомоторной геометрии](https://en.wikipedia.org/wiki/Taxicab_geometry). [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float) или [`Decimal`](/docs/ru/reference/data-types/decimal)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L1Norm((1, 2))
```

```response title=Response theme={null}
┌─L1Norm((1, 2))─┐
│              3 │
└────────────────┘
```

<div id="L1Normalize">
  ## L1Normalize
</div>

Добавленный в: v21.11.0

Вычисляет единичный вектор заданного вектора (элементы кортежа — координаты) в пространстве `L1` ([таксомоторная геометрия](https://en.wikipedia.org/wiki/Taxicab_geometry)).

**Синтаксис**

```sql theme={null}
L1Normalize(tuple)
```

**Псевдонимы**: `normalizeL1`

**Аргументы**

* `tuple` — Кортеж из числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает единичный вектор. [`Tuple(Float64)`](/docs/ru/reference/data-types/tuple)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L1Normalize((1, 2))
```

```response title=Response theme={null}
┌─L1Normalize((1, 2))─────────────────────┐
│ (0.3333333333333333,0.6666666666666666) │
└─────────────────────────────────────────┘
```

<div id="L2Distance">
  ## L2Distance
</div>

Добавленный в: v21.11.0

Вычисляет расстояние между двумя точками (элементы векторов служат координатами) в евклидовом пространстве ([евклидово расстояние](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Синтаксис**

```sql theme={null}
L2Distance(vector1, vector2)
```

**Псевдонимы**: `distanceL2`

**Аргументы**

* `vector1` — Первый вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает расстояние по 2-норме. Для входных данных типа `Array` возвращает `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, в противном случае — `Float64`. Для входных данных типа `Tuple` всегда возвращает `Float64`. [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L2Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L2Distance((1, 2), (2, 3))─┐
│         1.4142135623730951 │
└────────────────────────────┘
```

<div id="L2DistanceTransposed">
  ## L2DistanceTransposed
</div>

Добавленный в: v25.10.0

Вычисляет приблизительное расстояние между двумя точками в евклидовом пространстве, где значения векторов служат координатами ([евклидово расстояние](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Синтаксис**

```sql theme={null}
L2DistanceTransposed(vector1, vector2, p[, used_dims])
```

**Псевдонимы**: `distanceL2Transposed`

**Аргументы**

* `vectors` — Векторы. [`QBit(T, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор. [`Array(T)`](/docs/ru/reference/data-types/array)
* `p` — Количество битов из каждого элемента вектора, используемых при вычислении расстояния (от 1 до битовой ширины элемента). Уровень квантования определяет компромисс между точностью и скоростью. Использование меньшего количества битов ускоряет операции ввода-вывода и вычисления, но снижает точность, тогда как большее количество битов повышает точность ценой производительности. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество первых размерностей, которые нужно считывать, для поиска с уменьшенной размерностью в `QBit` со stride. Должно быть кратно stride в QBit и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (любые дополнительные конечные элементы игнорируются). Считываются только те группы stride, которые покрывают эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приблизительное расстояние по 2-норме. Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT L2DistanceTransposed(vec, array(1, 2), 16) FROM qbit;
```

```response title=Response theme={null}
┌─L2DistanceTransposed([0, 1], [1, 2], 16)─┐
│                       1.3922918381215914 │
└──────────────────────────────────────────┘
```

<div id="L2DistanceTransposedQuantized">
  ## L2DistanceTransposedQuantized
</div>

Добавленный в: v26.7.0

Вычисляет приблизительное [евклидово расстояние](https://en.wikipedia.org/wiki/Euclidean_distance) между `QBit(Int8)` из кодов `quantizeBFloat16ToInt8` (деквантованных на лету) и опорным вектором. Опорный вектор (запрос) типа `Float` сравнивается напрямую с точностью `Float32` — точностью восстановления деквантованных кодов, поэтому запрос `Float64` сужается до `Float32`, а запрос `BFloat16` точно расширяется до него (асимметричное вычисление расстояния); опорный вектор `Array(Int8)` сам рассматривается как коды `quantizeBFloat16ToInt8` и деквантуется до своих уровней восстановления. Обратите внимание, что `p` усекает только сохранённые коды `QBit`; опорный `Array(Int8)` сам является полным запросом и всегда восстанавливается с полной 8-битной точностью, поэтому это симметричное расстояние между квантованными векторами только при `p = 8` (при `p < 8` только сохранённая сторона считывается с более грубой точностью). Он должен находиться в том же пространстве, в котором значения были до квантования (то есть после того же случайного поворота и масштабирования), и ответственность за это лежит на вызывающей стороне. Косинусное расстояние инвариантно к масштабу; скалярное произведение и расстояние L2 — нет.

**Синтаксис**

```sql theme={null}
L2DistanceTransposedQuantized(vectors, reference, p[, used_dims])
```

**Аргументы**

* `vectors` — Векторы кодов `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор (запрос): массив `Float` (запрос сравнивается с точностью `Float32` — запрос `Float64` приводится к `Float32`) или `Array(Int8)` из кодов `quantizeBFloat16ToInt8`, деквантованных на лету. [`Array(Float32)`](/docs/ru/reference/data-types/array) или [`Array(Int8)`](/docs/ru/reference/data-types/array)
* `p` — Количество старших битов каждого сохранённого кода `QBit`, которые следует использовать (от 1 до 8). Меньшее количество битов восстанавливает более грубый встроенный квантизатор, обеспечивая более быстрый ввод-вывод ценой снижения точности; 8 бит — это восстановление с полной точностью. `p` усекает только сохранённый `QBit`; опорный `Array(Int8)` всегда восстанавливается с полной 8-битной точностью. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество первых размерностей, которые нужно считывать, для поиска с уменьшенной размерностью (Matryoshka) в `QBit` со stride. Должно быть кратно stride в QBit и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (любые дополнительные конечные элементы игнорируются). Считываются только те группы stride, которые покрывают эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приблизительное расстояние по 2-норме. Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT L2DistanceTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;
```

<div id="L2Norm">
  ## L2Norm
</div>

Добавленный в: v21.11.0

Вычисляет квадратный корень из суммы квадратов элементов вектора.

**Синтаксис**

```sql theme={null}
L2Norm(vector)
```

**Псевдонимы**: `normL2`

**Аргументы**

* `vector` — Вектор или кортеж из числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает норму L2 или [евклидово расстояние](https://en.wikipedia.org/wiki/Euclidean_distance). [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L2Norm((1, 2))
```

```response title=Response theme={null}
┌───L2Norm((1, 2))─┐
│ 2.23606797749979 │
└──────────────────┘
```

<div id="L2Normalize">
  ## L2Normalize
</div>

Добавленный в: v21.11.0

Вычисляет единичный вектор для заданного вектора (элементы кортежа служат координатами) в евклидовом пространстве (с помощью [евклидова расстояния](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Синтаксис**

```sql theme={null}
L2Normalize(tuple)
```

**Псевдонимы**: `normalizeL2`

**Аргументы**

* `tuple` — Кортеж числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает единичный вектор. [`Tuple(Float64)`](/docs/ru/reference/data-types/tuple)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L2Normalize((3, 4))
```

```response title=Response theme={null}
┌─L2Normalize((3, 4))─┐
│ (0.6,0.8)           │
└─────────────────────┘
```

<div id="L2SquaredDistance">
  ## L2SquaredDistance
</div>

Добавленный в: v22.7.0

Вычисляет сумму квадратов разностей соответствующих элементов двух векторов.

**Синтаксис**

```sql theme={null}
L2SquaredDistance(vector1, vector2)
```

**Псевдонимы**: `distanceL2Squared`

**Аргументы**

* `vector1` — Первый вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает сумму квадратов разностей соответствующих элементов двух векторов. Для входных значений `Array` возвращает `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, в противном случае — `Float64`. Для входных значений `Tuple` возвращаемый тип соответствует арифметическому типу результата поэлементных операций (целочисленные типы сохраняются). [`(U)Int*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L2SquaredDistance([1, 2, 3], [0, 0, 0])
```

```response title=Response theme={null}
┌─L2SquaredDis⋯ [0, 0, 0])─┐
│                       14 │
└──────────────────────────┘
```

<div id="L2SquaredNorm">
  ## L2SquaredNorm
</div>

Добавленный в: v22.7.0

Вычисляет квадрат нормы [`L2Norm`](#L2Norm), то есть сумму квадратов элементов вектора.

**Синтаксис**

```sql theme={null}
L2SquaredNorm(vector)
```

**Псевдонимы**: `normL2Squared`

**Аргументы**

* `vector` — Вектор или кортеж числовых значений. [`Array(T)`](/docs/ru/reference/data-types/array) или [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает квадрат нормы L2. [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float) или [`Decimal`](/docs/ru/reference/data-types/decimal)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT L2SquaredNorm((1, 2))
```

```response title=Response theme={null}
┌─L2SquaredNorm((1, 2))─┐
│                     5 │
└───────────────────────┘
```

<div id="LinfDistance">
  ## LinfDistance
</div>

Добавленный в: v21.11.0

Вычисляет расстояние между двумя точками (элементы векторов служат координатами) в пространстве `L_{inf}` ([максимальная норма](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Синтаксис**

```sql theme={null}
LinfDistance(vector1, vector2)
```

**Псевдонимы**: `distanceLinf`

**Аргументы**

* `vector1` — Первый вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает расстояние в норме бесконечности. Для входных значений типа `Array` возвращает `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, в противном случае — `Float64`. Для входных значений типа `Tuple` всегда возвращает `Float64`. [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT LinfDistance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─LinfDistance((1, 2), (2, 3))─┐
│                            1 │
└──────────────────────────────┘
```

<div id="LinfNorm">
  ## LinfNorm
</div>

Добавленный в: v21.11.0

Вычисляет максимальное по модулю значение элемента вектора.

**Синтаксис**

```sql theme={null}
LinfNorm(vector)
```

**Псевдонимы**: `normLinf`

**Аргументы**

* `vector` — Вектор или кортеж из числовых значений. [`Array(T)`](/docs/ru/reference/data-types/array) или [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает норму Linf, то есть максимальное по модулю значение. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT LinfNorm((1, -2))
```

```response title=Response theme={null}
┌─LinfNorm((1, -2))─┐
│                 2 │
└───────────────────┘
```

<div id="LinfNormalize">
  ## LinfNormalize
</div>

Добавленный в: v21.11.0

Вычисляет единичный вектор для заданного вектора (элементы кортежа служат координатами) в пространстве `L_{inf}` (с использованием [максимальной нормы](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Синтаксис**

```sql theme={null}
LinfNormalize(tuple)
```

**Псевдонимы**: `normalizeLinf`

**Аргументы**

* `tuple` — Кортеж из числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple)

**Возвращаемое значение**

Возвращает единичный вектор. [`Tuple(Float64)`](/docs/ru/reference/data-types/tuple)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT LinfNormalize((3, 4))
```

```response title=Response theme={null}
┌─LinfNormalize((3, 4))─┐
│ (0.75,1)              │
└───────────────────────┘
```

<div id="LpDistance">
  ## LpDistance
</div>

Добавленный в: v21.11.0

Вычисляет расстояние между двумя точками (элементы векторов являются координатами) в пространстве `Lp` ([расстояние p-нормы](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Синтаксис**

```sql theme={null}
LpDistance(vector1, vector2, p)
```

**Псевдонимы**: `distanceLp`

**Аргументы**

* `vector1` — Первый вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй вектор. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `p` — Степень. Возможные значения: действительное число в диапазоне `[1; inf)`. [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Возвращаемое значение**

Возвращает расстояние по p-норме. Для аргументов типа `Array` возвращает `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, в противном случае — `Float64`. Для аргументов типа `Tuple` всегда возвращает `Float64`. [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT LpDistance((1, 2), (2, 3), 3)
```

```response title=Response theme={null}
┌─LpDistance((1, 2), (2, 3), 3)─┐
│            1.2599210498948732 │
└───────────────────────────────┘
```

<div id="LpNorm">
  ## LpNorm
</div>

Добавленный в: v21.11.0

Вычисляет p-норму вектора, то есть корень степени p из суммы p-х степеней абсолютных значений его элементов.

Особые случаи:

* При p=1 эквивалентна L1Norm (манхэттенское расстояние).
* При p=2 эквивалентна L2Norm (евклидово расстояние).
* При p=∞ эквивалентна LinfNorm (максимальная норма).

**Синтаксис**

```sql theme={null}
LpNorm(vector, p)
```

**Псевдонимы**: `normLp`

**Аргументы**

* `vector` — Вектор или кортеж числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `p` — Степень. Возможные значения — действительные числа в диапазоне `[1; inf)`. [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Возвращаемое значение**

Возвращает [Lp-норму](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm). [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT LpNorm((1, -2), 2)
```

```response title=Response theme={null}
┌─LpNorm((1, -2), 2)─┐
│   2.23606797749979 │
└────────────────────┘
```

<div id="LpNormalize">
  ## LpNormalize
</div>

Добавленный в: v21.11.0

Вычисляет единичный вектор для заданного вектора (элементы кортежа служат координатами) в пространстве `Lp` (с использованием [p-нормы](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Синтаксис**

```sql theme={null}
LpNormalize(tuple, p)
```

**Псевдонимы**: `normalizeLp`

**Аргументы**

* `tuple` — Кортеж из числовых значений. [`Tuple(T)`](/docs/ru/reference/data-types/tuple)
* `p` — Степень. Возможные значения — любое число в диапазоне `[1; inf)`. [`UInt*`](/docs/ru/reference/data-types/int-uint) или [`Float*`](/docs/ru/reference/data-types/float)

**Возвращаемое значение**

Возвращает единичный вектор. [`Tuple(Float64)`](/docs/ru/reference/data-types/tuple)

**Примеры**

**Пример использования**

```sql title=Query theme={null}
SELECT LpNormalize((3, 4), 5)
```

```response title=Response theme={null}
┌─LpNormalize((3, 4), 5)──────────────────┐
│ (0.7187302630182624,0.9583070173576831) │
└─────────────────────────────────────────┘
```

<div id="cosineDistance">
  ## cosineDistance
</div>

Добавленный в: v21.11.0

Вычисляет [косинусное расстояние](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) между двумя векторами (элементы кортежей — это координаты). Чем меньше возвращаемое значение, тем больше векторы похожи друг на друга.

**Синтаксис**

```sql theme={null}
cosineDistance(vector1, vector2)
```

**Псевдонимы**: `distanceCosine`

**Аргументы**

* `vector1` — Первый кортеж. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)
* `vector2` — Второй кортеж. [`Tuple(T)`](/docs/ru/reference/data-types/tuple) или [`Array(T)`](/docs/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает косинусное расстояние (единица минус косинусное сходство). Для входных значений `Array` возвращается `Float32`, если наименьший общий супертип типов элементов — `Float32` или `BFloat16`, иначе — `Float64`. Для входных значений `Tuple` всегда возвращается `Float64`. [`Float*`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
SELECT cosineDistance((1, 2), (2, 3));
```

```response title=Response theme={null}
┌─cosineDistance((1, 2), (2, 3))─┐
│           0.007722123286332261 │
└────────────────────────────────┘
```

<div id="cosineDistanceTransposed">
  ## cosineDistanceTransposed
</div>

Добавленный в: v26.1.0

Вычисляет приблизительное [косинусное расстояние](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) между двумя точками (значения векторов служат координатами). Чем меньше возвращаемое значение, тем более похожи векторы.

**Синтаксис**

```sql theme={null}
cosineDistanceTransposed(vector1, vector2, p[, used_dims])
```

**Псевдонимы**: `distanceCosineTransposed`

**Аргументы**

* `vectors` — Векторы. [`QBit(T, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор. [`Array(T)`](/docs/ru/reference/data-types/array)
* `p` — Количество битов из каждого элемента вектора, используемых при вычислении расстояния (от 1 до разрядности элемента в битах). Уровень квантования определяет компромисс между точностью и скоростью. Использование меньшего количества битов ускоряет операции ввода-вывода и вычисления, но снижает точность, тогда как большее количество битов повышает точность ценой производительности. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество начальных размерностей для чтения при поиске с уменьшенной размерностью (Matryoshka) по `QBit` со stride. Должно быть кратно stride `QBit` и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (любые дополнительные конечные элементы игнорируются). Считываются только группы stride, покрывающие эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приближённое косинусное расстояние (единица минус косинусное сходство). Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT cosineDistanceTransposed(vec, array(1, 2), 16) FROM qbit;
```

```response title=Response theme={null}
┌─cosineDistanceTransposed([0, 1], [1, 2], 16)─┐
│                          0.10557280905788935 │
└──────────────────────────────────────────────┘
```

<div id="cosineDistanceTransposedQuantized">
  ## cosineDistanceTransposedQuantized
</div>

Добавленный в: v26.7.0

Вычисляет приблизительное [косинусное расстояние](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) между кодами `QBit(Int8)` функции `quantizeBFloat16ToInt8` (деквантуемыми на лету) и опорным вектором. Чем меньше возвращаемое значение, тем больше сходство между векторами. Опорный вектор `Float` (вектор `запроса`) сравнивается напрямую с точностью `Float32` — то есть с точностью восстановления деквантованных кодов, поэтому `Float64`-запрос приводится к `Float32`, а `BFloat16`-запрос точно расширяется до него (асимметричное вычисление расстояния); опорный `Array(Int8)` сам рассматривается как коды `quantizeBFloat16ToInt8` и деквантуется до своих уровней восстановления. Обратите внимание: `p` усекает только сохранённые коды `QBit`; опорный `Array(Int8)` сам по себе является полным запросом и всегда восстанавливается с полной 8-битной точностью, поэтому симметричное расстояние между квантованными векторами здесь получается только при `p = 8` (при `p < 8` только сохранённая сторона читается с более грубой точностью). Он должен находиться в том же пространстве, в котором значения находились до квантования (то есть после того же случайного поворота и масштабирования); это ответственность вызывающей стороны. Косинусное расстояние инвариантно к масштабу; скалярное произведение и L2-расстояние — нет.

**Синтаксис**

```sql theme={null}
cosineDistanceTransposedQuantized(vectors, reference, p[, used_dims])
```

**Аргументы**

* `vectors` — Векторы кодов `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор (`запрос`): массив `Float` (запрос сравнивается с точностью `Float32` — запрос `Float64` приводится к `Float32`) или `Array(Int8)` с кодами `quantizeBFloat16ToInt8`, деквантуемыми на лету. [`Array(Float32)`](/docs/ru/reference/data-types/array) или [`Array(Int8)`](/docs/ru/reference/data-types/array)
* `p` — Число старших битов каждого хранимого кода `QBit`, которое нужно использовать (от 1 до 8). Чем меньше битов, тем грубее восстанавливаемый квантизатор, но тем быстрее I/O и ниже точность; 8 бит — это восстановление с полной точностью. `p` усекает только хранимый `QBit`; опорный вектор `Array(Int8)` всегда восстанавливается с полной 8-битной точностью. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество начальных размерностей, которые нужно считывать для поиска с уменьшенной размерностью (Matryoshka) по QBit со stride. Должно быть кратно stride `QBit` и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (любые дополнительные конечные элементы игнорируются). Считываются только группы stride, покрывающие эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приближённое косинусное расстояние (единица минус косинусное сходство). Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT cosineDistanceTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;
```

<div id="dotProductTransposed">
  ## dotProductTransposed
</div>

Добавленный в: v26.7.0

Вычисляет приблизительное [скалярное произведение](https://en.wikipedia.org/wiki/Dot_product) (внутреннее произведение) двух векторов (значения векторов служат координатами). В отличие от функций расстояния, это мера сходства: чем больше возвращаемое значение, тем более похожи векторы.

**Синтаксис**

```sql theme={null}
dotProductTransposed(vector1, vector2, p[, used_dims])
```

**Псевдонимы**: `scalarProductTransposed`

**Аргументы**

* `vectors` — Векторы. [`QBit(T, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор. [`Array(T)`](/docs/ru/reference/data-types/array)
* `p` — Количество битов из каждого элемента вектора, используемых при вычислении (от 1 до разрядности элемента в битах). Уровень квантования определяет компромисс между точностью и скоростью. Использование меньшего количества битов ускоряет операции ввода-вывода и вычисления, но снижает точность, тогда как большее количество битов повышает точность ценой производительности. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество начальных размерностей, которые нужно считывать, для поиска с уменьшенной размерностью (Matryoshka) по `QBit` со stride. Должно быть кратно stride в QBit и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (любые дополнительные элементы в конце игнорируются). Считываются только группы stride, покрывающие эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приблизительное скалярное произведение двух векторов. Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT dotProductTransposed(vec, array(1, 2), 16) FROM qbit;
```

```response title=Response theme={null}
┌─dotProductTransposed([0, 1], [1, 2], 16)─┐
│                                   2.0625 │
└──────────────────────────────────────────┘
```

<div id="dotProductTransposedQuantized">
  ## dotProductTransposedQuantized
</div>

Добавленный в: v26.7.0

Вычисляет приблизительное [скалярное произведение](https://en.wikipedia.org/wiki/Dot_product) (внутреннее произведение) между `QBit(Int8)`, содержащим коды `quantizeBFloat16ToInt8` (деквантуемые на лету), и опорным вектором. Это мера сходства: чем больше возвращаемое значение, тем более похожи векторы. Опорный вектор (запрос) типа `Float` сравнивается напрямую с точностью `Float32` — точностью восстановления деквантованных кодов, поэтому запрос `Float64` сужается до `Float32`, а запрос `BFloat16` точно расширяется до этого типа (асимметричное вычисление расстояния); опорный вектор `Array(Int8)` сам рассматривается как коды `quantizeBFloat16ToInt8` и деквантуется до уровней их восстановления. Обратите внимание, что `p` усекает только сохранённые коды `QBit`; опорный вектор `Array(Int8)` сам по себе является полным запросом и всегда восстанавливается с полной 8-битной точностью, поэтому симметричное расстояние между квантованными представлениями получается только при `p = 8` (при `p < 8` только сохранённая сторона считывается с более грубой точностью). Он должен находиться в том же пространстве, в котором значения были до квантования (то есть после того же случайного поворота и масштабирования), и это ответственность вызывающей стороны. Косинусное расстояние инвариантно к масштабу; скалярное произведение и расстояние L2 — нет.

**Синтаксис**

```sql theme={null}
dotProductTransposedQuantized(vectors, reference, p[, used_dims])
```

**Аргументы**

* `vectors` — Векторы кодов `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/ru/reference/data-types/qbit)
* `reference` — Опорный вектор (запрос): массив `Float` (запрос сравнивается с точностью `Float32` — запрос типа `Float64` приводится к `Float32`) или `Array(Int8)` из кодов `quantizeBFloat16ToInt8`, деквантуемых на лету. [`Array(Float32)`](/docs/ru/reference/data-types/array) или [`Array(Int8)`](/docs/ru/reference/data-types/array)
* `p` — Количество старших битов каждого сохранённого кода `QBit`, используемых при вычислении (от 1 до 8). Меньшее количество битов даёт более грубое восстановление встроенного квантизатора, что ускоряет ввод-вывод ценой снижения точности; 8 бит — это восстановление с полной точностью. `p` усекает только сохранённый `QBit`; опорный `Array(Int8)` всегда восстанавливается с полной 8-битной точностью. [`UInt`](/docs/ru/reference/data-types/int-uint)
* `used_dims` — Необязательно. Количество начальных размерностей, которые нужно считывать, для поиска с уменьшенной размерностью (Matryoshka) по `QBit` со stride. Должно быть кратно stride в QBit и не превышать его размерность, а опорный вектор должен содержать как минимум столько элементов (все дополнительные элементы в конце игнорируются). Считываются только группы stride, покрывающие эти размерности. [`UInt`](/docs/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает приблизительное скалярное произведение двух векторов. Всегда возвращает `Float64`. [`Float64`](/docs/ru/reference/data-types/float)

**Примеры**

**Базовое использование**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT dotProductTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;
```