Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções Aritméticas

View as MarkdownEdit this pageReport an issueSet up docs MCP

Visão geral

As funções aritméticas funcionam com quaisquer dois operandos do tipo UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, Float32 ou Float64.

Antes de executar a operação, ambos os operandos são convertidos para o tipo de resultado. O tipo de resultado é determinado da seguinte forma (a menos que especificado de outra forma na documentação da função abaixo):

  • Se ambos os operandos tiverem até 32 bits, o tamanho do tipo de resultado será o do próximo tipo maior em relação ao maior dos dois operandos (promoção de tamanho de inteiro). Por exemplo, UInt8 + UInt16 = UInt32 ou Float32 * Float32 = Float64.
  • Se um dos operandos tiver 64 bits ou mais, o tamanho do tipo de resultado será o mesmo do maior dos dois operandos. Por exemplo, UInt32 + UInt128 = UInt128 ou Float32 * Float64 = Float64.
  • Se um dos operandos for com sinal, o tipo de resultado também será com sinal; caso contrário, será sem sinal. Por exemplo, UInt32 * Int32 = Int64 ou UInt32 * UInt32 = UInt64.

Essas regras garantem que o tipo de resultado será o menor tipo capaz de representar todos os resultados possíveis. Embora isso introduza um risco de overflow próximo ao limite do intervalo de valores, também garante que os cálculos sejam executados rapidamente usando a maior largura nativa de inteiro, de 64 bits. Esse comportamento também garante compatibilidade com muitos outros bancos de dados que oferecem inteiros de 64 bits (BIGINT) como o maior tipo inteiro.

Exemplo:

SELECT toTypeName(0), toTypeName(0 + 0), toTypeName(0 + 0 + 0), toTypeName(0 + 0 + 0 + 0)
┌─toTypeName(0)─┬─toTypeName(plus(0, 0))─┬─toTypeName(plus(plus(0, 0), 0))─┬─toTypeName(plus(plus(plus(0, 0), 0), 0))─┐
│ UInt8         │ UInt16                 │ UInt32                          │ UInt64                                   │
└───────────────┴────────────────────────┴─────────────────────────────────┴──────────────────────────────────────────┘

Os estouros ocorrem da mesma forma que em C++.

abs

Introduzido em: v1.1.0

Calcula o valor absoluto de x. Não tem efeito se x for de um tipo sem sinal. Se x for de um tipo com sinal, retorna um número sem sinal.

Sintaxe

abs(x)

Argumentos

  • x — Valor cujo valor absoluto será obtido

Valor retornado

O valor absoluto de x

Exemplos

Exemplo de uso

SELECT abs(-0.5)
0.5

avg2

Introduzido em: v25.11.0

Calcula e retorna o valor médio dos argumentos fornecidos. Suporta tipos numéricos e temporais.

Sintaxe

avg2(x1, x2])

Argumentos

  • x1, x2] — Aceita dois valores para calcular a média.

Valor retornado

Retorna a média dos argumentos fornecidos, convertida para o maior tipo compatível.

Exemplos

Tipos numéricos

SELECT avg2(toUInt8(3), 1.0) AS result, toTypeName(result) AS type;
-- O tipo retornado é Float64 pois o UInt8 deve ser promovido para 64 bits para a comparação.
┌─result─┬─type────┐
│      2 │ Float64 │
└────────┴─────────┘

Tipos decimais

SELECT avg2(toDecimal32(1, 2), 2) AS result, toTypeName(result) AS type;
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘

Tipos Date

SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘

Tipos de DateTime

