標準 SQL の数学関数

数学関数の動作は次のとおりです。

いずれかの入力パラメータが NULL の場合、NULL を返します。
いずれかの引数が NaN の場合、NaN を返します。

ABS

ABS(X)

説明

絶対値を計算します。引数が整数で、出力値を同じ型で表せない場合、エラーを返します（これは、正の表記が含まれていない最大の負の入力値に対してのみ発生します）。

X	ABS(X)
25	25
-25	25
`+inf`	`+inf`
`-inf`	`+inf`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	INT64	NUMERIC	BIGNUMERIC	FLOAT64

SIGN

SIGN(X)

説明

負、ゼロ、正の引数に対してそれぞれ -1、0、+1 を返します。浮動小数点引数では正と負のゼロは区別されません。

X	SIGN(X)
25	+1
0	0
-25	-1
NaN	NaN

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	INT64	NUMERIC	BIGNUMERIC	FLOAT64

IS_INF

IS_INF(X)

説明

値が正または負の無限大の場合に TRUE を返します。

X	IS_INF(X)
`+inf`	`TRUE`
`-inf`	`TRUE`
25	`FALSE`

IS_NAN

IS_NAN(X)

説明

値が NaN 値である場合、TRUE を返します。

X	IS_NAN(X)
`NaN`	`TRUE`
25	`FALSE`

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

説明

X を Y で除算します。この関数が失敗することはありません。FLOAT64 を返します。除算演算子（/）とは異なり、この関数はゼロまたはオーバーフローによる除算エラーを生成しません。

X	Y	IEEE_DIVIDE(X, Y)
20.0	4.0	5.0
0.0	25.0	0.0
25.0	0.0	`+inf`
-25.0	0.0	`-inf`
0.0	0.0	`NaN`
0.0	`NaN`	`NaN`
`NaN`	0.0	`NaN`
`+inf`	`+inf`	`NaN`
`-inf`	`-inf`	`NaN`

RAND

RAND()

説明

[0, 1) の範囲の FLOAT64 型の疑似ランダム値を生成します。0 は含まれますが、1 は含まれません。

SQRT

SQRT(X)

説明

X の平方根を計算します。X が 0 未満の場合にエラーを生成します。

X	SQRT(X)
`25.0`	`5.0`
`+inf`	`+inf`
`X < 0`	エラー

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

POW

POW(X, Y)

説明

X を Y 乗した値を返します。結果がアンダーフローし、表現できない場合、値 0 を返します。

X	Y	POW(X, Y)
2.0	3.0	8.0
1.0	`NaN` を含む任意の値	1.0
`NaN` を含む任意の値	0	1.0
-1.0	`+inf`	1.0
-1.0	`-inf`	1.0
ABS(X) < 1	`-inf`	`+inf`
ABS(X) > 1	`-inf`	0.0
ABS(X) < 1	`+inf`	0.0
ABS(X) > 1	`+inf`	`+inf`
`-inf`	Y < 0	0.0
`-inf`	Y > 0	Y が奇数の場合は `-inf`、それ以外は `+inf`
`+inf`	Y < 0	0
`+inf`	Y > 0	`+inf`
有限値 < 0	非整数	エラー
0	有限値 < 0	エラー

戻りデータの型

戻りデータの型は、次の表にある引数の型によって決まります。

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

POWER

POWER(X, Y)

説明

POW(X, Y) と同等です。

EXP

EXP(X)

説明

e の X 乗を計算します（自然指数関数）。結果がアンダーフローする場合、ゼロを返します。結果がオーバーフローする場合は、エラーを生成します。

X	EXP(X)
0.0	1.0
`+inf`	`+inf`
`-inf`	0.0

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

LN

LN(X)

説明

X の自然対数を計算します。X が 0 以下の場合、エラーを生成します。

X	LN(X)
1.0	0.0
`+inf`	`+inf`
`X < 0`	エラー

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

