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

> 丸め関数のドキュメント

# 丸め関数

<Note>
  以下のドキュメントは、`system.functions` システムテーブルから生成されています
</Note>

{/*AUTOGENERATED_START*/}

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

導入バージョン: v1.1.0

[`floor`](#floor) と同様ですが、`x` 以上となる最小の丸め後の値を返します。
丸めによってオーバーフローが発生した場合 (たとえば `ceiling(255, -1)`) 、結果は未定義です。

**構文**

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

**別名**: `ceiling`

**引数**

* `x` — 丸める対象の値。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)
* `N` — 任意。丸める小数点以下の桁数。デフォルトは 0 で、この場合は整数に丸められます。負の値も指定できます。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

`x` と同じ型の、丸められた数値を返します。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)

**例**

**基本的な使い方**

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

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

**負の精度指定**

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

導入バージョン: v1.1.0

`x` 以下の最大の丸め後の数値を返します。ここで、丸め後の数値は `1 / 10 * N` の倍数です。`1 / 10 * N` を正確に表せない場合は、適切なデータ型で最も近い数値を返します。

整数の引数は、`N` に負の値を指定して丸めることができます。
`N` が 0 以上の場合、この関数は `x` を返します。

丸めによってオーバーフローが発生した場合 (たとえば `floor(-128, -1)`) 、結果は未定義です。

**構文**

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

**引数**

* `x` — 丸める対象の値。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)
* `N` — 任意。丸める小数点以下の桁数です。デフォルトは 0 で、この場合は整数に丸められます。負の値も指定できます。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

`x` と同じ型の、丸められた数値を返します。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)

**例**

**使用例**

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

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

**負の精度指定**

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

導入バージョン: v1.1.0

値を、指定した小数点以下桁数 `N` に丸めます。

* `N > 0` の場合、関数は小数点の右側で丸めます。
* `N < 0` の場合、関数は小数点の左側で丸めます。
* `N = 0` の場合、関数は最も近い整数に丸めます。

この関数は、指定した桁で最も近い値を返します。
入力値が隣接する 2 つの数値から等距離にある場合、`Float*` 入力には銀行家の丸めを使用し、それ以外の数値型 (`Decimal*`) では 0 から遠ざかる方向に丸めます。

丸めによってオーバーフローが発生する場合 (たとえば `round(255, -1)`) 、結果は未定義です。

**構文**

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

**引数**

* `x` — 丸める対象の数値。[`Float*`](/ja/reference/data-types/float)、[`Decimal*`](/ja/reference/data-types/decimal)、または [`(U)Int*`](/ja/reference/data-types/int-uint)
* `N` — 任意。丸める小数点以下の桁数。デフォルトは `0` です。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

`x` と同じ型の丸められた数値を返します。[`Float*`](/ja/reference/data-types/float)、[`Decimal*`](/ja/reference/data-types/decimal)、または [`(U)Int*`](/ja/reference/data-types/int-uint)

**例**

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

**10進数入力**

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

導入バージョン: v1.1.0

人間の年齢を表す数値を受け取り、標準的な年齢区分と照らし合わせて、その数値が含まれる範囲の上限値または下限値を返します。

* `age < 1` の場合は `0` を返します。
* `1 ≤ age ≤ 17` の場合は `17` を返します。
* `18 ≤ age ≤ 24` の場合は `18` を返します。
* `25 ≤ age ≤ 34` の場合は `25` を返します。
* `35 ≤ age ≤ 44` の場合は `35` を返します。
* `45 ≤ age ≤ 54` の場合は `45` を返します。
* `age ≥ 55` の場合は `55` を返します。

**構文**

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

**引数**

