> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-1d264819.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

<div id="overview">
  ## Visão geral
</div>

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++.

{/*AUTOGENERATED_START*/}

<div id="abs">
  ## abs
</div>

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
```

<div id="avg2">
  ## avg2
</div>

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) │
└──────────┴───────────┘
```

<div id="byteSwap">
  ## byteSwap
</div>

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
```

<div id="divide">
  ## divide
</div>

Introduzido na versão: 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`.

<Note>
  A divisão por `0` retorna `inf`, `-inf` ou `nan`.
</Note>

**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
```

<div id="divideDecimal">
  ## divideDecimal
</div>

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.

<Note>
  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).
</Note>

**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}
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(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 5)─┐
│ -12 │ 2.1 │                                                       -5.7 │                                                   -5.71428 │
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
```

<div id="divideOrNull">
  ## divideOrNull
</div>

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
```

<div id="gcd">
  ## gcd
</div>

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**

```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
```

<div id="ifNotFinite">
  ## ifNotFinite
</div>

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
```

<div id="intDiv">
  ## intDiv
</div>

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(intDiv(toFloat64(1), 0.001))─┐
│ 1000 │ Int64                                   │
└──────┴─────────────────────────────────────────┘
```

**O quociente não cabe na faixa 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)
```

<div id="intDivOrNull">
  ## intDivOrNull
</div>

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
```

<div id="intDivOrZero">
  ## intDivOrZero
</div>

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
```

<div id="isFinite">
  ## isFinite
</div>

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**

```sql theme={null}
isFinite(x)
```

**Argumentos**

* `x` — Número a ser verificado quanto à finitude. [`Float*`](/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
```

<div id="isInfinite">
  ## isInfinite
</div>

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**

```sql theme={null}
isInfinite(x)
```

**Argumentos**

* `x` — Número a ser verificado quanto à infinitude. [`Float*`](/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
```

<div id="isNaN">
  ## isNaN
</div>

Introduzido em: v1.1.0

Retorna `1` se o argumento do tipo Float32 ou Float64 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)

**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
```

<div id="lcm">
  ## lcm
</div>

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
```

<div id="max2">
  ## max2
</div>

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), [`Float*`](/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), [`Float*`](/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
```

<div id="midpoint">
  ## midpoint
</div>

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) │
└──────────┴───────────┘
```

<div id="min2">
  ## min2
</div>

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 [`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 [`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
```

<div id="minus">
  ## minus
</div>

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**

```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
```

<div id="modulo">
  ## modulo
</div>

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
```

<div id="moduloLegacy">
  ## moduloLegacy
</div>

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
```

<div id="moduloOrNull">
  ## moduloOrNull
</div>

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**

```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 o divisor é zero.

**Exemplos**

**moduloOrNull com zero**

```sql title=Query theme={null}
SELECT moduloOrNull(5, 0)
```

```response title=Response theme={null}
\N
```

<div id="moduloOrZero">
  ## moduloOrZero
</div>

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**

```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`, ou `0` quando o divisor é `0`.

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT moduloOrZero(5, 0)
```

```response title=Response theme={null}
0
```

<div id="multiply">
  ## multiply
</div>

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
```

<div id="multiplyDecimal">
  ## multiplyDecimal
</div>

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.

<Note>
  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)
</Note>

**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 multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
```

```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 │
└──────────────────────────────────────────────────────────────────┘
```

**Estouro em decimal**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─────────────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)
```

<div id="negate">
  ## negate
</div>

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
```

<div id="plus">
  ## plus
</div>

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**

```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
```

<div id="positiveModulo">
  ## positiveModulo
</div>

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
```

<div id="positiveModuloOrNull">
  ## positiveModuloOrNull
</div>

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**

```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 inteiro mais próximo divisível por `y` que não seja maior que
`x`; `null` quando o divisor é zero.

**Exemplos**

**positiveModuloOrNull**

```sql title=Query theme={null}
SELECT positiveModuloOrNull(5, 0)
```

```response title=Response theme={null}
\N
```