LOG

LOG(X [, Y])

説明

X のみが存在する場合、LOG は LN と同義です。Y も存在する場合、LOG は Y を底とする X の対数を計算します。

X	Y	LOG(X, Y)
100.0	10.0	2.0
`-inf`	任意値	`NaN`
任意値	`+inf`	`NaN`
`+inf`	0.0 < Y < 1.0	`-inf`
`+inf`	Y > 1.0	`+inf`
X <= 0	任意値	エラー
任意値	Y <= 0	エラー
任意値	1.0	エラー

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

LOG10

LOG10(X)

説明

LOG と似ていますが、10 を底とする対数を計算します。

X	LOG10(X)
100.0	2.0
`-inf`	`NaN`
`+inf`	`NaN`
X <= 0	エラー

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

GREATEST

GREATEST(X1,...,XN)

説明

< 比較によって X1,...,XN の間の最大値を返します。

X1,...,XN	GREATEST(X1,...,XN)
3,5,1	5

戻りデータの型

入力値のデータ型。

LEAST

LEAST(X1,...,XN)

説明

> 比較によって X1,...,XN の間の最小値を返します。

X1,...,XN	LEAST(X1,...,XN)
3,5,1	1

戻りデータの型

入力値のデータ型。

DIV

DIV(X, Y)

説明

Y による X の整数除算の結果を返します。ゼロ除算はエラーを返します。-1 による除算はオーバーフローする可能性があります。

X	Y	DIV(X, Y)
20	4	5
0	20	0
20	0	エラー

戻りデータの型

戻りデータの型は、次の表にある引数の型によって決まります。

入力	INT64	NUMERIC	BIGNUMERIC
INT64	INT64	NUMERIC	BIGNUMERIC
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

説明

除算演算子（X / Y）と同じですが、0 で割った場合など、エラーがあると NULL を返します。

X	Y	SAFE_DIVIDE(X, Y)
20	4	5
0	20	`0`
20	0	`NULL`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

説明

乗算演算子（*）と同じですが、オーバーフローが発生すると NULL を返します。

X	Y	SAFE_MULTIPLY(X, Y)
20	4	80

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_NEGATE

SAFE_NEGATE(X)

説明

単項マイナス演算子（-）と同じですが、オーバーフローが発生すると NULL を返します。

X	SAFE_NEGATE(X)
+1	-1
-1	+1
0	0

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	INT64	NUMERIC	BIGNUMERIC	FLOAT64

SAFE_ADD

SAFE_ADD(X, Y)

説明

加算演算子（+）と同じですが、オーバーフローが発生すると NULL を返します。

X	Y	SAFE_ADD(X, Y)
5	4	9

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

説明

X から Y を減算した結果を返します。減算演算子（-）と同じですが、オーバーフローが発生すると NULL を返します。

X	Y	SAFE_SUBTRACT(X, Y)
5	4	1

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

MOD

MOD(X, Y)

説明

モジュロ関数: Y による X の除算の剰余を返します。返される値は X と同じ符号を持ちます。Y が 0 の場合、エラーが発生します。

X	Y	MOD(X, Y)
25	12	1
25	0	エラー

戻りデータの型

戻りデータの型は、次の表にある引数の型によって決まります。

入力	INT64	NUMERIC	BIGNUMERIC
INT64	INT64	NUMERIC	BIGNUMERIC
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC

ROUND

ROUND(X [, N])

説明

X のみが存在する場合、ROUND は X を最も近い整数に丸めます。N が存在する場合、ROUND は小数点以下の N 小数位に X を丸めます。N が負の場合、ROUND は小数点の左側の桁を丸めます。中間の値の場合は、ゼロから遠ざかるように丸めます。オーバーフローが発生した場合は、エラーが発生します。

X	ROUND(X)
2.0	2.0
2.3	2.0
2.8	3.0
2.5	3.0
-2.3	-2.0
-2.8	-3.0
-2.5	-3.0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