* `age` — 年齢 (年単位) を表す数値。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Float*`](/ja/reference/data-types/float)

**戻り値**

`age` が属する範囲の上限または下限の年齢を返します。[`UInt8`](/ja/reference/data-types/int-uint)

**例**

**使用例**

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

導入バージョン: v20.1.0

数値を指定した小数点位置 `N` に丸めます。
丸め対象の値が 2 つの数のちょうど中間にある場合、この関数では 銀行家の丸め と呼ばれる丸め方式を使用します。これは、IEEE 754 で定義されている浮動小数点数のデフォルトの丸め方式です。

* `N > 0` の場合、関数は小数点以下を丸めます
* `N < 0` の場合、関数は小数点より左側を丸めます
* `N = 0` の場合、関数は最も近い整数に丸めます

<Info>
  **注意**

  * 丸め対象の値が 2 つの数のちょうど中間にある場合、指定した小数点位置で最も近い偶数の桁に丸められます。
    たとえば、`3.5` は `4` に切り上げられ、`2.5` は `2` に切り下げられます。
  * `round` 関数は、浮動小数点数に対して同じ丸めを行います。
  * `roundBankers` 関数は整数も同様に丸めます。たとえば、`roundBankers(45, -1) = 40` です。
  * それ以外の場合、この関数は数値を最も近い整数に丸めます。
</Info>

<Tip>
  **数値の加算や減算には 銀行家の丸め を使用してください**

  銀行家の丸め を使用すると、数値の丸めが、それらの加算や減算の結果に与える影響を抑えられます。

  たとえば、`1.5, 2.5, 3.5, 4.5` を異なる丸め方法で合計すると、次のようになります。

  * 丸めなし: `1.5 + 2.5 + 3.5 + 4.5 = 12`。
  * 銀行家の丸め: `2 + 2 + 4 + 4 = 12`。
  * 最も近い整数への丸め: `2 + 3 + 4 + 5 = 14`。
</Tip>

**構文**

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

**引数**

* `x` — 丸め対象の数値。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Decimal*`](/ja/reference/data-types/decimal) または [`Float*`](/ja/reference/data-types/float)
* `[, N]` — 省略可能。丸める小数点以下の桁数です。デフォルト値は `0` です。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

銀行家の丸めで丸めた値を返します。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Decimal*`](/ja/reference/data-types/decimal) または [`Float*`](/ja/reference/data-types/float)

**例**

**基本的な使い方**

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

導入バージョン: v20.1.0

数値を、指定した配列内の要素に向かって切り下げます。
値が下限より小さい場合は、下限値が返されます。

**構文**

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

**引数**

* `num` — 切り下げる対象の数値。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Decimal*`](/ja/reference/data-types/decimal) または [`Float*`](/ja/reference/data-types/float)
* `arr` — `num` を切り下げる基準となる要素の Array。[`Array((U)Int*)`](/ja/reference/data-types/array) または [`Array(Float*)`](/ja/reference/data-types/array)

**戻り値**

`arr` の要素まで切り下げた数値を返します。値が最小の境界値より小さい場合は、最小の境界値が返されます。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Float*`](/ja/reference/data-types/float)

**例**

**使用例**

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

導入バージョン: v1.1.0

数値を、一般的によく使われる期間の値 `1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000` のうち、直近のより小さい値に切り下げます。
数値が 1 未満の場合は、`0` を返します。

**構文**

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

**引数**

* `num` — 一般的な期間の集合に含まれるいずれかの値に丸める対象の数値。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Float*`](/ja/reference/data-types/float)

**戻り値**

`num` \< 1 の場合は `0` を返します。それ以外の場合は、`1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000` のいずれかを返します。[`UInt16`](/ja/reference/data-types/int-uint)

**例**

**使用例**

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

導入バージョン: v1.1.0

数値を、最も近い (0 以上の整数の) 2 のべき乗へ切り下げます。
数値が 1 未満の場合は、`0` を返します。

**構文**

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

**引数**

* `num` — 丸める対象の数値。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Float*`](/ja/reference/data-types/float)

**戻り値**

`num` を、最も近い (0 以上の整数の) 2 のべき乗に切り下げて返します。`num < 1` の場合は `0` を返します。[`(U)Int*`](/ja/reference/data-types/int-uint) または [`Float*`](/ja/reference/data-types/float)

**例**

**使用例**

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

導入バージョン: v1.1.0

[`floor`](#floor) と似ていますが、`x` の絶対値以下で、絶対値が最大となる丸め後の数値を返します。

**構文**

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

**別名**: `truncate`

**引数**

* `x` — 丸める対象の値。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)
* `N` — オプション。丸める小数点以下の桁数。デフォルトは 0 で、この場合は整数に丸められます。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

`x` と同じ型の、丸められた数値を返します。[`Float*`](/ja/reference/data-types/float) または [`Decimal*`](/ja/reference/data-types/decimal) または [`(U)Int*`](/ja/reference/data-types/int-uint)

**例**

**基本的な使い方**

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

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