> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação das funções de arredondamento

# Funções de arredondamento

<Note>
  A documentação abaixo é gerada a partir da tabela de sistema `system.functions`
</Note>

{/*AUTOGENERATED_START*/}

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

Introduzido em: v1.1.0

Como [`floor`](#floor), mas retorna o menor número arredondado maior ou igual a `x`.
Se o arredondamento causar overflow (por exemplo, `ceiling(255, -1)`), o resultado é indefinido.

**Sintaxe**

```sql theme={null}
ceiling(x[, N])
```

**Aliases**: `ceiling`

**Argumentos**

* `x` — O valor a ser arredondado. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `N` — Opcional. O número de casas decimais para o arredondamento. O valor padrão é zero, o que significa arredondar para um inteiro. Pode ser negativo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um número arredondado do mesmo tipo de `x`. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT ceiling(123.45, 1) AS rounded
```

```response title=Response theme={null}
┌─rounded─┐
│   123.5 │
└─────────┘
```

**Precisão negativa**

```sql title=Query theme={null}
SELECT ceiling(123.45, -1)
```

```response title=Response theme={null}
┌─ceiling(123.45, -1)─┐
│                 130 │
└─────────────────────┘
```

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

Introduzido em: v1.1.0

Retorna o maior número arredondado menor ou igual a `x`, em que o número arredondado é um múltiplo de `1 / 10 * N`, ou o número mais próximo do tipo de dado apropriado se `1 / 10 * N` não for exato.

Argumentos inteiros podem ser arredondados com um argumento `N` negativo.
Com `N` não negativo, a função retorna `x`.

Se o arredondamento causar overflow (por exemplo, `floor(-128, -1)`), o resultado é indefinido.

**Sintaxe**

```sql theme={null}
floor(x[, N])
```

**Argumentos**

* `x` — O valor a ser arredondado. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `N` — Opcional. O número de casas decimais para o qual arredondar. O padrão é zero, o que significa arredondar para um número inteiro. Pode ser negativo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um número arredondado do mesmo tipo de `x`. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT floor(123.45, 1) AS rounded
```

```response title=Response theme={null}
┌─rounded─┐
│   123.4 │
└─────────┘
```

**Precisão negativa**

```sql title=Query theme={null}
SELECT floor(123.45, -1)
```

```response title=Response theme={null}
┌─floor(123.45, -1)─┐
│               120 │
└───────────────────┘
```

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

Introduzido na versão: v1.1.0

Arredonda um valor para um número especificado de casas decimais `N`.

* Se `N > 0`, a função arredonda à direita do separador decimal.
* Se `N < 0`, a função arredonda à esquerda do separador decimal.
* Se `N = 0`, a função arredonda para o inteiro mais próximo.

A função retorna o número mais próximo da ordem especificada.
Se o valor de entrada estiver à mesma distância de dois números vizinhos, a função usa arredondamento bancário para entradas `Float*` e arredonda para longe de zero para os demais tipos numéricos (`Decimal*`).

Se o arredondamento causar overflow (por exemplo, `round(255, -1)`), o resultado é indefinido.

**Sintaxe**

```sql theme={null}
round(x[, N])
```

**Argumentos**

* `x` — Um número a ser arredondado. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `N` — Opcional. O número de casas decimais para o qual arredondar. O padrão é `0`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um número arredondado do mesmo tipo de `x`. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Entradas do tipo Float**

```sql title=Query theme={null}
SELECT number / 2 AS x, round(x) FROM system.numbers LIMIT 3;
```

```response title=Response theme={null}
┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        0 │
│   1 │        1 │
└─────┴──────────┘
```

**Valores de entrada decimais**

```sql title=Query theme={null}
SELECT cast(number / 2 AS  Decimal(10,4)) AS x, round(x) FROM system.numbers LIMIT 3;
```

```response title=Response theme={null}
┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        1 │
│   1 │        1 │
└─────┴──────────┘
```

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

Introduzido em: v1.1.0

Recebe um número que representa a idade de uma pessoa, compara esse número com faixas etárias padrão e retorna o maior ou o menor valor da faixa em que ele se enquadra.

* Retorna `0`, para `idade < 1`.
* Retorna `17`, para `1 ≤ idade ≤ 17`.
* Retorna `18`, para `18 ≤ idade ≤ 24`.
* Retorna `25`, para `25 ≤ idade ≤ 34`.
* Retorna `35`, para `35 ≤ idade ≤ 44`.
* Retorna `45`, para `45 ≤ idade ≤ 54`.
* Retorna `55`, para `idade ≥ 55`.

**Sintaxe**

```sql theme={null}
roundAge(num)
```

**Argumentos**

* `age` — Um número que representa uma idade em anos. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)