TRUNC

TRUNC(X [, N])

説明

X のみが存在する場合、TRUNC は絶対値が X 以下で最も近い整数に X を丸めます。N も存在する場合、TRUNC の動作は ROUND(X, N) と似ていますが、常にゼロに近づくように丸め、オーバーフローすることはありません。

X	TRUNC(X)
2.0	2.0
2.3	2.0
2.8	2.0
2.5	2.0
-2.3	-2.0
-2.8	-2.0
-2.5	-2.0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

CEIL

CEIL(X)

説明

X 以上で最小の整数値を返します。

X	CEIL(X)
2.0	2.0
2.3	3.0
2.8	3.0
2.5	3.0
-2.3	-2.0
-2.8	-2.0
-2.5	-2.0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

CEILING

CEILING(X)

説明

CEIL(X) と同義

FLOOR

FLOOR(X)

説明

X 以下で最大の整数値を返します。

X	FLOOR(X)
2.0	2.0
2.3	2.0
2.8	2.0
2.5	2.0
-2.3	-3.0
-2.8	-3.0
-2.5	-3.0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

戻りデータの型

入力	INT64	NUMERIC	BIGNUMERIC	FLOAT64
出力	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

COS

COS(X)

説明

X のコサインを計算します。X は RADIANS で指定されます。失敗することはありません。

