Outras funções

Documentação da categoria “Outras funções”

A documentação das funções abaixo é gerada a partir da system table system.functions.

​

FQDN

Introduzido em: v20.1.0

Retorna o nome de domínio totalmente qualificado do servidor ClickHouse.

Sintaxe

FQDN()

Aliases: fullHostName

Argumentos

• Nenhum.

Valor retornado

Retorna o nome de domínio totalmente qualificado do servidor ClickHouse. String

Exemplos

Exemplo de uso

Query

SELECT fqdn()

Response

┌─FQDN()──────────────────────────┐
│ clickhouse.us-east-2.internal │
└─────────────────────────────────┘

​

MACNumToString

Introduzido em: v1.1.0

Interpreta um número UInt64 como um endereço MAC no formato big-endian. Retorna o endereço MAC correspondente no formato AA:BB:CC:DD:EE:FF (números hexadecimais separados por dois-pontos) como string.

Sintaxe

MACNumToString(num)

Argumentos

• num — número UInt64. UInt64

Valor retornado

Retorna um endereço MAC no formato AA:BB:CC:DD:EE:FF. String

Exemplos

Exemplo de uso

Query

SELECT MACNumToString(149809441867716) AS mac_address;

Response

┌─mac_address───────┐
│ 88:00:11:22:33:44 │
└───────────────────┘

​

MACStringToNum

Introduzida em: v1.1.0

A função inversa de MACNumToString. Se o endereço MAC estiver em um formato inválido, retorna 0.

Sintaxe

MACStringToNum(s)

Argumentos

• s — Endereço MAC em formato de string. String

Valor retornado

Retorna um número do tipo UInt64. UInt64

Exemplos

Exemplo de uso

Query

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

Response

1108152157446

​

MACStringToOUI

Introduzido em: v1.1.0

Dado um endereço MAC no formato AA:BB:CC:DD:EE:FF (números hexadecimais separados por dois-pontos), retorna os três primeiros octetos como um número UInt64. Se o endereço MAC tiver um formato inválido, retorna 0.

Sintaxe

MACStringToOUI(s)

Argumentos

• s — endereço MAC em formato de string. String

Valor retornado

Os três primeiros octetos como um número UInt64. UInt64

Exemplos

Exemplo de uso

Query

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

Response

20566

​

authenticatedUser

Introduzido em: v25.11.0

Se o usuário da sessão tiver sido alterado com o comando EXECUTE AS, esta função retorna o nome do usuário original usado para autenticação e criação da sessão. Alias: authUser()

Sintaxe

authenticatedUser()

Aliases: authUser

Argumentos

• Nenhum.

Valor retornado

O nome do usuário autenticado. String

Exemplos

Exemplo de uso

Query

EXECUTE as u1;
            SELECT currentUser(), authenticatedUser();

Response

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

​

bar

Introduzido em: v1.1.0

Cria um gráfico de barras. Desenha uma faixa com largura proporcional a (x - min) e igual a width caracteres quando x = max. A faixa é desenhada com precisão de um oitavo de caractere.

Sintaxe

bar(x, min, max[, width])

Argumentos

• x — Tamanho a exibir. (U)Int* ou Float* ou Decimal
• min — O valor mínimo. (U)Int* ou Float* ou Decimal
• max — O valor máximo. (U)Int* ou Float* ou Decimal
• width — Opcional. A largura da barra em caracteres. O padrão é 80. const (U)Int* ou const Float* ou const Decimal

Valor retornado

Retorna uma barra em arte Unicode como string. String

Exemplos

Exemplo de uso

Query

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600000, 20) AS bar
FROM test.hits
GROUP BY h
ORDER BY h ASC

Response

┌──h─┬──────c─┬─bar────────────────┐
│  0 │ 292907 │ █████████▋         │
│  1 │ 180563 │ ██████             │
│  2 │ 114861 │ ███▋               │
│  3 │  85069 │ ██▋                │
│  4 │  68543 │ ██▎                │
│  5 │  78116 │ ██▌                │
│  6 │ 113474 │ ███▋               │
│  7 │ 170678 │ █████▋             │
│  8 │ 278380 │ █████████▎         │
│  9 │ 391053 │ █████████████      │
│ 10 │ 457681 │ ███████████████▎   │
│ 11 │ 493667 │ ████████████████▍  │
│ 12 │ 509641 │ ████████████████▊  │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊  │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍  │
│ 23 │ 400397 │ █████████████▎     │
└────┴────────┴────────────────────┘

​

blockNumber

Introduzido em: v1.1.0

Retorna um número de sequência monotonicamente crescente do bloco que contém a linha. O número do bloco retornado é atualizado na medida do possível, ou seja, pode não ser totalmente preciso.

Sintaxe

blockNumber()

Argumentos

• Nenhum.

Valor retornado

Número de sequência do bloco de dados em que a linha se encontra. UInt64

Exemplos

Uso básico

Query

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

Response

┌─blockNumber()─┐
│             7 │
│             7 │
└───────────────┘
┌─blockNumber()─┐
│             8 │
│             8 │
└───────────────┘
┌─blockNumber()─┐
│             9 │
│             9 │
└───────────────┘
┌─blockNumber()─┐
│            10 │
│            10 │
└───────────────┘
┌─blockNumber()─┐
│            11 │
│            11 │
└───────────────┘

​

blockSerializedSize

Introduzido em: v20.3.0

Retorna o tamanho não comprimido, em bytes, de um bloco de valores em disco.

Sintaxe

blockSerializedSize(x1[, x2[, ...]])

Argumentos

• x1[, x2, ...] — Qualquer quantidade de valores dos quais se deseja obter o tamanho não comprimido do bloco. Any

Valor retornado

Retorna o número de bytes que serão gravados em disco para um bloco de valores sem compressão. UInt64

Exemplos

Exemplo de uso

Query

SELECT blockSerializedSize(maxState(1)) AS x;

Response

┌─x─┐
│ 2 │
└───┘

​

blockSize

Introduzido em: v1.1.0

No ClickHouse, as consultas são processadas em blocos (fragmentos). Esta função retorna o tamanho (número de linhas) do bloco em que a função é chamada.

Sintaxe

blockSize()

Argumentos

• Nenhum.

Valor retornado

Retorna o número de linhas do bloco atual. UInt64

Exemplos

Exemplo de uso

Query

SELECT blockSize()
FROM system.numbers LIMIT 5

Response

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

​

buildId

Introduzido em: v20.5.0

Retorna o ID de compilação gerado por um compilador para o binário do servidor ClickHouse em execução. Se for executada no contexto de uma tabela distribuída, essa função gera uma coluna comum com valores correspondentes a cada shard. Caso contrário, produz um valor constante.

Sintaxe

buildId()

Argumentos

• Nenhum.

Valor retornado

Retorna o ID da compilação. String

Exemplos

Exemplo de uso

Query

SELECT buildId()

Response

┌─buildId()────────────────────────────────┐
│ AB668BEF095FAA6BD26537F197AC2AF48A927FB4 │
└──────────────────────────────────────────┘

​

byteSize

Introduzido em: v21.1.0

Retorna uma estimativa do tamanho em bytes não comprimido de seus argumentos na memória. Para argumentos String, a função retorna o comprimento da string + 8 (comprimento). Se a função tiver vários argumentos, ela acumula seus tamanhos em bytes.

Sintaxe

byteSize(arg1[, arg2, ...])

Argumentos

• arg1[, arg2, ...] — Valores de qualquer tipo de dado cujos tamanhos em bytes não comprimidos devem ser estimados. Any

Valor retornado

Retorna uma estimativa do tamanho em bytes dos argumentos na memória. UInt64

Exemplos

Exemplo de uso

Query

SELECT byteSize('string')

Response

┌─byteSize('string')─┐
│                 15 │
└────────────────────┘

Vários argumentos

Query

SELECT byteSize(NULL, 1, 0.3, '')

Response

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         19 │
└────────────────────────────┘

​

catboostEvaluate

Introduzido em: v22.9.0

Avalia um modelo CatBoost externo. CatBoost é uma biblioteca de gradient boosting de código aberto desenvolvida pela Yandex para aprendizado de máquina. Aceita um caminho para um modelo CatBoost e argumentos do modelo (features).

Pré-requisitos

1. Compile a biblioteca de avaliação do CatBoost

Antes de avaliar modelos CatBoost, a biblioteca libcatboostmodel.<so|dylib> deve estar disponível. Consulte a documentação do CatBoost para saber como compilá-la.

Em seguida, especifique o caminho para libcatboostmodel.<so|dylib> na configuração do ClickHouse:

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

Por motivos de segurança e isolamento, a avaliação do modelo não é executada no processo do servidor, mas no processo clickhouse-library-bridge. Na primeira execução de catboostEvaluate(), o servidor inicia o processo clickhouse-library-bridge, caso ele ainda não esteja em execução. Ambos os processos se comunicam por meio de uma interface HTTP. Por padrão, a porta 9012 é usada. Uma porta diferente pode ser especificada da seguinte forma - isso é útil se a porta 9012 já estiver atribuída a outro serviço.

<library_bridge>
    <port>9019</port>
</library_bridge>

2. Treine um modelo catboost usando a libcatboost

Consulte Training and applying models para saber como treinar modelos catboost com base em um conjunto de dados de treinamento.

Sintaxe

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

Argumentos

• path_to_model — Caminho para o modelo CatBoost. const String
• feature — Um ou mais atributos/argumentos do modelo. Float*

Valor retornado

Retorna o resultado da avaliação do modelo. Float64

Exemplos

catboostEvaluate

Query

SELECT catboostEvaluate('/root/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

Response

4.695691092573497

​

colorOKLABToSRGB

Introduzido em: v26.2.0

Converte uma cor do espaço de cores perceptual OKLab para o espaço de cores sRGB.

A cor de entrada é especificada no espaço de cores OKLab. Se os valores de entrada estiverem fora das faixas típicas do OKLab, o resultado dependerá da implementação.

O OKLab usa três componentes:

• L: luminosidade perceptual (normalmente no intervalo [0..1])
  • a: eixo oponente verde-vermelho
  • b: eixo oponente azul-amarelo

Os componentes a e b são teoricamente ilimitados, mas, na prática, ficam entre -0.4 e 0.4. O OKLab foi projetado para ser perceptualmente uniforme e, ao mesmo tempo, ter baixo custo computacional.

A conversão foi concebida para ser o inverso de colorSRGBToOKLAB e consiste em os seguintes estágios:

1. Conversão de OKLab para Linear sRGB. 2) Conversão de Linear sRGB para sRGB com codificação gama.

O argumento opcional gamma especifica o expoente usado ao converter de Linear sRGB para valores RGB com codificação gama. Se não for especificado, será usado um valor gamma padrão para manter a consistência com colorSRGBToOKLAB.

Para mais informações sobre o espaço de cores OKLab e sua relação com sRGB, consulte https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab .

Sintaxe

colorOKLABToSRGB(tuple [, gamma])

Argumentos

• tuple — Uma tupla de três valores numéricos L, a, b, em que L está no intervalo [0...1]. Tuple(Float64, Float64, Float64)
• gamma — Opcional. O expoente usado para converter o Linear sRGB de volta para sRGB, aplicando (x ^ (1 / gamma)) * 255 a cada canal x. O padrão é 2.2. Float64

Valor retornado

Retorna uma tupla (R, G, B) que representa valores de cor sRGB. Tuple(Float64, Float64, Float64)

Exemplos

Converta OKLAB para sRGB (Float)

Query

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

Response

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

Converter OKLAB para sRGB (UInt8)

Query

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

Response

┌─RGB──────────┐
│ (255,0,0)    │
└──────────────┘

​

colorOKLCHToSRGB

Introduzido em: v25.7.0

Converte uma cor do espaço de cores perceptivo OKLCH para o conhecido espaço de cores sRGB.

Se L estiver fora do intervalo [0...1], C for negativo ou H estiver fora do intervalo [0...360], o resultado será definido pela implementação.

OKLCH é uma versão cilíndrica do espaço de cores OKLab. Suas três coordenadas são L (a luminosidade no intervalo [0...1]), C (croma >= 0) e H (matiz em graus no intervalo [0...360]). OKLab/OKLCH foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.

A conversão é a inversa de colorSRGBToOKLCH:

1. OKLCH para OKLab. 2) OKLab para Linear sRGB 3) Linear sRGB para sRGB

O segundo argumento, gamma, é usado na última etapa.

Para referências de cores no espaço OKLCH e como elas correspondem às cores sRGB, consulte https://oklch.com/.

Sintaxe

colorOKLCHToSRGB(tuple [, gamma])