**Valor retornado**

Retorna a maior ou a menor idade da faixa em que `age` se enquadra. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT *, roundAge(*) FROM system.numbers WHERE number IN (0, 5, 20, 31, 37, 54, 72);
```

```response title=Response theme={null}
┌─number─┬─roundAge(number)─┐
│      0 │                0 │
│      5 │               17 │
│     20 │               18 │
│     31 │               25 │
│     37 │               35 │
│     54 │               45 │
│     72 │               55 │
└────────┴──────────────────┘
```

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

Introduzido em: v20.1.0

Arredonda um número para uma posição decimal `N` especificada.
Se o número a ser arredondado estiver exatamente no meio entre dois números, a função usa um método de arredondamento chamado arredondamento bancário, que é o método de arredondamento padrão para números de ponto flutuante definido pelo IEEE 754.

* Se `N > 0`, a função arredonda à direita do separador decimal
* Se `N < 0`, a função arredonda à esquerda do separador decimal
* Se `N = 0`, a função arredonda para o inteiro seguinte

<Info>
  **Notas**

  * Quando o número a ser arredondado está exatamente no meio entre dois números, ele é arredondado para o dígito par mais próximo na posição decimal especificada.
    Por exemplo: `3.5` é arredondado para cima, para `4`, e `2.5` é arredondado para baixo, para `2`.
  * A função `round` realiza o mesmo arredondamento para números de ponto flutuante.
  * A função `roundBankers` também arredonda inteiros da mesma forma; por exemplo, `roundBankers(45, -1) = 40`.
  * Nos demais casos, a função arredonda os números para o inteiro mais próximo.
</Info>

<Tip>
  **Use o arredondamento bancário para somar ou subtrair números**

  Ao usar o arredondamento bancário, você pode reduzir o efeito que o arredondamento dos números tem nos resultados da soma ou subtração desses números.

  Por exemplo, some os números `1.5, 2.5, 3.5, 4.5` usando diferentes formas de arredondamento:

  * Sem arredondamento: `1.5 + 2.5 + 3.5 + 4.5 = 12`.
  * Arredondamento bancário: `2 + 2 + 4 + 4 = 12`.
  * Arredondamento para o inteiro mais próximo: `2 + 3 + 4 + 5 = 14`.
</Tip>

**Sintaxe**

```sql theme={null}
roundBankers(x[, N])
```

**Argumentos**

* `x` — Um número a ser arredondado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`Float*`](/pt-BR/reference/data-types/float)
* `[, N]` — Opcional. O número de casas decimais para arredondamento. O padrão é `0`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um valor arredondado pelo método de arredondamento bancário. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`Float*`](/pt-BR/reference/data-types/float)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT number / 2 AS x, roundBankers(x, 0) AS b FROM system.numbers LIMIT 10
```

```response title=Response theme={null}
┌───x─┬─b─┐
│   0 │ 0 │
│ 0.5 │ 0 │
│   1 │ 1 │
│ 1.5 │ 2 │
│   2 │ 2 │
│ 2.5 │ 2 │
│   3 │ 3 │
│ 3.5 │ 4 │
│   4 │ 4 │
│ 4.5 │ 4 │
└─────┴───┘
```

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

Introduzido em: v20.1.0

