Outras funções

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

SELECT fqdn()

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

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

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:40:3A:91:07:C4 │
└───────────────────┘

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

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

1108152157446

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

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

20566

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

CREATE USER u1;
EXECUTE AS u1 SELECT currentUser(), authenticatedUser();
DROP USER u1;

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

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

CREATE TABLE hits (EventTime DateTime('UTC')) ENGINE = Memory;

-- One row per page view, spread over the hours of a day.
INSERT INTO hits
SELECT toDateTime('2026-01-01 00:00:00', 'UTC') + toIntervalHour(hour)
FROM (
    SELECT
        number AS hour,
        [293, 181, 115, 85, 69, 78, 113, 171, 278, 391, 458, 494, 510, 523, 540, 528, 539, 524, 506, 521, 522, 542, 494, 400][number + 1] AS count
    FROM numbers(24)
)
ARRAY JOIN range(count);

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

┌──h─┬───c─┬─bar────────────────┐
│  0 │ 293 │ █████████▊         │
│  1 │ 181 │ ██████             │
│  2 │ 115 │ ███▊               │
│  3 │  85 │ ██▊                │
│  4 │  69 │ ██▎                │
│  5 │  78 │ ██▌                │
│  6 │ 113 │ ███▊               │
│  7 │ 171 │ █████▋             │
│  8 │ 278 │ █████████▎         │
│  9 │ 391 │ █████████████      │
│ 10 │ 458 │ ███████████████▎   │
│ 11 │ 494 │ ████████████████▍  │
│ 12 │ 510 │ █████████████████  │
│ 13 │ 523 │ █████████████████▍ │
│ 14 │ 540 │ ██████████████████ │
│ 15 │ 528 │ █████████████████▌ │
│ 16 │ 539 │ █████████████████▉ │
│ 17 │ 524 │ █████████████████▍ │
│ 18 │ 506 │ ████████████████▊  │
│ 19 │ 521 │ █████████████████▎ │
│ 20 │ 522 │ █████████████████▍ │
│ 21 │ 542 │ ██████████████████ │
│ 22 │ 494 │ ████████████████▍  │
│ 23 │ 400 │ █████████████▎     │
└────┴─────┴────────────────────┘

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

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

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

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

SELECT blockSerializedSize(maxState(1)) AS x;

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

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

SELECT blockSize()
FROM system.numbers LIMIT 5

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

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 de compilação. String

Exemplos

Exemplo de uso

SELECT buildId()

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

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

SELECT byteSize('string')

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

Vários argumentos

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

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

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.

O arquivo do modelo deve estar localizado dentro do diretório user_files, como na função file.

Sintaxe

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

Argumentos

• path_to_model — Caminho para o modelo CatBoost, localizado dentro do diretório user_files. const String
• feature — Um ou mais atributos/argumentos do modelo. Float*

Valor retornado

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

Exemplos

catboostEvaluate

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

4.695691092573497

Introduzido em: v26.2.0

Converte uma cor do espaço de cores perceptivo 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 será definido pela 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)

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

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

Converter OKLAB para sRGB (UInt8)

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

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

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.

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

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

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

Converter OKLCH em sRGB (UInt8)

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

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

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 é definido pela implementação.

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

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

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

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.

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

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

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

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

SELECT connectionId();

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

Introduzido em: v20.8.0

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

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

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));

┌─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 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

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, DATABASE, SCHEMA

Argumentos

• Nenhum.

Valor retornado

Retorna o nome do banco de dados atual. String

Exemplos

Exemplo de uso

SELECT currentDatabase()

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

Sintaxe SQL padrão sem parênteses

SELECT CURRENT_DATABASE

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

Introduzido em: v26.6.0

Retorna o nome do handler HTTP definido em SQL (criado com CREATE HANDLER) que invocou a consulta. Retorna uma string vazia se a consulta não tiver sido invocada por esse handler.

Útil para personalizar o comportamento da consulta conforme o handler invocado.

Sintaxe

currentHandler()

Argumentos

• Nenhum.

Valor retornado

Retorna o nome do handler atual. String

Exemplos

Exemplo de uso

SELECT currentHandler()

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

SELECT currentProfiles();

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

Introduzido em: v25.2.0

Retorna o ID da consulta atual.

Sintaxe

currentQueryID()

Aliases: current_query_id

Argumentos

• Nenhum.

Valor retornado

Exemplos

Exemplo

SELECT currentQueryID();

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

