Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções Tuple

View as MarkdownEdit this pageReport an issueSet up docs MCP

dotProduct

Introduzido em: v21.11.0

Calcula o produto escalar (produto interno) de dois vetores (tuplas ou arrays de mesmo tamanho). Retorna a soma dos produtos dos elementos correspondentes.

Sintaxe

dotProduct(vector1, vector2)

Aliases: scalarProduct

Argumentos

Valor retornado

Retorna o produto escalar dos dois vetores. Dois arrays BFloat16 acumulam e retornam Float32. (U)Int* ou Float* ou Decimal

Exemplos

Uso básico

SELECT dotProduct((1, 2), (3, 4))
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

flattenTuple(input)

Argumentos

Valor retornado

Retorna uma tupla de saída cujos elementos são os caminhos da entrada original. Tuple(T)

Exemplos

Exemplo de uso

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;
┌─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

tuple([t1[, t2[ ...]])

Argumentos

  • Nenhum.

Valor retornado

Exemplos

típico

SELECT tuple(1, 2)
(1,2)

tupleConcat

Introduzido em: v23.8.0

Combina as tuplas passadas como argumentos.

Sintaxe

tupleConcat(tuple1[, tuple2, [...]])

Argumentos

  • tupleN — Quantidade arbitrária de argumentos do tipo Tuple. Tuple(T)

Valor retornado

Retorna uma tupla que contém todos os elementos das tuplas de entrada. Tuple(T)

Exemplos

Exemplo de uso

SELECT tupleConcat((1, 2), ('a',), (true, false))
(1,2,'a',true,false)

tupleDivide

Introduzido em: v21.11.0

Calcula a divisão elemento a elemento de duas ou mais tuplas do mesmo tamanho, da esquerda para a direita.

Sintaxe

tupleDivide(t1, t2[, tN, ...])

Argumentos

Valor retornado

Retorna uma tupla que contém os quocientes de cada elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tupleDivide((1, 2), (2, 3))
(0.5,0.6666666666666666)

Três tuplas

SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))
(10,5)

tupleDivideByNumber

Introduzido em: v21.11.0

Retorna uma tupla com todos os elementos divididos por um número.

Sintaxe

tupleDivideByNumber(tuple, number)

Argumentos

Valor retornado

Retorna uma tupla com os elementos divididos. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleDivideByNumber((1, 2), 0.5)
(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

tupleElement(tuple, index|name[, default_value])

Argumentos

  • tuple — Uma tupla ou um array de tuplas. Tuple(T) ou Array(Tuple(T))
  • index — Índice da coluna, a partir de 1. const UInt8/16/32/64
  • name — Nome do elemento. const String
  • default_value — Valor padrão retornado quando o índice está fora dos limites ou o elemento não existe. Any

Valor retornado

Retorna o elemento no índice ou com o nome especificado. Any

Exemplos

Acesso por índice

SELECT tupleElement((1, 'hello'), 2)
hello

Indexação com índices negativos

SELECT tupleElement((1, 'hello'), -1)
hello

Tupla nomeada com tabela

CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;
Alice

Com valor padrão

SELECT tupleElement((1, 2), 5, 'not_found')
not_found

Sintaxe do operador

SELECT (1, 'hello').2
hello

tupleHammingDistance

Introduzido em: v21.1.0

Retorna a distância de Hamming entre duas tuplas do mesmo tamanho.

Sintaxe

tupleHammingDistance(t1, t2)

Argumentos

Valor retornado

Retorna a distância de Hamming. UInt8/16/32/64

Exemplos

Exemplo de uso

SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))
2

Com MinHash para detectar strings quase duplicadas

SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)
2

tupleIntDiv

Introduzido em: v23.8.0

Executa a divisão inteira elemento a elemento de duas ou mais tuplas do mesmo tamanho, da esquerda para a direita. Retorna uma tupla de quocientes. Se alguma tupla 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 faz com que uma exceção seja lançada.

Sintaxe

tupleIntDiv(t1, t2[, tN, ...])

Argumentos

Valor retornado

Retorna uma tupla com quocientes inteiros. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))
(3,2,1)

Com números decimais

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))
(2,1,0)

Três tuplas

SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))
(15,5)

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

tupleIntDivByNumber(tuple_num, div)

Argumentos

Valor retornado

Retorna uma tupla com os quocientes. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleIntDivByNumber((15, 10, 5), 5)
(3,2,1)

Com decimais

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)
(2,1,0)

tupleIntDivOrZero

Introduzido na versão: v23.8.0

Assim como tupleIntDiv, realiza a divisão inteira elemento a elemento entre duas ou mais tuplas do mesmo tamanho, aplicada da esquerda para a direita. Em caso de divisão por 0, retorna 0 para esse elemento 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

tupleIntDivOrZero(t1, t2[, tN, ...])

