Introduzido em: v1.1.0Interpreta 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
Introduzido em: v1.1.0Dado 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
Introduzido em: v25.11.0Se 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: authUserArgumentos
Nenhum.
Valor retornadoO nome do usuário autenticado. StringExemplosExemplo de uso
Query
EXECUTE as u1; SELECT currentUser(), authenticatedUser();
Introduzido em: v1.1.0Cria 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
Introduzido em: v1.1.0Retorna 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 retornadoNúmero de sequência do bloco de dados em que a linha se encontra. UInt64ExemplosUso básico
Introduzido em: v1.1.0No 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 retornadoRetorna o número de linhas do bloco atual. UInt64ExemplosExemplo de uso
Introduzido em: v20.5.0Retorna 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 retornadoRetorna o ID da compilação. StringExemplosExemplo de uso
Introduzido em: v21.1.0Retorna uma estimativa do tamanho em bytes descomprimido 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 retornadoRetorna uma estimativa do tamanho em bytes dos argumentos na memória. UInt64ExemplosExemplo de uso
Introduzido em: v22.9.0Avalia 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
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:
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.
Introduzido em: v26.2.0Converte uma cor do espaço de cores perceptual OKLab para o espaço de cores sRGB.A cor de entrada é especificada no espaço de cores OKLab. Se os valores de entrada estiverem fora
das faixas típicas do OKLab, o resultado dependerá da implementação.O OKLab usa três componentes:
L: luminosidade perceptual (normalmente no intervalo [0..1])
a: eixo oponente verde-vermelho
b: eixo oponente azul-amarelo
Os componentes a e b são teoricamente ilimitados, mas, na prática, ficam entre -0.4 e 0.4.
O OKLab foi projetado para ser perceptualmente uniforme
e, ao mesmo tempo, ter baixo custo computacional.A conversão foi concebida para ser o inverso de colorSRGBToOKLAB e consiste em
os seguintes estágios:
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
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 retornadoRetorna uma tupla (R, G, B) que representa valores de cor sRGB. Tuple(Float64, Float64, Float64)ExemplosConverta OKLAB para sRGB (Float)
Query
SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;
Introduzido em: v25.7.0Converte uma cor do espaço de cores perceptivo OKLCH para o conhecido espaço de cores sRGB.Se L estiver fora do intervalo [0...1], C for negativo ou H estiver fora do intervalo [0...360], o resultado será definido pela implementação.
OKLCH é uma versão cilíndrica do espaço de cores OKLab.
Suas três coordenadas são L (a luminosidade no intervalo [0...1]), C (croma >= 0) e H (matiz em graus no intervalo [0...360]).
OKLab/OKLCH foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.
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 retornadoRetorna uma tupla (R, G, B) que representa valores de cor sRGB. Tuple(Float64, Float64, Float64)ExemplosConverter OKLCH para sRGB
Introduzido em: v26.2.0Converte uma cor codificada no espaço de cores sRGB para o espaço de cores OKLAB, perceptualmente uniforme.Se algum canal de entrada estiver fora de [0...255] ou se o valor de gamma não for positivo, o comportamento depende da implementação.
OKLAB é um espaço de cores perceptualmente uniforme.
Suas três coordenadas são L (a luminosidade no intervalo [0...1]), a (eixo Verde-Vermelho) e b (eixo Azul-Amarelo).
O OKLab foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.
gamma — Opcional. Expoente usado para linearizar o sRGB, aplicando (x / 255)^gamma a cada canal x. O padrão é 2.2. Float64
Valor retornadoRetorna uma tupla (L, a, b) que representa os valores no espaço de cores OKLAB. Tuple(Float64, Float64, Float64)ExemplosConverta sRGB para OKLAB
Query
SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;
Introduzido em: v25.7.0Converte uma cor codificada no espaço de cores sRGB para o espaço de cores OKLCH, que é perceptualmente uniforme.Se algum canal de entrada estiver fora de [0...255] ou se o valor de gamma não for positivo, o comportamento é definido pela implementação.
OKLCH é uma versão cilíndrica do espaço de cores OKLab.
Suas três coordenadas são L (a luminosidade no intervalo [0...1]), C (croma >= 0) e H (a matiz em graus no intervalo [0...360]).
OKLab/OKLCH foi projetado para ser perceptualmente uniforme, mantendo baixo custo computacional.
A conversão consiste em três etapas:
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
gamma — Opcional. Expoente usado para linearizar o sRGB, aplicando (x / 255)^gamma a cada canal x. O padrão é 2.2. Float64
Valor retornadoRetorna uma tupla (L, C, H) que representa os valores do espaço de cores OKLCH. Tuple(Float64, Float64, Float64)ExemplosConverter sRGB em OKLCH
Query
SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;
Introduzido em: v21.3.0Retorna 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 retornadoRetorna o ID da conexão do cliente atual. UInt64ExemplosExemplo de uso
Introduzido em: v20.8.0Retorna o número de dígitos decimais necessários para representar um valor.
Esta função leva em conta as escalas dos valores decimais, ou seja, calcula o resultado com base no tipo inteiro subjacente, que é (value * scale).Por exemplo:
countDigits(42) = 2
countDigits(42.000) = 5
countDigits(0.04200) = 4
Você pode verificar se há overflow em Decimal64 com countDigits(x) > 18,
embora isso seja mais lento do que isDecimalOverflow.
Introduzido em: v1.1.0Retorna 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
Introduzido em: v1.1.0Retorna 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 retornadoRetorna 0 para números, uma string vazia para Strings ou NULL para tipos Nullable. UInt8 ou String ou NULLExemplosExemplo de uso
Query
SELECT defaultValueOfArgumentType(CAST(1 AS Int8));
Introduzido em: v1.1.0Retorna 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 retornadoRetorna 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 NULLExemplosExemplo de uso
Introduzido em: v22.11.0Retorna 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 retornadoRetorna o valor de display_name da config ou o FQDN do servidor, caso não esteja definido. StringExemplosExemplo de uso
Introduzido em: v20.12.0Retorna 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
Introduzido em: v21.3.0Lê 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 retornadoRetorna o conteúdo do arquivo como string. StringExemplosInserir arquivos em uma tabela
Query
INSERT INTO table SELECT file('a.txt'), file('b.txt');
Introduzido na versão: v20.1.0Retorna a quantidade de espaço livre no sistema de arquivos que hospeda a persistência da database.
O valor retornado é sempre menor que o espaço livre total (filesystemUnreserved), porque parte do espaço é reservada para o sistema operacional.Sintaxe
filesystemAvailable([disk_name])
Argumentos
disk_name — Opcional. O nome do disco para o qual encontrar a quantidade de espaço livre. Se omitido, usa o disco padrão. String ou FixedString
Valor retornadoRetorna a quantidade de espaço livre restante em bytes. UInt64ExemplosExemplo de uso
Query
SELECT formatReadableSize(filesystemAvailable()) AS "Available space";
Introduzido em: v20.1.0Retorna 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 retornadoRetorna a capacidade do sistema de arquivos em bytes. UInt64ExemplosExemplo de uso
Query
SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";
Introduzido na versão: v22.12.0Retorna 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 retornadoRetorna a quantidade de espaço livre em bytes. UInt64ExemplosExemplo de uso
Query
SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";
Introduzido em: v1.1.0Dado um estado de agregação, esta função retorna o resultado da agregação (ou o estado finalizado ao usar o combinador -State).Sintaxe
WITH initializeAggregation('sumState', number) AS one_row_sum_stateSELECT number, finalizeAggregation(one_row_sum_state) AS one_row_sum, runningAccumulate(one_row_sum_state) AS cumulative_sumFROM numbers(5);
Introduzido em: v25.11.0Inverte as coordenadas x e y de objetos geométricos. Essa operação troca latitude e longitude, o que é útil para converter entre diferentes sistemas de coordenadas ou corrigir a ordem das coordenadas.Para um Point, troca as coordenadas x e y. Para geometrias complexas (LineString, Polygon, MultiPolygon, Ring, MultiLineString), aplica recursivamente a transformação a cada par de coordenadas.A função oferece suporte tanto a tipos geométricos individuais (Point, Ring, Polygon, MultiPolygon, LineString, MultiLineString) quanto ao tipo Geometry Variant.Sintaxe
flipCoordinates(geometry)
Argumentos
geometry — A geometria a ser transformada. Tipos suportados: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)) ou Geometry (uma variante que contém qualquer um desses tipos).
Introduzido em: v23.10.0Retorna uma versão formatada, possivelmente multilinha, da consulta SQL fornecida. Gera uma exceção em caso de erro de parsing.
[example:multiline]Sintaxe
Introduzido em: v23.11.0Retorna uma versão formatada, possivelmente em várias linhas, da consulta SQL fornecida. Retorna NULL em caso de erro de parsing.
[exemplo:multilinha]Sintaxe
Introduzido em: v23.10.0Como 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
Introduzido em: v23.11.0Como 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
Introduzido em: v22.11.0Dado 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
Introduzido em: v20.10.0Dado 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
Introduzido em: v1.1.0Dado 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
Introduzido em: v20.12.0Dado um intervalo de tempo (delta) em segundos, 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.Sintaxe
column — Uma coluna com uma diferença de tempo numérica. Float64
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 retornadoRetorna uma diferença de tempo como string. StringExemplosExemplo de uso
Query
SELECT arrayJoin([100, 12345, 432546534]) AS elapsed, formatReadableTimeDelta(elapsed) AS time_delta
Response
┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐│ 100 │ 1 minute and 40 seconds ││ 12345 │ 3 hours, 25 minutes and 45 seconds ││ 432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│└────────────┴────────────────────────────────────────────────────────────────┘
Com a unidade máxima
Query
SELECT arrayJoin([100, 12345, 432546534]) AS elapsed, formatReadableTimeDelta(elapsed, 'minutes') AS time_delta
Response
┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐│ 100 │ 1 minute and 40 seconds ││ 12345 │ 205 minutes and 45 seconds ││ 432546534 │ 7209108 minutes and 54 seconds │└────────────┴─────────────────────────────────────────────────────────────────┘
Introduzido em: v26.2.0Analisa 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 retornadoA string da consulta após o fuzzing StringExemplosbásico
Query
SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');
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 retornadoEstrutura de tabela gerada aleatoriamente. StringExemplosExemplo de uso
Introduzido em: v25.1.0Gera 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
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 retornadoRetorna números sequenciais a partir do valor anterior do contador. UInt64Exemplosprimeira chamada
Introduzido em: v24.5.0Obtém o valor de um cabeçalho HTTP.
Se esse cabeçalho não existir ou se a solicitação atual não for feita pela interface HTTP, a função retornará uma string vazia.
Alguns cabeçalhos HTTP (por exemplo, Authentication e X-ClickHouse-*) são restritos.
A configuração allow_get_client_http_header é obrigatóriaA função exige que a configuração allow_get_client_http_header esteja habilitada.
Por motivos de segurança, essa configuração não vem habilitada por padrão, pois alguns cabeçalhos, como Cookie, podem conter informações sensíveis.
Os cabeçalhos HTTP diferenciam maiúsculas de minúsculas nesta função.
Se a função for usada no contexto de uma consulta distribuída, ela retornará um resultado não vazio apenas no nó iniciador.Sintaxe
Introduzido em: v20.1.0Retorna 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
Introduzido em: v24.10.0Retorna 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
Introduzido em: v23.3.0Recebe uma expressão ou identificador e uma string constante com o nome da subcoluna.Retorna a subcoluna solicitada, extraída da expressão.Sintaxe
Introduzido em: v20.5.0Recebe 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
Introduzido em: v1.1.0Verifica 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
Introduzido em: v26.5.0Analisa 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.
Introduzido em: v20.5.0Retorna 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: hostnameArgumentos
Nenhum.
Valor retornadoRetorna o nome do host. StringExemplosExemplo de uso
Introduzido em: v1.1.0Esta 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
Introduzido em: v1.1.0Esta função se destina à depuração e à introspecção.
Ela ignora o argumento e sempre retorna 1.
Os argumentos não são avaliados.Durante a análise do índice, considera-se que o argumento desta função não esteja encapsulado em indexHint.
Isso permite selecionar dados em intervalos do índice pela condição correspondente, mas sem aplicar filtragem adicional por essa condição.
O índice no ClickHouse é esparso, e usar indexHint retornará mais dados do que especificar a mesma condição diretamente.
Explicação
Quando você executa:
SELECT * FROM test WHERE key = 123;
O ClickHouse faz duas coisas:
Usa o índice para encontrar quais grânulos (blocos de ~8192 linhas) podem conter key = 123
Lê esses grânulos e filtra suas linhas para retornar apenas aquelas em que key = 123
Assim, mesmo que ele leia 8.192 linhas do disco, retorna apenas a 1 linha que realmente corresponde.Com indexHint, quando você executa:
SELECT * FROM test WHERE indexHint(key = 123);
O ClickHouse faz apenas uma coisa:
Usa o índice para encontrar quais grânulos podem conter key = 123 e retorna todas as linhas desses grânulos sem filtrá-las.
Ele retorna todas as 8.192 linhas, incluindo linhas em que key = 456, key = 789 etc. (Tudo o que, por acaso, estava armazenado no mesmo grânulo.)
indexHint() não serve para melhorar o desempenho. Ele serve para depuração e para entender como o índice do ClickHouse funciona:
Quais grânulos a minha condição seleciona?
Quantas linhas há nesses grânulos?
Meu índice está sendo usado de forma eficaz?
Observação: não é possível otimizar uma consulta com a função indexHint. A função indexHint não otimiza a consulta, pois não fornece nenhuma informação adicional para a análise da consulta. Ter uma expressão dentro da função indexHint não é, de forma alguma, melhor do que não usar a função indexHint. A função indexHint pode ser usada apenas para fins de introspecção e depuração e não melhora o desempenho. Se você vir o uso de indexHint por alguém que não seja um colaborador do ClickHouse, provavelmente é um erro, e você deve removê-lo.Sintaxe
indexHint(expression)
Argumentos
expression — Qualquer expressão para seleção de intervalo de índice. Expression
Valor retornadoRetorna 1 em todos os casos. UInt8ExemplosExemplo de uso com filtro por data
Query
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;
Introduzido em: v1.1.0Retorna 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_idArgumentos
Nenhum.
Valor retornadoRetorna o ID da consulta inicial da consulta atual. StringExemplosExemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introduzido em: v25.4.0Retorna o horário de início da consulta inicial atual.
initialQueryStartTime retorna os mesmos resultados em diferentes shards.Sintaxe
initialQueryStartTime()
Aliases: initial_query_start_timeArgumentos
Nenhum.
Valor retornadoRetorna o horário de início da consulta inicial atual. DateTimeExemplosExemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introduzido em: v20.6.0Calcula 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
aggregate_function — Nome da função de agregação a ser inicializada. String
arg1[, arg2, ...] — Argumentos da função de agregação. Any
Valor retornadoRetorna 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. AnyExemplosUso básico com uniqState
Query
SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
Response
┌─uniqMerge(state)─┐│ 3 │└──────────────────┘
Uso de sumState e finalizeAggregation
Query
SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
Introduzido em: v20.3.0Retorna 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
Introduzido em: v20.8.0Verifica 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 retornadoRetorna 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. UInt8ExemplosExemplo de uso
Introduzido em: v18.16.0Permite extrair dados de uma tabela da mesma forma que de um Dicionário.
Obtém dados de tabelas Join usando a chave de junção especificada.
Compatível apenas com tabelas criadas com a instrução ENGINE = Join(ANY, LEFT, <join_keys>)instrução.
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
Introduzido em: v20.4.0Permite extrair dados de uma tabela da mesma forma que de um Dicionário.
Obtém dados de tabelas Join usando a chave de junção especificada.
Ao contrário de joinGet, retorna NULL quando a chave não existe.
Suporta apenas tabelas criadas com a instruçãoENGINE = Join(ANY, LEFT, <join_keys>).
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
Introduzido em: v18.12.0Retorna 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
Valor retornadoA posição do valor no dicionário da parte atual. UInt64ExemplosExemplos de uso
Query
DROP TABLE IF EXISTS test;CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;-- criar duas partes:INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');SELECT s, lowCardinalityIndices(s) FROM test;
Response
┌─s──┬─lowCardinalityIndices(s)─┐│ ab │ 1 ││ cd │ 2 ││ ab │ 1 ││ ab │ 1 ││ df │ 3 │└────┴──────────────────────────┘┌─s──┬─lowCardinalityIndices(s)─┐│ ef │ 1 ││ cd │ 2 ││ ab │ 3 ││ cd │ 2 ││ ef │ 1 │└────┴──────────────────────────┘
Introduzido em: v18.12.0Retorna 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
Valor retornadoRetorna as chaves do dicionário. UInt64ExemploslowCardinalityKeys
Query
DROP TABLE IF EXISTS test;CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;-- criar duas partes:INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');SELECT s, lowCardinalityKeys(s) FROM test;
Response
┌─s──┬─lowCardinalityKeys(s)─┐│ ef │ ││ cd │ ef ││ ab │ cd ││ cd │ ab ││ ef │ │└────┴───────────────────────┘┌─s──┬─lowCardinalityKeys(s)─┐│ ab │ ││ cd │ ab ││ ab │ cd ││ ab │ df ││ df │ │└────┴───────────────────────┘
Introduzido em: v1.1.0Transforma 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
Valor retornadoRetorna uma coluna completa que contém o valor constante. AnyExemplosExemplo de uso
Query
-- No exemplo abaixo, a função `countMatches` espera que o segundo argumento seja constante.-- Esse comportamento pode ser depurado usando a função `materialize` para transformar uma constante em uma coluna completa,-- verificando que a função gera um erro quando o argumento não é constante.SELECT countMatches('foobarfoo', 'foo');SELECT countMatches('foobarfoo', materialize('foo'));
Response
2Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String
Introduzido na versão: v23.10.0Calcula 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
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 retornadoRetorna 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)ExemplosminSampleSizeContinuous
Query
SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size
Introduzido em: v22.6.0Calcula 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
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 retornadoRetorna 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)ExemplosminSampleSizeConversion
Query
SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size
Introduzido em: v20.1.0Retorna 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
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 retornadoRetorna um valor no deslocamento especificado ou o valor padrão, se estiver fora dos limites. AnyExemplosExemplo de uso
Query
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;
Introduzido em: v20.8.0Substitui 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
Introduzido em: v21.2.0Substitui 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
Valor retornadoRetorna a sequência de caracteres informada com placeholders. StringExemplosExemplo de uso
Query
SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')
Response
┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐│ SELECT ? AS `?` │ SELECT ? AS aComplexName123 │└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
Introduzido na versão: v20.8.0Retorna 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
Introduzido em: v21.2.0Assim 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
Valor retornadoRetorna um valor de hash de 64 bits. UInt64ExemplosExemplo de uso
Query
SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;
Introduzido em: v26.4.0Ofusca 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
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 retornadoA consulta ofuscada, com identificadores e literais substituídos, preservando a estrutura original da consulta. StringExemplosUso básico
Query
SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')
Response
SELECT fruit, number FROM table WHERE number > 12
Com tag para evitar a eliminação de subexpressões comuns
Query
SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)
Response
SELECT a FROM b, SELECT c FROM d
Linhas diferentes geram resultados diferentes
Query
SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b
Introduzido em: v26.4.0Ofusca 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()
Introduzido em: v24.6.0Dada 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 retornadoRetorna o número de bytes, arredondado para cima para o inteiro mais próximo. UInt64ExemplosExemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;
Introduzido em: v24.6.0Dada 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 retornadoRetorna 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)ExemplosExemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;
Introduzido em: v24.6.0Dada 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 retornadoRetorna 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. UInt64ExemplosExemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;
Introduzido em: v22.7.0Analisa 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 retornadoO número de segundos. Float64ExemplosExemplo de uso
Esta função é lenta e não deve ser usada com um grande número de linhas.
Sintaxe
partitionId(column1[, column2, ...])
Aliases: partitionIDArgumentos
column1, column2, ... — Coluna cujo ID da partição deve ser retornado.
Valor retornadoRetorna o ID da partição à qual a linha pertence. StringExemplosExemplo de uso
Query
DROP TABLE IF EXISTS tab;CREATE TABLE tab( i int, j int)ENGINE = MergeTreePARTITION BY iORDER 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;
Introduzido em: v21.9.0Retorna 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_idArgumentos
Nenhum.
Valor retornadoRetorna o ID da consulta atual. StringExemplosExemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introduzido em: v1.1.0Para cada block processado por rowNumberInBlock, retorna o número da linha atual.O número retornado começa em 0 para cada block.Sintaxe
rowNumberInBlock()
Argumentos
Nenhum.
Valor retornadoRetorna o número ordinal da linha no bloco de dados, a partir de 0. UInt64ExemplosExemplo de uso
Introduzido em: v1.1.0Acumula os estados de uma função de agregação para cada linha de um bloco de dados.
DescontinuadoO estado é redefinido a cada novo bloco de dados.
Devido a esse comportamento propenso a erros, a função foi descontinuada, e recomenda-se usar funções de janela em vez dela.
Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.
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 retornadoRetorna o resultado acumulado para cada linha. AnyExemplosExemplo de uso com initializeAggregation
Query
WITH initializeAggregation('sumState', number) AS one_row_sum_stateSELECT number, finalizeAggregation(one_row_sum_state) AS one_row_sum, runningAccumulate(one_row_sum_state) AS cumulative_sumFROM numbers(5);
Introduzido em: v21.3.0Calcula 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.
RequisitosOs eventos devem ser ordenados pelo horário de início em ordem crescente.
Se esse requisito for violado, a função gera uma exceção.
Cada bloco de dados é processado separadamente.
Se eventos de blocos de dados diferentes se sobrepuserem, eles não poderão ser processados corretamente.
Introduzido em: v1.1.0Calcula 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.
DescontinuadoRetorna diferenças apenas dentro do bloco de dados que está sendo processado no momento.
Por causa desse comportamento propenso a erros, a função está descontinuada.
Recomenda-se usar funções de janela em vez dela.Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.
O resultado da função depende dos blocos de dados envolvidos e da ordem dos dados no bloco.
A ordem das linhas durante o cálculo de runningDifference() pode ser diferente da ordem das linhas retornadas ao usuário.
Para evitar isso, você pode criar uma subconsulta com ORDER BY e chamar a função fora da subconsulta.
Observe que o tamanho do bloco afeta o resultado.
O estado interno de runningDifference é reiniciado a cada novo bloco.Sintaxe
runningDifference(x)
Argumentos
x — Coluna para a qual calcular a diferença entre valores consecutivos. Any
Valor retornadoRetorna a diferença entre valores consecutivos, com 0 para a primeira linha.ExemplosExemplo de uso
Query
SELECT EventID, EventTime, runningDifference(EventTime) AS deltaFROM( SELECT EventID, EventTime FROM events WHERE EventDate = '2025-11-24' ORDER BY EventTime ASC LIMIT 5);
Introduzido em: v1.1.0Calcula a diferença entre os valores de linhas consecutivas em um bloco de dados, mas, ao contrário de runningDifference, retorna o valor real da primeira linha em vez de 0.
DescontinuadoRetorna diferenças apenas dentro do bloco de dados que está sendo processado no momento.
Devido a esse comportamento sujeito a erros, a função foi descontinuada.
Recomenda-se usar funções de janela em vez disso.Você pode usar a configuração allow_deprecated_error_prone_window_functions para permitir o uso desta função.
Sintaxe
runningDifferenceStartingWithFirstValue(x)
Argumentos
x — Coluna para a qual calcular a diferença acumulada. Any
Valor retornadoRetorna a diferença entre valores consecutivos, sendo que, para a primeira linha, retorna o valor da própria primeira linha. AnyExemplosExemplo de uso
Query
SELECT number, runningDifferenceStartingWithFirstValue(number) AS diffFROM numbers(5);
Introduzido em: v20.1.0Retorna o UUID (v4) aleatório e exclusivo gerado quando o servidor é iniciado pela primeira vez.
O UUID é persistido, ou seja, a segunda, a terceira etc. inicialização do servidor retorna o mesmo UUID.Sintaxe
serverUUID()
Argumentos
Nenhum.
Valor retornadoRetorna o UUID aleatório do servidor. UUIDExemplosExemplo de uso
Introduzido em: v21.9.0Retorna o número total de shards de uma consulta distribuída.
Se uma consulta não for distribuída, retorna o valor constante 0.Sintaxe
shardCount()
Argumentos
Nenhum.
Valor retornadoRetorna o número total de shards ou 0. UInt32ExemplosExemplo de uso
Query
-- Veja o exemplo de shardNum() acima, que também ilustra shardCount()CREATE TABLE shard_count_example (dummy UInt8)ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);SELECT shardCount() FROM shard_count_example;
Introduzido em: v21.9.0Retorna o índice do shard que processa parte dos dados em uma consulta distribuída.
Os índices começam em 1.
Se uma consulta não for distribuída, será retornado o valor constante 0.Sintaxe
shardNum()
Argumentos
Nenhum.
Valor retornadoRetorna o índice do shard ou uma constante 0. UInt32ExemplosExemplo de uso
Introduzido em: v22.6.0Exibe informações sobre o certificado Secure Sockets Layer (SSL) atual do servidor, se ele estiver configurado.
Consulte Configurando TLS para mais informações sobre como configurar o ClickHouse para usar certificados OpenSSL para validar conexões.Sintaxe
showCertificate()
Argumentos
Nenhum.
Valor retornadoRetorna um map de pares chave-valor referentes ao certificado SSL configurado. Map(String, String)ExemplosExemplo de uso
Introduzido em: v1.1.0Pausa a execução de uma consulta pelo número especificado de segundos.
A função é usada principalmente para fins de teste e depuração.Em geral, a função sleep() não deve ser usada em ambientes de produção, pois pode afetar negativamente o desempenho das consultas e a capacidade de resposta do sistema.
No entanto, ela pode ser útil nos seguintes cenários:
Teste: Ao testar ou fazer benchmarking do ClickHouse, talvez você queira simular atrasos ou introduzir pausas para observar como o sistema se comporta em determinadas condições.
Depuração: Se você precisar examinar o estado do sistema ou a execução de uma consulta em um momento específico, poderá usar sleep() para introduzir uma pausa, permitindo inspecionar ou coletar informações relevantes.
Simulação: Em alguns casos, talvez você queira simular cenários do mundo real em que ocorram atrasos ou pausas, como latência de rede ou dependências de sistemas externos.
É importante usar a função sleep() com critério e somente quando necessário, pois ela pode afetar o desempenho geral e a capacidade de resposta do seu sistema ClickHouse.
Por motivos de segurança, a função só pode ser executada no perfil do usuário default (com allow_sleep habilitado).Sintaxe
sleep(seconds)
Argumentos
seconds — O número de segundos para pausar a execução da consulta, com um máximo de 3 segundos. Pode ser um valor de ponto flutuante para especificar frações de segundo. const UInt* ou const Float*
Valor retornadoRetorna 0. UInt8ExemplosExemplo de uso
Query
-- Esta consulta fará uma pausa de 2 segundos antes de ser concluída.-- Durante esse tempo, nenhum resultado será retornado, e a consulta parecerá travada ou sem resposta.SELECT sleep(2);
Response
┌─sleep(2)─┐│ 0 │└──────────┘1 row in set. Elapsed: 2.012 sec.
Introduzido em: v1.1.0Pausa a execução de uma consulta por um número específico de segundos para cada linha no conjunto de resultados.A função sleepEachRow() é usada principalmente para testes e depuração, de forma semelhante à função sleep().
Ela permite simular atrasos ou inserir pausas no processamento de cada linha, o que pode ser útil em cenários como:
Testes: Ao testar ou fazer benchmarking do desempenho do ClickHouse em condições específicas, você pode usar sleepEachRow() para simular atrasos ou inserir pausas em cada linha processada.
Depuração: Se você precisar examinar o estado do sistema ou a execução de uma consulta para cada linha processada, poderá usar sleepEachRow() para inserir pausas, permitindo inspecionar ou coletar informações relevantes.
Simulação: Em alguns casos, você pode querer simular cenários reais em que ocorram atrasos ou pausas para cada linha processada, como ao lidar com sistemas externos ou latência de rede.
Assim como a função sleep(), é importante usar sleepEachRow() com critério e somente quando necessário, pois ela pode afetar significativamente o desempenho geral e a capacidade de resposta do seu sistema ClickHouse, especialmente ao lidar com grandes conjuntos de resultados.
Sintaxe
sleepEachRow(seconds)
Argumentos
seconds — O número de segundos para pausar a execução da consulta para cada linha do conjunto de resultados, com um máximo de 3 segundos. Pode ser um valor de ponto flutuante para especificar frações de segundo. const UInt* ou const Float*
Valor retornadoRetorna 0 para cada linha. UInt8ExemplosExemplo de uso
Query
-- A saída terá um atraso, com uma pausa de 0,5 segundo entre cada linha.SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;
Introduzido em: v23.8.0Converte a estrutura de uma tabela do ClickHouse em um schema no formato Protobuf.Esta função recebe a definição da estrutura de uma tabela do ClickHouse e a converte em uma
definição de schema em Protocol Buffers (Protobuf) na sintaxe proto3. Isso é útil para gerar
schemas Protobuf que correspondam às estruturas das suas tabelas do ClickHouse para intercâmbio de dados.Sintaxe
structure — Definição da estrutura da tabela do ClickHouse como uma string (por exemplo, ‘column1 Type1, column2 Type2’). String
message_name — Nome do tipo de mensagem Protobuf no schema gerado. String
Valor retornadoRetorna uma definição de schema Protobuf na sintaxe proto3 que corresponde à estrutura de entrada do ClickHouse. StringExemplosConversão da estrutura do ClickHouse para schema Protobuf
Query
SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;
Response
syntax = "proto3";message MessageName{ bytes s = 1; uint32 x = 2;}
Introduzido em: v20.12.0Retorna o número da porta TCP da interface nativa em que o servidor escuta.
Se executada no contexto de uma tabela distribuída, esta função gera uma coluna comum com valores relevantes para cada shard.
Caso contrário, gera um valor constante.Sintaxe
tcpPort()
Argumentos
Nenhum.
Valor retornadoRetorna o número da porta TCP. UInt16ExemplosExemplo de uso
Introduzido em: v1.1.0Lança uma exceção se o argumento x for true.
Para usar o argumento error_code, o parâmetro de configuração allow_custom_error_code_in_throw deve estar habilitado.Sintaxe
Introduzido em: v1.1.0Retorna o nome interno do tipo de dados do valor fornecido.
Diferentemente da função toTypeName, o tipo de dados retornado pode incluir colunas internas de encapsulamento, como Const e LowCardinality.Sintaxe
toColumnTypeName(value)
Argumentos
value — Valor cujo tipo de dado interno deve ser retornado. Any
Valor retornadoRetorna o tipo de dado interno usado para representar o valor. StringExemplosExemplo de uso
Query
SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));
Introduzido em: v1.1.0Retorna o nome do tipo do argumento informado.
Se NULL for informado, a função retorna o tipo Nullable(Nothing), que corresponde à representação interna de NULL no ClickHouse.Sintaxe
Introduzido em: v26.5.0Tokeniza uma string de consulta em ClickHouse SQL e retorna um array de tokens.
Cada token é uma tupla nomeada com a posição inicial (em bytes), a posição final e o tipo do token.Sintaxe
tokenizeQuery(query)
Argumentos
query — Uma string de consulta em ClickHouse SQL. String.
Introduzido em: v22.6.0Retorna o ID de uma transação.
Esta função faz parte de um conjunto de funcionalidades experimentais.
Ative o suporte experimental a transações adicionando esta configuração aos seus arquivos de configuração:
Introduzido em: v22.6.0Retorna o snapshot mais recente (Commit Sequence Number) de uma transação disponível para leitura.
Esta função faz parte de um conjunto de recursos experimentais. Ative o suporte experimental a transações adicionando esta configuração às suas configurações:
Introduzido em: v1.1.0Transforma um valor de acordo com um mapeamento explicitamente definido entre determinados elementos e outros elementos.Há duas variações desta função:
transform(x, array_from, array_to, default) - transforma x usando arrays de mapeamento, com um valor padrão para elementos sem correspondência
transform(x, array_from, array_to) - faz a mesma transformação, mas retorna o x original se nenhuma correspondência for encontrada
A função procura x em array_from e retorna o elemento correspondente de array_to no mesmo índice.
Se x não for encontrado em array_from, ela retorna o valor default (versão com 4 parâmetros) ou o x original (versão com 3 parâmetros).
Se houver vários elementos correspondentes em array_from, ela retorna o elemento correspondente à primeira correspondência.Requisitos:
array_from e array_to devem ter o mesmo número de elementos
Para a versão com 4 parâmetros: transform(T, Array(T), Array(U), U) -> U, em que T e U podem ser tipos compatíveis diferentes
Para a versão com 3 parâmetros: transform(T, Array(T), Array(T)) -> T, em que todos os tipos devem ser iguais
default — Opcional. Valor a ser retornado se x não for encontrado em array_from. Se omitido, retorna x sem alterações. (U)Int* or Decimal or Float* or String or Date or DateTime
Valor retornadoRetorna o valor correspondente de array_to se x corresponder a um elemento de array_from; caso contrário, retorna default (se fornecido) ou x (se default não for fornecido). AnyExemplostransform(T, Array(T), Array(U), U) -> U
Query
SELECTtransform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,count() AS cFROM test.hitsWHERE SearchEngineID != 0GROUP BY titleORDER BY c DESC
Response
┌─title─────┬──────c─┐│ Yandex │ 498635 ││ Google │ 229872 ││ Other │ 104472 │└───────────┴────────┘
transform(T, Array(T), Array(T)) -> T
Query
SELECTtransform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS cFROM test.hitsGROUP BY domain(Referer)ORDER BY count() DESCLIMIT 10
Introduzido em: v22.9.0Dois objetos uniqThetaSketch são usados para calcular a interseção (operação de conjunto ∩); o resultado é um novo uniqThetaSketch.Sintaxe
Valor retornadoUm novo uniqThetaSketch contendo o resultado da interseção. UInt64ExemplosExemplo de uso
Query
SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
Introduzido em: v22.9.0Dois objetos uniqThetaSketch para realizar o cálculo a_not_b (operação de conjunto ×); o resultado é um novo uniqThetaSketch.Sintaxe
Valor retornadoRetorna um novo uniqThetaSketch contendo o resultado de a_not_b. UInt64ExemplosExemplo de uso
Query
SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);
Valor retornadoRetorna um novo uniqThetaSketch com o resultado da união. UInt64ExemplosExemplo de uso
Query
SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
Introduzido em: v1.1.0Retorna o uptime do servidor em segundos.
Se for executada no contexto de uma tabela distribuída, essa função gera uma coluna comum com valores correspondentes a cada shard.
Caso contrário, produz um valor constante.Sintaxe
uptime()
Argumentos
Nenhum.
Valor retornadoRetorna o uptime do servidor em segundos. UInt32ExemplosExemplo de uso
Valor retornadoRetorna uma coluna Enum com o nome do tipo da variante para cada linha. EnumExemplosExemplo de uso
Query
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);SELECT variantType(v) FROM test;
Introduzido na versão: v1.1.0Retorna a versão atual do ClickHouse como uma string no formato: major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release.
Se for executada no contexto de uma tabela distribuída, esta função gera uma coluna comum com valores específicos de cada shard.
Caso contrário, produz um valor constante.Sintaxe
version()
Argumentos
Nenhum.
Valor retornadoRetorna a versão atual do ClickHouse. StringExemplosExemplo de uso
Introduzido em: v1.1.0Calcula a largura aproximada ao gerar valores no console em formato de texto (separado por tabulação).
Esta função é usada pelo sistema para implementar os formatos Pretty.
NULL é representado como uma string correspondente a NULL nos formatos Pretty.Sintaxe