Introduzida na versão: v26.6.0

Retorna a URL da requisição HTTP (caminho e string de consulta) que invocou a consulta. Retorna uma string vazia se a consulta não tiver sido invocada por HTTP.

Útil em combinação com handlers HTTP definidos em SQL (CREATE HANDLER) para extrair parâmetros embutidos no caminho da requisição.

Sintaxe

currentRequestURL()

Argumentos

• Nenhum.

Valor retornado

Retorna a URL da requisição HTTP atual. String

Exemplos

Exemplo de uso

SELECT currentRequestURL()

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

SELECT currentRoles();

┌─currentRoles()─┐
│ []             │
└────────────────┘

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

SELECT currentSchemas(true)

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

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, current_user, 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

SELECT currentUser()

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

Sintaxe SQL padrão sem parênteses

SELECT CURRENT_USER

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

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

SELECT defaultProfiles();

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

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

SELECT defaultRoles();

┌─defaultRoles()─┐
│ []             │
└────────────────┘

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

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

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

Exemplo de Nullable

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

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

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

SELECT defaultValueOfTypeName('Int8');

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

Exemplo de Nullable

SELECT defaultValueOfTypeName('Nullable(Int8)');

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

Introduzido em: v26.7.0

Retorna os dígitos de um número n, começando no índice offset especificado. A contagem começa em 1, seguindo a lógica abaixo:

• Se offset for 0, uma exceção é lançada, pois offset é indexado a partir de 1.
• Se offset for negativo, a contagem começa offset dígitos a partir do fim do número, em vez do início.
• Se offset for maior que o número de dígitos em n, 0 é retornado.

Um argumento opcional length segue a lógica abaixo:

• Se length for positivo, significa o número de dígitos a considerar a partir de offset
• Se length for negativo, significa o número de dígitos à direita do número a serem excluídos

Veja também a função substring, que realiza a operação análoga em strings.

Sintaxe

digits(n, offset[, length])

Argumentos

• n — O número cujos dígitos serão calculados. (U)Int8 ou (U)Int16 ou (U)Int32 ou (U)Int64
• offset — A posição inicial do dígito em n. (U)Int8 ou (U)Int16 ou (U)Int32 ou (U)Int64
• length — Opcional. O comprimento máximo dos dígitos. (U)Int8 ou (U)Int16 ou (U)Int32 ou (U)Int64

Valor retornado

Os dígitos selecionados de n, interpretados como UInt64. Retorna 0 se o intervalo selecionado estiver vazio. Zeros à esquerda não são preservados. UInt64

Exemplos

Offset positivo

SELECT digits(1234567890, 7)

7890

Deslocamento e comprimento positivos

SELECT digits(1234567890, 7, 2)

78

Offset negativo conta a partir da direita

SELECT digits(1234567890, -3)

890

Comprimento negativo exclui dígitos à direita

SELECT digits(1234567890, 3, -2)

345678

Offset após o fim retorna 0

SELECT digits(1234567890, 11)

0

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

SELECT displayName();

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

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

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

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

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

SELECT enabledProfiles();

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

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

SELECT enabledRoles();

┌─enabledRoles()─┐
│ []             │
└────────────────┘

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

SELECT errorCodeToName(252);

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

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

INSERT INTO FUNCTION file('a.txt', 'RawBLOB') SELECT 'Hello' SETTINGS engine_file_truncate_on_insert = 1;
INSERT INTO FUNCTION file('b.txt', 'RawBLOB') SELECT 'World!' SETTINGS engine_file_truncate_on_insert = 1;

CREATE TABLE data (a String, b String) ENGINE = Memory;
INSERT INTO data SELECT file('a.txt'), file('b.txt');

SELECT * FROM data;

┌─a─────┬─b──────┐
│ Hello │ World! │
└───────┴────────┘

Introduzido na versão: v20.1.0

Retorna a quantidade de espaço livre no sistema de arquivos que hospeda a persistência do banco de dados. 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

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

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

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

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

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

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

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

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

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

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

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

Em combinação com initializeAggregation

SET allow_deprecated_error_prone_window_functions = 1;
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);

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

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 (MultiPoint, 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, MultiPoint, 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)), MultiPoint (Array(Point)), 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 MultiPoint ou Ring ou Polygon ou MultiPolygon ou LineString ou MultiLineString ou Geometry

Exemplos

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2,1)

Ring

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

[(2,1),(4,3)]

polygon

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

