> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentação de Funções Aritméticas
# Funções Aritméticas
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:
```sql theme={null}
SELECT toTypeName(0), toTypeName(0 + 0), toTypeName(0 + 0 + 0), toTypeName(0 + 0 + 0 + 0)
```
```text theme={null}
┌─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**
```sql theme={null}
abs(x)
```
**Argumentos**
* `x` — Valor cujo valor absoluto será obtido
**Valor retornado**
O valor absoluto de `x`
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT abs(-0.5)
```
```response title=Response theme={null}
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**
```sql theme={null}
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**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─result─┬─type────┐
│ 2 │ Float64 │
└────────┴─────────┘
```
**Tipos decimais**
```sql title=Query theme={null}
SELECT avg2(toDecimal32(1, 2), 2) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌─result─┬─type──────────┐
│ 1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
```
**Tipos Date**
```sql title=Query theme={null}
SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
```
**Tipos de DateTime**
```sql title=Query theme={null}
SELECT avg2(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
```
**Tipos de Time64**
```sql title=Query theme={null}
SELECT avg2(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌───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](https://en.wikipedia.org/wiki/Endianness).
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:
```result theme={null}
┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
│ 199.199.251.205 │
└───────────────────────────────────────────────────────┘
```
**Sintaxe**
```sql theme={null}
byteSwap(x)
```
**Argumentos**
* `x` — Um valor inteiro. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna `x` com a ordem dos bytes invertida. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT byteSwap(3351772109)
```
```response title=Response theme={null}
3455829959
```
**8 bits**
```sql title=Query theme={null}
SELECT byteSwap(54)
```
```response title=Response theme={null}
54
```
**16 bits**
```sql title=Query theme={null}
SELECT byteSwap(4135)
```
```response title=Response theme={null}
10000
```
**32 bits**
```sql title=Query theme={null}
SELECT byteSwap(3351772109)
```
```response title=Response theme={null}
3455829959
```
**64 bits**
```sql title=Query theme={null}
SELECT byteSwap(123294967295)
```
```response title=Response theme={null}
18439412204227788800
```
## divide
Introduzido em: v1.1.0
Calcula o quociente entre dois valores, `a` e `b`. O tipo do resultado é sempre [Float64](/pt-BR/reference/data-types/float).
A divisão inteira é fornecida pela função `intDiv`.
A divisão por `0` retorna `inf`, `-inf` ou `nan`.
**Sintaxe**
```sql theme={null}
divide(x, y)
```
**Argumentos**
* `x` — Dividendo - `y` — Divisor
**Valor retornado**
O quociente de x e y
**Exemplos**
**Divisão de dois números**
```sql title=Query theme={null}
SELECT divide(25,5) AS quotient, toTypeName(quotient)
```
```response title=Response theme={null}
5 Float64
```
**Divisão por zero**
```sql title=Query theme={null}
SELECT divide(25,0)
```
```response title=Response theme={null}
inf
```
## divideDecimal
Introduzido em: v22.12.0
Realiza a divisão entre dois valores decimais. O valor resultante será do tipo [Decimal256](/pt-BR/reference/data-types/decimal).
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](#divide).
**Sintaxe**
```sql theme={null}
divideDecimal(x, y[, result_scale])
```
**Argumentos**
* `x` — Primeiro valor: [Decimal](/pt-BR/reference/data-types/decimal). - `y` — Segundo valor: [Decimal](/pt-BR/reference/data-types/decimal). - `result_scale` — Escala do resultado. Tipo [Int/UInt](/pt-BR/reference/data-types/int-uint).
**Valor retornado**
O resultado da divisão com a escala especificada. [`Decimal256`](/pt-BR/reference/data-types/decimal)
**Exemplos**
**Exemplo 1**
```sql title=Query theme={null}
SELECT divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)
```
```response title=Response theme={null}
┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
│ -5.7142857142 │
└──────────────────────────────────────────────────────────────┘
```
**Exemplo 2**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql theme={null}
divideOrNull(x, y)
```
**Argumentos**
* `x` — Dividendo - `y` — Divisor
**Valor retornado**
O quociente entre x e y, ou NULL.
**Exemplos**
**Divisão por zero**
```sql title=Query theme={null}
SELECT divideOrNull(25, 0)
```
```response title=Response theme={null}
\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**
```sql theme={null}
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**
```sql title=Query theme={null}
SELECT gcd(12, 18)
```
```response title=Response theme={null}
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](/pt-BR/reference/functions/regular-functions/conditional-functions#if): `isFinite(x) ? x : y`.
**Sintaxe**
```sql theme={null}
ifNotFinite(x,y)
```
**Argumentos**
* `x` — Valor a ser verificado para saber se é infinito. [`Float*`](/pt-BR/reference/data-types/float)
* `y` — Valor de fallback. [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
* `x` se `x` for finito.
* `y` se `x` não for finito.
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT 1/0 AS infimum, ifNotFinite(infimum,42)
```
```response title=Response theme={null}
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**
```sql theme={null}
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**
```sql title=Query theme={null}
SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)
```
```response title=Response theme={null}
┌──res─┬─toTypeName(res)─┐
│ 1000 │ Int64 │
└──────┴─────────────────┘
```
**O quociente não cabe no intervalo do dividendo**
```sql title=Query theme={null}
SELECT
intDiv(1, 0.001) AS res,
toTypeName(res)
```
```response title=Response theme={null}
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**
```sql theme={null}
intDivOrNull(x, y)
```
**Argumentos**
* `x` — Operando esquerdo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `y` — Operando direito. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Resultado da divisão inteira de `x` por `y`, ou NULL.
**Exemplos**
**Divisão inteira por zero**
```sql title=Query theme={null}
SELECT intDivOrNull(1, 0)
```
```response title=Response theme={null}
\N
```
**Divisão do menor número negativo por -1**
```sql title=Query theme={null}
SELECT intDivOrNull(-9223372036854775808, -1)
```
```response title=Response theme={null}
\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**
```sql theme={null}
intDivOrZero(a, b)
```
**Argumentos**
* `a` — Operando esquerdo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `b` — Operando direito. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Resultado da divisão inteira de a por b, ou zero.
**Exemplos**
**Divisão inteira por zero**
```sql title=Query theme={null}
SELECT intDivOrZero(1, 0)
```
```response title=Response theme={null}
0
```
**Divisão do menor número negativo por -1**
```sql title=Query theme={null}
SELECT intDivOrZero(0.05, -1)
```
```response title=Response theme={null}
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**
```sql theme={null}
isFinite(x)
```
**Argumentos**
* `x` — Número a ser verificado quanto à finitude. [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float)
**Valor retornado**
`1` se x não for infinito nem `NaN`; caso contrário, `0`.
**Exemplos**
**Verifique se um número é finito**
```sql title=Query theme={null}
SELECT isFinite(inf)
```
```response title=Response theme={null}
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**
```sql theme={null}
isInfinite(x)
```
**Argumentos**
* `x` — Número a ser verificado quanto à infinitude. [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float)
**Valor retornado**
`1` se x for infinito; caso contrário, `0` (inclusive para `NaN`).
**Exemplos**
**Verifique se um número é infinito**
```sql title=Query theme={null}
SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10)
```
```response title=Response theme={null}
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**
```sql theme={null}
isNaN(x)
```
**Argumentos**
* `x` — Argumento a ser avaliado para verificar se é `NaN`. [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float)
**Valor retornado**
`1` se for `NaN`; caso contrário, `0`
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT isNaN(NaN)
```
```response title=Response theme={null}
1
```
## kqlBin
Introduzido em: v26.8.0
Arredonda um valor para baixo até o múltiplo de `roundTo`, como faz `bin()` da Kusto Query Language.
A regra depende dos tipos de argumento: um número é arredondado aritmeticamente; um intervalo de tempo (um `Interval`) é arredondado por um intervalo de tempo; e um DateTime é arredondado por um intervalo de tempo. Um DateTime do KQL é um `DateTime64`; os tipos mais restritos `DateTime` e `Date` são rejeitados porque não conseguem representar todos os bins que um DateTime do KQL pode produzir.
Esta função dá suporte a `bin()` quando `dialect = 'kusto'`. Ela não deve ser chamada diretamente do SQL.
**Sintaxe**
```sql theme={null}
kqlBin(value, roundTo)
```
**Argumentos**
* `value` — Um número, um intervalo de tempo ou uma DateTime (um `DateTime64`). - `roundTo` — O tamanho do bin.
**Valor retornado**
`value` arredondado para baixo até o múltiplo mais próximo de `roundTo`.
**Exemplos**
**número**
```sql title=Query theme={null}
SELECT kqlBin(4.5, 1)
```
```response title=Response theme={null}
4
```
**intervalo de tempo**
```sql title=Query theme={null}
SELECT kqlBin(toIntervalNanosecond(16 * 86400000000000), toIntervalNanosecond(7 * 86400000000000))
```
```response title=Response theme={null}
1209600000000000
```
**DateTime**
```sql title=Query theme={null}
SELECT kqlBin(toDateTime64('2026-08-01 12:34:56', 7, 'UTC'), toIntervalHour(1))
```
```response title=Response theme={null}
2026-08-01 12:00:00.0000000
```
## kqlBinAt
Introduzido em: v26.8.0
Arredonda um valor para baixo até um múltiplo de `binSize`, contado a partir de `fixedPoint`, como faz `bin_at()` da Kusto Query
Language. Os bins podem se alinhar antes ou depois do ponto fixo.
A regra depende dos tipos de argumento: um número é arredondado aritmeticamente; um intervalo de tempo (que
é um `Interval`) é arredondado por um intervalo de tempo a partir de outro intervalo de tempo; e uma DateTime é arredondada por um
intervalo de tempo contado a partir de um ponto fixo de DateTime. Uma DateTime KQL é um `DateTime64`; os tipos mais restritos
`DateTime` e `Date` são rejeitados, pois não conseguem representar todos os bins que uma DateTime KQL
pode produzir.
Esta função dá suporte a `bin_at()` quando `dialect = 'kusto'`. Ela não deve ser chamada diretamente
em SQL.
**Sintaxe**
```sql theme={null}
kqlBinAt(value, binSize, fixedPoint)
```
**Argumentos**
* `value` — Um número, um intervalo de tempo ou uma DateTime (um `DateTime64`). - `binSize` — O tamanho do bin. - `fixedPoint` — O ponto fixo para a contagem dos bins.
**Valor retornado**
`value` arredondado para baixo até o múltiplo de `binSize` mais próximo, a partir de `fixedPoint`.
**Exemplos**
**número**
```sql title=Query theme={null}
SELECT kqlBinAt(6.5, 2.5, -0.5)
```
```response title=Response theme={null}
4.5
```
**DateTime**
```sql title=Query theme={null}
SELECT kqlBinAt(toDateTime64('2026-08-01 12:34:56', 7, 'UTC'), toIntervalHour(1), toDateTime64('2026-08-01 00:30:00', 7, 'UTC'))
```
```response title=Response theme={null}
2026-08-01 12:30:00.0000000
```
## kqlDateTimeBinAt
Introduzido em: v26.8.0
Arredonda um DateTime para baixo até o múltiplo de intervalo de tempo, contado a partir de um ponto fixo de DateTime.
**Sintaxe**
```sql theme={null}
kqlDateTimeBinAt(value, binSize, fixedPoint)
```
**Argumentos**
* `value` — O DateTime a ser arredondado. - `binSize` — O tamanho do intervalo de tempo do bin. - `fixedPoint` — O ponto fixo do DateTime.
**Valor retornado**
O DateTime arredondado.
**Exemplos**
## kqlDivide
Introduzido na versão: v26.8.0
Divisão conforme definida pela Kusto Query Language: dois operandos inteiros resultam em um inteiro,
portanto `7 / 2` é `3`, e dois operandos de intervalo de tempo (que são valores `Interval`) resultam em sua
razão de números reais, portanto `15ms / 10ms` é `1.5`. Qualquer outra combinação de tipos de operandos é dividida
como [`divide`](#divide).
Esta função implementa o operador `/` quando `dialect = 'kusto'`. Ela não deve ser chamada
diretamente em SQL.
**Sintaxe**
```sql theme={null}
kqlDivide(x, y)
```
**Argumentos**
* `x` — O dividendo. - `y` — O divisor.
**Valor retornado**
`intDiv(x, y)` quando ambos os argumentos são inteiros, a razão entre os ticks dos intervalos quando ambos são intervalos e `divide(x, y)` caso contrário.
**Exemplos**
**inteiros**
```sql title=Query theme={null}
SELECT kqlDivide(7, 2)
```
```response title=Response theme={null}
3
```
**reais**
```sql title=Query theme={null}
SELECT kqlDivide(7.0, 2)
```
```response title=Response theme={null}
3.5
```
**intervalos de tempo**
```sql title=Query theme={null}
SELECT kqlDivide(toIntervalNanosecond(15000000), toIntervalNanosecond(10000000))
```
```response title=Response theme={null}
1.5
```
## kqlMultiply
Introduzido na versão: v26.8.0
Multiplicação conforme definida pela Kusto Query Language: um intervalo de tempo (um `Interval`) é multiplicado por um
número em qualquer uma das posições, portanto `2 * 1h` equivale a duas horas. Dois argumentos sem um intervalo são multiplicados como em
[`multiply`](#multiply).
Esta função implementa o operador `*` quando `dialect = 'kusto'`. Ela não deve ser chamada
diretamente em SQL.
**Sintaxe**
```sql theme={null}
kqlMultiply(x, y)
```
**Argumentos**
* `x` — Um número ou um intervalo de tempo. - `y` — Um número ou um intervalo de tempo se `x` for um número.
**Valor retornado**
O produto; um intervalo do mesmo tipo quando um dos argumentos for um intervalo.
**Exemplos**
**intervalo de tempo**
```sql title=Query theme={null}
SELECT kqlMultiply(2, toIntervalNanosecond(3600000000000))
```
```response title=Response theme={null}
7200000000000
```
**números**
```sql title=Query theme={null}
SELECT kqlMultiply(6, 7)
```
```response title=Response theme={null}
42
```
## kqlRangeCount
Introduzido em: v26.8.0
O número de linhas produzidas pela fonte `range` da Kusto Query Language: `floor((to - from)
/ step) + 1`, nunca inferior a zero. Os limites e o passo podem ser números, datetimes
incrementados por um intervalo de tempo (um `Interval`) ou intervalos de tempo; as formas temporais são contadas em nanossegundos
inteiros, o que não pode ser expresso por uma única divisão no ClickHouse. Inteiros e decimais são contados
exatamente, sem usar `Float64`.
Esta função dá suporte à fonte `range` quando `dialect = 'kusto'`. Ela não deve ser chamada
diretamente em SQL.
**Sintaxe**
```sql theme={null}
kqlRangeCount(from, to, step)
```
**Argumentos**
* `from` — O primeiro valor do intervalo. - `to` — O valor que o intervalo não excede. - `step` — A diferença entre dois valores consecutivos.
**Valor retornado**
O número de valores no intervalo.
**Exemplos**
**numbers**
```sql title=Query theme={null}
SELECT kqlRangeCount(1, 7, 2)
```
```response title=Response theme={null}
4
```
**datetimes**
```sql title=Query theme={null}
SELECT kqlRangeCount(toDateTime64('2026-08-01 00:00:00', 7, 'UTC'), toDateTime64('2026-08-01 12:00:00', 7, 'UTC'), toIntervalHour(5))
```
```response title=Response theme={null}
3
```
## 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**
```sql theme={null}
lcm(x, y)
```
**Argumentos**
* `x` — Primeiro número inteiro. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `y` — Segundo número inteiro. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna o mínimo múltiplo comum de `x` e `y`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT lcm(6, 8)
```
```response title=Response theme={null}
24
```
## max2
Introduzido em: v21.11.0
Retorna o maior de dois valores numéricos, `x` e `y`.
**Sintaxe**
```sql theme={null}
max2(x, y)
```
**Argumentos**
* `x` — Primeiro valor [`(U)Int8/16/32/64`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `y` — Segundo valor [`(U)Int8/16/32/64`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna o maior valor entre `x` e `y`. [`Float64`](/pt-BR/reference/data-types/float)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT max2(-1, 2)
```
```response title=Response theme={null}
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**
```sql theme={null}
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**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─result─┬─type────┐
│ 1.5 │ Float64 │
└────────┴─────────┘
```
**Tipos decimais**
```sql title=Query theme={null}
SELECT midpoint(toDecimal32(1.5, 2), toDecimal32(1, 1), 2) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌─result─┬─type──────────┐
│ 1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
```
**Tipo Date**
```sql title=Query theme={null}
SELECT midpoint(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
```
**Tipos de DateTime**
```sql title=Query theme={null}
SELECT midpoint(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
```
**Tipos Time64**
```sql title=Query theme={null}
SELECT midpoint(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
```
```response title=Response theme={null}
┌───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**
```sql theme={null}
min2(x, y)
```
**Argumentos**
* `x` — Primeiro valor [`(U)Int8/16/32/64`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `y` — Segundo valor [`(U)Int8/16/32/64`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna o menor valor entre `x` e `y`. [`Float64`](/pt-BR/reference/data-types/float)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT min2(-1, 2)
```
```response title=Response theme={null}
-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.
Também é possível subtrair um `Time` ou `Time64` de um `DateTime` ou `DateTime64`;
o valor de tempo é aplicado como um deslocamento em segundos. `DateTime` menos `Time` produz
um `DateTime`; qualquer combinação que envolva `DateTime64` ou `Time64` produz um `DateTime64`
com a escala máxima dos dois argumentos.
**Sintaxe**
```sql theme={null}
minus(x, y)
```
**Argumentos**
* `x` — Minuendo. - `y` — Subtraendo.
**Valor retornado**
x menos y
**Exemplos**
**Subtraindo dois números**
```sql title=Query theme={null}
SELECT minus(10, 5)
```
```response title=Response theme={null}
5
```
**Subtração entre um inteiro e uma data**
```sql title=Query theme={null}
SELECT minus(toDate('2025-01-01'),5)
```
```response title=Response theme={null}
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**
```sql theme={null}
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**
```sql title=Query theme={null}
SELECT modulo(5, 2)
```
```response title=Response theme={null}
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**
```sql theme={null}
moduloLegacy(a, b)
```
**Argumentos**
* `a` — O dividendo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
* `b` — O divisor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna o resto da divisão. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Exemplos**
**Uso básico**
```sql title=Query theme={null}
SELECT moduloLegacy(10, 3)
```
```response title=Response theme={null}
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**
```sql theme={null}
moduloOrNull(x, y)
```
**Aliases**: `modOrNull`
**Argumentos**
* `x` — O dividendo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
* `y` — O divisor (módulo). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**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**
```sql title=Query theme={null}
SELECT moduloOrNull(5, 0)
```
```response title=Response theme={null}
\N
```
**moduloOrNull do menor inteiro negativo por -1**
```sql title=Query theme={null}
SELECT moduloOrNull(toInt8(-128), toInt8(-1))
```
```response title=Response theme={null}
\N
```
## moduloOrZero
Introduzido em: v20.3.0
Semelhante a `modulo`, mas retorna zero em vez de lançar uma exceção para resultados inteiros quando, de outro modo, a operação geraria uma
exceção. Para resultados de ponto flutuante, um divisor zero produz `NaN`.
**Sintaxe**
```sql theme={null}
moduloOrZero(a, b)
```
**Argumentos**
* `a` — O dividendo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
* `b` — O divisor (módulo). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna o resto de `a % b`. Para resultados inteiros, retorna `0` quando a operação, de outra forma, lançaria uma exceção.
Para resultados de ponto flutuante, um divisor zero produz `NaN`.
**Exemplos**
**Divisor zero inteiro**
```sql title=Query theme={null}
SELECT moduloOrZero(5, 0)
```
```response title=Response theme={null}
0
```
**Divisor zero de ponto flutuante**
```sql title=Query theme={null}
SELECT moduloOrZero(toFloat64(5), toFloat64(0))
```
```response title=Response theme={null}
nan
```
## multiply
Introduzido em: v1.1.0
Calcula o produto de dois valores, `x` e `y`.
**Sintaxe**
```sql theme={null}
multiply(x, y)
```
**Argumentos**
* `x` — fator. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `y` — fator. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna o produto de x e y
**Exemplos**
**Multiplicação de dois números**
```sql title=Query theme={null}
SELECT multiply(5,5)
```
```response title=Response theme={null}
25
```
## multiplyDecimal
Introduzido em: v22.12.0
Realiza a multiplicação de dois números decimais. O valor resultante será do tipo [Decimal256](/pt-BR/reference/data-types/decimal).
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](#multiply)
**Sintaxe**
```sql theme={null}
multiplyDecimal(a, b[, result_scale])
```
**Argumentos**
* `a` — Primeiro valor. [`Decimal`](/pt-BR/reference/data-types/decimal)
* `b` — Segundo valor. [`Decimal`](/pt-BR/reference/data-types/decimal)
* `result_scale` — Escala do resultado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
O resultado da multiplicação com a escala fornecida. Tipo: [`Decimal256`](/pt-BR/reference/data-types/decimal)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
```
```response title=Response theme={null}
25.2
```
**Diferença em relação à multiplicação normal**
```sql title=Query theme={null}
SELECT multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));
SELECT multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT
toDecimal64(-12.647987876, 9) AS a,
toDecimal64(123.967645643, 9) AS b,
multiplyDecimal(a, b);
```
```response title=Response theme={null}
┌─────────────a─┬─────────────b─┬─multiplyDecimal(a, b)─┐
│ -12.647987876 │ 123.967645643 │ -1567.941279108 │
└───────────────┴───────────────┴───────────────────────┘
```
**Estouro em decimal com multiplicação normal**
```sql title=Query theme={null}
SELECT
toDecimal64(-12.647987876, 9) AS a,
toDecimal64(123.967645643, 9) AS b,
a * b;
```
```response title=Response theme={null}
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**
```sql theme={null}
negate(x)
```
**Argumentos**
* `x` — O valor a ser negado.
**Valor retornado**
Retorna -x a partir de x
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT negate(10)
```
```response title=Response theme={null}
-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`.
Somar um `Time` ou `Time64` a um `DateTime` ou `DateTime64` aplica o valor de hora
como um deslocamento em segundos. `DateTime` mais `Time` produz um `DateTime`,
qualquer combinação que envolva `DateTime64` ou `Time64` produz um `DateTime64`
com a escala máxima dos dois argumentos.
**Sintaxe**
```sql theme={null}
plus(x, y)
```
**Argumentos**
* `x` — Operando esquerdo. - `y` — Operando direito.
**Valor retornado**
Retorna a soma de x e y
**Exemplos**
**Somando dois números**
```sql title=Query theme={null}
SELECT plus(5,5)
```
```response title=Response theme={null}
10
```
**Somando um inteiro e uma data**
```sql title=Query theme={null}
SELECT plus(toDate('2025-01-01'),5)
```
```response title=Response theme={null}
2025-01-06
```
**Adicionando data e hora**
```sql title=Query theme={null}
SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')
```
```response title=Response theme={null}
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**
```sql theme={null}
positiveModulo(x, y)
```
**Aliases**: `positive_modulo`, `pmod`
**Argumentos**
* `x` — O dividendo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `y` — O divisor (módulo). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**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**
```sql title=Query theme={null}
SELECT positiveModulo(-1, 10)
```
```response title=Response theme={null}
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**
```sql theme={null}
positiveModuloOrNull(x, y)
```
**Aliases**: `positive_modulo_or_null`, `pmodOrNull`
**Argumentos**
* `x` — O dividendo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)/[`Float32/64`](/pt-BR/reference/data-types/float). - `y` — O divisor (módulo). [`(U)Int*`](/pt-BR/reference/data-types/int-uint)/[`Float32/64`](/pt-BR/reference/data-types/float).
**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**
```sql title=Query theme={null}
SELECT positiveModuloOrNull(5, 0)
```
```response title=Response theme={null}
\N
```
**positiveModuloOrNull do menor inteiro negativo por -1**
```sql title=Query theme={null}
SELECT positiveModuloOrNull(toInt8(-128), toInt8(-1))
```
```response title=Response theme={null}
\N
```
## sqr
Introduzido em: v26.7.0
Calcula o quadrado de um valor `x`.
**Sintaxe**
```sql theme={null}
sqr(x)
```
**Argumentos**
* `x` — Valor a ser elevado ao quadrado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna o produto de `x` por ele mesmo.
**Exemplos**
**Elevando um número ao quadrado**
```sql title=Query theme={null}
SELECT sqr(5)
```
```response title=Response theme={null}
25
```