Funções Tuple - ClickHouse Documentation

A documentação abaixo é gerada a partir da tabela de sistema system.functions.

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

vector1 — Primeiro vetor. Array(T) ou Tuple(T)
vector2 — Segundo vetor. Deve ter o mesmo tamanho do primeiro vetor. Array(T) ou Tuple(T)

Valor retornado Retorna o produto escalar dos dois vetores. (U)Int* ou Float* ou Decimal Exemplos Uso básico

Query

SELECT dotProduct((1, 2), (3, 4))

Response

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

input — Tupla nomeada e aninhada a ser achatada. Tuple(n1 T1[, n2 T2, ... ])

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

Query

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

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

Query

SELECT tuple(1, 2)

Response

(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

Query

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

Response

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

A divisão por zero retornará inf.

Sintaxe

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

Argumentos

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

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

Query

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

Response

(0.5, 0.6666666666666666)

Três tuplas

Query

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

Response

(10, 5)

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

tupleDivideByNumber(tuple, number)

Argumentos

tuple — tupla a ser dividida. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
number — Divisor. (U)Int* ou Float* ou Decimal

Valor retornado Retorna uma tupla com os elementos divididos. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

SELECT tupleDivideByNumber((1, 2), 0.5)

Response

(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

Query

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

Response

hello

Indexação com índices negativos

Query

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

Response

hello

Tupla nomeada com tabela

Query

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

Response

Alice

Com valor padrão

Query

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

Response

not_found

Sintaxe do operador

Query

SELECT (1, 'hello').2

Response

hello

tupleHammingDistance

Introduzido em: v21.1.0 Retorna a distância de Hamming entre duas tuplas do mesmo tamanho.

O tipo do resultado é determinado da mesma forma que nas funções aritméticas, com base no número de elementos nas tuplas de entrada.

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

┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘

Sintaxe

tupleHammingDistance(t1, t2)

Argumentos

t1 — Primeira tupla. Tuple(*)
t2 — Segunda tupla. Tuple(*)

Valor retornado Retorna a distância de Hamming. UInt8/16/32/64 Exemplos Exemplo de uso

Query

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

Response

Com MinHash para detectar strings quase duplicadas

Query

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

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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Valor retornado Retorna uma tupla com quocientes inteiros. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Duas tuplas

Query

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))

Response

(3, 2, 1)

Com números decimais

Query

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))

Response

(2, 1, 0)

Três tuplas

Query

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

Response

(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

tuple_num — tupla de valores do numerador. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
div — O valor do divisor. (U)Int* ou Float* ou Decimal

Valor retornado Retorna uma tupla com os quocientes. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

SELECT tupleIntDivByNumber((15, 10, 5), 5)

Response

(3, 2, 1)

Com decimais

Query

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)

Response

(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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

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

Query

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

Response

(0, 0, 0)

Três tuplas

Query

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

Response

(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

tuple_num — tupla de valores do numerador. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
div — O valor do divisor. (U)Int* ou Float* ou Decimal

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

Query

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

Response

(3, 2, 1)

Com divisor igual a zero

Query

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

Response

(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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Valor retornado Retorna uma tupla com as diferenças elemento a elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Duas tuplas

Query

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

Response

(-1, -1)

Três tuplas

Query

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

Response

(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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

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

Query

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

Response

(0, 1, 1)

Três tuplas

Query

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

Response

(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

tuple_num — tupla dos elementos do numerador. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
div — O valor do divisor. (U)Int* ou Float* ou 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*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

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

Response

(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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais tuplas de entrada adicionais. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Valor retornado Retorna uma tupla contendo os produtos calculados elemento a elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Duas tuplas

Query

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

Response

(2, 6)

Três tuplas

Query

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

Response

(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

tuple — Tupla a ser multiplicada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
number — Multiplicador. (U)Int* ou Float* ou Decimal

Valor retornado Retorna uma tupla com os elementos multiplicados. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

SELECT tupleMultiplyByNumber((1, 2), -2.1)

Response

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

Query

SELECT tupleNames(tuple(1 as a, 2 as b))

Response

['a','b']

tupleNegate

Introduzido em: v21.11.0 Calcula o oposto dos elementos da tupla. Sintaxe

tupleNegate(t)

Argumentos

t — tupla a ser negada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Valor retornado Retorna uma tupla com o resultado da negação. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

SELECT tupleNegate((1, 2))

Response

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

t1 — Primeira tupla de entrada. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
t2, ..., tN — Uma ou mais outras tuplas de entrada. Todas as tuplas devem ter o mesmo tamanho. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)

Valor retornado Retorna uma tupla contendo as somas de cada elemento. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Duas tuplas

Query

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

Response

(3, 5)

Três tuplas

Query

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

Response

(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

tuple_num — tupla com valores do numerador. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal)
div — O valor do divisor. (U)Int* ou Float* ou Decimal

Valor retornado Retorna uma tupla de restos não negativos. Tuple((U)Int*) ou Tuple(Float*) ou Tuple(Decimal) Exemplos Uso básico

Query

SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)

Response

(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

tuple — Tupla nomeada com valores de qualquer tipo. Tuple(n1 T1[, n2 T2, ...])

Valor retornado Retorna um array de pares (name, value). Array(Tuple(String, T)) Exemplos Tupla nomeada

Query

SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))

Response

[('1', 1593), ('2', 2502)]

Tupla sem nome

Query

SELECT tupleToNameValuePairs(tuple(3, 2, 1))

Response

[('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:

Query

SELECT untuple(v6) FROM kv;

Response

┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

Exemplo de uso da expressão EXCEPT:

Query

SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;

Response

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

​dotProduct

​flattenTuple

​tuple

​tupleConcat

​tupleDivide

​tupleDivideByNumber

​tupleElement

​tupleHammingDistance

​tupleIntDiv

​tupleIntDivByNumber

​tupleIntDivOrZero

​tupleIntDivOrZeroByNumber

​tupleMinus

​tupleModulo

​tupleModuloByNumber

​tupleMultiply

​tupleMultiplyByNumber

​tupleNames

​tupleNegate

​tuplePlus

​tuplePositiveModuloByNumber

​tupleToNameValuePairs

​untuple

​Funções de distância

dotProduct

flattenTuple

tuple

tupleConcat

tupleDivide

tupleDivideByNumber

tupleElement

tupleHammingDistance

tupleIntDiv

tupleIntDivByNumber

tupleIntDivOrZero

tupleIntDivOrZeroByNumber

tupleMinus

tupleModulo

tupleModuloByNumber

tupleMultiply

tupleMultiplyByNumber

tupleNames

tupleNegate

tuplePlus

tuplePositiveModuloByNumber

tupleToNameValuePairs

untuple

Funções de distância