SELECT avg2(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘

Tipos de Time64

SELECT avg2(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘

byteSwap

Introduzido em: v23.10.0

Inverte os bytes de um inteiro, ou seja, altera sua ordem de bytes.

O exemplo abaixo pode ser entendido da seguinte forma:

  1. Converta o inteiro decimal para seu equivalente hexadecimal em ordem big-endian, ou seja, 3351772109 -> C7 C7 FB CD (4 bytes)
  2. Inverta os bytes, ou seja, C7 C7 FB CD -> CD FB C7 C7
  3. Converta o resultado de volta para um inteiro, assumindo big-endian, ou seja, CD FB C7 C7 -> 3455829959 Um caso de uso dessa função é inverter endereços IPv4:
┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
│ 199.199.251.205                                       │
└───────────────────────────────────────────────────────┘

Sintaxe

byteSwap(x)

Argumentos

Valor retornado

Retorna x com a ordem dos bytes invertida. (U)Int*

Exemplos

Exemplo de uso

SELECT byteSwap(3351772109)
3455829959

8 bits

SELECT byteSwap(54)
54

16 bits

SELECT byteSwap(4135)
10000

32 bits

SELECT byteSwap(3351772109)
3455829959

64 bits

SELECT byteSwap(123294967295)
18439412204227788800

divide

Introduzido em: v1.1.0

Calcula o quociente entre dois valores, a e b. O tipo do resultado é sempre Float64. A divisão inteira é fornecida pela função intDiv.

Sintaxe

divide(x, y)

Argumentos

  • x — Dividendo - y — Divisor

Valor retornado

O quociente de x e y

Exemplos

Divisão de dois números

SELECT divide(25,5) AS quotient, toTypeName(quotient)
5	Float64

Divisão por zero

SELECT divide(25,0)
inf

divideDecimal

Introduzido em: v22.12.0

Realiza a divisão entre dois valores decimais. O valor resultante será do tipo Decimal256. A escala do resultado pode ser especificada explicitamente pelo argumento result_scale (um Integer constante no intervalo [0, 76]). Se não for especificada, a escala do resultado será a maior escala entre os argumentos fornecidos.

Sintaxe

divideDecimal(x, y[, result_scale])

Argumentos

  • x — Primeiro valor: Decimal. - y — Segundo valor: Decimal. - result_scale — Escala do resultado. Tipo Int/UInt.

Valor retornado

O resultado da divisão com a escala especificada. Decimal256

Exemplos

Exemplo 1

SELECT divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)
┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
│                                                -5.7142857142 │
└──────────────────────────────────────────────────────────────┘

Exemplo 2

SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
│                                             -5.7 │
└──────────────────────────────────────────────────┘
┌───a─┬───b─┬─divideDecimal(a, b, 1)─┬─divideDecimal(a, b, 5)─┐
│ -12 │ 2.1 │                   -5.7 │               -5.71428 │
└─────┴─────┴────────────────────────┴────────────────────────┘

divideOrNull

Introduzido em: v25.5.0

O mesmo que divide, mas retorna NULL ao dividir por zero.

Sintaxe

divideOrNull(x, y)

Argumentos

  • x — Dividendo - y — Divisor

Valor retornado

O quociente entre x e y, ou NULL.

Exemplos

Divisão por zero

SELECT divideOrNull(25, 0)
\N

gcd

Introduzido em: v1.1.0

Retorna o máximo divisor comum de dois valores a e b.

Uma exceção é lançada ao dividir por zero ou ao dividir o menor número negativo por menos um.

Sintaxe

gcd(x, y)

Argumentos

  • x — Primeiro inteiro - y — Segundo inteiro

Valor retornado

O máximo divisor comum entre x e y.

Exemplos

Exemplo de uso

SELECT gcd(12, 18)
6

ifNotFinite

Introduzido em: v20.3.0

Verifica se um valor de ponto flutuante é finito.

Você pode obter um resultado semelhante usando o operador ternário: isFinite(x) ? x : y.

Sintaxe

ifNotFinite(x,y)

Argumentos

  • x — Valor a ser verificado para saber se é infinito. Float*
  • y — Valor de fallback. Float*

Valor retornado

  • x se x for finito.
  • y se x não for finito.

Exemplos

Exemplo de uso

SELECT 1/0 AS infimum, ifNotFinite(infimum,42)
inf	42

intDiv

Introduzido em: v1.1.0

Executa a divisão inteira de dois valores, x por y. Em outras palavras, calcula o quociente arredondado para baixo até o menor inteiro seguinte.

O resultado tem a mesma largura que o dividendo (o primeiro parâmetro).

Uma exceção é lançada ao dividir por zero, quando o quociente não cabe no intervalo do dividendo ou ao dividir o menor número negativo por menos um.

Sintaxe

intDiv(x, y)

Argumentos

  • x — Operando esquerdo. - y — Operando direito.

Valor retornado

Resultado da divisão inteira de x por y

Exemplos

Divisão inteira de dois floats

SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)
┌──res─┬─toTypeName(res)─┐
│ 1000 │ Int64           │
└──────┴─────────────────┘

O quociente não cabe no intervalo do dividendo

