> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentação das funções de distância # Funções de distância {/*AUTOGENERATED_START*/}
## L1Distance
Introduzido em: v21.11.0 Calcula a distância entre dois pontos (os elementos dos vetores são as coordenadas) no espaço `L1` (norma 1 (distância da [geometria do táxi](https://en.wikipedia.org/wiki/Taxicab_geometry))). **Sintaxe** ```sql theme={null} L1Distance(vector1, vector2) ``` **Aliases**: `distanceL1` **Argumentos** * `vector1` — Primeiro vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segundo vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a distância L1. Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos de elemento for `Float32` ou `BFloat16`; caso contrário, `Float64`. Para entradas `Tuple`, o tipo de retorno segue o tipo de resultado aritmético das operações elemento a elemento (os tipos inteiros são preservados). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L1Distance((1, 2), (2, 3)) ``` ```response title=Response theme={null} ┌─L1Distance((1, 2), (2, 3))─┐ │ 2 │ └────────────────────────────┘ ```
## L1Norm
Introduzido na versão: v21.11.0 Calcula a soma dos valores absolutos dos elementos de um vetor. **Sintaxe** ```sql theme={null} L1Norm(vector) ``` **Aliases**: `normL1` **Argumentos** * `vector` — Vetor ou tupla de valores numéricos. [`Array(T)`](/pt-BR/reference/data-types/array) ou [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna a norma L1 ou a distância em [geometria do táxi](https://en.wikipedia.org/wiki/Taxicab_geometry). [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L1Norm((1, 2)) ``` ```response title=Response theme={null} ┌─L1Norm((1, 2))─┐ │ 3 │ └────────────────┘ ```
## L1Normalize
Introduzido em: v21.11.0 Calcula o vetor unitário de um dado vetor (os elementos da tupla são as coordenadas) no espaço `L1` ([geometria do táxi](https://en.wikipedia.org/wiki/Taxicab_geometry)). **Sintaxe** ```sql theme={null} L1Normalize(tuple) ``` **Aliases**: `normalizeL1` **Argumentos** * `tuple` — Uma tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna o vetor unitário. [`Tuple(Float64)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L1Normalize((1, 2)) ``` ```response title=Response theme={null} ┌─L1Normalize((1, 2))─────────────────────┐ │ (0.3333333333333333,0.6666666666666666) │ └─────────────────────────────────────────┘ ```
## L2Distance
Introduzido em: v21.11.0 Calcula a distância entre dois pontos (os elementos dos vetores são as coordenadas) no espaço euclidiano ([distância euclidiana](https://en.wikipedia.org/wiki/Euclidean_distance)). **Sintaxe** ```sql theme={null} L2Distance(vector1, vector2) ``` **Aliases**: `distanceL2` **Argumentos** * `vector1` — Primeiro vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segundo vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a distância de norma 2. Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos de elemento for `Float32` ou `BFloat16`; caso contrário, `Float64`. Para entradas `Tuple`, sempre retorna `Float64`. [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L2Distance((1, 2), (2, 3)) ``` ```response title=Response theme={null} ┌─L2Distance((1, 2), (2, 3))─┐ │ 1.4142135623730951 │ └────────────────────────────┘ ```
## L2DistanceTransposed
Introduzido na: v25.10.0 Calcula a distância aproximada entre dois pontos (os valores dos vetores são as coordenadas) no espaço euclidiano ([distância euclidiana](https://en.wikipedia.org/wiki/Euclidean_distance)). **Sintaxe** ```sql theme={null} L2DistanceTransposed(vector1, vector2, p) ``` **Aliases**: `distanceL2Transposed` **Argumentos** * `vectors` — Vetores. [`QBit(T, UInt64)`](/pt-BR/reference/data-types/qbit) * `reference` — Vetor de referência. [`Array(T)`](/pt-BR/reference/data-types/array) * `p` — Número de bits de cada elemento do vetor a ser usado no cálculo da distância (de 1 até a largura de bits do elemento). O nível de quantização controla o equilíbrio entre precisão e velocidade. Usar menos bits resulta em E/S e cálculos mais rápidos, com menor precisão, enquanto usar mais bits aumenta a precisão à custa do desempenho. [`UInt`](/pt-BR/reference/data-types/int-uint) **Valor retornado** Retorna a distância aproximada de norma 2. Sempre retorna `Float64`. [`Float64`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```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.4142135623730951 │ └──────────────────────────────────────────┘ ```
## L2Norm
Introduzido em: v21.11.0 Calcula a raiz quadrada da soma dos quadrados dos elementos de um vetor. **Sintaxe** ```sql theme={null} L2Norm(vector) ``` **Aliases**: `normL2` **Argumentos** * `vector` — Vetor ou tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a norma L2, ou a [distância euclidiana](https://en.wikipedia.org/wiki/Euclidean_distance). [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L2Norm((1, 2)) ``` ```response title=Response theme={null} ┌───L2Norm((1, 2))─┐ │ 2.23606797749979 │ └──────────────────┘ ```
## L2Normalize
Introduzido em: v21.11.0 Calcula o vetor unitário de um vetor dado (os elementos da tupla são as coordenadas) no espaço euclidiano (usando a [distância euclidiana](https://en.wikipedia.org/wiki/Euclidean_distance)). **Sintaxe** ```sql theme={null} L2Normalize(tuple) ``` **Aliases**: `normalizeL2` **Argumentos** * `tuple` — Uma tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna o vetor unitário. [`Tuple(Float64)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L2Normalize((3, 4)) ``` ```response title=Response theme={null} ┌─L2Normalize((3, 4))─┐ │ (0.6,0.8) │ └─────────────────────┘ ```
## L2SquaredDistance
Introduzido em: v22.7.0 Calcula a soma dos quadrados das diferenças entre os elementos correspondentes de dois vetores. **Sintaxe** ```sql theme={null} L2SquaredDistance(vector1, vector2) ``` **Aliases**: `distanceL2Squared` **Argumentos** * `vector1` — Primeiro vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segundo vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a soma dos quadrados das diferenças entre os elementos correspondentes de dois vetores. Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos de elemento for `Float32` ou `BFloat16`; caso contrário, retorna `Float64`. Para entradas `Tuple`, o tipo de retorno segue o tipo de resultado aritmético das operações elemento a elemento (os tipos inteiros são preservados). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L2SquaredDistance([1, 2, 3], [0, 0, 0]) ``` ```response title=Response theme={null} ┌─L2SquaredDis⋯ [0, 0, 0])─┐ │ 14 │ └──────────────────────────┘ ```
## L2SquaredNorm
Introduzido em: v22.7.0 Calcula o quadrado da raiz quadrada da soma dos quadrados dos elementos do vetor (a [`L2Norm`](#L2Norm)). **Sintaxe** ```sql theme={null} L2SquaredNorm(vector) ``` **Aliases**: `normL2Squared` **Argumentos** * `vector` — Vetor ou tupla de valores numéricos. [`Array(T)`](/pt-BR/reference/data-types/array) ou [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna o quadrado da norma L2. [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT L2SquaredNorm((1, 2)) ``` ```response title=Response theme={null} ┌─L2SquaredNorm((1, 2))─┐ │ 5 │ └───────────────────────┘ ```
## LinfDistance
Introduzido na versão: v21.11.0 Calcula a distância entre dois pontos (os elementos dos vetores são as coordenadas) no espaço `L_{inf}` ([norma máxima](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))). **Sintaxe** ```sql theme={null} LinfDistance(vector1, vector2) ``` **Aliases**: `distanceLinf` **Argumentos** * `vector1` — Primeiro vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segundo vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a distância na norma infinita. Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos de elemento for `Float32` ou `BFloat16`; caso contrário, retorna `Float64`. Para entradas `Tuple`, sempre retorna `Float64`. [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT LinfDistance((1, 2), (2, 3)) ``` ```response title=Response theme={null} ┌─LinfDistance((1, 2), (2, 3))─┐ │ 1 │ └──────────────────────────────┘ ```
## LinfNorm
Introduzido em: v21.11.0 Calcula o máximo dos valores absolutos dos elementos de um vetor. **Sintaxe** ```sql theme={null} LinfNorm(vector) ``` **Aliases**: `normLinf` **Argumentos** * `vector` — Vetor ou tupla com valores numéricos. [`Array(T)`](/pt-BR/reference/data-types/array) ou [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna a norma Linf, ou seja, o maior valor absoluto. [`Float64`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT LinfNorm((1, -2)) ``` ```response title=Response theme={null} ┌─LinfNorm((1, -2))─┐ │ 2 │ └───────────────────┘ ```
## LinfNormalize
Introduzido em: v21.11.0 Calcula o vetor unitário de um determinado vetor (os elementos da tupla são as coordenadas) no espaço `L_{inf}` (usando a [norma máxima](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))). **Sintaxe** ```sql theme={null} LinfNormalize(tuple) ``` **Aliases**: `normalizeLinf` **Argumentos** * `tuple` — Uma tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna o vetor unitário. [`Tuple(Float64)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT LinfNormalize((3, 4)) ``` ```response title=Response theme={null} ┌─LinfNormalize((3, 4))─┐ │ (0.75,1) │ └───────────────────────┘ ```
## LpDistance
Introduzido em: v21.11.0 Calcula a distância entre dois pontos (os elementos dos vetores são as coordenadas) no espaço `Lp` ([distância da norma p](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)). **Sintaxe** ```sql theme={null} LpDistance(vector1, vector2, p) ``` **Aliases**: `distanceLp` **Argumentos** * `vector1` — Primeiro vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segundo vetor. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `p` — A potência. Valores possíveis: número real em `[1; inf)`. [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Valor retornado** Retorna a distância da norma-p. Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos de elemento for `Float32` ou `BFloat16`; caso contrário, `Float64`. Para entradas `Tuple`, sempre retorna `Float64`. [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```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 │ └───────────────────────────────┘ ```
## LpNorm
Introduzido em: v21.11.0 Calcula a norma p de um vetor, que é a raiz p-ésima da soma das p-ésimas potências dos valores absolutos de seus componentes. Casos especiais: * Quando p=1, é equivalente a L1Norm (distância de Manhattan). * Quando p=2, é equivalente a L2Norm (distância euclidiana). * Quando p=∞, é equivalente a LinfNorm (norma máxima). * **Sintaxe** ```sql theme={null} LpNorm(vector, p) ``` **Aliases**: `normLp` **Arguments** * `vector` — Vetor ou tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `p` — A potência. Os valores possíveis são números reais no intervalo `[1; inf)`. [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Returned value** Retorna a [norma Lp](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm). [`Float64`](/pt-BR/reference/data-types/float) **Examples** **Basic usage** ```sql title=Query theme={null} SELECT LpNorm((1, -2), 2) ``` ```response title=Response theme={null} ┌─LpNorm((1, -2), 2)─┐ │ 2.23606797749979 │ └────────────────────┘ ```
## LpNormalize
Introduzido em: v21.11.0 Calcula o vetor unitário de um vetor dado (os elementos da tupla são as coordenadas) no espaço `Lp` (usando [norma p](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)). **Sintaxe** ```sql theme={null} LpNormalize(tuple, p) ``` **Aliases**: `normalizeLp` **Argumentos** * `tuple` — Uma tupla de valores numéricos. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) * `p` — A potência. Os valores possíveis são quaisquer números no intervalo `[1; inf)`. [`UInt*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) **Valor retornado** Retorna o vetor unitário. [`Tuple(Float64)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Exemplo de uso** ```sql title=Query theme={null} SELECT LpNormalize((3, 4), 5) ``` ```response title=Response theme={null} ┌─LpNormalize((3, 4), 5)──────────────────┐ │ (0.7187302630182624,0.9583070173576831) │ └─────────────────────────────────────────┘ ```
## cosineDistance
Introduzido em: v21.11.0 Calcula a [distância de cosseno](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) entre dois vetores (os elementos das tuplas são as coordenadas). Quanto menor for o valor retornado, mais semelhantes serão os vetores. **Sintaxe** ```sql theme={null} cosineDistance(vector1, vector2) ``` **Aliases**: `distanceCosine` **Argumentos** * `vector1` — Primeira tupla. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) * `vector2` — Segunda tupla. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) **Valor retornado** Retorna a distância de cosseno (um menos a similaridade de cosseno). Para entradas `Array`, retorna `Float32` se o menor supertipo comum dos tipos dos elementos for `Float32` ou `BFloat16`; caso contrário, `Float64`. Para entradas `Tuple`, sempre retorna `Float64`. [`Float*`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT cosineDistance((1, 2), (2, 3)); ``` ```response title=Response theme={null} ┌─cosineDistance((1, 2), (2, 3))─┐ │ 0.007722123286332261 │ └────────────────────────────────┘ ```
## cosineDistanceTransposed
Introduzido em: v26.1.0 Calcula a [distância de cosseno](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) aproximada entre dois pontos (os valores dos vetores são as coordenadas). Quanto menor o valor retornado, mais semelhantes são os vetores. **Sintaxe** ```sql theme={null} cosineDistanceTransposed(vector1, vector2, p) ``` **Aliases**: `distanceCosineTransposed` **Argumentos** * `vectors` — Vetores. [`QBit(T, UInt64)`](/pt-BR/reference/data-types/qbit) * `reference` — Vetor de referência. [`Array(T)`](/pt-BR/reference/data-types/array) * `p` — Número de bits de cada elemento do vetor usados no cálculo da distância (de 1 até a largura de bits do elemento). O nível de quantização controla o equilíbrio entre precisão e velocidade. Usar menos bits resulta em E/S e cálculos mais rápidos, com menor precisão, enquanto usar mais bits aumenta a precisão ao custo do desempenho. [`UInt`](/pt-BR/reference/data-types/int-uint) **Valor retornado** Retorna a distância de cosseno aproximada (um menos a similaridade de cosseno). Sempre retorna Float64. [`Float64`](/pt-BR/reference/data-types/float) **Exemplos** **Uso básico** ```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.10557281085638826 │ └──────────────────────────────────────────────┘ ```