[[(2,1),(4,3)],[(6,5),(8,7)]]

geometry_wkt

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

(20,10)

geometry_polygon_wkt

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

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

Introduzido em: v23.10.0

Retorna uma versão formatada, possivelmente múltiplas linhas, da consulta SQL fornecida. Lança 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

múltiplas linhas

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

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

Introduzido em: v26.8.0

Recebe uma representação JSON de uma AST SQL (produzida por parseQueryToJSON) e a formata novamente como uma string de consulta SQL.

Com um argumento, produz SQL formatado canonicamente. Com dois argumentos (json, original_query), preserva comentários, espaços em branco e indentação da consulta original da melhor maneira possível.

A AST desserializada é limitada pelas configurações max_ast_depth e max_ast_elements da sessão atual. Juntamente com parseQueryToJSON, esta função permite inspecionar e transformar consultas programaticamente por meio de sua representação de AST em JSON.

Sintaxe

formatQueryFromJSON(json[, original_query])

Argumentos

• json — Uma string JSON que representa uma AST SQL. String
• original_query — Opcional. A consulta SQL original, cuja formatação deve ser preservada. String

Valor retornado

Uma string de consulta SQL. String

Exemplos

Ida e volta

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'))─┐
│ SELECT a, b FROM t WHERE x > 1                                          │
└─────────────────────────────────────────────────────────────────────────┘

Preservar a formatação

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t');

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t')─┐
│ SELECT /* comment */ a FROM t                                                             │
└───────────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.11.0

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

Sintaxe

formatQueryOrNull(query)

Argumentos

• query — A consulta SQL a ser formatada. String

Valor retornado

A consulta formatada String

Exemplos

múltiplas linhas

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

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

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

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

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

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

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

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

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

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

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

Com precisão explícita

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

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

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

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

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

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

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

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

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

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

Com precisão explícita

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

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

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

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

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

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

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

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

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

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

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

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

SELECT generateRandomStructure()

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

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