SELECT
intDiv(1, 0.001) AS res,
toTypeName(res)
Received exception from server (version 23.2.1):
Code: 153. DB::Exception: Received from localhost:9000. DB::Exception:
Cannot perform integer division, because it will produce infinite or too
large number: While processing intDiv(1, 0.001) AS res, toTypeName(res).
(ILLEGAL_DIVISION)

intDivOrNull

Introduzido em: v25.5.0

Igual a intDiv, mas retorna NULL ao dividir por zero ou ao dividir o menor número negativo por menos um.

Sintaxe

intDivOrNull(x, y)

Argumentos

Valor retornado

Resultado da divisão inteira de x por y, ou NULL.

Exemplos

Divisão inteira por zero

SELECT intDivOrNull(1, 0)
\N

Divisão do menor número negativo por -1

SELECT intDivOrNull(-9223372036854775808, -1)
\N

intDivOrZero

Introduzido em: v1.1.0

Igual a intDiv, mas retorna zero ao dividir por zero ou ao dividir o menor número negativo por menos um.

Sintaxe

intDivOrZero(a, b)

Argumentos

Valor retornado

Resultado da divisão inteira de a por b, ou zero.

Exemplos

Divisão inteira por zero

SELECT intDivOrZero(1, 0)
0

Divisão do menor número negativo por -1

SELECT intDivOrZero(0.05, -1)
0

isFinite

Introduzido em: v1.1.0

Retorna 1 se o argumento Float32 ou Float64, ou BFloat16, não for infinito nem NaN; caso contrário, retorna 0.

Sintaxe

isFinite(x)

Argumentos

  • x — Número a ser verificado quanto à finitude. Float* ou BFloat16

Valor retornado

1 se x não for infinito nem NaN; caso contrário, 0.

Exemplos

Verifique se um número é finito

SELECT isFinite(inf)
0

isInfinite

Introduzido em: v1.1.0

Retorna 1 se o argumento Float32, Float64 ou BFloat16 for infinito; caso contrário, retorna 0. Observe que 0 é retornado para NaN.

Sintaxe

isInfinite(x)

Argumentos

  • x — Número a ser verificado quanto à infinitude. Float* ou BFloat16

Valor retornado

1 se x for infinito; caso contrário, 0 (inclusive para NaN).

Exemplos

Verifique se um número é infinito

SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10)
1	0	0

isNaN

Introduzido em: v1.1.0

Retorna 1 se o argumento do tipo Float32, Float64 ou BFloat16 for NaN; caso contrário, retorna 0.

Sintaxe

isNaN(x)

Argumentos

  • x — Argumento a ser avaliado para verificar se é NaN. Float* ou BFloat16

Valor retornado

1 se for NaN; caso contrário, 0

Exemplos

Exemplo de uso

SELECT isNaN(NaN)
1

lcm

Introduzido em: v1.1.0

Retorna o mínimo múltiplo comum de dois valores x e y.

Uma exceção é gerada ao dividir por zero ou ao dividir o menor número negativo por menos um.

Sintaxe

lcm(x, y)

Argumentos

  • x — Primeiro número inteiro. (U)Int*
  • y — Segundo número inteiro. (U)Int*

Valor retornado

Retorna o mínimo múltiplo comum de x e y. (U)Int*

Exemplos

Exemplo de uso

SELECT lcm(6, 8)
24

max2

Introduzido em: v21.11.0

Retorna o maior de dois valores numéricos, x e y.

Sintaxe

max2(x, y)

Argumentos

Valor retornado

Retorna o maior valor entre x e y. Float64

Exemplos

Exemplo de uso

SELECT max2(-1, 2)
2

midpoint

Introduzido em: v25.11.0

Calcula e retorna a média dos argumentos fornecidos. Oferece suporte a tipos numéricos e temporais.

Sintaxe

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

Argumentos

  • x1[, x2, ...] — Aceita um único valor ou vários valores para calcular a média.

Valor retornado

Retorna a média dos argumentos fornecidos, promovida para o maior tipo compatível.

Exemplos

Tipos numéricos

SELECT midpoint(1, toUInt8(3), 0.5) AS result, toTypeName(result) AS type;
-- O tipo retornado é Float64 pois o UInt8 deve ser promovido para 64 bits para a comparação.
┌─result─┬─type────┐
│    1.5 │ Float64 │
└────────┴─────────┘