Arredonda um número para baixo até um elemento do array especificado.
Se o valor for menor que o limite inferior, o limite inferior será retornado.

**Sintaxe**

```sql theme={null}
roundDown(num, arr)
```

**Argumentos**

* `num` — Um número a ser arredondado para baixo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`Float*`](/pt-BR/reference/data-types/float)
* `arr` — Array de elementos para os quais `num` será arredondado para baixo. [`Array((U)Int*)`](/pt-BR/reference/data-types/array) ou [`Array(Float*)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Retorna um número arredondado para baixo até um elemento de `arr`. Se o valor for menor que o limite inferior, esse limite será retornado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT *, roundDown(*, [3, 4, 5]) FROM system.numbers WHERE number IN (0, 1, 2, 3, 4, 5)
```

```response title=Response theme={null}
┌─number─┬─roundDown(number, [3, 4, 5])─┐
│      0 │                            3 │
│      1 │                            3 │
│      2 │                            3 │
│      3 │                            3 │
│      4 │                            4 │
│      5 │                            5 │
└────────┴──────────────────────────────┘
```

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

Introduzido em: v1.1.0

Arredonda um número para baixo até o valor mais próximo dentre um conjunto de durações comumente usadas: `1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000`.
Se o número for menor que um, retorna `0`.

**Sintaxe**

```sql theme={null}
roundDuration(num)
```

**Argumentos**

* `num` — Um número a ser arredondado para um dos valores no conjunto de durações comuns. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)

**Valor retornado**

Retorna `0` para `num` \< 1. Caso contrário, retorna um dos seguintes valores: `1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000`. [`UInt16`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT *, roundDuration(*) FROM system.numbers WHERE number IN (0, 9, 19, 47, 101, 149, 205, 271, 421, 789, 1423, 2345, 4567, 9876, 24680, 42573)
```

```response title=Response theme={null}
┌─number─┬─roundDuration(number)─┐
│      0 │                     0 │
│      9 │                     1 │
│     19 │                    10 │
│     47 │                    30 │
│    101 │                    60 │
│    149 │                   120 │
│    205 │                   180 │
│    271 │                   240 │
│    421 │                   300 │
│    789 │                   600 │
│   1423 │                  1200 │
│   2345 │                  1800 │
│   4567 │                  3600 │
│   9876 │                  7200 │
│  24680 │                 18000 │
│  42573 │                 36000 │
└────────┴───────────────────────┘
```

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

Introduzido em: v1.1.0

Arredonda um número para baixo para a potência de dois (inteira não negativa) mais próxima.
Se o número for menor que um, retorna `0`.

**Sintaxe**

```sql theme={null}
roundToExp2(num)
```

**Argumentos**

* `num` — Um número a ser arredondado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)

**Valor retornado**

Retorna `num` arredondado para baixo para a potência de dois mais próxima (inteira e não negativa); caso contrário, `0` para `num < 1`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT *, roundToExp2(*) FROM system.numbers WHERE number IN (0, 2, 5, 10, 19, 50)
```

```response title=Response theme={null}
┌─number─┬─roundToExp2(number)─┐
│      0 │                   0 │
│      2 │                   2 │
│      5 │                   4 │
│     10 │                   8 │
│     19 │                  16 │
│     50 │                  32 │
└────────┴─────────────────────┘
```

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

Introduzido em: v1.1.0

Como [`floor`](#floor), mas retorna o número arredondado cujo valor absoluto é o maior valor menor ou igual ao de `x`.

**Sintaxe**

```sql theme={null}
truncate(x[, N])
```

**Aliases**: `truncate`

**Argumentos**

* `x` — O valor a ser arredondado. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `N` — Opcional. O número de casas decimais para arredondar. O padrão é zero, o que significa arredondar para um número inteiro. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um número arredondado do mesmo tipo de `x`. [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal*`](/pt-BR/reference/data-types/decimal) ou [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT truncate(123.499, 1) AS res;
```

```response title=Response theme={null}
┌───res─┐
│ 123.4 │
└───────┘
```