com seed definida

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8(\'c2V0\' = -123, \'c2V1\' = 94, \'c2V2\' = -105, \'c2V3\' = 67), c3 Nullable(UInt8), c4 String, c5 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(71))), c6 UInt32, c7 Bool, c8 Float64

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

SELECT generateSerialID('id1')

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

segunda chamada

SELECT generateSerialID('id1')

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

chamada da coluna

CREATE TABLE test_table (CounterID UInt32, UserID UInt32, ver UInt32) ENGINE = Memory;
INSERT INTO test_table VALUES (1, 3, 3), (1, 1, 1), (1, 2, 2), (1, 5, 5), (1, 4, 4);

SELECT *, generateSerialID('id1') FROM test_table

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

com valor inicial

SELECT generateSerialID('id2', 100)

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

com valor inicial na segunda chamada

SELECT generateSerialID('id2', 100)

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

Introduzido em: v24.5.0

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

Os cabeçalhos HTTP não diferenciam maiúsculas de minúsculas de acordo com a RFC 9110. Se a função for usada no contexto de uma consulta distribuída, ela retorna um resultado não vazio somente no nó iniciador.

getClientHTTPHeader lê os cabeçalhos da requisição atual, portanto retorna um valor não vazio somente quando a consulta é enviada pela interface HTTP. Por exemplo, envie o cabeçalho na requisição e leia-o de volta via HTTP:

echo "SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1" | \
    curl 'http://localhost:8123/' --data-binary @- -H 'Content-Type: application/x-www-form-urlencoded'

O comando acima retorna application/x-www-form-urlencoded.

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

-- Over a non-HTTP interface (such as `clickhouse-client` or `clickhouse-local`) there are
-- no request headers, so the function returns an empty string. See the description above
-- for an HTTP example that returns the actual header value.
SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1

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

SELECT getMacro('test');

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

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

SELECT getMaxTableNameLengthForDatabase('default');

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

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

SELECT getMergeTreeSetting('index_granularity');

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

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

SELECT getOSKernelVersion();

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

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

SELECT getServerPort('tcp_port');

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

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

SELECT getServerSetting('allow_use_jemalloc_memory');

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

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

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

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

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

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

my_value
100
\N

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

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

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

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

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')
FROM values('array_col Array(UInt32), tuple_col Tuple(elem_name String)', ([1, 2, 3], tuple('abc')));

┌─getSubcolumn(array_col, 'size0')─┬─getSubcolumn(tuple_col, 'elem_name')─┐
│                                3 │ abc                                  │
└──────────────────────────────────┴──────────────────────────────────────┘

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

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

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

map

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

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

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

SELECT globalVariable('max_allowed_packet')

67108864

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(database, table, column)

Argumentos

• database — Nome do banco de dados. const String
• table — Nome da tabela. const String
• column — Nome da coluna. const String

Valor retornado

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

Exemplos

Verificar uma coluna existente

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

1

Verifique uma coluna inexistente

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

0

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

SELECT hasThreadFuzzer()

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

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

SELECT highlightQuery('SELECT 1')

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

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

SELECT hostName()

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

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

SELECT icebergBucket(5, 1.0 :: Float32)

4

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

SELECT icebergTruncate(3, 'iceberg')

ice

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

SELECT identity(42)

42

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

SELECT ignore(0, 'ClickHouse', NULL)

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

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.

SELECT * FROM test WHERE key = 123;

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

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

-- `index_granularity` is lowered to 8 here only to keep the example small enough to follow.
-- Do not change it in production: the default of 8192 is what makes the index sparse and cheap,
-- and a small value makes the index large and slows queries down.
CREATE TABLE ontime (FlightDate Date, Carrier String)
ENGINE = MergeTree ORDER BY FlightDate
SETTINGS index_granularity = 8;

-- Ten flights on each of four days, so a granule of eight rows spans more than one day.
INSERT INTO ontime SELECT toDate('2025-09-14') + intDiv(number, 10), 'AA' FROM numbers(40);

-- The granules that hold the rows of 2025-09-15 also hold rows of the neighbouring days,
-- and `indexHint` returns all of them.
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │       2 │
│ 2025-09-15 │      10 │
│ 2025-09-16 │       4 │
└────────────┴─────────┘

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

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

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

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

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

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

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

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

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

Uso de sumState e finalizeAggregation

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

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

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

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

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

Constante com função

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

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

Expressão não constante

SELECT isConstant(number)
FROM numbers(1)

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

Comportamento da função now()

SELECT isConstant(now())

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

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

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

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

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.

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

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

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

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

Uso com tabela do banco de dados atual

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

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

Usar arrays como chaves de junção

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', toUInt32(1), toUInt32(11));

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

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.

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

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

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

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

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

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

-- create two parts:

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

-- the order the blocks are read in is not defined, so sort the result to make it reproducible:

SELECT s, lowCardinalityIndices(s) AS index FROM test ORDER BY s, index;

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

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

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

-- create two parts:

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

SELECT s, lowCardinalityKeys(s) FROM test;

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

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

-- 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');

2

Transformando uma constante em uma coluna completa

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

Received exception:
Code: 44. DB::Exception: A value of illegal type was provided as 2nd argument 'pattern' to function 'countMatches'. Expected: constant String, got: String. (ILLEGAL_COLUMN)

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

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

(616.2931945826209,108.8825,115.6175)

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

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

(3396.077603219163,0.22,0.28)

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

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

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

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

┌─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 │
└────────┴──────────────────────────┘

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

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

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

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

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

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

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

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

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

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

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;

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

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

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

SELECT fruit, number FROM table WHERE number > 12

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

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

SELECT a FROM b, SELECT c FROM d

Linhas diferentes geram resultados diferentes

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

SELECT 1	SELECT 1

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

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

SELECT name FROM users

Ofuscação determinística com seed textual

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

SELECT id, value FROM data

A mesma seed gera o mesmo resultado

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

1

Introduzido em: v26.8.0

Analisa uma string de consulta SQL e a converte em sua AST (Árvore de Sintaxe Abstrata), retornando uma representação JSON dessa árvore. O JSON resultante pode ser passado para formatQueryFromJSON para reconstruir a consulta SQL ou enviado diretamente ao servidor usando o valor clickhouse_json da configuração dialect (condicionado a enable_json_ast_dialect).

Isso é útil para ferramentas que desejam inspecionar ou transformar consultas programaticamente sem passar pela gramática SQL.

Nem toda consulta SQL tem uma representação JSON fiel. Consultas que contêm dados que o formato JSON não consegue reproduzir (por exemplo, dados inline em INSERT ... VALUES / INSERT ... FORMAT) e tipos de nós da AST que ainda não implementam serialização JSON são rejeitados com BAD_ARGUMENTS, em vez de gerar um JSON que formatQueryFromJSON não conseguiria ler novamente.

Os limites de análise (max_query_size, max_parser_depth, max_parser_backtracks) são obtidos das configurações da sessão atual.

Sintaxe

parseQueryToJSON(sql)

Argumentos

• sql — Uma string de consulta SQL a ser analisada. String

Valor retornado

Uma string JSON que representa a AST. String

Exemplos

SELECT simples

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT 1'))─┐
│ SELECT 1                                          │
└───────────────────────────────────────────────────┘

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

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

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

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

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

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

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

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

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

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

SELECT parseTimeDelta('11s+22min')

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

Unidades de tempo complexas

SELECT parseTimeDelta('1yr2mo')

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

Introduzido em: v21.4.0

Calcula o ID da partição.

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

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;

┌─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             │
└───┴───┴────────────────┴───────────────┘

Introduzida em: v26.8.0

Função de compatibilidade para o protocolo wire do PostgreSQL, equivalente a pg_catalog.pg_get_userbyid. Clientes PostgreSQL (por exemplo, o comando \d no psql) a usam para exibir o proprietário de uma tabela. O ClickHouse não rastreia a propriedade de tabelas, portanto a função ignora o argumento e retorna o nome do usuário atual.

Sintaxe

pgGetUserById(oid)

Aliases: pg_get_userbyid

Argumentos

• oid — Identificador de objeto da função. O valor é ignorado. UInt32

Valor retornado

Retorna o nome do usuário atual. String

Exemplos

Exemplo de uso

SELECT pg_get_userbyid(10)

┌─pg_get_userbyid(10)─┐
│ default             │
└─────────────────────┘

Introduzido em: v26.8.0

Função de compatibilidade para o protocolo wire do PostgreSQL, equivalente a pg_catalog.pg_table_is_visible. Clientes PostgreSQL (por exemplo, o comando \d no psql) a usam para filtrar tabelas visíveis no caminho de busca. Como a view pg_class emulada pelo ClickHouse expõe apenas as tabelas do banco de dados atual, que são todas visíveis, a função sempre retorna 1.

Sintaxe

pgTableIsVisible(oid)

Aliases: pg_table_is_visible

Argumentos

• oid — Identificador de objeto da tabela, conforme exposto pela view pg_class emulada. O valor é ignorado. UInt32

Valor retornado

Sempre retorna 1. UInt8

Exemplos

Exemplo de uso

SELECT pg_table_is_visible(0)

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

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

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

┌─countDistinct(t)─┐
│                3 │
└──────────────────┘

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

SELECT revision()

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

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

-- The data is processed in blocks of two rows: rowNumberInBlock restarts from 0 in every block,
-- while rowNumberInAllBlocks keeps counting across them.
SELECT
    number,
    rowNumberInBlock(),
    rowNumberInAllBlocks()
FROM system.numbers
LIMIT 6
SETTINGS max_block_size = 2

┌─number─┬─rowNumberInBlock()─┬─rowNumberInAllBlocks()─┐
│      0 │                  0 │                      0 │
│      1 │                  1 │                      1 │
│      2 │                  0 │                      2 │
│      3 │                  1 │                      3 │
│      4 │                  0 │                      4 │
│      5 │                  1 │                      5 │
└────────┴────────────────────┴────────────────────────┘

Introduzido em: v1.1.0

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

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

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

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

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

Introduzido em: v1.1.0

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

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

SET allow_deprecated_error_prone_window_functions = 1;
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);

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

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.

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 concorrentes em cada horário de início dos eventos. UInt32

Exemplos

Exemplo de uso

CREATE TABLE example_table (start Date, end Date) ENGINE = Memory;
INSERT INTO example_table VALUES ('2025-03-03', '2025-03-11'), ('2025-03-06', '2025-03-08'), ('2025-03-07', '2025-03-09'), ('2025-03-11', '2025-03-12');

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

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

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.

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 acumulada. Any

Valor retornado

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

Exemplos

Exemplo de uso

SET allow_deprecated_error_prone_window_functions = 1;

CREATE TABLE events
(
    EventID UInt32,
    EventDate Date,
    EventTime DateTime
)
ENGINE = Memory;

INSERT INTO events VALUES
    (1106, '2025-11-24', '2025-11-24 00:00:04'),
    (1107, '2025-11-24', '2025-11-24 00:00:05'),
    (1108, '2025-11-24', '2025-11-24 00:00:05'),
    (1109, '2025-11-24', '2025-11-24 00:00:09'),
    (1110, '2025-11-24', '2025-11-24 00:00:10');

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

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

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