X	COS(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

COSH

COSH(X)

説明

X の双曲線コサインを計算します。X は RADIANS で指定されます。オーバーフローが発生した場合は、エラーが発生します。

X	COSH(X)
`+inf`	`+inf`
`-inf`	`+inf`
`NaN`	`NaN`

ACOS

ACOS(X)

説明

X の逆コサインの主値を計算します。戻り値は [0,π] の範囲内です。X が [-1, 1] の範囲外の値である場合、エラーになります。

X	ACOS(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	エラー
X > 1	エラー

ACOSH

ACOSH(X)

説明

X の逆双曲線コサインを計算します。X が 1 未満の値の場合、エラーになります。

X	ACOSH(X)
`+inf`	`+inf`
`-inf`	`NaN`
`NaN`	`NaN`
X < 1	エラー

SIN

SIN(X)

説明

X のサインを計算します。X は RADIANS で指定されます。失敗することはありません。

X	SIN(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

SINH

SINH(X)

説明

X の双曲線サインを計算します。X は RADIANS で指定されます。オーバーフローが発生した場合は、エラーが発生します。

X	SINH(X)
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

ASIN

ASIN(X)

説明

X の逆サインの主値を計算します。戻り値は [-π/2,π/2] の範囲内です。X が [-1, 1] の範囲外である場合、エラーになります。

X	ASIN(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	エラー
X > 1	エラー

ASINH

ASINH(X)

説明

X の逆双曲線正サインを計算します。失敗することはありません。

X	ASINH(X)
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

TAN

TAN(X)

説明

X のタンジェントを計算します。X は RADIANS で指定されます。オーバーフローが発生した場合は、エラーが発生します。

X	Tan(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`

TANH

TANH(X)

説明

X の双曲線タンジェントを計算します。X は RADIANS で指定されます。失敗することはありません。

X	TANH(X)
`+inf`	1.0
`-inf`	-1.0
`NaN`	`NaN`

ATAN

ATAN(X)

説明

X の逆タンジェントの主値を計算します。戻り値は [-π/2,π/2] の範囲内です。失敗することはありません。

X	ATAN(X)
`+inf`	π/2
`-inf`	-π/2
`NaN`	`NaN`

ATANH

ATANH(X)

説明

X の逆双曲線タンジェントを計算します。X が [-1, 1] 未満の範囲外である場合、エラーになります。

X	ATANH(X)
`+inf`	`NaN`
`-inf`	`NaN`
`NaN`	`NaN`
X < -1	エラー
X > 1	エラー

ATAN2

ATAN2(X, Y)

説明

象限を判断するために 2 つの引数の符号を用いて、X/Y の逆タンジェントの主値を計算します。戻り値は [-π,π] の範囲内です。

X	Y	ATAN2(X, Y)
`NaN`	任意値	`NaN`
任意値	`NaN`	`NaN`
0.0	0.0	0.0
正の有限値	`-inf`	π
負の有限値	`-inf`	-π
有限値	`+inf`	0.0
`+inf`	有限値	π/2
`-inf`	有限値	-π/2
`+inf`	`-inf`	¾π
`-inf`	`-inf`	-¾π
`+inf`	`+inf`	π/4
`-inf`	`+inf`	-π/4

RANGE_BUCKET

RANGE_BUCKET(point, boundaries_array)

説明

RANGE_BUCKET は、並べ替えられた配列をスキャンして、ポイントの上限の 0 ベースの位置を返します。ビルドパーティション、ヒストグラム、ビジネス定義ルールなどでデータをグループ化する必要がある場合に有用です。

RANGE_BUCKET は、次のルールに従います。

配列内にポイントがある場合は、次に大きい値のインデックスを返します。

RANGE_BUCKET(20, [0, 10, 20, 30, 40]) -- 3 is return value
RANGE_BUCKET(20, [0, 10, 20, 20, 40, 40]) -- 4 is return value

ポイントが配列内に存在せず、2 つの値の間にある場合は、大きい方の値のインデックスを返します。
```
RANGE_BUCKET(25, [0, 10, 20, 30, 40]) -- 3 is return value
```
ポイントが配列の最初の値より小さい場合は 0 が返されます。
```
RANGE_BUCKET(-10, [5, 10, 20, 30, 40]) -- 0 is return value
```
ポイントが配列の最後の値以上である場合、配列の長さを返します。
```
RANGE_BUCKET(80, [0, 10, 20, 30, 40]) -- 5 is return value
```
配列が空の場合は 0 を返します。
```
RANGE_BUCKET(80, []) -- 0 is return value
```
ポイントが NULL または NaN である場合、NULL を返します。
```
RANGE_BUCKET(NULL, [0, 10, 20, 30, 40]) -- NULL is return value
```

ポイントと配列のデータ型は互換性がある必要があります。

RANGE_BUCKET('a', ['a', 'b', 'c', 'd']) -- 1 is return value
RANGE_BUCKET(1.2, [1, 1.2, 1.4, 1.6]) -- 2 is return value
RANGE_BUCKET(1.2, [1, 2, 4, 6]) -- execution failure

次の場合に実行エラーが発生します。

配列に NaN 値または NULL 値が含まれている。

RANGE_BUCKET(80, [NULL, 10, 20, 30, 40]) -- execution failure

配列が昇順で並べ替えられていない。

RANGE_BUCKET(30, [10, 30, 20, 40, 50]) -- execution failure

パラメータ

point: 汎用値です。
boundaries_array: 汎用値の汎用配列です。

戻り値

INT64

例

students という名前のテーブル内で、各 age_group バケットにいくつのレコードが存在するかを、生徒の年齢に基づいて確認します。

age_group 0 (age < 10)
age_group 1 (age >= 10, age < 20)
age_group 2 (age >= 20, age < 30)
age_group 3（age >= 30）

WITH students AS
(
  SELECT 9 AS age UNION ALL
  SELECT 20 AS age UNION ALL
  SELECT 25 AS age UNION ALL
  SELECT 31 AS age UNION ALL
  SELECT 32 AS age UNION ALL
  SELECT 33 AS age
)
SELECT RANGE_BUCKET(age, [10, 20, 30]) AS age_group, COUNT(*) AS count
FROM students
GROUP BY 1

+--------------+-------+
| age_group    | count |
+--------------+-------+
| 0            | 1     |
| 2            | 2     |
| 3            | 3     |
+--------------+-------+