Argumentos

• tuple — Uma tupla de três valores numéricos L, C, H, em que L está no intervalo [0...1], C >= 0 e H está no intervalo [0...360]. Tuple(Float64, Float64, Float64)
• gamma — Opcional. O expoente usado para converter Linear sRGB de volta para sRGB, aplicando (x ^ (1 / gamma)) * 255 a cada canal x. O padrão é 2.2. Float64

Valor retornado

Retorna uma tupla (R, G, B) que representa valores de cor sRGB. Tuple(Float64, Float64, Float64)

Exemplos

Converter OKLCH para sRGB

Query

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

Response

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

Converter OKLCH em sRGB (UInt8)

Query

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

Response

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

​

colorSRGBToOKLAB

Introduzido em: v26.2.0

Converte uma cor codificada no espaço de cores sRGB para o espaço de cores OKLAB, perceptualmente uniforme.

Se algum canal de entrada estiver fora de [0...255] ou se o valor de gamma não for positivo, o comportamento depende da implementação.

OKLAB é um espaço de cores perceptualmente uniforme. Suas três coordenadas são L (a luminosidade no intervalo [0...1]), a (eixo Verde-Vermelho) e b (eixo Azul-Amarelo). O OKLab foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.

A conversão consiste em duas etapas:

1. sRGB para Linear sRGB 2) Linear sRGB para OKLab

Sintaxe

colorSRGBToOKLAB(tuple[, gamma])

Argumentos

• tuple — Tupla de três valores R, G, B no intervalo [0...255]. Tuple(UInt8, UInt8, UInt8)
• gamma — Opcional. Expoente usado para linearizar o sRGB, aplicando (x / 255)^gamma a cada canal x. O padrão é 2.2. Float64

Valor retornado

Retorna uma tupla (L, a, b) que representa os valores no espaço de cores OKLAB. Tuple(Float64, Float64, Float64)

Exemplos

Converta sRGB para OKLAB

Query

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

Response

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

​

colorSRGBToOKLCH

Introduzido em: v25.7.0

Converte uma cor codificada no espaço de cores sRGB para o espaço de cores OKLCH, que é perceptualmente uniforme.

Se algum canal de entrada estiver fora de [0...255] ou se o valor de gamma não for positivo, o comportamento é definido pela implementação.

OKLCH é uma versão cilíndrica do espaço de cores OKLab. Suas três coordenadas são L (a luminosidade no intervalo [0...1]), C (croma >= 0) e H (a matiz em graus no intervalo [0...360]). OKLab/OKLCH foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.

A conversão consiste em três etapas:

1. sRGB para Linear sRGB 2) Linear sRGB para OKLab 3) OKLab para OKLCH.

Para ver referências de cores no espaço OKLCH e como elas correspondem às cores sRGB, consulte https://OKLCH.com/.

Sintaxe

colorSRGBToOKLCH(tuple[, gamma])

Argumentos

• tuple — Tuple de três valores R, G, B no intervalo [0...255]. Tuple(UInt8, UInt8, UInt8)
• gamma — Opcional. Expoente usado para linearizar o sRGB, aplicando (x / 255)^gamma a cada canal x. O padrão é 2.2. Float64

Valor retornado

Retorna uma tupla (L, C, H) que representa os valores do espaço de cores OKLCH. Tuple(Float64, Float64, Float64)

Exemplos

Converter sRGB em OKLCH

Query

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

Response

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

​

connectionId

Introduzido em: v21.3.0

Retorna o ID da conexão do cliente que enviou a consulta atual. Esta função é mais útil em cenários de depuração. Ela foi criada para manter a compatibilidade com a função CONNECTION_ID do MySQL. Ela normalmente não é usada em consultas em produção.

Sintaxe

connectionId()

Argumentos

• Nenhum.

Valor retornado

Retorna o ID da conexão do cliente atual. UInt64

Exemplos

Exemplo de uso

Query

SELECT connectionId();

Response

┌─connectionId()─┐
│              0 │
└────────────────┘

​

countDigits

Introduzido em: v20.8.0

Retorna o número de dígitos decimais necessários para representar um valor.

Esta função leva em conta as escalas dos valores decimais, ou seja, calcula o resultado com base no tipo inteiro subjacente, que é (value * scale).

Por exemplo:

• countDigits(42) = 2
• countDigits(42.000) = 5
• countDigits(0.04200) = 4

Você pode verificar se há overflow em Decimal64 com countDigits(x) > 18, embora isso seja mais lento do que isDecimalOverflow.

Sintaxe

countDigits(x)

Argumentos

• x — Um valor inteiro ou decimal. (U)Int* ou Decimal

Valor retornado

Retorna o número de dígitos necessários para representar x. UInt8

Exemplos

Exemplo de uso

Query

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

Response

┌─countDigits(toDecimal32(1, 9))─┬─countDigits(toDecimal32(-1, 9))─┬─countDigits(toDecimal64(1, 18))─┬─countDigits(toDecimal64(-1, 18))─┬─countDigits(toDecimal128(1, 38))─┬─countDigits(toDecimal128(-1, 38))─┐
│                             10 │                              10 │                              19 │                               19 │                               39 │                                39 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

​

currentDatabase

Introduzido em: v1.1.0

Retorna o nome do banco de dados atual. Útil nos parâmetros do mecanismo de tabela em consultas CREATE TABLE nas quais você precisa especificar o banco de dados.

Veja também a instrução SET.

Sintaxe

currentDatabase()

Aliases: current_database, SCHEMA, DATABASE

Argumentos

• Nenhum.

Valor retornado

Retorna o nome do banco de dados atual. String

Exemplos

Exemplo de uso

Query

SELECT currentDatabase()

Response

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

Sintaxe SQL padrão sem parênteses

Query

SELECT CURRENT_DATABASE

Response

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

​

currentProfiles

Introduzido em: v21.9.0

Retorna um array com os perfis de configuração do usuário atual.

Sintaxe

currentProfiles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array de perfis de configuração do usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT currentProfiles();

Response

┌─currentProfiles()─────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics'] │
└───────────────────────────────────────────────┘

​

currentQueryID

Introduzido em: v25.2.0

Retorna o ID da consulta atual.

Sintaxe

currentQueryID()

Aliases: current_query_id

Argumentos

• Nenhum.

Valor retornado

Exemplos

Exemplo

Query

SELECT currentQueryID();

Response

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

​

currentRoles

Introduzido em: v21.9.0

Retorna um array com as funções atribuídas ao usuário atual.

Sintaxe

currentRoles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array das funções atribuídas ao usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT currentRoles();

Response

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────┘

​

currentSchemas

Introduzido em: v23.7.0

Igual à função currentDatabase, mas

• aceita um argumento booleano que é ignorado
• retorna o nome do banco de dados como um Array com um único valor.

A função currentSchemas existe apenas para compatibilidade com o PostgreSQL. Use currentDatabase.

Veja também a instrução SET.

Sintaxe

currentSchemas(bool)

Aliases: current_schemas

Argumentos

• bool — Um valor booleano, que é ignorado. Bool

Valor retornado

Retorna um array com um único elemento contendo o nome do banco de dados atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT currentSchemas(true)

Response

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

​

currentUser

Introduzido em: v20.1.0

Retorna o nome do usuário atual. Em uma consulta distribuída, retorna o nome do usuário que iniciou a consulta.

Sintaxe

currentUser()

Aliases: session_user, user, current_user

Argumentos

• Nenhum.

Valor retornado

Retorna o nome do usuário atual ou, alternativamente, o login do usuário que iniciou a consulta. String

Exemplos

Exemplo de uso

Query

SELECT currentUser()

Response

┌─currentUser()─┐
│ default       │
└───────────────┘

Sintaxe SQL padrão sem parênteses

Query

SELECT CURRENT_USER

Response

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

​

defaultProfiles

Introduzido em: v21.9.0

Retorna um array com os nomes dos perfis de configuração padrão do usuário atual.

Sintaxe

defaultProfiles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array com os nomes dos perfis de configuração padrão do usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT defaultProfiles();

Response

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

​

defaultRoles

Introduzido em: v21.9.0

Retorna um array com as funções padrão do usuário atual.

Sintaxe

defaultRoles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array de funções padrão do usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT defaultRoles();

Response

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────┘

​

defaultValueOfArgumentType

Introduzido em: v1.1.0

Retorna o valor padrão de um determinado tipo de dado. Não inclui os valores padrão de colunas personalizadas definidas pelo usuário.

Sintaxe

defaultValueOfArgumentType(expression)

Argumentos

• expression — Tipo arbitrário de valor ou uma expressão que resulta em um valor de tipo arbitrário. Any

Valor retornado

Retorna 0 para números, uma string vazia para Strings ou NULL para tipos Nullable. UInt8 ou String ou NULL

Exemplos

Exemplo de uso

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

Response

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

Exemplo de Nullable

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

Response

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

​

defaultValueOfTypeName

Introduzido em: v1.1.0

Retorna o valor padrão para o nome de tipo fornecido.

Sintaxe

defaultValueOfTypeName(type)

Argumentos

• type — Uma string que representa um nome de tipo. String

Valor retornado

Retorna o valor padrão para o nome de tipo especificado: 0 para números, uma string vazia para strings, ou NULL para UInt8 Nullable, String Nullable ou NULL

Exemplos

Exemplo de uso

Query

SELECT defaultValueOfTypeName('Int8');

Response

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

Exemplo de Nullable

Query

SELECT defaultValueOfTypeName('Nullable(Int8)');

Response

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

​

displayName

Introduzido em: v22.11.0

Retorna o valor de display_name de config ou o Fully Qualified Domain Name (FQDN) do servidor, caso não esteja definido.

Sintaxe

displayName()

Argumentos

• Nenhum.

Valor retornado

Retorna o valor de display_name da config ou o FQDN do servidor, caso não esteja definido. String

Exemplos

Exemplo de uso

Query

SELECT displayName();

Response

┌─displayName()─┐
│ production    │
└───────────────┘

​

dumpColumnStructure

Introduzido em: v1.1.0

Exibe uma descrição detalhada da estrutura interna de uma coluna e do seu tipo de dado.

Sintaxe

dumpColumnStructure(x)

Argumentos

• x — Valor do qual se deseja obter a descrição. Any

Valor retornado

Retorna uma descrição da estrutura de coluna usada para representar o valor. String

Exemplos

Exemplo de uso

Query

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

Response

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

​

enabledProfiles

Introduzido em: v21.9.0

Retorna um array com os nomes dos perfis de configuração habilitados para o usuário atual.

Sintaxe

enabledProfiles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array com os nomes dos perfis de configuração habilitados para o usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT enabledProfiles();

Response

┌─enabledProfiles()─────────────────────────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics', 'batch_processing'] │
└───────────────────────────────────────────────────────────────────┘

​

enabledRoles

Introduzido em: v21.9.0

Retorna um array das funções habilitadas para o usuário atual.

Sintaxe

enabledRoles()

Argumentos

• Nenhum.

Valor retornado

Retorna um array com os nomes das funções habilitadas para o usuário atual. Array(String)

Exemplos

Exemplo de uso

Query

SELECT enabledRoles();

Response

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────────────────────┘

​

errorCodeToName

Introduzido em: v20.12.0

Retorna o nome textual de um código de erro numérico do ClickHouse. O mapeamento de códigos de erro numéricos para nomes de erro está disponível aqui.

Sintaxe

errorCodeToName(error_code)

Argumentos

• error_code — Código de erro do ClickHouse. (U)Int* ou Float* ou Decimal

Valor retornado

Retorna o nome textual de error_code. String

Exemplos

Exemplo de uso

Query

SELECT errorCodeToName(252);

Response

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

​

file

Introduzido em: v21.3.0

Lê um arquivo como string e carrega os dados na coluna especificada. O conteúdo do arquivo não é interpretado.

Veja também a função de tabela file.

Sintaxe

file(path[, default])

Argumentos

• path — O caminho do arquivo em relação a user_files_path. Suporta curingas *, **, ?, {abc,def} e {N..M}, em que N e M são números e 'abc' e 'def' são strings. String
• default — O valor retornado se o arquivo não existir ou não puder ser acessado. String ou NULL

Valor retornado

Retorna o conteúdo do arquivo como string. String

Exemplos

Inserir arquivos em uma tabela

Query

INSERT INTO table SELECT file('a.txt'), file('b.txt');

Response

​

filesystemAvailable

Introduzido na versão: v20.1.0

Retorna a quantidade de espaço livre no sistema de arquivos que hospeda a persistência da database. O valor retornado é sempre menor que o espaço livre total (filesystemUnreserved), porque parte do espaço é reservada para o sistema operacional.

