Pular para o conteúdo principal

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
Query
SELECT abs(-0.5)
Response
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
Query
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.
Response
┌─result─┬─type────┐
│      2 │ Float64 │
└────────┴─────────┘
Tipos decimais
Query
SELECT avg2(toDecimal32(1, 2), 2) AS result, toTypeName(result) AS type;
Response
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
Tipos Date
Query
SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
Response
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
Tipos de DateTime
Query
SELECT avg2(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
Response
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
Tipos de Time64
Query
SELECT avg2(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
Response
┌───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
Query
SELECT byteSwap(3351772109)
Response
3455829959
8 bits
Query
SELECT byteSwap(54)
Response
54
16 bits
Query
SELECT byteSwap(4135)
Response
10000
32 bits
Query
SELECT byteSwap(3351772109)
Response
3455829959
64 bits
Query
SELECT byteSwap(123294967295)
Response
18439412204227788800

divide

Introduzido na versão: 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.
A divisão por 0 retorna inf, -inf ou nan.
Sintaxe
divide(x, y)
Argumentos
  • x — Dividendo - y — Divisor
Valor retornado O quociente de x e y Exemplos Divisão de dois números
Query
SELECT divide(25,5) AS quotient, toTypeName(quotient)
Response
5 Float64
Divisão por zero
Query
SELECT divide(25,0)
Response
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.
Esta função é significativamente mais lenta do que a divide comum. Se você não precisar realmente de precisão controlada e/ou precisar de cálculo rápido, considere usar divide.
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
Query
divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)
Response
┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
│                                                -5.7142857142 │
└──────────────────────────────────────────────────────────────┘
Exemplo 2
Query
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);
Response
┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
│                                             -5.7 │
└──────────────────────────────────────────────────┘
┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 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
Query
SELECT divideOrNull(25, 0)
Response
\N

gcd

Introduzido em: v1.1.0 Retorna o máximo divisor comum de dois valores a e b. Uma exceção é gerada 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
Query
SELECT gcd(12, 18)
Response
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
Query
SELECT 1/0 AS infimum, ifNotFinite(infimum,42)
Response
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
Query
SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)
Response
┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
│ 1000 │ Int64                                   │
└──────┴─────────────────────────────────────────┘
O quociente não cabe na faixa do dividendo
Query
SELECT
intDiv(1, 0.001) AS res,
toTypeName(res)
Response
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
Query
SELECT intDivOrNull(1, 0)
Response
\N
Divisão do menor número negativo por -1
Query
SELECT intDivOrNull(-9223372036854775808, -1)
Response
\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
Query
SELECT intDivOrZero(1, 0)
Response
0
Divisão do menor número negativo por -1
Query
SELECT intDivOrZero(0.05, -1)
Response
0

isFinite

Introduzido em: v1.1.0 Retorna 1 se o argumento Float32 ou Float64 não for infinito nem NaN; caso contrário, retorna 0. Sintaxe
isFinite(x)
Argumentos
  • x — Número a ser verificado quanto à finitude. Float*
Valor retornado 1 se x não for infinito nem NaN; caso contrário, 0. Exemplos Verifique se um número é finito
Query
SELECT isFinite(inf)
Response
0

isInfinite

Introduzido em: v1.1.0 Retorna 1 se o argumento Float32 ou Float64 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*
Valor retornado 1 se x for infinito; caso contrário, 0 (inclusive para NaN). Exemplos Verifique se um número é infinito
Query
SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10))
Response
1 0 0

isNaN

Introduzido em: v1.1.0 Retorna 1 se o argumento do tipo Float32 ou Float64 for NaN; caso contrário, retorna 0. Sintaxe
isNaN(x)
Argumentos
  • x — Argumento a ser avaliado para verificar se é NaN. Float*
Valor retornado 1 se for NaN; caso contrário, 0 Exemplos Exemplo de uso
Query
SELECT isNaN(NaN)
Response
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
Query
SELECT lcm(6, 8)
Response
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
Query
SELECT max2(-1, 2)
Response
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
Query
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.
Response
┌─result─┬─type────┐
│    1.5 │ Float64 │
└────────┴─────────┘
Tipos decimais
Query
SELECT midpoint(toDecimal32(1.5, 2), toDecimal32(1, 1), 2) AS result, toTypeName(result) AS type;
Response
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
Tipo Date
Query
SELECT midpoint(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
Response
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
Tipos de DateTime
Query
SELECT midpoint(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
Response
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
Tipos Time64
Query
SELECT midpoint(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
Response
┌───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
Query
SELECT min2(-1, 2)
Response
-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
Query
SELECT minus(10, 5)
Response
5
Subtração entre um inteiro e uma data
Query
SELECT minus(toDate('2025-01-01'),5)
Response
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
Query
SELECT modulo(5, 2)
Response
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
Query
SELECT moduloLegacy(10, 3)
Response
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 se o argumento da direita for 0. Sintaxe
moduloOrNull(x, y)
Aliases: modOrNull Argumentos Valor retornado Retorna o resto da divisão de x por y, ou NULL quando o divisor é zero. Exemplos moduloOrNull com zero
Query
SELECT moduloOrNull(5, 0)
Response
\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
Query
SELECT moduloOrZero(5, 0)
Response
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
Query
SELECT multiply(5,5)
Response
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.
Essas funções são significativamente mais lentas do que a multiply comum. Se você não precisa de precisão controlada e/ou precisa de um cálculo rápido, considere usar multiply
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
Query
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
Response
25.2
Diferença em relação à multiplicação normal
Query
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
Response
┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                               -26.8609633 │
└───────────────────────────────────────────────────────────┘
┌─multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                                         -26.8609 │
└──────────────────────────────────────────────────────────────────┘
Estouro em decimal
Query
SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    multiplyDecimal(a, b);
SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    a * b;
Response
┌─────────────a─┬─────────────b─┬─multiplyDecimal(toDecimal64(-12.647987876, 9), toDecimal64(123.967645643, 9))─┐
│ -12.647987876 │ 123.967645643 │                                                               -1567.941279108 │
└───────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────┘
Received exception from server (version 22.11.1):
Code: 407. DB::Exception: Received from localhost:9000. DB::Exception: Decimal math overflow:
While processing toDecimal64(-12.647987876, 9) AS a, toDecimal64(123.967645643, 9) AS b, a * b. (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
Query
SELECT negate(10)
Response
-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
Query
SELECT plus(5,5)
Response
10
Somando um inteiro e uma data
Query
SELECT plus(toDate('2025-01-01'),5)
Response
2025-01-06
Adicionando data e hora
Query
SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')
Response
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
Query
SELECT positiveModulo(-1, 10)
Response
9

positiveModuloOrNull

Introduzido em: v25.5.0 Calcula o resto da divisão de a por b. Semelhante à função positiveModulo, exceto que positiveModuloOrNull retornará NULL se o argumento da direita for 0. Sintaxe
positiveModuloOrNull(x, y)
Aliases: positive_modulo_or_null, pmodOrNull Argumentos Valor retornado Retorna a diferença entre x e o inteiro mais próximo divisível por y que não seja maior que x; null quando o divisor é zero. Exemplos positiveModuloOrNull
Query
SELECT positiveModuloOrNull(5, 0)
Response
\N
Última modificação em 10 de junho de 2026