Tipos decimais

SELECT midpoint(toDecimal32(1.5, 2), toDecimal32(1, 1), 2) AS result, toTypeName(result) AS type;
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘

Tipo Date

SELECT midpoint(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘

Tipos de DateTime

SELECT midpoint(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘

Tipos Time64

SELECT midpoint(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘

min2

Introduzido em: v21.11.0

Retorna o menor entre dois valores numéricos, x e y.

Sintaxe

min2(x, y)

Argumentos

Valor retornado

Retorna o menor valor entre x e y. Float64

Exemplos

Exemplo de uso

SELECT min2(-1, 2)
-1

minus

Introduzido em: v1.1.0

Calcula a diferença entre dois valores a e b. O resultado é sempre com sinal. Assim como em plus, é possível subtrair um inteiro de uma data ou data com hora. Além disso, há suporte à subtração entre data com hora, resultando na diferença de tempo entre elas.

Sintaxe

minus(x, y)

Argumentos

  • x — Minuendo. - y — Subtraendo.

Valor retornado

x menos y

Exemplos

Subtraindo dois números

SELECT minus(10, 5)
5

Subtração entre um inteiro e uma data

SELECT minus(toDate('2025-01-01'),5)
2024-12-27

modulo

Introduzido em: v1.1.0

Calcula o resto da divisão de a por b.

O tipo do resultado é inteiro se ambas as entradas forem inteiras. Se uma das entradas for um número de ponto flutuante, o tipo do resultado será Float64.

O resto é calculado como em C++. A divisão truncada é usada para números negativos.

É lançada uma exceção ao dividir por zero ou ao dividir o menor número negativo por menos um.

Sintaxe

modulo(a, b)

Aliases: mod

Argumentos

  • a — O dividendo - b — O divisor (módulo)

Valor retornado

O resto da divisão de a por b

Exemplos

Exemplo de uso

SELECT modulo(5, 2)
1

moduloLegacy

Introduzido na versão: v1.1.0

Calcula o resto de uma divisão. Esta é a implementação legada do módulo que usa o operador % do C++, que pode produzir resultados negativos para argumentos negativos. Esta função existe para manter a compatibilidade com a lógica antiga de particionamento de tabelas. Use modulo ou positiveModulo para o comportamento padrão.

Sintaxe

moduloLegacy(a, b)

Argumentos

Valor retornado

Retorna o resto da divisão. (U)Int* ou Float*

Exemplos

Uso básico

SELECT moduloLegacy(10, 3)
1

moduloOrNull

Introduzido em: v25.5.0

Calcula o resto da divisão de a por b. Semelhante à função modulo, exceto que moduloOrNull retorna NULL quando a operação, de outra forma, geraria uma exceção de ponto flutuante. Para argumentos de ponto flutuante, isso acontece apenas quando o divisor é 0; para argumentos inteiros, isso também inclui o menor valor negativo módulo -1 (por exemplo, -128 % -1 para Int8).

Sintaxe

moduloOrNull(x, y)

Aliases: modOrNull

Argumentos

Valor retornado

Retorna o resto da divisão de x por y, ou NULL quando a operação geraria uma exceção de ponto flutuante: quando o divisor é zero ou, para argumentos inteiros, ao calcular o menor valor negativo módulo -1.

Exemplos

moduloOrNull com zero

SELECT moduloOrNull(5, 0)
\N

moduloOrNull do menor inteiro negativo por -1

SELECT moduloOrNull(toInt8(-128), toInt8(-1))
\N

moduloOrZero

Introduzido em: v20.3.0

Semelhante a modulo, mas retorna zero quando o divisor é zero, em vez de lançar uma exceção, como ocorre com a função modulo.

Sintaxe

moduloOrZero(a, b)

Argumentos

Valor retornado

Retorna o resto de a % b, ou 0 quando o divisor é 0.

Exemplos

Exemplo de uso

SELECT moduloOrZero(5, 0)
0

multiply

Introduzido em: v1.1.0

Calcula o produto de dois valores, x e y.

Sintaxe

multiply(x, y)

Argumentos

Valor retornado

Retorna o produto de x e y

Exemplos

Multiplicação de dois números

SELECT multiply(5,5)
25

multiplyDecimal

Introduzido em: v22.12.0

Realiza a multiplicação de dois números decimais. O valor resultante será do tipo Decimal256. A escala do resultado pode ser especificada explicitamente pelo argumento result_scale (Integer constante no intervalo [0, 76]). Se não for especificada, a escala do resultado será a maior escala entre os argumentos fornecidos.

Sintaxe

multiplyDecimal(a, b[, result_scale])

Argumentos

  • a — Primeiro valor. Decimal
  • b — Segundo valor. Decimal
  • result_scale — Escala do resultado. (U)Int*

Valor retornado

O resultado da multiplicação com a escala fornecida. Tipo: Decimal256

Exemplos

Exemplo de uso

SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
25.2

Diferença em relação à multiplicação normal

SELECT multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));
SELECT multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));
┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                               -26.8609633 │
└───────────────────────────────────────────────────────────┘
┌─multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                                         -26.8609 │
└──────────────────────────────────────────────────────────────────┘