Sintaxe

filesystemAvailable([disk_name])

Argumentos

• disk_name — Opcional. O nome do disco para o qual encontrar a quantidade de espaço livre. Se omitido, usa o disco padrão. String ou FixedString

Valor retornado

Retorna a quantidade de espaço livre restante em bytes. UInt64

Exemplos

Exemplo de uso

Query

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

Response

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

​

filesystemCapacity

Introduzido em: v20.1.0

Retorna a capacidade do sistema de arquivos em bytes. É necessário que o caminho para o diretório de dados esteja configurado.

Sintaxe

filesystemCapacity([disk_name])

Argumentos

• disk_name — Opcional. O nome do disco cuja capacidade será obtida. Se omitido, usa o disco padrão. String ou FixedString

Valor retornado

Retorna a capacidade do sistema de arquivos em bytes. UInt64

Exemplos

Exemplo de uso

Query

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

Response

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

​

filesystemUnreserved

Introduzido na versão: v22.12.0

Retorna a quantidade total de espaço livre no sistema de arquivos que hospeda a persistência do banco de dados (anteriormente filesystemFree). Veja também filesystemAvailable.

Sintaxe

filesystemUnreserved([disk_name])

Argumentos

• disk_name — Opcional. O nome do disco para o qual será buscada a quantidade total de espaço livre. Se omitido, usa o disco padrão. String ou FixedString

Valor retornado

Retorna a quantidade de espaço livre em bytes. UInt64

Exemplos

Exemplo de uso

Query

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

Response

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

​

finalizeAggregation

Introduzido em: v1.1.0

Dado um estado de agregação, esta função retorna o resultado da agregação (ou o estado finalizado ao usar o combinador -State).

Sintaxe

finalizeAggregation(state)

Argumentos

• state — Estado da agregação. AggregateFunction

Valor retornado

Retorna o resultado final da agregação. Any

Exemplos

Exemplo de uso

Query

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

Response

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

Em combinação com initializeAggregation

Query

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

Response

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

​

flipCoordinates

Introduzido em: v25.11.0

Inverte as coordenadas x e y de objetos geométricos. Essa operação troca latitude e longitude, o que é útil para converter entre diferentes sistemas de coordenadas ou corrigir a ordem das coordenadas.

Para um Point, troca as coordenadas x e y. Para geometrias complexas (LineString, Polygon, MultiPolygon, Ring, MultiLineString), aplica recursivamente a transformação a cada par de coordenadas.

A função oferece suporte tanto a tipos geométricos individuais (Point, Ring, Polygon, MultiPolygon, LineString, MultiLineString) quanto ao tipo Geometry Variant.

Sintaxe

flipCoordinates(geometry)

Argumentos

• geometry — A geometria a ser transformada. Tipos suportados: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)) ou Geometry (uma variante que contém qualquer um desses tipos).

Valor retornado

A geometria com as coordenadas invertidas. O tipo de retorno corresponde ao tipo de entrada. Point ou Ring ou Polygon ou MultiPolygon ou LineString ou MultiLineString ou Geometry

Exemplos

basic_point

Query

SELECT flipCoordinates((1.0, 2.0));

Response

(2.0, 1.0)

anel

Query

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

Response

[(2.0, 1.0), (4.0, 3.0)]

polygon

Query

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

Response

[[(2.0, 1.0), (4.0, 3.0)], [(6.0, 5.0), (8.0, 7.0)]]

geometry_wkt

Query

SELECT flipCoordinates(readWkt('POINT(10 20)'));

Response

(20, 10)

geometry_polygon_wkt

Query

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

Response

[[(0, 0), (0, 5), (5, 5), (5, 0), (0, 0)]]

​

formatQuery

Introduzido em: v23.10.0

Retorna uma versão formatada, possivelmente multilinha, da consulta SQL fornecida. Gera uma exceção em caso de erro de parsing. [example:multiline]

Sintaxe

formatQuery(query)

Argumentos

• query — A consulta SQL a ser formatada. String

Valor retornado

A consulta formatada String

Exemplos

multilinha

Query

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

​

formatQueryOrNull

Introduzido em: v23.11.0

Retorna uma versão formatada, possivelmente em várias linhas, da consulta SQL fornecida. Retorna NULL em caso de erro de parsing. [exemplo:multilinha]

Sintaxe

formatQueryOrNull(query)

Argumentos

• query — A consulta SQL a ser formatada. String

Valor retornado

A consulta formatada String

Exemplos

múltiplas linhas

Query

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

​

formatQuerySingleLine

Introduzido em: v23.10.0

Como formatQuery(), mas a string formatada retornada não contém quebras de linha. Lança uma exceção em caso de erro de parsing. [example:multiline]

Sintaxe

formatQuerySingleLine(query)

Argumentos

• query — A consulta SQL a ser formatada. String

Valor retornado

A consulta formatada String

Exemplos

múltiplas linhas

Query

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

​

formatQuerySingleLineOrNull

Introduzido em: v23.11.0

Como formatQuery(), mas a string formatada retornada não contém nenhuma quebra de linha. Retorna NULL em caso de erro de parsing. [example:multiline]

Sintaxe

formatQuerySingleLineOrNull(query)

Argumentos

• query — A consulta SQL a ser formatada. String

Valor retornado

A consulta formatada String

Exemplos

múltiplas linhas

Query

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

​

formatReadableDecimalSize

Introduzido em: v22.11.0

Dado um tamanho (número de bytes), esta função retorna um valor de tamanho legível e arredondado com sufixo (KB, MB etc.), como string.

A operação oposta desta função é parseReadableSize.

Sintaxe

formatReadableDecimalSize(value[, precision])

Argumentos

• value — Tamanho em bytes. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Opcional. Número de dígitos após o separador decimal. O padrão é 2. const UInt8

Valor retornado

Retorna um tamanho legível e arredondado, com sufixo, na forma de uma String

Exemplos

Formatar tamanhos de arquivo

Query

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

Response

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.02 KB    │
│        1048576 │ 1.05 MB    │
│      192851925 │ 192.85 MB  │
└────────────────┴────────────┘

Com precisão explícita

Query

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

​

formatReadableQuantity

Introduzido em: v20.10.0

Dado um número, esta função retorna uma string com o número arredondado e um sufixo (mil, milhão, bilhão etc.).

Esta função aceita qualquer tipo numérico como entrada, mas, internamente, converte os valores para Float64. Os resultados podem não ser ideais com valores grandes.

Sintaxe

formatReadableQuantity(value[, precision])

Argumentos

• value — Um número a ser formatado. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Opcional. Número de dígitos após o separador decimal. O padrão é 2. const UInt8

Valor retornado

Retorna um número arredondado com sufixo na forma de string. String

Exemplos

Formatar números com sufixos

Query

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

Response

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

Com precisão explícita

Query

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

Response

┌─no_decimals──┬─four_decimals─────┐
│ 99 trillion  │ 98.7654 trillion  │
└──────────────┴───────────────────┘

​

formatReadableSize

Introduzido em: v1.1.0

Dado um tamanho (número de bytes), esta função retorna um tamanho legível e arredondado com sufixo (KiB, MiB etc.) como string.

As operações inversas desta função são parseReadableSize, parseReadableSizeOrZero e parseReadableSizeOrNull. Esta função aceita qualquer tipo numérico como entrada, mas internamente os converte para Float64. Os resultados podem não ser ideais com valores grandes.

Sintaxe

formatReadableSize(value[, precision])

Aliases: FORMAT_BYTES

Argumentos

• value — Tamanho em bytes. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Opcional. Número de dígitos após o separador decimal. O padrão é 2. const UInt8

Valor retornado

Retorna um tamanho legível e arredondado com sufixo, como string. String

Exemplos

Formatar tamanhos de arquivos

Query

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

Response

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

Com precisão explícita

Query

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals──┐
│ 184 MiB     │ 183.9179 MiB   │
└─────────────┴────────────────┘

​

formatReadableTimeDelta

Introduzido em: v20.12.0

Dado um intervalo de tempo (delta) em segundos ou uma expressão INTERVAL, esta função retorna esse delta como uma string em ano/mês/dia/hora/minuto/segundo/milissegundo/microssegundo/nanosegundo.

Esta função aceita qualquer tipo numérico como entrada, mas internamente converte esses valores para Float64. Os resultados podem não ser ideais com valores altos.

Quando uma expressão INTERVAL é passada, seu valor é convertido em segundos. Unidades de INTERVAL de MONTH e superiores (MONTH, QUARTER, YEAR) não são compatíveis, pois não representam um intervalo de tamanho fixo em segundos.

Sintaxe

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

Argumentos

• column — Uma coluna com uma diferença de tempo numérica ou uma expressão INTERVAL. Unidades de intervalo MONTH e superiores não são compatíveis. Float64 ou Interval
• maximum_unit — Opcional. Unidade máxima a ser exibida. Valores aceitos: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Valor padrão: years. const String
• minimum_unit — Opcional. Unidade mínima a ser exibida. Todas as unidades menores são truncadas. Valores aceitos: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Se o valor especificado explicitamente for maior que maximum_unit, uma exceção será lançada. Valor padrão: seconds se maximum_unit for seconds ou maior; caso contrário, nanoseconds. const String

Valor retornado

Retorna uma diferença de tempo como string. String

Exemplos

Exemplo de uso

Query

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

Response

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                        │
│      12345 │ 3 hours, 25 minutes and 45 seconds                             │
│  432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│
└────────────┴────────────────────────────────────────────────────────────────┘

Com a unidade máxima

Query

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

Response

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                         │
│      12345 │ 205 minutes and 45 seconds                                      │
│  432546534 │ 7209108 minutes and 54 seconds                                  │
└────────────┴─────────────────────────────────────────────────────────────────┘

Com uma expressão INTERVAL

Query

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

Response

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

​

fuzzQuery

Introduzido em: v26.2.0

Analisa a string de consulta fornecida e aplica mutações aleatórias na AST (fuzzing). Retorna a consulta com fuzzing como string. Não determinística: cada chamada pode produzir um resultado diferente. Requer allow_fuzz_query_functions = 1.

Sintaxe

fuzzQuery(query)

Argumentos

• query — A consulta SQL a ser submetida a fuzzing. String

Valor retornado

A string da consulta após o fuzzing String

Exemplos

básico

Query

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

Response

​

generateRandomStructure

Introduzido em: v23.5.0

Gera uma estrutura aleatória de tabela no formato column1_name column1_type, column2_name column2_type, ....

Sintaxe

generateRandomStructure([number_of_columns, seed])

Argumentos

• number_of_columns — O número desejado de colunas na estrutura da tabela resultante. Se definido como 0 ou Null, o número de colunas será aleatório, entre 1 e 128. Valor padrão: Null. UInt64
• seed — Semente aleatória para gerar resultados estáveis. Se seed não for especificado ou for definido como Null, será gerado aleatoriamente. UInt64

Valor retornado

Estrutura de tabela gerada aleatoriamente. String

Exemplos

Exemplo de uso

Query

SELECT generateRandomStructure()

Response

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

com o número de colunas especificado

Query

SELECT generateRandomStructure(1)

Response

c1 Map(UInt256, UInt16)

com seed definida

Query

SELECT generateRandomStructure(NULL, 33)

Response

c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70)))

​

generateSerialID

Introduzido em: v25.1.0

Gera e retorna números sequenciais a partir do valor anterior do contador. Esta função recebe um argumento string — um identificador de série — e um valor inicial opcional. O servidor deve ser configurado com Keeper. As séries são armazenadas em nós do Keeper no caminho, que pode ser configurado em series_keeper_path na configuração do servidor.

Sintaxe

generateSerialID(series_identifier[, start_value])

Argumentos

• series_identifier — Identificador da série const String
• start_value — Opcional. Valor inicial do contador. O padrão é 0. Observação: esse valor só é usado ao criar uma nova série e é ignorado se a série já existir UInt*

Valor retornado

Retorna números sequenciais a partir do valor anterior do contador. UInt64

Exemplos

primeira chamada

Query

SELECT generateSerialID('id1')

Response

┌─generateSerialID('id1')──┐
│                        1 │
└──────────────────────────┘

segunda chamada

Query

SELECT generateSerialID('id1')

Response

┌─generateSerialID('id1')──┐
│                        2 │
└──────────────────────────┘

chamada da coluna

Query

SELECT *, generateSerialID('id1') FROM test_table

Response

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')──┐
│         1 │      3 │   3 │                        3 │
│         1 │      1 │   1 │                        4 │
│         1 │      2 │   2 │                        5 │
│         1 │      5 │   5 │                        6 │
│         1 │      4 │   4 │                        7 │
└───────────┴────────┴─────┴──────────────────────────┘

