> ## 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.

> Documentation des fonctions de distance

# Fonctions de distance

{/*AUTOGENERATED_START*/}

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

Introduit dans : v21.11.0

Calcule la distance entre deux points (les éléments des vecteurs correspondent aux coordonnées) dans l’espace `L1` (norme 1, ou distance en [géométrie de Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry)).

**Syntaxe**

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

**alias**: `distanceL1`

**Arguments**

* `vector1` — Premier vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la distance selon la norme 1. Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types d’éléments est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, le type de retour suit le type du résultat arithmétique des opérations appliquées élément par élément (les types entiers sont conservés). [`(U)Int*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduite dans : v21.11.0

Calcule la somme des valeurs absolues des éléments d’un vecteur.

**Syntaxe**

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

**Alias** : `normL1`

**Arguments**

* `vector` — Vecteur ou tuple de valeurs numériques. [`Array(T)`](/docs/fr/reference/data-types/array) ou [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Renvoie la norme L1 ou la distance de [géométrie de Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry). [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float) ou [`Decimal`](/docs/fr/reference/data-types/decimal)

**Exemples**

**Utilisation de base**

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

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

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

Introduit dans : v21.11.0

Calcule le vecteur unitaire d’un vecteur donné (les éléments du tuple sont les coordonnées) dans l’espace `L1` ([géométrie de Manhattan](https://en.wikipedia.org/wiki/Taxicab_geometry)).

**Syntaxe**

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

**Alias** : `normalizeL1`

**Arguments**

* `tuple` — Un tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Renvoie le vecteur unitaire. [`Tuple(Float64)`](/docs/fr/reference/data-types/tuple)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule la distance entre deux points (les éléments des vecteurs correspondent aux coordonnées) dans l’espace euclidien ([distance euclidienne](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntaxe**

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

**Alias** : `distanceL2`

**Arguments**

* `vector1` — Premier vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la distance de norme 2. Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types des éléments est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, renvoie toujours `Float64`. [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v25.10.0

Calcule la distance approximative entre deux points (les valeurs des vecteurs correspondent aux coordonnées) dans l’espace euclidien ([distance euclidienne](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntaxe**

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

**Alias** : `distanceL2Transposed`

**Arguments**

* `vectors` — Vecteurs. [`QBit(T, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence. [`Array(T)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de chaque élément du vecteur à utiliser pour le calcul de la distance (de 1 à la largeur en bits de l’élément). Le niveau de quantification détermine le compromis entre précision et vitesse. Utiliser moins de bits accélère les E/S et les calculs, au prix d’une précision moindre, tandis qu’en utiliser davantage améliore la précision au détriment des performances. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Doit être un multiple du stride du QBit sans dépasser sa dimension, et le vecteur de référence doit comporter au moins ce nombre d’éléments (tout élément supplémentaire en fin de vecteur est ignoré). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie une distance de norme 2 approximative. Renvoie toujours `Float64`. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v26.7.0

Calcule la [distance euclidienne](https://en.wikipedia.org/wiki/Euclidean_distance) approximative entre un `QBit(Int8)` de codes `quantizeBFloat16ToInt8` (déquantifiés à la volée) et un vecteur de référence. Un vecteur de référence (requête) `Float` est comparé directement avec une précision `Float32` -- la précision de reconstruction des codes déquantifiés, de sorte qu’une query `Float64` est ramenée à `Float32`, tandis qu’une query `BFloat16` y est étendue exactement (calcul de distance asymétrique) ; une référence `Array(Int8)` est elle-même traitée comme des codes `quantizeBFloat16ToInt8` et déquantifiée vers ses niveaux de reconstruction. Notez que `p` tronque uniquement les codes `QBit` stockés ; la référence `Array(Int8)` constitue elle-même une query complète et est toujours reconstruite avec la pleine précision de 8 bits, de sorte qu’il s’agit d’une distance quantifiée contre quantifiée symétrique uniquement pour `p = 8` (pour `p < 8`, seul le côté stocké est lu avec une précision plus grossière). Elle doit se trouver dans le même espace que celui où se trouvaient les values avant la quantification (c’est-à-dire après la même rotation aléatoire et la même mise à l’échelle), ce qui relève de la responsabilité de l’appelant. La distance cosinus est invariante par changement d’échelle ; le produit scalaire et la distance L2 ne le sont pas.

**Syntaxe**

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

**Arguments**

* `vectors` — Vecteurs de codes `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence (requête) : un tableau de `Float` (la requête, comparée avec une précision `Float32` -- une requête `Float64` est convertie en `Float32`), ou un `Array(Int8)` de codes `quantizeBFloat16ToInt8` déquantifiés à la volée. [`Array(Float32)`](/docs/fr/reference/data-types/array) ou [`Array(Int8)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de poids fort de chaque code `QBit` stocké à utiliser (de 1 à 8). Utiliser moins de bits reconstruit un quantificateur embarqué plus grossier, pour des E/S plus rapides au prix d’une précision réduite ; 8 bits correspondent à une reconstruction en précision complète. `p` tronque uniquement le `QBit` stocké ; une référence `Array(Int8)` est toujours reconstruite avec la précision complète de 8 bits. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Doit être un multiple du stride du QBit sans dépasser sa dimension, et le vecteur de référence doit comporter au moins ce nombre d’éléments (tous les éléments supplémentaires en fin de tableau sont ignorés). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie une distance de norme 2 approximative. Renvoie toujours `Float64`. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule la racine carrée de la somme des carrés des éléments du vecteur.

**Syntaxe**

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

**alias** : `normL2`

**Arguments**

* `vector` — Vecteur ou tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la norme L2 ou la [distance euclidienne](https://en.wikipedia.org/wiki/Euclidean_distance). [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

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

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

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

Introduit dans : v21.11.0

Calcule le vecteur unitaire du vecteur donné (les éléments du tuple en sont les coordonnées) dans l’espace euclidien (à l’aide de la [distance euclidienne](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntaxe**

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

**Alias** : `normalizeL2`

**Arguments**

* `tuple` — Un tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Renvoie le vecteur unitaire. [`Tuple(Float64)`](/docs/fr/reference/data-types/tuple)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v22.7.0

Calcule la somme des carrés des écarts entre les éléments correspondants de deux vecteurs.

**Syntaxe**

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

**Alias** : `distanceL2Squared`

**Arguments**

* `vector1` — Premier vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la somme des carrés des différences entre les éléments correspondants de deux vecteurs. Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types d’éléments est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, le type de retour suit le type de résultat arithmétique des opérations élément par élément (les types entiers sont conservés). [`(U)Int*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v22.7.0

Calcule le carré de la norme L2 du vecteur (la [`L2Norm`](#L2Norm)).

**Syntaxe**

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

**Alias** : `normL2Squared`

**Arguments**

* `vector` — Vecteur ou tuple de valeurs numériques. [`Array(T)`](/docs/fr/reference/data-types/array) ou [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Carré de la norme L2. [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float) ou [`Decimal`](/docs/fr/reference/data-types/decimal)

**Exemples**

**Utilisation de base**

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

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

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

Introduit dans : v21.11.0

Calcule la distance entre deux points (les éléments des vecteurs correspondant aux coordonnées) dans l’espace `L_{inf}` ([norme maximale](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Syntaxe**

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

**Alias** : `distanceLinf`

**Arguments**

* `vector1` — Premier vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la distance selon la norme infinie. Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types d’élément est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, renvoie toujours `Float64`. [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule la plus grande valeur absolue des éléments d’un vecteur.

**Syntaxe**

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

**Alias** : `normLinf`

**Arguments**

* `vector` — Vecteur ou tuple de valeurs numériques. [`Array(T)`](/docs/fr/reference/data-types/array) ou [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Renvoie la norme Linf, c’est-à-dire la valeur absolue maximale. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

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

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

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

Introduit dans : v21.11.0

Calcule le vecteur unitaire d’un vecteur donné (les éléments du tuple en sont les coordonnées) dans l’espace `L_{inf}` (à l’aide de la [norme maximale](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Syntaxe**

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

**Alias** : `normalizeLinf`

**Arguments**

* `tuple` — Un tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple)

**Valeur renvoyée**

Renvoie le vecteur unitaire. [`Tuple(Float64)`](/docs/fr/reference/data-types/tuple)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule la distance entre deux points (les éléments des vecteurs sont les coordonnées) dans l’espace `Lp` ([distance de p-norme](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Syntaxe**

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

**Alias** : `distanceLp`

**Arguments**

* `vector1` — Premier vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième vecteur. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `p` — La puissance. **Valeurs possibles** : nombre réel compris dans `[1; inf)`. [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Valeur renvoyée**

Renvoie la distance selon la norme p. Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types des éléments est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, renvoie toujours `Float64`. [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule la p-norme d'un vecteur, c'est-à-dire la racine p-ième de la somme des puissances p-ièmes des valeurs absolues de ses éléments.

Cas particuliers :

* Quand p=1, elle est équivalente à L1Norm (distance de Manhattan).
* Quand p=2, elle est équivalente à L2Norm (distance euclidienne).
* Quand p=∞, elle est équivalente à LinfNorm (norme maximale).

**Syntaxe**

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

**Alias** : `normLp`

**Arguments**

* `vector` — Vecteur ou tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `p` — La puissance. Les valeurs possibles sont des nombres réels dans l’intervalle `[1; inf)`. [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Valeur renvoyée**

Renvoie la [norme Lp](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm). [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v21.11.0

Calcule le vecteur unitaire d’un vecteur donné (les éléments du Tuple sont les coordonnées) dans l’espace `Lp` (à l’aide de la [p-norme](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Syntaxe**

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

**Alias** : `normalizeLp`

**Arguments**

* `tuple` — Un tuple de valeurs numériques. [`Tuple(T)`](/docs/fr/reference/data-types/tuple)
* `p` — L’exposant. Les valeurs possibles sont tous les nombres de l’intervalle `[1; inf)`. [`UInt*`](/docs/fr/reference/data-types/int-uint) ou [`Float*`](/docs/fr/reference/data-types/float)

**Valeur renvoyée**

Renvoie le vecteur unitaire. [`Tuple(Float64)`](/docs/fr/reference/data-types/tuple)

**Exemples**

**Exemple d’utilisation**

```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>

Introduit dans : v21.11.0

Calcule la [distance cosinus](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) entre deux vecteurs (les éléments des tuples correspondent aux coordonnées). Plus la valeur renvoyée est faible, plus les vecteurs sont similaires.

**Syntaxe**

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

**Alias** : `distanceCosine`

**Arguments**

* `vector1` — Premier tuple. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)
* `vector2` — Deuxième tuple. [`Tuple(T)`](/docs/fr/reference/data-types/tuple) ou [`Array(T)`](/docs/fr/reference/data-types/array)

**Valeur renvoyée**

Renvoie la distance cosinus (un moins la similarité cosinus). Pour les entrées `Array`, renvoie `Float32` si le plus petit supertype commun des types des éléments est `Float32` ou `BFloat16`, sinon `Float64`. Pour les entrées `Tuple`, renvoie toujours `Float64`. [`Float*`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v26.1.0

Calcule la [distance cosinus](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) approximative entre deux points (les valeurs des vecteurs correspondent aux coordonnées). Plus la valeur renvoyée est faible, plus les vecteurs sont similaires.

**Syntaxe**

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

**Alias** : `distanceCosineTransposed`

**Arguments**

* `vectors` — Vecteurs. [`QBit(T, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence. [`Array(T)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de chaque élément du vecteur à utiliser pour le calcul de la distance (de 1 à la largeur en bits de l’élément). Le niveau de quantification détermine le compromis entre précision et vitesse. Utiliser moins de bits accélère les opérations d’E/S et les calculs, au prix d’une précision réduite, tandis qu’utiliser davantage de bits améliore la précision au détriment des performances. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Doit être un multiple du stride du QBit sans dépasser sa dimension, et le vecteur de référence doit comporter au moins ce nombre d’éléments (tout élément supplémentaire en fin de vecteur est ignoré). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie la distance cosinus approximative (un moins la similarité cosinus). Renvoie toujours un Float64. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduite dans : v26.7.0

Calcule la [distance cosinus](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) approximative entre un `QBit(Int8)` de codes `quantizeBFloat16ToInt8` (déquantifiés à la volée) et un vecteur de référence. Plus la valeur renvoyée est faible, plus les vecteurs se ressemblent. Un vecteur de référence (requête) `Float` est comparé directement à la précision `Float32` -- la précision de reconstruction des codes déquantifiés, si bien qu’une requête `Float64` est ramenée à `Float32`, tandis qu’une requête `BFloat16` y est convertie exactement (calcul de distance asymétrique) ; une référence `Array(Int8)` est elle-même traitée comme des codes `quantizeBFloat16ToInt8` et déquantifiée vers ses niveaux de reconstruction. Notez que `p` tronque uniquement les codes `QBit` stockés ; la référence `Array(Int8)` constitue, elle, une requête complète et est toujours reconstruite avec la pleine précision de 8 bits. Il s’agit donc d’une distance quantifiée contre quantifiée symétrique uniquement pour `p = 8` (pour `p < 8`, seul le côté stocké est lu avec une précision plus grossière). Il doit se trouver dans le même espace que celui où se trouvaient les valeurs avant la quantification (c.-à-d. après la même rotation aléatoire et la même mise à l’échelle), ce qui relève de la responsabilité de l’appelant. La distance cosinus est invariante par changement d’échelle ; le produit scalaire et la distance L2 ne le sont pas.

**Syntaxe**

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

**Arguments**

* `vectors` — Vecteurs de codes `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence (requête) : un tableau de `Float` (la requête, comparée avec une précision `Float32` -- une requête `Float64` est ramenée à `Float32`), ou un `Array(Int8)` de codes `quantizeBFloat16ToInt8` déquantifiés à la volée. [`Array(Float32)`](/docs/fr/reference/data-types/array) ou [`Array(Int8)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de poids fort de chaque code `QBit` stocké à utiliser (de 1 à 8). Moins de bits reconstruisent un quantificateur intégré plus grossier pour des E/S plus rapides, au prix d'une précision réduite ; 8 bits correspondent à une reconstruction en pleine précision. `p` tronque uniquement le `QBit` stocké ; une référence `Array(Int8)` est toujours reconstruite avec la pleine précision de 8 bits. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Cette valeur doit être un multiple du stride du QBit, sans dépasser sa dimension, et le vecteur de référence doit contenir au moins ce nombre d'éléments (tout élément supplémentaire en fin de tableau est ignoré). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie la distance cosinus approximative (1 moins la similarité cosinus). Renvoie toujours `Float64`. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v26.7.0

Calcule le [produit scalaire](https://en.wikipedia.org/wiki/Dot_product) approximatif (produit intérieur) de deux vecteurs (les valeurs des vecteurs correspondent aux coordonnées). Contrairement aux fonctions de distance, il s’agit d’une mesure de similarité : plus la valeur renvoyée est élevée, plus les vecteurs sont similaires.

**Syntaxe**

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

**Alias** : `scalarProductTransposed`

**Arguments**

* `vectors` — Vecteurs. [`QBit(T, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence. [`Array(T)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de chaque élément du vecteur à utiliser pour le calcul (de 1 à la largeur en bits de l’élément). Le niveau de quantification détermine le compromis entre précision et vitesse. Utiliser moins de bits accélère les opérations d’E/S et les calculs, au prix d’une précision réduite, tandis qu’utiliser davantage de bits améliore la précision au détriment des performances. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Doit être un multiple du stride du QBit sans dépasser sa dimension, et le vecteur de référence doit contenir au moins ce nombre d’éléments (tous les éléments supplémentaires en fin de vecteur sont ignorés). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie le produit scalaire approximatif des deux vecteurs. Renvoie toujours un Float64. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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>

Introduit dans : v26.7.0

Calcule le [produit scalaire](https://en.wikipedia.org/wiki/Dot_product) approximatif (produit intérieur) entre un `QBit(Int8)` de codes `quantizeBFloat16ToInt8` (déquantifiés à la volée) et un vecteur de référence. Il s’agit d’une mesure de similarité : plus la valeur renvoyée est élevée, plus les vecteurs sont similaires. Un vecteur de référence (requête) `Float` est comparé directement à une précision `Float32` -- la précision de reconstruction des codes déquantifiés ; ainsi, une requête `Float64` est ramenée à `Float32`, tandis qu’une requête `BFloat16` y est élargie exactement (calcul de distance asymétrique). Une référence `Array(Int8)` est elle-même traitée comme des codes `quantizeBFloat16ToInt8` et déquantifiée vers ses niveaux de reconstruction. Notez que `p` tronque uniquement les codes `QBit` stockés ; la référence `Array(Int8)` constitue une requête complète et est toujours reconstruite avec la pleine précision de 8 bits, de sorte qu’il ne s’agit d’une distance symétrique quantifié-contre-quantifié qu’à `p = 8` (pour `p < 8`, seul le côté stocké est lu avec une précision plus grossière). Ce vecteur doit se trouver dans le même espace que celui des valeurs avant quantification (c’est-à-dire après la même rotation aléatoire et la même mise à l’échelle), ce qui relève de la responsabilité de l’appelant. La distance cosinus est invariante par changement d’échelle ; le produit scalaire et la distance L2 ne le sont pas.

**Syntaxe**

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

**Arguments**

* `vectors` — Vecteurs de codes `quantizeBFloat16ToInt8`. [`QBit(Int8, UInt64[, UInt64])`](/docs/fr/reference/data-types/qbit)
* `reference` — Vecteur de référence (requête) : un tableau de `Float` (la requête, comparée avec une précision `Float32` -- une requête `Float64` est convertie en `Float32`), ou un `Array(Int8)` de codes `quantizeBFloat16ToInt8` déquantifiés à la volée. [`Array(Float32)`](/docs/fr/reference/data-types/array) ou [`Array(Int8)`](/docs/fr/reference/data-types/array)
* `p` — Nombre de bits de poids fort de chaque code `QBit` stocké à utiliser (de 1 à 8). Utiliser moins de bits reconstruit un quantificateur embarqué plus grossier pour des E/S plus rapides, au prix d’une précision réduite ; 8 bits correspondent à une reconstruction en pleine précision. `p` tronque uniquement le `QBit` stocké ; une référence `Array(Int8)` est toujours reconstruite avec la pleine précision de 8 bits. [`UInt`](/docs/fr/reference/data-types/int-uint)
* `used_dims` — Facultatif. Nombre de dimensions initiales à lire, pour une recherche à dimension réduite (Matryoshka) sur un `QBit` avec stride. Doit être un multiple du stride du QBit sans dépasser sa dimension, et le vecteur de référence doit contenir au moins ce nombre d’éléments (tout élément supplémentaire en fin de vecteur est ignoré). Seuls les groupes de stride couvrant ces dimensions sont lus. [`UInt`](/docs/fr/reference/data-types/int-uint)

**Valeur renvoyée**

Renvoie le produit scalaire approximatif des deux vecteurs. Renvoie toujours un Float64. [`Float64`](/docs/fr/reference/data-types/float)

**Exemples**

**Utilisation de base**

```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;
```