Sem estouro com multiplyDecimal

SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    multiplyDecimal(a, b);
┌─────────────a─┬─────────────b─┬─multiplyDecimal(a, b)─┐
│ -12.647987876 │ 123.967645643 │       -1567.941279108 │
└───────────────┴───────────────┴───────────────────────┘

Estouro em decimal com multiplicação normal

SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    a * b;
Received exception:
Code: 407. DB::Exception: Decimal math overflow. (DECIMAL_OVERFLOW)

negate

Introduzido em: v1.1.0

Nega o argumento x. O resultado é sempre um número com sinal.

Sintaxe

negate(x)

Argumentos

  • x — O valor a ser negado.

Valor retornado

Retorna -x a partir de x

Exemplos

Exemplo de uso

SELECT negate(10)
-10

plus

Introduzido em: v1.1.0

Calcula a soma de dois valores x e y. Alias: x + y (operador). É possível somar um inteiro e uma data ou uma data com hora. A primeira operação incrementa o número de dias da data; a segunda incrementa o número de segundos da data com hora. Também é possível somar uma data e uma hora. Somar um Date e um Time produz um DateTime. Somar um Date e um Time64, ou um Date32 e um Time ou Time64, produz um DateTime64.

Sintaxe

plus(x, y)

Argumentos

  • x — Operando esquerdo. - y — Operando direito.

Valor retornado

Retorna a soma de x e y

Exemplos

Somando dois números

SELECT plus(5,5)
10

Somando um inteiro e uma data

SELECT plus(toDate('2025-01-01'),5)
2025-01-06

Adicionando data e hora

SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')
2025-01-01 14:30:25

positiveModulo

Introduzido em: v22.11.0

Calcula o resto da divisão de x por y. Semelhante à função modulo, exceto que positiveModulo sempre retorna um número não negativo.

Sintaxe

positiveModulo(x, y)

Aliases: positive_modulo, pmod

Argumentos

Valor retornado

Retorna a diferença entre x e o maior inteiro não superior a x que seja divisível por y.

Exemplos

Exemplo de uso

SELECT positiveModulo(-1, 10)
9

positiveModuloOrNull

Introduzido em: v25.5.0

Calcula o resto da divisão de a por b. Semelhante à função positiveModulo, exceto que positiveModuloOrNull retorna NULL quando a operação, de outra forma, geraria uma exceção de ponto flutuante. Para argumentos de ponto flutuante, isso acontece apenas quando o divisor é 0; para argumentos inteiros, isso também cobre o menor valor negativo módulo -1 (por exemplo, -128 % -1 para Int8).

Sintaxe

positiveModuloOrNull(x, y)

Aliases: positive_modulo_or_null, pmodOrNull

Argumentos

Valor retornado

Retorna a diferença entre x e o maior inteiro não superior a x que seja divisível por y, ou NULL quando a operação geraria uma exceção de ponto flutuante: quando o divisor é zero ou, para argumentos inteiros, ao calcular o menor valor negativo módulo -1.

Exemplos

positiveModuloOrNull por zero

SELECT positiveModuloOrNull(5, 0)
\N

positiveModuloOrNull do menor inteiro negativo por -1

SELECT positiveModuloOrNull(toInt8(-128), toInt8(-1))
\N

sqr

Introduzido em: v26.7.0

Calcula o quadrado de um valor x.

Sintaxe

sqr(x)

Argumentos

Valor retornado

Retorna o produto de x por ele mesmo.

Exemplos

Elevando um número ao quadrado

SELECT sqr(5)
25
Navigation