com valor inicial

Query

SELECT generateSerialID('id2', 100)

Response

┌─generateSerialID('id2', 100)──┐
│                           100 │
└───────────────────────────────┘

com valor inicial na segunda chamada

Query

SELECT generateSerialID('id2', 100)

Response

┌─generateSerialID('id2', 100)──┐
│                           101 │
└───────────────────────────────┘

​

getClientHTTPHeader

Introduzido em: v24.5.0

Obtém o valor de um cabeçalho HTTP. Se esse cabeçalho não existir ou se a solicitação atual não for feita pela interface HTTP, a função retornará uma string vazia. Alguns cabeçalhos HTTP (por exemplo, Authentication e X-ClickHouse-*) são restritos.

A configuração allow_get_client_http_header é obrigatória

A função exige que a configuração allow_get_client_http_header esteja habilitada. Por motivos de segurança, essa configuração não vem habilitada por padrão, pois alguns cabeçalhos, como Cookie, podem conter informações sensíveis.

Os cabeçalhos HTTP diferenciam maiúsculas de minúsculas nesta função. Se a função for usada no contexto de uma consulta distribuída, ela retornará um resultado não vazio apenas no nó iniciador.

Sintaxe

getClientHTTPHeader(name)

Argumentos

• name — O nome do cabeçalho HTTP. String

Valor retornado

Retorna o valor do cabeçalho. String

Exemplos

Exemplo de uso

Query

SELECT getClientHTTPHeader('Content-Type');

Response

┌─getClientHTTPHeader('Content-Type')─┐
│ application/x-www-form-urlencoded   │
└─────────────────────────────────────┘

​

getMacro

Introduzido em: v20.1.0

Retorna o valor de uma macro do arquivo de configuração do servidor. As macros são definidas na seção <macros> do arquivo de configuração e podem ser usadas para diferenciar servidores por nomes convenientes, mesmo que tenham hostname complexos. Se a função for executada no contexto de uma tabela distribuída, ela gerará uma coluna normal com valores correspondentes a cada shard.

Sintaxe

getMacro(name)

Argumentos

• name — O nome da macro a ser obtida. const String

Valor retornado

Retorna o valor da macro especificada. String

Exemplos

Uso básico

Query

SELECT getMacro('test');

Response

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

​

getMaxTableNameLengthForDatabase

Introduzido na versão: v25.1.0

Retorna o comprimento máximo do nome da tabela no banco de dados especificado.

Sintaxe

getMaxTableNameLengthForDatabase(database_name)

Argumentos

• database_name — O nome do banco de dados especificado. String

Valor retornado

Retorna o comprimento do maior nome de tabela, um Integer

Exemplos

típico

Query

SELECT getMaxTableNameLengthForDatabase('default');

Response

┌─getMaxTableNameLengthForDatabase('default')─┐
            │                                         206 │
            └─────────────────────────────────────────────┘

​

getMergeTreeSetting

Introduzido em: v25.6.0

Retorna o valor atual de uma configuração do MergeTree.

Sintaxe

getMergeTreeSetting(setting_name)

Argumentos

• setting_name — O nome da configuração. String

Valor retornado

Retorna o valor atual da configuração do MergeTree.

Exemplos

Exemplo de uso

Query

SELECT getMergeTreeSetting('index_granularity');

Response

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

​

getOSKernelVersion

Introduzido em: v21.11.0

Retorna uma string com a versão do kernel do sistema operacional.

Sintaxe

getOSKernelVersion()

Argumentos

• Nenhum.

Valor retornado

Retorna a versão atual do kernel do sistema operacional. String

Exemplos

Exemplo de uso

Query

SELECT getOSKernelVersion();

Response

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

​

getServerPort

Introduzido em: v21.10.0

Retorna o número da porta do servidor para um determinado protocolo.

Sintaxe

getServerPort(port_name)

Argumentos

• port_name — Nome da porta. String

Valor retornado

Retorna o número da porta do servidor. UInt16

Exemplos

Exemplo de uso

Query

SELECT getServerPort('tcp_port');

Response

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

​

getServerSetting

Introduzido em: v25.6.0

Retorna o valor definido no momento para a configuração do servidor informada.

Sintaxe

