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++.
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
Argumentos
x — Valor cujo valor absoluto será obtido
Valor retornado
O valor absoluto de x
Exemplos
Exemplo de uso
Introduzido em: v25.11.0
Calcula e retorna o valor médio dos argumentos fornecidos.
Suporta tipos numéricos e temporais.
Sintaxe
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) │
└──────────┴───────────┘
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:
- Converta o inteiro decimal para seu equivalente hexadecimal em ordem big-endian, ou seja, 3351772109 -> C7 C7 FB CD (4 bytes)
- Inverta os bytes, ou seja, C7 C7 FB CD -> CD FB C7 C7
- 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
Argumentos
Valor retornado
Retorna x com a ordem dos bytes invertida. (U)Int*
Exemplos
Exemplo de uso
SELECT byteSwap(3351772109)
8 bits
16 bits
32 bits
SELECT byteSwap(3351772109)
64 bits
SELECT byteSwap(123294967295)
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
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)
Divisão por zero
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
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(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 5)─┐
│ -12 │ 2.1 │ -5.7 │ -5.71428 │
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
Introduzido em: v25.5.0
O mesmo que divide, mas retorna NULL ao dividir por zero.
Sintaxe
Argumentos
x — Dividendo - y — Divisor
Valor retornado
O quociente entre x e y, ou NULL.
Exemplos
Divisão por zero
SELECT divideOrNull(25, 0)
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
Argumentos
x — Primeiro inteiro - y — Segundo inteiro
Valor retornado
O máximo divisor comum entre x e y.
Exemplos
Exemplo de uso
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
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)
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
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(intDiv(toFloat64(1), 0.001))─┐
│ 1000 │ Int64 │
└──────┴─────────────────────────────────────────┘
O quociente não cabe na faixa 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)
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
Argumentos
Valor retornado
Resultado da divisão inteira de x por y, ou NULL.
Exemplos
Divisão inteira por zero
SELECT intDivOrNull(1, 0)
Divisão do menor número negativo por -1
SELECT intDivOrNull(-9223372036854775808, -1)
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
Argumentos
Valor retornado
Resultado da divisão inteira de a por b, ou zero.
Exemplos
Divisão inteira por zero
SELECT intDivOrZero(1, 0)
Divisão do menor número negativo por -1
SELECT intDivOrZero(0.05, -1)
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
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
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
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
SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10))
Introduzido em: v1.1.0
Retorna 1 se o argumento do tipo Float32 ou Float64 for NaN; caso contrário, retorna 0.
Sintaxe
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
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
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
Introduzido em: v21.11.0
Retorna o maior de dois valores numéricos, x e y.
Sintaxe
Argumentos
Valor retornado
Retorna o maior valor entre x e y. Float64
Exemplos
Exemplo de uso
Introduzido em: v25.11.0
Calcula e retorna a média dos argumentos fornecidos.
Oferece suporte a tipos numéricos e temporais.
Sintaxe
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) │
└──────────┴───────────┘
Introduzido em: v21.11.0
Retorna o menor entre dois valores numéricos, x e y.
Sintaxe
Argumentos
Valor retornado
Retorna o menor valor entre x e y. Float64
Exemplos
Exemplo de uso
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
Argumentos
x — Minuendo. - y — Subtraendo.
Valor retornado
x menos y
Exemplos
Subtraindo dois números
Subtração entre um inteiro e uma data
SELECT minus(toDate('2025-01-01'),5)
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
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
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
Argumentos
Valor retornado
Retorna o resto da divisão. (U)Int* ou Float*
Exemplos
Uso básico
SELECT moduloLegacy(10, 3)
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
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
SELECT moduloOrNull(5, 0)
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
Argumentos
Valor retornado
Retorna o resto de a % b, ou 0 quando o divisor é 0.
Exemplos
Exemplo de uso
SELECT moduloOrZero(5, 0)
Introduzido em: v1.1.0
Calcula o produto de dois valores, x e y.
Sintaxe
Argumentos
Valor retornado
Retorna o produto de x e y
Exemplos
Multiplicação de dois números
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
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)
Diferença em relação à multiplicação normal
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
┌─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
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;
┌─────────────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)
Introduzido em: v1.1.0
Nega o argumento x. O resultado é sempre um número com sinal.
Sintaxe
Argumentos
x — O valor a ser negado.
Valor retornado
Retorna -x a partir de x
Exemplos
Exemplo de uso
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
Argumentos
x — Operando esquerdo. - y — Operando direito.
Valor retornado
Retorna a soma de x e y
Exemplos
Somando dois números
Somando um inteiro e uma data
SELECT plus(toDate('2025-01-01'),5)
Adicionando data e hora
SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')
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
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)
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
SELECT positiveModuloOrNull(5, 0)