> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentação das funções Tuple # Funções Tuple A documentação abaixo é gerada a partir da tabela de sistema `system.functions`. {/*AUTOGENERATED_START*/}
## dotProduct
Introduzido em: v21.11.0 Calcula o [produto escalar](https://en.wikipedia.org/wiki/Dot_product) (produto interno) de dois vetores (tuplas ou arrays de mesmo tamanho). Retorna a soma dos produtos dos elementos correspondentes. **Sintaxe** ```sql theme={null} dotProduct(vector1, vector2) ``` **Aliases**: `scalarProduct` **Argumentos** * `vector1` — Primeiro vetor. [`Array(T)`](/pt-BR/reference/data-types/array) ou [`Tuple(T)`](/pt-BR/reference/data-types/tuple) * `vector2` — Segundo vetor. Deve ter o mesmo tamanho do primeiro vetor. [`Array(T)`](/pt-BR/reference/data-types/array) ou [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna o produto escalar dos dois vetores. [`(U)Int*`](/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 dotProduct((1, 2), (3, 4)) ``` ```response title=Response theme={null} 11 ```
## flattenTuple
Introduzido em: v22.6.0 Achata uma tupla nomeada e aninhada. Os elementos da tupla retornada são os caminhos da tupla de entrada. **Sintaxe** ```sql theme={null} flattenTuple(input) ``` **Argumentos** * `input` — Tupla nomeada e aninhada a ser achatada. [`Tuple(n1 T1[, n2 T2, ... ])`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla de saída cujos elementos são os caminhos da entrada original. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Exemplo de uso** ```sql title=Query theme={null} CREATE TABLE tab(t Tuple(a UInt32, b Tuple(c String, d UInt32))) ENGINE = MergeTree ORDER BY tuple(); INSERT INTO tab VALUES ((3, ('c', 4))); SELECT flattenTuple(t) FROM tab; ``` ```response title=Response theme={null} ┌─flattenTuple(t)┐ │ (3, 'c', 4) │ └────────────────┘ ```
## tuple
Introduzido em: v1.1.0 Retorna uma tupla agrupando os argumentos de entrada. Para as colunas C1, C2, ... com os tipos T1, T2, ..., retorna uma tupla do tipo nomeado Tuple(C1 T1, C2 T2, ...) contendo essas colunas se os nomes forem únicos e puderem ser tratados como identificadores sem aspas; caso contrário, retorna Tuple(T1, T2, ...). Não há custo para executar a função. Tuplas normalmente são usadas como valores intermediários para um argumento de operadores IN ou para criar uma lista de parâmetros formais de funções lambda. Tuplas não podem ser gravadas em uma tabela. A função implementa o operador `(x, y, ...)`. **Sintaxe** ```sql theme={null} tuple([t1[, t2[ ...]]) ``` **Argumentos** * Nenhum. **Valor retornado** **Exemplos** **típico** ```sql title=Query theme={null} SELECT tuple(1, 2) ``` ```response title=Response theme={null} (1,2) ```
## tupleConcat
Introduzido em: v23.8.0 Combina as tuplas passadas como argumentos. **Sintaxe** ```sql theme={null} tupleConcat(tuple1[, tuple2, [...]]) ``` **Argumentos** * `tupleN` — Quantidade arbitrária de argumentos do tipo Tuple. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla que contém todos os elementos das tuplas de entrada. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Exemplo de uso** ```sql title=Query theme={null} SELECT tupleConcat((1, 2), ('a',), (true, false)) ``` ```response title=Response theme={null} (1, 2, 'a', true, false) ```
## tupleDivide
Introduzido em: v21.11.0 Calcula a divisão entre os elementos correspondentes de duas tuplas do mesmo tamanho. A divisão por zero retorna `inf`. **Sintaxe** ```sql theme={null} tupleDivide(t1, t2) ``` **Argumentos** * `t1` — Primeira tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `t2` — Segunda tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com o resultado da divisão. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleDivide((1, 2), (2, 3)) ``` ```response title=Response theme={null} (0.5, 0.6666666666666666) ```
## tupleDivideByNumber
Introduzido em: v21.11.0 Retorna uma tupla com todos os elementos divididos por um número. A divisão por zero retorna `inf`. **Sintaxe** ```sql theme={null} tupleDivideByNumber(tuple, number) ``` **Argumentos** * `tuple` — tupla a ser dividida. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `number` — Divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla com os elementos divididos. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleDivideByNumber((1, 2), 0.5) ``` ```response title=Response theme={null} (2, 4) ```
## tupleElement
Introduzido em: v1.1.0 Extrai um elemento de uma tupla por índice ou nome. Para acesso por índice, espera-se um índice numérico com base 1. Para acesso por nome, o nome do elemento pode ser fornecido como uma string (funciona apenas para tuplas nomeadas). Índices negativos são suportados. Nesse caso, o elemento correspondente é selecionado, numerado a partir do fim. Por exemplo, `tuple.-1` é o último elemento da tupla. Um terceiro argumento opcional especifica um valor padrão, retornado em vez de lançar uma exceção quando o elemento acessado não existe. Todos os argumentos devem ser constantes. Esta função não tem custo em tempo de execução e implementa os operadores `x.index` e `x.name`. **Sintaxe** ```sql theme={null} tupleElement(tuple, index|name[, default_value]) ``` **Argumentos** * `tuple` — Uma tupla ou um array de tuplas. [`Tuple(T)`](/pt-BR/reference/data-types/tuple) ou [`Array(Tuple(T))`](/pt-BR/reference/data-types/array) * `index` — Índice da coluna, a partir de 1. [`const UInt8/16/32/64`](/pt-BR/reference/data-types/int-uint) * `name` — Nome do elemento. [`const String`](/pt-BR/reference/data-types/string) * `default_value` — Valor padrão retornado quando o índice está fora dos limites ou o elemento não existe. [`Any`](/pt-BR/reference/data-types) **Valor retornado** Retorna o elemento no índice ou com o nome especificado. [`Any`](/pt-BR/reference/data-types) **Exemplos** **Acesso por índice** ```sql title=Query theme={null} SELECT tupleElement((1, 'hello'), 2) ``` ```response title=Response theme={null} hello ``` **Indexação com índices negativos** ```sql title=Query theme={null} SELECT tupleElement((1, 'hello'), -1) ``` ```response title=Response theme={null} hello ``` **Tupla nomeada com tabela** ```sql title=Query theme={null} CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory; INSERT INTO example VALUES (('Alice', 30)); SELECT tupleElement(values, 'name') FROM example; ``` ```response title=Response theme={null} Alice ``` **Com valor padrão** ```sql title=Query theme={null} SELECT tupleElement((1, 2), 5, 'not_found') ``` ```response title=Response theme={null} not_found ``` **Sintaxe do operador** ```sql title=Query theme={null} SELECT (1, 'hello').2 ``` ```response title=Response theme={null} hello ```
## tupleHammingDistance
Introduzido em: v21.1.0 Retorna a [distância de Hamming](https://en.wikipedia.org/wiki/Hamming_distance) entre duas tuplas do mesmo tamanho. O tipo do resultado é determinado da mesma forma que nas [funções aritméticas](/pt-BR/reference/functions/regular-functions/arithmetic-functions), com base no número de elementos nas tuplas de entrada. ```sql theme={null} SELECT toTypeName(tupleHammingDistance(tuple(0), tuple(0))) AS t1, toTypeName(tupleHammingDistance((0, 0), (0, 0))) AS t2, toTypeName(tupleHammingDistance((0, 0, 0), (0, 0, 0))) AS t3, toTypeName(tupleHammingDistance((0, 0, 0, 0), (0, 0, 0, 0))) AS t4, toTypeName(tupleHammingDistance((0, 0, 0, 0, 0), (0, 0, 0, 0, 0))) AS t5 ``` ```text theme={null} ┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐ │ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │ └───────┴────────┴────────┴────────┴────────┘ ``` **Sintaxe** ```sql theme={null} tupleHammingDistance(t1, t2) ``` **Argumentos** * `t1` — Primeira tupla. [`Tuple(*)`](/pt-BR/reference/data-types/tuple) * `t2` — Segunda tupla. [`Tuple(*)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna a distância de Hamming. [`UInt8/16/32/64`](/pt-BR/reference/data-types/int-uint) **Exemplos** **Exemplo de uso** ```sql title=Query theme={null} SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1)) ``` ```response title=Response theme={null} 2 ``` **Com MinHash para detectar strings quase duplicadas** ```sql title=Query theme={null} SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string) ``` ```response title=Response theme={null} 2 ```
## tupleIntDiv
Introduzido em: v23.8.0 Executa uma divisão inteira com uma tupla de numeradores e uma tupla de denominadores. Retorna uma tupla de quocientes. Se qualquer uma das tuplas contiver elementos não inteiros, o resultado será calculado arredondando cada numerador ou divisor não inteiro para o inteiro mais próximo. A divisão por 0 gera um erro. **Sintaxe** ```sql theme={null} tupleIntDiv(tuple_num, tuple_div) ``` **Argumentos** * `tuple_num` — Tupla de valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `tuple_div` — Tupla de valores do divisor. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com os quocientes. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleIntDiv((15, 10, 5), (5, 5, 5)) ``` ```response title=Response theme={null} (3, 2, 1) ``` **Com decimais** ```sql title=Query theme={null} SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5)) ``` ```response title=Response theme={null} (2, 1, 0) ```
## tupleIntDivByNumber
Introduzido em: v23.8.0 Realiza a divisão inteira de uma tupla de numeradores por um determinado denominador e retorna uma tupla com os quocientes. Se qualquer um dos parâmetros de entrada contiver elementos não inteiros, o resultado será calculado arredondando cada numerador ou divisor não inteiro para o inteiro mais próximo. Um erro será gerado em caso de divisão por 0. **Sintaxe** ```sql theme={null} tupleIntDivByNumber(tuple_num, div) ``` **Argumentos** * `tuple_num` — tupla de valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `div` — O valor do divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla com os quocientes. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleIntDivByNumber((15, 10, 5), 5) ``` ```response title=Response theme={null} (3, 2, 1) ``` **Com decimais** ```sql title=Query theme={null} SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8) ``` ```response title=Response theme={null} (2, 1, 0) ```
## tupleIntDivOrZero
Introduzido na versão: v23.8.0 Assim como [`tupleIntDiv`](#tupleIntDiv), realiza a divisão inteira entre uma tupla de numeradores e uma tupla de denominadores e retorna uma tupla com os quocientes. Em caso de divisão por 0, retorna o quociente como 0 em vez de gerar uma exceção. Se qualquer uma das tuplas contiver elementos não inteiros, o resultado será calculado arredondando cada numerador ou divisor não inteiro para o inteiro mais próximo. **Sintaxe** ```sql theme={null} tupleIntDivOrZero(tuple_num, tuple_div) ``` **Argumentos** * `tuple_num` — tupla com os valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `tuple_div` — tupla com os valores do divisor. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com os quocientes. Retorna 0 para os quocientes em que o divisor é 0. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Com divisores iguais a zero** ```sql title=Query theme={null} SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0)) ``` ```response title=Response theme={null} (0, 0, 0) ```
## tupleIntDivOrZeroByNumber
Introduzido em: v23.8.0 Assim como [`tupleIntDivByNumber`](#tupleIntDivByNumber), faz a divisão inteira de uma tupla de numeradores por um denominador especificado e retorna uma tupla com os quocientes. Não gera um erro em caso de divisor zero; em vez disso, retorna zero como quociente. Se a tupla ou `div` contiver elementos não inteiros, o resultado será calculado arredondando cada numerador ou divisor não inteiro para o inteiro mais próximo. **Sintaxe** ```sql theme={null} tupleIntDivOrZeroByNumber(tuple_num, div) ``` **Argumentos** * `tuple_num` — tupla de valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `div` — O valor do divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla dos quocientes, com `0` para os quocientes cujo divisor é `0`. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5) ``` ```response title=Response theme={null} (3, 2, 1) ``` **Com divisor igual a zero** ```sql title=Query theme={null} SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0) ``` ```response title=Response theme={null} (0, 0, 0) ```
## tupleMinus
Introduzido em: v21.11.0 Calcula a diferença entre os elementos correspondentes de duas tuplas de mesmo tamanho. **Sintaxe** ```sql theme={null} tupleMinus(t1, t2) ``` **Aliases**: `vectorDifference` **Argumentos** * `t1` — Primeira tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `t2` — Segunda tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla contendo os resultados das operações de subtração. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleMinus((1, 2), (2, 3)) ``` ```response title=Response theme={null} (-1, -1) ```
## tupleModulo
Introduzido na versão: v23.8.0 Retorna uma tupla com os restos (módulos) das operações de divisão entre duas tuplas. **Sintaxe** ```sql theme={null} tupleModulo(tuple_num, tuple_mod) ``` **Argumentos** * `tuple_num` — tupla de valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `tuple_mod` — tupla de valores do divisor. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com os restos da divisão. É gerado um erro em caso de divisão por zero. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleModulo((15, 10, 5), (5, 3, 2)) ``` ```response title=Response theme={null} (0, 1, 1) ```
## tupleModuloByNumber
Introduzido em: v23.8.0 Retorna uma tupla com os módulos (restos) das operações de divisão entre uma tupla e um divisor especificado. **Sintaxe** ```sql theme={null} tupleModuloByNumber(tuple_num, div) ``` **Argumentos** * `tuple_num` — tupla dos elementos do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `div` — O valor do divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla com os restos da divisão. Um erro é gerado em caso de divisão por zero. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleModuloByNumber((15, 10, 5), 2) ``` ```response title=Response theme={null} (1, 0, 1) ```
## tupleMultiply
Introduzido em: v21.11.0 Calcula a multiplicação dos elementos correspondentes de duas tuplas de mesmo tamanho. **Sintaxe** ```sql theme={null} tupleMultiply(t1, t2) ``` **Argumentos** * `t1` — Primeira tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `t2` — Segunda tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com os resultados das multiplicações. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleMultiply((1, 2), (2, 3)) ``` ```response title=Response theme={null} (2, 6) ```
## tupleMultiplyByNumber
Introduzido em: v21.11.0 Retorna uma tupla com todos os elementos multiplicados por um número. **Sintaxe** ```sql theme={null} tupleMultiplyByNumber(tuple, number) ``` **Argumentos** * `tuple` — Tupla a ser multiplicada. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `number` — Multiplicador. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla com os elementos multiplicados. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleMultiplyByNumber((1, 2), -2.1) ``` ```response title=Response theme={null} (-2.1, -4.2) ```
## tupleNames
Introduzido em: v24.8.0 Converte uma tupla em um array de nomes de colunas. Para uma tupla na forma `Tuple(a T, b T, ...)`, retorna um array de strings que representam os nomes das colunas da tupla. Se os elementos da tupla não tiverem nomes explícitos, seus índices serão usados como nomes de colunas. **Sintaxe** ```sql theme={null} tupleNames(tuple) ``` **Argumentos** * Nenhum. **Valor retornado** **Exemplos** **típico** ```sql title=Query theme={null} SELECT tupleNames(tuple(1 as a, 2 as b)) ``` ```response title=Response theme={null} ['a','b'] ```
## tupleNegate
Introduzido em: v21.11.0 Calcula o oposto dos elementos da tupla. **Sintaxe** ```sql theme={null} tupleNegate(t) ``` **Argumentos** * `t` — tupla a ser negada. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla com o resultado da negação. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tupleNegate((1, 2)) ``` ```response title=Response theme={null} (-1, -2) ```
## tuplePlus
Introduzido em: v21.11.0 Calcula a soma dos elementos correspondentes de duas tuplas de mesmo tamanho. **Sintaxe** ```sql theme={null} tuplePlus(t1, t2) ``` **Aliases**: `vectorSum` **Argumentos** * `t1` — Primeira tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `t2` — Segunda tupla. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna uma tupla contendo as somas dos elementos correspondentes das tuplas de entrada. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tuplePlus((1, 2), (2, 3)) ``` ```response title=Response theme={null} (3, 5) ```
## tuplePositiveModuloByNumber
Introduzido em: v26.4.0 Retorna uma tupla com os módulos positivos (restos) das divisões entre uma tupla e um determinado divisor. Diferentemente de tupleModuloByNumber, o resultado é sempre não negativo. **Sintaxe** ```sql theme={null} tuplePositiveModuloByNumber(tuple_num, div) ``` **Argumentos** * `tuple_num` — tupla com valores do numerador. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) * `div` — O valor do divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal) **Valor retornado** Retorna uma tupla de restos não negativos. [`Tuple((U)Int*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Float*)`](/pt-BR/reference/data-types/tuple) ou [`Tuple(Decimal)`](/pt-BR/reference/data-types/tuple) **Exemplos** **Uso básico** ```sql title=Query theme={null} SELECT tuplePositiveModuloByNumber((15, 10, 5), 2) ``` ```response title=Response theme={null} (1, 0, 1) ```
## tupleToNameValuePairs
Introduzido em: v21.9.0 Converte uma tupla em um array de pares `(name, value)`. Por exemplo, a tupla `Tuple(n1 T1, n2 T2, ...)` é convertida em `Array(Tuple('n1', T1), Tuple('n2', T2), ...)`. Todos os valores da tupla devem ser do mesmo tipo. **Sintaxe** ```sql theme={null} tupleToNameValuePairs(tuple) ``` **Argumentos** * `tuple` — Tupla nomeada com valores de qualquer tipo. [`Tuple(n1 T1[, n2 T2, ...])`](/pt-BR/reference/data-types/tuple) **Valor retornado** Retorna um array de pares `(name, value)`. [`Array(Tuple(String, T))`](/pt-BR/reference/data-types/array) **Exemplos** **Tupla nomeada** ```sql title=Query theme={null} SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID)) ``` ```response title=Response theme={null} [('1', 1593), ('2', 2502)] ``` **Tupla sem nome** ```sql title=Query theme={null} SELECT tupleToNameValuePairs(tuple(3, 2, 1)) ``` ```response title=Response theme={null} [('1', 3), ('2', 2), ('3', 1)] ```
## untuple
Realiza a substituição sintática de elementos [tupla](/pt-BR/reference/data-types/tuple) no ponto da chamada. Os nomes das colunas resultantes são específicos da implementação e podem mudar. Não presuma nomes de colunas específicos após `untuple`. **Sintaxe** ```sql theme={null} untuple(x) ``` Você pode usar a expressão `EXCEPT` para omitir colunas no resultado da consulta. **Argumentos** * `x` — Uma função `tuple`, uma coluna ou uma tupla de elementos. [Tuple](/pt-BR/reference/data-types/tuple). **Valor retornado** * Nenhum. **Exemplos** Tabela de entrada: ```text theme={null} ┌─key─┬─v1─┬─v2─┬─v3─┬─v4─┬─v5─┬─v6────────┐ │ 1 │ 10 │ 20 │ 40 │ 30 │ 15 │ (33,'ab') │ │ 2 │ 25 │ 65 │ 70 │ 40 │ 6 │ (44,'cd') │ │ 3 │ 57 │ 30 │ 20 │ 10 │ 5 │ (55,'ef') │ │ 4 │ 55 │ 12 │ 7 │ 80 │ 90 │ (66,'gh') │ │ 5 │ 30 │ 50 │ 70 │ 25 │ 55 │ (77,'kl') │ └─────┴────┴────┴────┴────┴────┴───────────┘ ``` Exemplo de uso de uma coluna do tipo `Tuple` como parâmetro da função `untuple`: ```sql title="Query" theme={null} SELECT untuple(v6) FROM kv; ``` ```text title="Response" theme={null} ┌─_ut_1─┬─_ut_2─┐ │ 33 │ ab │ │ 44 │ cd │ │ 55 │ ef │ │ 66 │ gh │ │ 77 │ kl │ └───────┴───────┘ ``` Exemplo de uso da expressão `EXCEPT`: ```sql title="Query" theme={null} SELECT untuple((* EXCEPT (v2, v3),)) FROM kv; ``` ```text title="Response" theme={null} ┌─key─┬─v1─┬─v4─┬─v5─┬─v6────────┐ │ 1 │ 10 │ 30 │ 15 │ (33,'ab') │ │ 2 │ 25 │ 40 │ 6 │ (44,'cd') │ │ 3 │ 57 │ 10 │ 5 │ (55,'ef') │ │ 4 │ 55 │ 80 │ 90 │ (66,'gh') │ │ 5 │ 30 │ 25 │ 55 │ (77,'kl') │ └─────┴────┴────┴────┴───────────┘ ```
## Funções de distância
Todas as funções suportadas estão descritas na [documentação sobre funções de distância](/pt-BR/reference/functions/regular-functions/distance-functions).