getServerSetting(setting_name')

Argumentos

• setting_name — O nome da configuração do servidor. String

Valor retornado

Retorna o valor atual da configuração do servidor. Any

Exemplos

Exemplo de uso

Query

SELECT getServerSetting('allow_use_jemalloc_memory');

Response

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

​

getSetting

Introduzido em: v20.7.0

Retorna o valor atual de uma configuração.

Sintaxe

getSetting(setting_name)

Argumentos

• setting_Name — O nome da configuração. const String

Valor retornado

Retorna o valor atual da configuração. Any

Exemplos

Exemplo de uso

Query

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

Response

┌─getSetting('⋯_analyzer')─┐
│ true                     │
└──────────────────────────┘
┌─getSetting('⋯_analyzer')─┐
│ false                    │
└──────────────────────────┘

​

getSettingOrDefault

Introduzido em: v24.10.0

Retorna o valor atual de uma configuração ou, caso ela não esteja definida no perfil atual, o valor padrão especificado no segundo argumento.

Sintaxe

getSettingOrDefault(setting_name, default_value)

Argumentos

• setting_name — O nome da configuração. String
• default_value — Valor a ser retornado caso custom_setting não esteja definida. O valor pode ser de qualquer tipo de dado ou Null.

Valor retornado

Retorna o valor atual da configuração especificada ou default_value caso a configuração não esteja definida.

Exemplos

Exemplo de uso

Query

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

Response

my_value
100
NULL

​

getSizeOfEnumType

Introduzido em: v1.1.0

Retorna o número de campos no Enum fornecido.

Sintaxe

getSizeOfEnumType(x)

Argumentos

• x — Valor do tipo Enum. Enum

Valor retornado

Retorna o número de campos cujos valores de entrada são do tipo Enum. UInt8/16

Exemplos

Exemplo de uso

Query

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

Response

┌─x─┐
│ 2 │
└───┘

​

getSubcolumn

Introduzido em: v23.3.0

Recebe uma expressão ou identificador e uma string constante com o nome da subcoluna.

Retorna a subcoluna solicitada, extraída da expressão.

Sintaxe

getSubcolumn(nested_value, subcolumn_name)

Argumentos

• Nenhum.

Valor retornado

Exemplos

getSubcolumn

Query

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')

Response

​

getTypeSerializationStreams

Introduzido em: v22.6.0

Enumera os caminhos de stream de um tipo de dado. Esta função se destina a uso em desenvolvimento.

Sintaxe

getTypeSerializationStreams(col)

Argumentos

• col — Coluna ou representação textual de um tipo de dado a partir do qual o tipo de dado será detectado. Any

Valor retornado

Retorna um array com todos os caminhos dos substreams de serialização. Array(String)

Exemplos

tuple

Query

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

Response

['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

map

Query

SELECT getTypeSerializationStreams('Map(String, Int64)')

Response

['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

​

globalVariable

Introduzido em: v20.5.0

Recebe um argumento String constante e retorna o valor da variável global com esse nome. Esta função é destinada à compatibilidade com o MySQL e não é necessária nem útil para a operação normal do ClickHouse. Apenas algumas variáveis globais fictícias estão definidas.

Sintaxe

globalVariable(name)

Argumentos

• name — Nome da variável global. String

Valor retornado

Retorna o valor da variável name. Any

Exemplos

globalVariable

Query

SELECT globalVariable('max_allowed_packet')

Response

67108864

​

hasColumnInTable

Introduzido em: v1.1.0

Verifica se uma coluna específica existe em uma tabela de um banco de dados. Para elementos em uma estrutura de dados aninhada, a função verifica a existência de uma coluna. Para a própria estrutura de dados aninhada, a função retorna 0.

Sintaxe

hasColumnInTable([hostname[, username[, password]],]database, table, column)

Argumentos

• database — Nome do banco de dados. const String
• table — Nome da tabela. const String
• column — Nome da coluna. const String
• hostname — Opcional. Nome do servidor remoto em que a verificação será realizada. const String
• username — Opcional. Nome de usuário do servidor remoto. const String
• password — Opcional. Senha do servidor remoto. const String

Valor retornado

Retorna 1 se a coluna informada existir, 0 caso contrário. UInt8

Exemplos

Verificar uma coluna existente

Query

SELECT hasColumnInTable('system','metrics','metric')

Response

1

Verifique uma coluna inexistente

Query

SELECT hasColumnInTable('system','metrics','non-existing_column')

Response

0

​

hasThreadFuzzer

Introduzido em: v20.6.0

Retorna se o thread fuzzer está habilitado. Esta função só é útil para testes e depuração.

Sintaxe

hasThreadFuzzer()

Argumentos

• Nenhum.

Valor retornado

Indica se o Thread Fuzzer está ativo. UInt8

Exemplos

Verificar o status do Thread Fuzzer

Query

SELECT hasThreadFuzzer()

Response

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

​

highlightQuery

Introduzido em: v26.5.0

Analisa uma string de consulta em ClickHouse SQL e retorna um array de faixas destacadas para realce de sintaxe. Cada faixa é uma tupla nomeada com a posição inicial (em bytes), a posição final e o tipo de destaque. Os tipos de destaque descrevem o papel sintático do fragmento (palavra-chave, identificador, função etc.) e podem ser usados para atribuir cores na UI. Em padrões de string de LIKE e REGEXP, metacaracteres e caracteres de escape são destacados separadamente.

Sintaxe

highlightQuery(query)

Argumentos

• query — Uma string de consulta em ClickHouse SQL. String.

Valor retornado

Um array de tuplas nomeadas (begin UInt64, end UInt64, type Enum8(...)) que representa intervalos destacados. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

Exemplos

simples

Query

SELECT highlightQuery('SELECT 1')

Response

[(0,6,'keyword'),(7,8,'number')]

​

hostName

Introduzido em: v20.5.0

Retorna o nome do host em que esta função foi executada. Se a função for executada em um servidor remoto (processamento distribuído), o nome desse servidor remoto será retornado. Se a função for executada no contexto de uma tabela distribuída, ela gera uma coluna normal com valores correspondentes a cada shard. Caso contrário, produz um valor constante.

Sintaxe

hostName()

Aliases: hostname

Argumentos

• Nenhum.

Valor retornado

Retorna o nome do host. String

Exemplos

Exemplo de uso

Query

SELECT hostName()

Response

┌─hostName()─┐
│ clickhouse │
└────────────┘

​

icebergBucket

Introduzido em: v25.5.0

Implementa a lógica da transformação de bucket do Iceberg

Sintaxe

icebergBucket(N, value)

Argumentos

• N — O número de buckets, módulo. const (U)Int*
• value — O valor de entrada a ser transformado. (U)Int* ou Bool ou Decimal ou Float* ou String ou FixedString ou UUID ou Date ou Time ou DateTime

Valor retornado

Retorna um hash de 32 bits do valor de entrada. Int32

Exemplos

Exemplo

Query

SELECT icebergBucket(5, 1.0 :: Float32)

Response

4

​

icebergTruncate

Introduzido em: v25.3.0

Implementa a lógica da transformação truncate do Iceberg: https://iceberg.apache.org/spec/#truncate-transform-details.

Sintaxe

icebergTruncate(N, value)

Argumentos

• value — O valor a ser transformado. String ou (U)Int* ou Decimal

Valor retornado

O mesmo tipo que o argumento

Exemplos

Exemplo

Query

SELECT icebergTruncate(3, 'iceberg')

Response

ice

​

identity

Introduzido em: v1.1.0

Esta função retorna o argumento que você passa a ela, o que é útil para depuração e testes. Ela permite evitar o uso de índices para observar o desempenho de uma varredura completa. O analisador de consultas ignora tudo o que estiver dentro de funções identity ao procurar índices para usar e também desabilita a dobra de constantes.

Sintaxe

identity(x)

Argumentos

• x — Valor de entrada. Any

Valor retornado

Retorna o valor de entrada inalterado. Any

Exemplos

Exemplo de uso

Query

SELECT identity(42)

Response

42

​

ignore

Introduzido em: v1.1.0

Aceita argumentos arbitrários e retorna 0 incondicionalmente.

Sintaxe

ignore(x)

Argumentos

• x — Um valor de entrada que não é usado e é passado apenas para evitar um erro de sintaxe. Any

Valor retornado

Sempre retorna 0. UInt8

Exemplos

Exemplo de uso

Query

SELECT ignore(0, 'ClickHouse', NULL)

Response

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

​

indexHint

Introduzido em: v1.1.0

Esta função se destina à depuração e à introspecção. Ela ignora o argumento e sempre retorna 1. Os argumentos não são avaliados.

Durante a análise do índice, considera-se que o argumento desta função não esteja encapsulado em indexHint. Isso permite selecionar dados em intervalos do índice pela condição correspondente, mas sem aplicar filtragem adicional por essa condição. O índice no ClickHouse é esparso, e usar indexHint retornará mais dados do que especificar a mesma condição diretamente.

Explicação

Quando você executa:

SELECT * FROM test WHERE key = 123;

O ClickHouse faz duas coisas:

1. Usa o índice para encontrar quais grânulos (blocos de ~8192 linhas) podem conter key = 123
2. Lê esses grânulos e filtra suas linhas para retornar apenas aquelas em que key = 123

Assim, mesmo que ele leia 8.192 linhas do disco, retorna apenas a 1 linha que realmente corresponde.

Com indexHint, quando você executa:

SELECT * FROM test WHERE indexHint(key = 123);

O ClickHouse faz apenas uma coisa:

1. Usa o índice para encontrar quais grânulos podem conter key = 123 e retorna todas as linhas desses grânulos sem filtrá-las.

Ele retorna todas as 8.192 linhas, incluindo linhas em que key = 456, key = 789 etc. (Tudo o que, por acaso, estava armazenado no mesmo grânulo.) indexHint() não serve para melhorar o desempenho. Ele serve para depuração e para entender como o índice do ClickHouse funciona:

• Quais grânulos a minha condição seleciona?
• Quantas linhas há nesses grânulos?
• Meu índice está sendo usado de forma eficaz?

Observação: não é possível otimizar uma consulta com a função indexHint. A função indexHint não otimiza a consulta, pois não fornece nenhuma informação adicional para a análise da consulta. Ter uma expressão dentro da função indexHint não é, de forma alguma, melhor do que não usar a função indexHint. A função indexHint pode ser usada apenas para fins de introspecção e depuração e não melhora o desempenho. Se você vir o uso de indexHint por alguém que não seja um colaborador do ClickHouse, provavelmente é um erro, e você deve removê-lo.

Sintaxe

indexHint(expression)

Argumentos

• expression — Qualquer expressão para seleção de intervalo de índice. Expression

Valor retornado

Retorna 1 em todos os casos. UInt8

Exemplos

Exemplo de uso com filtro por data

Query

SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

Response

┌──────────k─┬─count()─┐
│ 2025-09-14 │    7071 │
│ 2025-09-15 │   16428 │
│ 2025-09-16 │    1077 │
│ 2025-09-30 │    8167 │
└────────────┴─────────┘

​

initialQueryID

Introduzido em: v1.1.0

Retorna o ID da consulta inicial atual. Outros parâmetros de uma consulta podem ser extraídos do campo initial_query_id em system.query_log.

Ao contrário da função queryID, initialQueryID retorna os mesmos resultados em diferentes shards.

Sintaxe

initialQueryID()

Aliases: initial_query_id

Argumentos

• Nenhum.

Valor retornado

Retorna o ID da consulta inicial da consulta atual. String

Exemplos

Exemplo de uso

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

​

initialQueryStartTime

Introduzido em: v25.4.0

Retorna o horário de início da consulta inicial atual. initialQueryStartTime retorna os mesmos resultados em diferentes shards.

Sintaxe

initialQueryStartTime()

Aliases: initial_query_start_time

Argumentos

• Nenhum.

Valor retornado

Retorna o horário de início da consulta inicial atual. DateTime

Exemplos

Exemplo de uso

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

​

initializeAggregation

Introduzido em: v20.6.0

Calcula o resultado de uma função de agregação com base em um único valor. Esta função pode ser usada para inicializar funções de agregação com o combinador -State. Você pode criar estados de funções de agregação e inseri-los em colunas do tipo AggregateFunction ou usar agregados inicializados como valores padrão.

Sintaxe

initializeAggregation(aggregate_function, arg1[, arg2, ...])

Argumentos

• aggregate_function — Nome da função de agregação a ser inicializada. String
• arg1[, arg2, ...] — Argumentos da função de agregação. Any

Valor retornado

Retorna o resultado da agregação para cada linha passada à função. O tipo de retorno é o mesmo da função que initializeAggregation recebe como primeiro argumento. Any

Exemplos

Uso básico com uniqState

Query

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

Response

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

Uso de sumState e finalizeAggregation

Query

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

Response

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

​

isConstant

Introduzido em: v20.3.0

Retorna se o argumento é uma expressão constante. Uma expressão constante é uma expressão cujo resultado é conhecido durante a análise da consulta, isto é, antes da execução. Por exemplo, expressões com literais são expressões constantes. Esta função se destina principalmente a desenvolvimento, depuração e demonstração.

Sintaxe

isConstant(x)

Argumentos

• x — Uma expressão a ser verificada. Any

Valor retornado

Retorna 1 se x for constante e 0 se x não for constante. UInt8

Exemplos

Expressão constante

Query

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

Response

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

Constante com função

Query

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

Response

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

Expressão não constante

Query

SELECT isConstant(number)
FROM numbers(1)

Response

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

Comportamento da função now()

Query

SELECT isConstant(now())

Response

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

​

isDecimalOverflow

Introduzido em: v20.8.0

Verifica se um número decimal tem dígitos demais para caber corretamente em um tipo de dado Decimal com a precisão especificada.

Sintaxe

isDecimalOverflow(value[, precision])

Argumentos

• value — Valor do tipo Decimal a ser verificado. Decimal
• precision — Opcional. A precisão do tipo Decimal. Se omitida, será usada a precisão inicial do primeiro argumento. UInt8

Valor retornado

Retorna 1 se o valor decimal tiver mais dígitos do que o permitido pela sua precisão e 0 se o valor decimal atender à precisão especificada. UInt8

Exemplos

Exemplo de uso

Query

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

Response

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

​

joinGet

Introduzido em: v18.16.0

Permite extrair dados de uma tabela da mesma forma que de um Dicionário. Obtém dados de tabelas Join usando a chave de junção especificada.

Compatível apenas com tabelas criadas com a instrução ENGINE = Join(ANY, LEFT, <join_keys>) instrução.

Sintaxe

joinGet(join_storage_table_name, value_column, join_keys)

Argumentos

• join_storage_table_name — Um identificador que indica onde realizar a busca. O identificador é procurado no banco de dados padrão (consulte o parâmetro default_database no arquivo de configuração). Para substituir o banco de dados padrão, use a consulta USE database_name ou especifique o banco de dados e a tabela com um ponto, como em database_name.table_name. String
• value_column — O nome da coluna da tabela que contém os dados necessários. const String
• join_keys — Uma lista de chaves de junção. Any

Valor retornado

Retorna uma lista de valores correspondente à lista de chaves. Any

Exemplos

Exemplo de uso

Query

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(db_test.id_val, 'val', toUInt32(1));

Response

┌─joinGet(db_test.id_val, 'val', toUInt32(1))─┐
│                                          11 │
└─────────────────────────────────────────────┘

Uso com tabela do banco de dados atual

Query

USE db_test;
SELECT joinGet(id_val, 'val', toUInt32(2));

Response

┌─joinGet(id_val, 'val', toUInt32(2))─┐
│                                  12 │
└─────────────────────────────────────┘

Usar arrays como chaves de junção

Query

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', 1, 11);

Response

┌─joinGet(some_table, 'name', 1, 11)─┐
│ a                                  │
└────────────────────────────────────┘

​

joinGetOrNull

Introduzido em: v20.4.0

Permite extrair dados de uma tabela da mesma forma que de um Dicionário. Obtém dados de tabelas Join usando a chave de junção especificada. Ao contrário de joinGet, retorna NULL quando a chave não existe.

Suporta apenas tabelas criadas com a instrução ENGINE = Join(ANY, LEFT, <join_keys>).

Sintaxe

joinGetOrNull(join_storage_table_name, value_column, join_keys)

Argumentos

• join_storage_table_name — Um identificador que indica onde realizar a busca. O identificador é procurado no banco de dados padrão (consulte o parâmetro default_database no arquivo de configuração). Para substituir o banco de dados padrão, use a consulta USE database_name ou especifique o banco de dados e a tabela separados por um ponto, como em database_name.table_name. String
• value_column — O nome da coluna da tabela que contém os dados necessários. const String
• join_keys — Uma lista de chaves de junção. Any

Valor retornado

Retorna uma lista de valores correspondente à lista de chaves, ou NULL se uma chave não for encontrada. Any

Exemplos

Exemplo de uso

Query

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(db_test.id_val, 'val', toUInt32(1)), joinGetOrNull(db_test.id_val, 'val', toUInt32(999));

Response

┌─joinGetOrNull(db_test.id_val, 'val', toUInt32(1))─┬─joinGetOrNull(db_test.id_val, 'val', toUInt32(999))─┐
│                                                11 │                                                ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

​

lowCardinalityIndices

Introduzido em: v18.12.0

Retorna a posição de um valor no dicionário de uma coluna LowCardinality. As posições começam em 1. Como LowCardinality tem dicionários por parte, esta função pode retornar posições diferentes para o mesmo valor em partes diferentes.

Sintaxe

lowCardinalityIndices(col)

Argumentos

• col — Uma coluna de baixa cardinalidade. LowCardinality

Valor retornado

A posição do valor no dicionário da parte atual. UInt64

Exemplos

Exemplos de uso

Query

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- criar duas partes:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityIndices(s) FROM test;

Response

┌─s──┬─lowCardinalityIndices(s)─┐
│ ab │                        1 │
│ cd │                        2 │
│ ab │                        1 │
│ ab │                        1 │
│ df │                        3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
│ ef │                        1 │
│ cd │                        2 │
│ ab │                        3 │
│ cd │                        2 │
│ ef │                        1 │
└────┴──────────────────────────┘

​

lowCardinalityKeys

Introduzido em: v18.12.0

Retorna os valores do dicionário de uma coluna LowCardinality. Se o bloco for menor ou maior que o tamanho do dicionário, o resultado será truncado ou preenchido com valores padrão. Como o LowCardinality tem dicionários por parte, esta função pode retornar valores de dicionário diferentes em partes diferentes.

Sintaxe

lowCardinalityKeys(col)

Argumentos

• col — Uma coluna de baixa cardinalidade. LowCardinality

Valor retornado

Retorna as chaves do dicionário. UInt64

Exemplos

lowCardinalityKeys

Query

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- criar duas partes:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

Response

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

​

materialize

Introduzido em: v1.1.0

Transforma uma constante em uma coluna completa que contém um único valor. Colunas completas e constantes são representadas de forma diferente na memória. As funções geralmente executam código diferente para argumentos normais e constantes, embora o resultado normalmente deva ser o mesmo. Esta função pode ser usada para depurar esse comportamento.

Sintaxe

materialize(x)

Argumentos

• x — Uma constante. Any

Valor retornado

Retorna uma coluna completa que contém o valor constante. Any

Exemplos

Exemplo de uso

Query

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));

Response

2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String

​

minSampleSizeContinuous

Introduzido na versão: v23.10.0

Calcula o tamanho mínimo de amostra necessário para um teste A/B que compara as médias de uma métrica contínua em duas amostras.

Usa a fórmula descrita neste artigo. Pressupõe tamanhos iguais para os grupos de tratamento e de controle. Retorna o tamanho de amostra necessário para um grupo (ou seja, o tamanho de amostra necessário para todo o experimento é o dobro do valor retornado). Também pressupõe variância igual da métrica de teste nos grupos de tratamento e de controle.

Sintaxe

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

Aliases: minSampleSizeContinous

Argumentos

• baseline — Valor de referência de uma métrica. (U)Int* ou Float*
• sigma — Desvio padrão de referência de uma métrica. (U)Int* ou Float*
• mde — Efeito mínimo detectável (MDE) como porcentagem do valor de referência (por exemplo, para um valor de referência de 112.25, MDE 0.03 significa uma variação esperada para 112.25 ± 112.25*0.03). (U)Int* ou Float*
• power — Poder estatístico necessário de um teste (1 - probabilidade de erro do Tipo II). (U)Int* ou Float*
• alpha — Nível de significância necessário de um teste (probabilidade de erro do Tipo I). (U)Int* ou Float*

Valor retornado

Retorna uma Tuple nomeada com 3 elementos: minimum_sample_size, detect_range_lower e detect_range_upper. Eles correspondem, respectivamente, a: o tamanho de amostra necessário, o limite inferior do intervalo de valores que não podem ser detectados com o tamanho de amostra necessário retornado, calculado como baseline * (1 - mde), e o limite superior do intervalo de valores que não podem ser detectados com o tamanho de amostra necessário retornado, calculado como baseline * (1 + mde) (Float64). Tuple(Float64, Float64, Float64)

Exemplos

minSampleSizeContinuous

Query

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

Response

(616.2931945826209,108.8825,115.6175)

​

minSampleSizeConversion

Introduzido em: v22.6.0

Calcula o tamanho mínimo de amostra necessário para um teste A/B que compara conversões (proporções) entre duas amostras.

Usa a fórmula descrita neste artigo. Pressupõe tamanhos iguais para os grupos de tratamento e controle. Retorna o tamanho de amostra necessário para um grupo (ou seja, o tamanho de amostra necessário para todo o experimento é o dobro do valor retornado).

Sintaxe

minSampleSizeConversion(baseline, mde, power, alpha)

Argumentos

• baseline — Conversão de base. Float*
• mde — Efeito mínimo detectável (MDE), em pontos percentuais (por exemplo, para uma conversão de base de 0.25, um MDE de 0.03 significa uma mudança esperada para 0.25 ± 0.03). Float*
• power — Poder estatístico exigido para um teste (1 - probabilidade de erro Tipo II). Float*
• alpha — Nível de significância exigido para um teste (probabilidade de erro Tipo I). Float*

Valor retornado

Retorna uma Tuple nomeada com 3 elementos: minimum_sample_size, detect_range_lower, detect_range_upper. Eles são, respectivamente: o tamanho de amostra exigido, o limite inferior do intervalo de valores que não podem ser detectados com o tamanho de amostra exigido retornado, calculado como baseline - mde, e o limite superior do intervalo de valores que não podem ser detectados com o tamanho de amostra exigido retornado, calculado como baseline + mde. Tuple(Float64, Float64, Float64)

Exemplos

minSampleSizeConversion

Query

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

Response

(3396.077603219163,0.22,0.28)

​

neighbor

Introduzido em: v20.1.0

Retorna um valor de uma coluna em um deslocamento especificado em relação à linha atual. Esta função está obsoleta e é propensa a erros porque opera na ordem física dos blocos de dados, que pode não corresponder à ordem lógica esperada pelos usuários. Considere usar funções de janela adequadas em vez dela.

A função pode ser habilitada definindo allow_deprecated_error_prone_window_functions = 1.

Sintaxe

neighbor(column, offset[, default_value])

Argumentos

• column — A coluna de origem. Any
• offset — O deslocamento em relação à linha atual. Valores positivos avançam, e valores negativos retrocedem. Integer
• default_value — Opcional. O valor retornado se o deslocamento ultrapassar os limites dos dados. Se não for especificado, usa o valor padrão do tipo da coluna. Any

Valor retornado

Retorna um valor no deslocamento especificado ou o valor padrão, se estiver fora dos limites. Any

Exemplos

Exemplo de uso

Query

SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

Response

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

Com valor padrão

Query

SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

Response

┌─number─┬─neighbor(number, 2, 999)─┐
│      0 │                        2 │
│      1 │                        3 │
│      2 │                        4 │
│      3 │                        5 │
│      4 │                        6 │
│      5 │                        7 │
│      6 │                        8 │
│      7 │                        9 │
│      8 │                      999 │
│      9 │                      999 │
└────────┴──────────────────────────┘

​

normalizeQuery

Introduzido em: v20.8.0

Substitui literais, sequências de literais e aliases complexos (contendo espaços em branco, mais de dois dígitos ou com pelo menos 36 bytes, como UUIDs) por um placeholder ?.

Sintaxe

normalizeQuery(x)

Argumentos

• x — Sequência de caracteres. String

Valor retornado

Retorna a sequência de caracteres informada com placeholders. String

Exemplos

Exemplo de uso

Query

SELECT normalizeQuery('[1, 2, 3, x]') AS query

Response

┌─query────┐
│ [?.., x] │
└──────────┘

​

normalizeQueryKeepNames

Introduzido em: v21.2.0

Substitui literais e sequências de literais pelo placeholder ?, mas não substitui aliases complexos (que contêm espaços em branco, mais de dois dígitos ou têm pelo menos 36 bytes de comprimento, como UUIDs). Isso ajuda a analisar melhor logs de consultas complexas.

Sintaxe

normalizeQueryKeepNames(x)

Argumentos

• x — Sequência de caracteres. String

Valor retornado

Retorna a sequência de caracteres informada com placeholders. String

Exemplos

Exemplo de uso

Query

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

Response

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

​

normalizedQueryHash

Introduzido na versão: v20.8.0

Retorna valores de hash de 64 bits idênticos para consultas semelhantes, sem considerar os valores dos literais. Pode ser útil para analisar logs de consultas.

Sintaxe

normalizedQueryHash(x)

Argumentos

• x — Sequência de caracteres. String

Valor retornado

Retorna um valor de hash de 64 bits. UInt64

Exemplos

Exemplo de uso

Query

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

Response

┌─res─┐
│   1 │
└─────┘

​

normalizedQueryHashKeepNames

Introduzido em: v21.2.0

Assim como normalizedQueryHash, retorna valores de hash de 64 bits idênticos para consultas semelhantes, sem os valores dos literais, mas não substitui aliases complexos (que contêm espaços em branco, mais de dois dígitos ou têm pelo menos 36 bytes de comprimento, como UUIDs) por um placeholder antes de calcular o hash. Pode ser útil para analisar logs de consulta.

Sintaxe

normalizedQueryHashKeepNames(x)

Argumentos

• x — Sequência de caracteres. String

Valor retornado

Retorna um valor de hash de 64 bits. UInt64

Exemplos

Exemplo de uso

Query

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

Response

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

​

obfuscateQuery

Introduzido em: v26.4.0

Ofusca uma consulta SQL substituindo identificadores por palavras aleatórias e literais por valores aleatórios, preservando a estrutura da consulta.

Esta função é útil para anonimizar consultas antes de registrá-las em logs ou compartilhá-las para fins de depuração. Linhas diferentes produzirão resultados ofuscados distintos, mesmo para a mesma consulta de entrada, o que ajuda a preservar a privacidade ao trabalhar com várias consultas.

O parâmetro opcional tag evita a eliminação de subexpressões comuns quando a mesma chamada de função é usada várias vezes em uma consulta. Isso garante que cada invocação produza um resultado ofuscado diferente.

Recursos:

• Substitui nomes de tabelas, nomes de colunas e aliases por palavras aleatórias
• Substitui literais numéricos e de string por valores aleatórios
• Preserva a estrutura geral da consulta e a sintaxe SQL
• Produz resultados diferentes para linhas diferentes

Sintaxe

obfuscateQuery(query[, tag])

Argumentos

• query — A consulta SQL a ser ofuscada. String
• tag — Opcional. Um valor para evitar a eliminação de subexpressões comuns quando a mesma chamada de função é usada várias vezes.

Valor retornado

A consulta ofuscada, com identificadores e literais substituídos, preservando a estrutura original da consulta. String

Exemplos

Uso básico

Query

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

Response

SELECT fruit, number FROM table WHERE number > 12

Com tag para evitar a eliminação de subexpressões comuns

Query

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

Response

SELECT a FROM b, SELECT c FROM d

Linhas diferentes geram resultados diferentes

Query

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

Response

A B

​

obfuscateQueryWithSeed

Introduzido em: v26.4.0

Ofusca uma consulta SQL usando uma seed especificada para gerar resultados determinísticos.

Diferentemente de obfuscateQuery(), esta função produz resultados determinísticos quando recebe a mesma seed. Isso é útil quando você precisa de ofuscação consistente em várias execuções ou quando quer reproduzir a mesma consulta ofuscada para fins de teste ou depuração.

Características:

• Ofuscação determinística com base na seed fornecida
• A mesma seed sempre produz o mesmo resultado ofuscado
• Seeds diferentes produzem resultados diferentes
• Preserva a estrutura da consulta, assim como obfuscateQuery()

Casos de uso:

• Casos de teste reproduzíveis
• Anonimização consistente em várias execuções
• Depuração com consultas ofuscadas consistentes

Sintaxe

obfuscateQueryWithSeed(query, seed)

Argumentos

• query — A consulta SQL a ser ofuscada. String
• seed — A seed usada na ofuscação. A mesma seed produz resultados determinísticos. Integer ou String

Valor retornado

A consulta ofuscada, gerada de forma determinística com base na seed fornecida. String

Exemplos

Ofuscação determinística com seed inteira

Query

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

Response

SELECT fruit FROM table

Ofuscação determinística com seed textual

Query

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

Response

SELECT a, b FROM c

A mesma seed gera o mesmo resultado

Query

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

Response

true

​

parseReadableSize

Introduzido em: v24.6.0

Dada uma string que contém um tamanho em bytes e B, KiB, KB, MiB, MB etc. como unidade (isto é, ISO/IEC 80000-13 ou unidade decimal de byte), esta função retorna o número correspondente de bytes. Se a função não conseguir interpretar o valor de entrada, ela gera uma exceção.

As operações inversas desta função são formatReadableSize e formatReadableDecimalSize.

Sintaxe

parseReadableSize(x)

Argumentos

• x — Tamanho em formato legível com unidade de byte decimal ou ISO/IEC 80000-13. String

Valor retornado

Retorna o número de bytes, arredondado para cima para o inteiro mais próximo. UInt64

Exemplos

Exemplo de uso

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

​

parseReadableSizeOrNull

Introduzido em: v24.6.0

Dada uma string que contém um tamanho em bytes e B, KiB, KB, MiB, MB etc. como unidade (isto é, ISO/IEC 80000-13 ou unidade decimal de byte), esta função retorna o número de bytes correspondente. Se a função não conseguir interpretar o valor de entrada, retornará NULL.

As operações inversas desta função são formatReadableSize e formatReadableDecimalSize.

Sintaxe

parseReadableSizeOrNull(x)

Argumentos

• x — Tamanho legível com unidade de byte decimal ou no padrão ISO/IEC 80000-13. String

Valor retornado

Retorna o número de bytes, arredondado para cima para o inteiro mais próximo, ou NULL se não for possível interpretar a entrada Nullable(UInt64)

Exemplos

Exemplo de uso

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

​

parseReadableSizeOrZero

Introduzido em: v24.6.0

Dada uma string contendo um tamanho em bytes e B, KiB, KB, MiB, MB etc. como unidade (isto é, ISO/IEC 80000-13 ou unidade decimal de bytes), esta função retorna o número correspondente de bytes. Se a função não conseguir analisar o valor de entrada, ela retornará 0.

As operações inversas desta função são formatReadableSize e formatReadableDecimalSize.

Sintaxe

parseReadableSizeOrZero(x)

Argumentos

• x — Tamanho em formato legível com ISO/IEC 80000-13 ou unidade decimal de bytes. String

Valor retornado

Retorna o número de bytes, arredondado para cima até o inteiro mais próximo, ou 0 se não for possível analisar a entrada. UInt64

Exemplos

Exemplo de uso

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

​

parseTimeDelta

Introduzido em: v22.7.0

Analisa uma sequência de números seguida de algo semelhante a uma unidade de tempo.

A string de intervalo de tempo usa as seguintes especificações de unidade de tempo:

• years, year, yr, y
• months, month, mo
• weeks, week, w
• days, day, d
• hours, hour, hr, h
• minutes, minute, min, m
• seconds, second, sec, s
• milliseconds, millisecond, millisec, ms
• microseconds, microsecond, microsec, μs, µs, us
• nanoseconds, nanosecond, nanosec, ns

Várias unidades de tempo podem ser combinadas com separadores (espaço, ;, -, +, ,, :).

A duração de anos e meses é aproximada: um ano tem 365 dias, e um mês tem 30,5 dias.

Sintaxe

parseTimeDelta(timestr)

Argumentos

• timestr — Uma sequência de números seguida de algo semelhante a uma unidade de tempo. String

Valor retornado

O número de segundos. Float64

Exemplos

Exemplo de uso

Query

SELECT parseTimeDelta('11s+22min')

Response

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

Unidades de tempo complexas

Query

SELECT parseTimeDelta('1yr2mo')

Response

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

​

partitionId

Introduzido em: v21.4.0

Calcula o ID da partição.

Esta função é lenta e não deve ser usada com um grande número de linhas.

Sintaxe

partitionId(column1[, column2, ...])

Aliases: partitionID

Argumentos

• column1, column2, ... — Coluna cujo ID da partição deve ser retornado.

Valor retornado

Retorna o ID da partição à qual a linha pertence. String

Exemplos

Exemplo de uso

Query

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

Response

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

​

queryID

Introduzido em: v21.9.0

Retorna o ID da consulta atual. Outros parâmetros da consulta podem ser extraídos do campo query_id na tabela system.query_log.

Em contraste com a função initialQueryID, queryID pode retornar resultados diferentes em shards distintos.

Sintaxe

queryID()

Aliases: query_id

Argumentos

• Nenhum.

Valor retornado

Retorna o ID da consulta atual. String

Exemplos

Exemplo de uso

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

┌─count(DISTINCT t)─┐
│                 3 │
└───────────────────┘

​

revision

Introduzido em: v22.7.0

Retorna a revisão atual do servidor ClickHouse.

Sintaxe

revision()

Argumentos

• Nenhum.

Valor retornado

Retorna a revisão atual do servidor ClickHouse. UInt32

Exemplos

Exemplo de uso

Query

SELECT revision()

Response

┌─revision()─┐
│      54485 │
└────────────┘

​

rowNumberInAllBlocks

Introduzido em: v1.1.0

Retorna um número de linha único para cada linha processada.

Sintaxe

rowNumberInAllBlocks()

Argumentos

• Nenhum.

Valor retornado

Retorna o número ordinal da linha no bloco de dados, a partir de 0. UInt64

Exemplos

Exemplo de uso

Query

SELECT rowNumberInAllBlocks()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
)
SETTINGS max_block_size = 2