Argumentos

Valor retornado

Retorna uma tupla de quocientes inteiros, com 0 para qualquer elemento em que o divisor seja 0. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Com divisores iguais a zero

SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))
(0,0,0)

Três tuplas

SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))
(15,5)

tupleIntDivOrZeroByNumber

Introduzido em: v23.8.0

Assim como 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

tupleIntDivOrZeroByNumber(tuple_num, div)

Argumentos

Valor retornado

Retorna uma tupla dos quocientes, com 0 para os quocientes cujo divisor é 0. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)
(3,2,1)

Com divisor igual a zero

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)
(0,0,0)

tupleMinus

Introduzido em: v21.11.0

Calcula a diferença elemento a elemento entre duas ou mais tuplas do mesmo tamanho, da esquerda para a direita.

Sintaxe

tupleMinus(t1, t2[, tN, ...])

Aliases: vectorDifference

Argumentos

Valor retornado

Retorna uma tupla com as diferenças elemento a elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tupleMinus((1, 2), (2, 3))
(-1,-1)

Três tuplas

SELECT tupleMinus((10, 10), (3, 4), (2, 1))
(5,5)

tupleModulo

Introduzido em: v23.8.0

Retorna uma tupla com os restos da divisão, elemento a elemento, entre duas ou mais tuplas do mesmo tamanho, aplicada da esquerda para a direita.

Sintaxe

tupleModulo(t1, t2[, tN, ...])

Argumentos

Valor retornado

Retorna uma tupla com os restos de cada elemento. Uma exceção é lançada em caso de divisão por zero. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tupleModulo((15, 10, 5), (5, 3, 2))
(0,1,1)

Três tuplas

SELECT tupleModulo((10, 20), (7, 9), (3, 5))
(0,2)

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

tupleModuloByNumber(tuple_num, div)

Argumentos

Valor retornado

Retorna uma tupla com os restos da divisão. Um erro é gerado em caso de divisão por zero. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleModuloByNumber((15, 10, 5), 2)
(1,0,1)

tupleMultiply

Introduzido na versão: v21.11.0

Calcula o produto elemento a elemento de duas ou mais tuplas do mesmo tamanho.

Sintaxe

tupleMultiply(t1, t2[, tN, ...])

Argumentos

Valor retornado

Retorna uma tupla contendo os produtos calculados elemento a elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tupleMultiply((1, 2), (2, 3))
(2,6)

Três tuplas

SELECT tupleMultiply((1, 2), (2, 3), (1, 2))
(2,12)

tupleMultiplyByNumber

Introduzido em: v21.11.0

Retorna uma tupla com todos os elementos multiplicados por um número.

Sintaxe

tupleMultiplyByNumber(tuple, number)

Argumentos

Valor retornado

Retorna uma tupla com os elementos multiplicados. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleMultiplyByNumber((1, 2), -2.1)
(-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

tupleNames(tuple)

Argumentos

  • Nenhum.

Valor retornado

Exemplos

típico

SELECT tupleNames(tuple(1 as a, 2 as b))
['1','2']

tupleNegate

Introduzido em: v21.11.0

Calcula o oposto dos elementos da tupla.

Sintaxe

tupleNegate(t)

Argumentos

Valor retornado

Retorna uma tupla com o resultado da negação. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tupleNegate((1, 2))
(-1,-2)

tuplePlus

Introduzido em: v21.11.0

Calcula a soma elemento a elemento de duas ou mais tuplas do mesmo tamanho.

Sintaxe

tuplePlus(t1, t2[, tN, ...])

Aliases: vectorSum

Argumentos

Valor retornado

Retorna uma tupla contendo as somas de cada elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Duas tuplas

SELECT tuplePlus((1, 2), (2, 3))
(3,5)

Três tuplas

SELECT tuplePlus((1, 2), (2, 3), (3, 4))
(6,9)

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

tuplePositiveModuloByNumber(tuple_num, div)

Argumentos

Valor retornado

Retorna uma tupla de restos não negativos. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Exemplos

Uso básico

SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)
(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

tupleToNameValuePairs(tuple)

Argumentos

Valor retornado

Retorna um array de pares (name, value). Array(Tuple(String, T))

Exemplos

Tupla nomeada

SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))
[('1',1593),('2',2502)]

Tupla sem nome

SELECT tupleToNameValuePairs(tuple(3, 2, 1))
[('1',3),('2',2),('3',1)]

untuple

Realiza a substituição sintática de elementos tupla 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

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.

Valor retornado

  • Nenhum.

Exemplos

Tabela de entrada:

┌─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:

Querysql
SELECT untuple(v6) FROM kv;
Responsetext
┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

Exemplo de uso da expressão EXCEPT:

Querysql
SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;
Responsetext
┌─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.

Navigation