Response

┌─rowNumberInAllBlocks()─┐
│                      0 │
│                      1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      4 │
│                      5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      2 │
│                      3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      6 │
│                      7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      8 │
│                      9 │
└────────────────────────┘

​

rowNumberInBlock

Introduzido em: v1.1.0

Para cada block processado por rowNumberInBlock, retorna o número da linha atual.

O número retornado começa em 0 para cada block.

Sintaxe

rowNumberInBlock()

Argumentos

• Nenhum.

Valor retornado

Retorna o número ordinal da linha no bloco de dados, a partir de 0. UInt64

Exemplos

Exemplo de uso

Query

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

Response

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘

​

runningAccumulate

Introduzido em: v1.1.0

Acumula os estados de uma função de agregação para cada linha de um bloco de dados.

Descontinuado

O estado é redefinido a cada novo bloco de dados. Devido a esse comportamento propenso a erros, a função foi descontinuada, e recomenda-se usar funções de janela em vez dela. Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.

Sintaxe

runningAccumulate(agg_state[, grouping])

Argumentos

• agg_state — Estado da função de agregação. AggregateFunction
• grouping — Opcional. Chave de agrupamento. O estado da função é redefinido se o valor de grouping for alterado. Pode ser qualquer um dos tipos de dados suportados para os quais o operador de igualdade esteja definido. Any

Valor retornado

Retorna o resultado acumulado para cada linha. Any

Exemplos

Exemplo de uso com initializeAggregation

Query

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

Response

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

​

runningConcurrency

Introduzido em: v21.3.0

Calcula o número de eventos concorrentes. Cada evento tem um horário de início e um horário de término. O horário de início é incluído no evento, enquanto o horário de término é excluído. As colunas com horário de início e horário de término devem ser do mesmo tipo de dado. A função calcula o número total de eventos ativos (concorrentes) para cada horário de início do evento.

Requisitos

Os eventos devem ser ordenados pelo horário de início em ordem crescente. Se esse requisito for violado, a função gera uma exceção. Cada bloco de dados é processado separadamente. Se eventos de blocos de dados diferentes se sobrepuserem, eles não poderão ser processados corretamente.

Descontinuado

É recomendável usar funções de janela.

Sintaxe

runningConcurrency(start, end)

Argumentos

• start — Uma coluna com o horário de início dos eventos. Date ou DateTime ou DateTime64
• end — Uma coluna com o horário de término dos eventos. Date ou DateTime ou DateTime64

Valor retornado

Retorna o número de eventos simultâneos em cada horário de início dos eventos. UInt32

Exemplos

Exemplo de uso

Query

SELECT start, runningConcurrency(start, end) FROM example_table;

Response

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              2 │
└────────────┴────────────────────────────────┘

​

runningDifference

Introduzido em: v1.1.0

Calcula a diferença entre os valores de duas linhas consecutivas no bloco de dados. Retorna 0 para a primeira linha e, para as linhas subsequentes, a diferença em relação à linha anterior.

Descontinuado

Retorna diferenças apenas dentro do bloco de dados que está sendo processado no momento. Por causa desse comportamento propenso a erros, a função está descontinuada. Recomenda-se usar funções de janela em vez dela.

Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.

O resultado da função depende dos blocos de dados envolvidos e da ordem dos dados no bloco. A ordem das linhas durante o cálculo de runningDifference() pode ser diferente da ordem das linhas retornadas ao usuário. Para evitar isso, você pode criar uma subconsulta com ORDER BY e chamar a função fora da subconsulta. Observe que o tamanho do bloco afeta o resultado. O estado interno de runningDifference é reiniciado a cada novo bloco.

Sintaxe

runningDifference(x)

Argumentos

• x — Coluna para a qual calcular a diferença entre valores consecutivos. Any

Valor retornado

Retorna a diferença entre valores consecutivos, com 0 para a primeira linha.

Exemplos

Exemplo de uso

Query

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC
    LIMIT 5
);

Response

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

Exemplo do impacto do tamanho do bloco

Query

SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;

Response

┌─number─┬─diff─┐
│      0 │    0 │
└────────┴──────┘
┌─number─┬─diff─┐
│  65536 │    0 │
└────────┴──────┘

​

runningDifferenceStartingWithFirstValue

Introduzido em: v1.1.0

Calcula a diferença entre os valores de linhas consecutivas em um bloco de dados, mas, ao contrário de runningDifference, retorna o valor real da primeira linha em vez de 0.

Descontinuado

Retorna diferenças apenas dentro do bloco de dados que está sendo processado no momento. Devido a esse comportamento sujeito a erros, a função foi descontinuada. Recomenda-se usar funções de janela em vez disso.

Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.

Sintaxe

runningDifferenceStartingWithFirstValue(x)

Argumentos

• x — Coluna para a qual calcular a diferença acumulada. Any

Valor retornado

Retorna a diferença entre valores consecutivos, sendo que, para a primeira linha, retorna o valor da própria primeira linha. Any

Exemplos

Exemplo de uso

Query

SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

Response

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

​

serverUUID

Introduzido em: v20.1.0

Retorna o UUID (v4) aleatório e exclusivo gerado quando o servidor é iniciado pela primeira vez. O UUID é persistido, ou seja, a segunda, a terceira etc. inicialização do servidor retorna o mesmo UUID.

Sintaxe

serverUUID()

Argumentos

• Nenhum.

Valor retornado

Retorna o UUID aleatório do servidor. UUID

Exemplos

Exemplo de uso

Query

SELECT serverUUID();

Response

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

​

shardCount

Introduzido em: v21.9.0

Retorna o número total de shards de uma consulta distribuída. Se uma consulta não for distribuída, retorna o valor constante 0.

Sintaxe

shardCount()

Argumentos

• Nenhum.

Valor retornado

Retorna o número total de shards ou 0. UInt32

Exemplos

Exemplo de uso

Query

-- Veja o exemplo de shardNum() acima, que também ilustra shardCount()
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

Response

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

​

shardNum

Introduzido em: v21.9.0

Retorna o índice do shard que processa parte dos dados em uma consulta distribuída. Os índices começam em 1. Se uma consulta não for distribuída, será retornado o valor constante 0.

Sintaxe

shardNum()

Argumentos

• Nenhum.

Valor retornado

Retorna o índice do shard ou uma constante 0. UInt32

Exemplos

Exemplo de uso

Query

CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

Response

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          1 │            2 │
│     0 │          2 │            2 │
└───────┴────────────┴──────────────┘

​

showCertificate

Introduzido em: v22.6.0

Exibe informações sobre o certificado Secure Sockets Layer (SSL) atual do servidor, se ele estiver configurado. Consulte Configurando TLS para mais informações sobre como configurar o ClickHouse para usar certificados OpenSSL para validar conexões.

Sintaxe

showCertificate()

Argumentos

• Nenhum.

Valor retornado

Retorna um map de pares chave-valor referentes ao certificado SSL configurado. Map(String, String)

Exemplos

Exemplo de uso

Query

SELECT showCertificate() FORMAT LineAsString;

Response

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

​

sleep

Introduzido em: v1.1.0

Pausa a execução de uma consulta pelo número especificado de segundos. A função é usada principalmente para fins de teste e depuração.

Em geral, a função sleep() não deve ser usada em ambientes de produção, pois pode afetar negativamente o desempenho das consultas e a capacidade de resposta do sistema. No entanto, ela pode ser útil nos seguintes cenários:

1. Teste: Ao testar ou fazer benchmarking do ClickHouse, talvez você queira simular atrasos ou introduzir pausas para observar como o sistema se comporta em determinadas condições.
2. Depuração: Se você precisar examinar o estado do sistema ou a execução de uma consulta em um momento específico, poderá usar sleep() para introduzir uma pausa, permitindo inspecionar ou coletar informações relevantes.
3. Simulação: Em alguns casos, talvez você queira simular cenários do mundo real em que ocorram atrasos ou pausas, como latência de rede ou dependências de sistemas externos.

É importante usar a função sleep() com critério e somente quando necessário, pois ela pode afetar o desempenho geral e a capacidade de resposta do seu sistema ClickHouse.

Por motivos de segurança, a função só pode ser executada no perfil do usuário default (com allow_sleep habilitado).

Sintaxe

sleep(seconds)

Argumentos

• seconds — O número de segundos para pausar a execução da consulta, com um máximo de 3 segundos. Pode ser um valor de ponto flutuante para especificar frações de segundo. const UInt* ou const Float*

Valor retornado

Retorna 0. UInt8

Exemplos

Exemplo de uso

Query

-- Esta consulta fará uma pausa de 2 segundos antes de ser concluída.
-- Durante esse tempo, nenhum resultado será retornado, e a consulta parecerá travada ou sem resposta.
SELECT sleep(2);

Response

┌─sleep(2)─┐
│        0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.

​

sleepEachRow

Introduzido em: v1.1.0

Pausa a execução de uma consulta por um número específico de segundos para cada linha no conjunto de resultados.

A função sleepEachRow() é usada principalmente para testes e depuração, de forma semelhante à função sleep(). Ela permite simular atrasos ou inserir pausas no processamento de cada linha, o que pode ser útil em cenários como:

1. Testes: Ao testar ou fazer benchmarking do desempenho do ClickHouse em condições específicas, você pode usar sleepEachRow() para simular atrasos ou inserir pausas em cada linha processada.
2. Depuração: Se você precisar examinar o estado do sistema ou a execução de uma consulta para cada linha processada, poderá usar sleepEachRow() para inserir pausas, permitindo inspecionar ou coletar informações relevantes.
3. Simulação: Em alguns casos, você pode querer simular cenários reais em que ocorram atrasos ou pausas para cada linha processada, como ao lidar com sistemas externos ou latência de rede.

Assim como a função sleep(), é importante usar sleepEachRow() com critério e somente quando necessário, pois ela pode afetar significativamente o desempenho geral e a capacidade de resposta do seu sistema ClickHouse, especialmente ao lidar com grandes conjuntos de resultados.

Sintaxe

sleepEachRow(seconds)

Argumentos

• seconds — O número de segundos para pausar a execução da consulta para cada linha do conjunto de resultados, com um máximo de 3 segundos. Pode ser um valor de ponto flutuante para especificar frações de segundo. const UInt* ou const Float*

Valor retornado

Retorna 0 para cada linha. UInt8

Exemplos

Exemplo de uso

Query

-- A saída terá um atraso, com uma pausa de 0,5 segundo entre cada linha.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

Response

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

​

structureToCapnProtoSchema

Introduzido em: v23.8.0

Função que converte a estrutura de uma tabela do ClickHouse para um schema no formato CapnProto

Sintaxe

structureToCapnProtoSchema(table_structure, message)

Argumentos

• Nenhum.

Valor retornado

Exemplos

random

Query

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

Response

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

​

structureToProtobufSchema

Introduzido em: v23.8.0

Converte a estrutura de uma tabela do ClickHouse em um schema no formato Protobuf.

Esta função recebe a definição da estrutura de uma tabela do ClickHouse e a converte em uma definição de schema em Protocol Buffers (Protobuf) na sintaxe proto3. Isso é útil para gerar schemas Protobuf que correspondam às estruturas das suas tabelas do ClickHouse para intercâmbio de dados.

Sintaxe

structureToProtobufSchema(structure, message_name)

Argumentos

• structure — Definição da estrutura da tabela do ClickHouse como uma string (por exemplo, ‘column1 Type1, column2 Type2’). String
• message_name — Nome do tipo de mensagem Protobuf no schema gerado. String

Valor retornado

Retorna uma definição de schema Protobuf na sintaxe proto3 que corresponde à estrutura de entrada do ClickHouse. String

Exemplos

Conversão da estrutura do ClickHouse para schema Protobuf

Query

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

Response

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

​

tcpPort

Introduzido em: v20.12.0

Retorna o número da porta TCP da interface nativa em que o servidor escuta. Se executada no contexto de uma tabela distribuída, esta função gera uma coluna comum com valores relevantes para cada shard. Caso contrário, gera um valor constante.

Sintaxe

tcpPort()

Argumentos

• Nenhum.

Valor retornado

Retorna o número da porta TCP. UInt16

Exemplos

Exemplo de uso

Query

SELECT tcpPort()

Response

┌─tcpPort()─┐
│      9000 │
└───────────┘

​

throwIf

Introduzido em: v1.1.0

Lança uma exceção se o argumento x for true. Para usar o argumento error_code, o parâmetro de configuração allow_custom_error_code_in_throw deve estar habilitado.

Sintaxe

throwIf(x[, message[, error_code]])

Argumentos

• x — Condição a ser verificada. Any
• message — Opcional. Mensagem de erro personalizada. const String
• error_code — Opcional. Código de erro personalizado. const Int8/16/32

Valor retornado

Retorna 0 se a condição for false e lança uma exceção se a condição for true. UInt8

Exemplos

Exemplo de uso

Query

SELECT throwIf(number = 3, 'Too many') FROM numbers(10);

Response

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

​

toColumnTypeName

Introduzido em: v1.1.0

Retorna o nome interno do tipo de dados do valor fornecido. Diferentemente da função toTypeName, o tipo de dados retornado pode incluir colunas internas de encapsulamento, como Const e LowCardinality.

Sintaxe

toColumnTypeName(value)

Argumentos

• value — Valor cujo tipo de dado interno deve ser retornado. Any

Valor retornado

Retorna o tipo de dado interno usado para representar o valor. String

Exemplos

Exemplo de uso

Query

SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));

Response

┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

​

toTypeName

Introduzido em: v1.1.0

Retorna o nome do tipo do argumento informado. Se NULL for informado, a função retorna o tipo Nullable(Nothing), que corresponde à representação interna de NULL no ClickHouse.

Sintaxe

toTypeName(x)

Argumentos

• x — Um valor de tipo arbitrário. Any

Valor retornado

Retorna o nome do tipo de dado do valor fornecido. String

Exemplos

Exemplo de uso

Query

SELECT toTypeName(123)

Response

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

​

tokenizeQuery

Introduzido em: v26.5.0

Tokeniza uma string de consulta em ClickHouse SQL e retorna um array de tokens. Cada token é uma tupla nomeada com a posição inicial (em bytes), a posição final e o tipo do token.

Sintaxe

tokenizeQuery(query)

Argumentos

• query — Uma string de consulta em ClickHouse SQL. String.

Valor retornado

Um array de tuplas nomeadas (begin UInt64, end UInt64, type Enum8(...)) representando os tokens da consulta. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

Exemplos

simples

Query

SELECT tokenizeQuery('SELECT 1')

Response

[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]

​

transactionID

Introduzido em: v22.6.0

Retorna o ID de uma transação.

Esta função faz parte de um conjunto de funcionalidades experimentais. Ative o suporte experimental a transações adicionando esta configuração aos seus arquivos de configuração:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Para mais informações, consulte a página Suporte transacional (ACID).

Sintaxe

transactionID()

Argumentos

• Nenhum.

Valor retornado

Retorna uma tupla composta por start_csn, local_tid e host_id.

• start_csn: Número sequencial global; o timestamp de commit mais recente observado quando esta transação foi iniciada.
• local_tid: Número sequencial local, exclusivo para cada transação iniciada por este host dentro de um start_csn específico.
• host_id: UUID do host que iniciou esta transação. Tuple(UInt64, UInt64, UUID)

Exemplos

Exemplo de uso

Query

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

Response

┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘

​

transactionLatestSnapshot

Introduzido em: v22.6.0

Retorna o snapshot mais recente (Commit Sequence Number) de uma transação disponível para leitura.

Esta função faz parte de um conjunto de recursos experimentais. Ative o suporte experimental a transações adicionando esta configuração às suas configurações:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Para mais informações, consulte a página Suporte transacional (ACID).

Sintaxe

transactionLatestSnapshot()

Argumentos

• Nenhum.

Valor retornado

Retorna o snapshot (CSN) mais recente da transação. UInt64

Exemplos

Exemplo de uso

Query

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Response

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

​

transactionOldestSnapshot

Introduzido em: v22.6.0

Retorna o snapshot mais antigo (Commit Sequence Number) visível para alguma transação em execução.

Esta função faz parte de um conjunto de recursos experimentais. Ative o suporte experimental a transações adicionando esta opção à sua configuração:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

Para mais informações, consulte a página suporte transacional (ACID).

Sintaxe

transactionOldestSnapshot()

Argumentos

• Nenhum.

Valor retornado

Retorna o snapshot (CSN) mais antigo de uma transação. UInt64

Exemplos

Exemplo de uso

Query

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

Response

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

​

transform

Introduzido em: v1.1.0

Transforma um valor de acordo com um mapeamento explicitamente definido entre determinados elementos e outros elementos.

Há duas variações desta função:

• transform(x, array_from, array_to, default) - transforma x usando arrays de mapeamento, com um valor padrão para elementos sem correspondência
• transform(x, array_from, array_to) - faz a mesma transformação, mas retorna o x original se nenhuma correspondência for encontrada

A função procura x em array_from e retorna o elemento correspondente de array_to no mesmo índice. Se x não for encontrado em array_from, ela retorna o valor default (versão com 4 parâmetros) ou o x original (versão com 3 parâmetros). Se houver vários elementos correspondentes em array_from, ela retorna o elemento correspondente à primeira correspondência.

Requisitos:

• array_from e array_to devem ter o mesmo número de elementos
• Para a versão com 4 parâmetros: transform(T, Array(T), Array(U), U) -> U, em que T e U podem ser tipos compatíveis diferentes
• Para a versão com 3 parâmetros: transform(T, Array(T), Array(T)) -> T, em que todos os tipos devem ser iguais

Sintaxe

transform(x, array_from, array_to[, default])

Argumentos

• x — Valor a ser transformado. (U)Int* or Decimal or Float* or String or Date or DateTime
• array_from — Array constante de valores para buscar correspondências. Array((U)Int*) or Array(Decimal) or Array(Float*) or Array(String) or Array(Date) or Array(DateTime)
• array_to — Array constante de valores a serem retornados para as correspondências encontradas em array_from. Array((U)Int*) or Array(Decimal) or Array(Float*) or Array(String) or Array(Date) or Array(DateTime)
• default — Opcional. Valor a ser retornado se x não for encontrado em array_from. Se omitido, retorna x sem alterações. (U)Int* or Decimal or Float* or String or Date or DateTime

Valor retornado

Retorna o valor correspondente de array_to se x corresponder a um elemento de array_from; caso contrário, retorna default (se fornecido) ou x (se default não for fornecido). Any

Exemplos

transform(T, Array(T), Array(U), U) -> U

Query

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

Response

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Other     │ 104472 │
└───────────┴────────┘

transform(T, Array(T), Array(T)) -> T

Query

SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10

Response

┌─s──────────────┬───────c─┐
│                │ 2906259 │
│ www.yandex     │  867767 │
│ ███████.ru     │  313599 │
│ mail.yandex.ru │  107147 │
│ ██████.ru      │  100355 │
│ █████████.ru   │   65040 │
│ news.yandex.ru │   64515 │
│ ██████.net     │   59141 │
│ example.com    │   57316 │
└────────────────┴─────────┘

​

uniqThetaIntersect

Introduzido em: v22.9.0

Dois objetos uniqThetaSketch são usados para calcular a interseção (operação de conjunto ∩); o resultado é um novo uniqThetaSketch.

Sintaxe

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

Argumentos

• uniqThetaSketch — objeto uniqThetaSketch. Tuple ou Array ou Date ou DateTime ou String ou (U)Int* ou Float* ou Decimal

Valor retornado

Um novo uniqThetaSketch contendo o resultado da interseção. UInt64

Exemplos

Exemplo de uso

Query

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

​

uniqThetaNot

Introduzido em: v22.9.0

Dois objetos uniqThetaSketch para realizar o cálculo a_not_b (operação de conjunto ×); o resultado é um novo uniqThetaSketch.

Sintaxe

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

Argumentos

• uniqThetaSketch — objeto do tipo uniqThetaSketch. Tuple ou Array ou Date ou DateTime ou String ou (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um novo uniqThetaSketch contendo o resultado de a_not_b. UInt64

Exemplos

Exemplo de uso

Query

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

Response

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

​

uniqThetaUnion

Introduzido em: v22.9.0

Usa dois objetos uniqThetaSketch para calcular a união (operação de conjunto ∪); o resultado é um novo uniqThetaSketch.

Sintaxe

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

Argumentos

• uniqThetaSketch — objeto uniqThetaSketch. Tuple ou Array ou Date ou DateTime ou String ou (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um novo uniqThetaSketch com o resultado da união. UInt64

Exemplos

Exemplo de uso

Query

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

​

uptime

Introduzido em: v1.1.0

Retorna o uptime do servidor em segundos. Se for executada no contexto de uma tabela distribuída, essa função gera uma coluna comum com valores correspondentes a cada shard. Caso contrário, produz um valor constante.

Sintaxe

uptime()

Argumentos

• Nenhum.

Valor retornado

Retorna o uptime do servidor em segundos. UInt32

Exemplos

Exemplo de uso

Query

SELECT uptime() AS Uptime

Response

┌─Uptime─┐
│  55867 │
└────────┘

​

variantElement

Introduzido em: v25.2.0

Extrai, de uma coluna Variant, uma coluna do tipo especificado.

Sintaxe

variantElement(variant, type_name[, default_value])

Argumentos

• variant — Coluna Variant. Variant
• type_name — O nome do tipo de variante a ser extraído. String
• default_value — O valor padrão que será usado se variant não tiver uma variante do tipo especificado. Pode ser de qualquer tipo. Opcional. Any

Valor retornado

Retorna uma coluna com o tipo de variante especificado extraído da coluna Variant. Any

Exemplos

Exemplo de uso

Query

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

Response

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

​

variantType

Introduzido em: v24.2.0

Retorna o nome do tipo de variante de cada linha da coluna Variant. Se a linha contiver NULL, retorna ‘None’.

Sintaxe

variantType(variant)

Argumentos

• variant — coluna Variant. Variant

Valor retornado

Retorna uma coluna Enum com o nome do tipo da variante para cada linha. Enum

Exemplos

Exemplo de uso

Query

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

Response

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

​

version

Introduzido na versão: v1.1.0

Retorna a versão atual do ClickHouse como uma string no formato: major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release. Se for executada no contexto de uma tabela distribuída, esta função gera uma coluna comum com valores específicos de cada shard. Caso contrário, produz um valor constante.

Sintaxe

version()

Argumentos

• Nenhum.

Valor retornado

Retorna a versão atual do ClickHouse. String

Exemplos

Exemplo de uso

Query

SELECT version()

Response

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

​

visibleWidth

Introduzido em: v1.1.0

Calcula a largura aproximada ao gerar valores no console em formato de texto (separado por tabulação). Esta função é usada pelo sistema para implementar os formatos Pretty. NULL é representado como uma string correspondente a NULL nos formatos Pretty.

Sintaxe

visibleWidth(x)

Argumentos

• x — Um valor de qualquer tipo de dado. Any

Valor retornado

Retorna a largura aproximada do valor quando ele é exibido em formato de texto. UInt64

Exemplos

Calcular a largura visível de NULL

Query

SELECT visibleWidth(NULL)

Response

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

​

zookeeperSessionUptime

Introduzido em: v21.11.0

Retorna o uptime da sessão atual do ZooKeeper, em segundos.

Sintaxe

zookeeperSessionUptime()

Argumentos

• Nenhum.

Valor retornado

Retorna o uptime da sessão atual do ZooKeeper em segundos. UInt32

Exemplos

Exemplo de uso

Query

SELECT zookeeperSessionUptime();

Response

┌─zookeeperSessionUptime()─┐
│                      286 │
└──────────────────────────┘