Mathematische Funktionen in Standard-SQL

Alle mathematischen Funktionen verhalten sich in folgender Weise:

  • Sie geben NULL zurück, wenn einer der Eingabeparameter NULL ist.
  • Sie geben NaN zurück, wenn eines der Argumente NaN ist.

ABS

ABS(X)

Beschreibung

Berechnet den absoluten Wert. Gibt einen Fehler zurück, wenn das Argument eine Ganzzahl ist und der Ausgabewert nicht als der gleiche Typ dargestellt werden kann. Dies geschieht nur mit dem größten negativen Eingabewert, der nicht positiv dargestellt werden kann. Gibt +inf für ein +/-inf-Argument zurück.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTINT64NUMERICFLOAT64

SIGN

SIGN(X)

Beschreibung

Gibt -1, 0 oder +1 für negative, Null- bzw. positive Argumente zurück. Bei Gleitkommaargumenten unterscheidet diese Funktion nicht zwischen positiv und negativ null. Gibt NaN für ein NaN-Argument zurück.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTINT64NUMERICFLOAT64

IS_INF

IS_INF(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert positiv oder negativ unendlich ist.

Gibt NULL für NULL-Eingaben zurück.

IS_NAN

IS_NAN(X)

Beschreibung

Gibt TRUE zurück, wenn der Wert ein NaN-Wert ist.

Gibt NULL für NULL-Eingaben zurück.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Beschreibung

Dividiert X durch Y. Diese Funktion schlägt nie fehl. Gibt FLOAT64 zurück. Erzeugt im Gegensatz zum Divisionsoperator (/) keinen Fehler bei der Division durch null oder bei Überlauf.

Sonderfälle:

  • Wenn das Ergebnis überläuft, wird +/-inf zurückgegeben.
  • Wenn Y=0 und X=0, wird NaN zurückgegeben.
  • Wenn Y=0 und X!=0, wird +/-inf zurückgegeben.
  • Wenn X = +/-inf und Y = +/-inf, wird NaN zurückgegeben.

Das Verhalten von IEEE_DIVIDE wird in der nachfolgenden Tabelle weiter veranschaulicht.

Sonderfälle für IEEE_DIVIDE

In der folgenden Tabelle sind Sonderfälle für IEEE_DIVIDE aufgelistet:

Zähler-Datentyp (X) Nenner-Datentyp (Y) Ergebniswert
Alles außer 0 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

RAND

RAND()

Beschreibung

Erzeugt einen Pseudozufallswert vom Typ FLOAT64 im Bereich von [0, 1], einschließlich 0 und exklusiv 1.

SQRT

SQRT(X)

Beschreibung

Berechnet die Quadratwurzel aus X. Generiert einen Fehler, wenn X kleiner als 0 ist.

Gibt +inf zurück, wenn X +inf ist.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTFLOAT64NUMERICFLOAT64

POW

POW(X, Y)

Beschreibung

Gibt den Wert X zurück, der mit Y potenziert wird. Wenn das Ergebnis unterläuft und nicht darstellbar ist, gibt die Funktion den Wert null zurück. Gibt einen Fehler zurück, wenn eine der folgenden Bedingungen zutrifft:

  • X ist ein endlicher Wert, der kleiner als 0 ist, und Y ist keine ganze Zahl.
  • X ist 0 und Y ist ein endlicher Wert, der kleiner als 0 ist.

Rückgabedatentyp Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUTINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

Sonderfälle für POW(X, Y)

Im Folgenden sind Sonderfälle für POW(X, Y) aufgeführt.

X Y POW(X, Y) oder POWER(X, Y)
1,0 Beliebiger Wert, einschließlich NaN 1,0
Beliebig, einschließlich NaN 0 1,0
-1,0 +/-inf 1,0
ABS (X) < 1 -inf +inf
ABS (X) > 1 -inf 0
ABS (X) < 1 +inf 0
ABS (X) > 1 +inf +inf
-inf Y < 0 0
-inf Y > 0 -inf, wenn Y eine ungerade Ganzzahl ist, sonst +inf
+inf Y < 0 0
+inf Y > 0 +inf

POWER

POWER(X, Y)

Beschreibung

Synonym für POW(X, Y).

EXP

EXP(X)

Beschreibung

Potenziert e mit X, was auch als natürliche Exponentialfunktion bezeichnet wird. Bei einem Unterlauf des Ergebnisses gibt diese Funktion eine Null zurück. Erzeugt einen Fehler, wenn ein Überlauf des Ergebnisses auftritt. Wenn X +/-inf ist, gibt diese Funktion +inf oder 0 zurück.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTFLOAT64NUMERICFLOAT64

LN

LN(X)

Beschreibung

Berechnet den natürlichen Logarithmus von X. Generiert einen Fehler, wenn X kleiner als oder gleich null ist. Wenn X +inf ist, gibt diese Funktion +inf zurück.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTFLOAT64NUMERICFLOAT64

LOG

LOG(X [, Y])

Beschreibung

Wenn nur X vorhanden ist, ist LOG ein Synonym für LN. Falls Y ebenfalls vorhanden ist, berechnet LOG den Logarithmus von X zur Basis Y. Erzeugt in folgenden Fällen einen Fehler:

  • X ist kleiner oder gleich null.
  • Y ist 1,0.
  • Y ist kleiner oder gleich null.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

Das Verhalten von LOG(X, Y) ist in der nachfolgenden Tabelle weiter veranschaulicht.

Sonderfälle für LOG(X, Y)

X Y LOG(X, Y)
-inf Beliebiger Wert NaN
Beliebiger Wert +inf NaN
+inf 0,0 Y < 1,0 -inf
+inf Y > 1,0 +inf

LOG10

LOG10(X)

Beschreibung

Ähnlich wie bei LOG, berechnet den Logarithmus aber auf Basis 10.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTFLOAT64NUMERICFLOAT64

GREATEST

GREATEST(X1,...,XN)

Beschreibung

Gibt NULL zurück, wenn eine der Eingaben NULL ist. NaN wird zurückgegeben, wenn eine der Eingaben NaN ist. Andernfalls wird der größte Wert unter X1,…,XN gemäß Kleiner-als-Vergleich (<) zurückgegeben.

Rückgabedatentypen

Der Datentyp der Eingabewerte.

LEAST

LEAST(X1,...,XN)

Beschreibung

Gibt NULL zurück, wenn eine der Eingaben NULL ist. NaN wird zurückgegeben, wenn eine der Eingaben NaN ist. Andernfalls wird der kleinste Wert zwischen X1,...,XN gemäß Größer-als-Vergleich (>) zurückgegeben.

Rückgabedatentypen

Der Datentyp der Eingabewerte.

DIV

DIV(X, Y)

Beschreibung

Gibt das Ergebnis der Ganzzahldivision von X durch Y zurück. Die Division durch null gibt einen Fehler zurück. Division durch -1 kann überlaufen.

Rückgabedatentyp

Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUTINT64NUMERIC
INT64INT64NUMERIC
NUMERICNUMERICNUMERIC

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Beschreibung

Entspricht dem Divisionsoperator (X / Y), gibt jedoch NULL zurück, wenn ein Fehler auftritt, beispielsweise bei einer Division durch null.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Beschreibung

Entspricht dem Multiplikationsoperator (*), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

SAFE_NEGATE

SAFE_NEGATE(X)

Beschreibung

Entspricht dem Unäres-Minus-Operator (-), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
OUTPUTINT64NUMERICFLOAT64

SAFE_ADD

SAFE_ADD(X, Y)

Beschreibung

Entspricht dem Additionsoperator (+), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Beschreibung

Gibt das Ergebnis von X minus Y zurück. Entspricht dem Subtraktionsoperator (-), gibt jedoch NULL zurück, wenn ein Überlauf auftritt.

Rückgabedatentyp

INPUTINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

MOD

MOD(X, Y)

Beschreibung

Modulo-Funktion: gibt den Rest der Division von X durch Y zurück. Der zurückgegebene Wert hat dasselbe Vorzeichen wie X. Wenn Y gleich 0 ist, wird ein Fehler ausgegeben.

Rückgabedatentyp

Der Rückgabedatentyp wird durch die Argumenttypen mit der folgenden Tabelle bestimmt.

INPUTINT64NUMERIC
INT64INT64NUMERIC
NUMERICNUMERICNUMERIC

ROUND

ROUND(X [, N])

Beschreibung

Wenn nur X vorhanden ist, rundet ROUND X auf die nächste Ganzzahl. Wenn N vorhanden ist, rundet ROUND X auf N-Dezimalstellen nach dem Dezimalzeichen. Wenn N negativ ist, rundet ROUND die Ziffern links vom Dezimalzeichen ab. Rundet halbe Zahlen von null weg. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

TRUNC

TRUNC(X [, N])

Beschreibung

Wenn nur X vorhanden ist, rundet TRUNC X auf die nächste Ganzzahl, deren absoluter Wert nicht größer als der absolute Wert von X ist. Wenn N ebenfalls vorhanden ist, verhält sich TRUNC wie ROUND(X, N), rundet aber immer gegen null und läuft nie über.

CEIL

CEIL(X)

Beschreibung

Gibt den kleinsten Integralwert (mit FLOAT64-Typ) zurück, der nicht kleiner als X ist.

CEILING

CEILING(X)

Beschreibung

Synonym von CEIL(X)

FLOOR

FLOOR(X)

Beschreibung

Gibt den größten Integralwert (mit FLOAT64-Typ) zurück, der nicht größer als X ist.

Beispiel für Verhalten der Rundungsfunktion

Beispielverhalten von BigQuery-Rundungsfunktionen:

Eingabe "X" ROUND(X) TRUNC(X) CEIL(X) FLOOR(X)
2,0 2,0 2,0 2,0 2,0
2,3 2,0 2,0 3,0 2,0
2,8 3,0 2,0 3,0 2,0
2,5 3,0 2,0 3,0 2,0
-2,3 -2,0 -2,0 -2,0 -3,0
-2,8 -3,0 -2,0 -2,0 -3,0
-2,5 -3,0 -2,0 -2,0 -3,0
0 0 0 0 0
+/-inf +/-inf +/-inf +/-inf +/-inf
NaN NaN NaN NaN NaN

COS

COS(X)

Beschreibung

Berechnet den Kosinus von X, wobei X als Radiant angegeben wird. Schlägt niemals fehl.

COSH

COSH(X)

Beschreibung

Berechnet den hyperbolischen Kosinus von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

ACOS

ACOS(X)

Beschreibung

Berechnet den Hauptwert des inversen Kosinus von X. Der zurückgegebene Wert liegt im Bereich [0,π]. Erzeugt einen Fehler, wenn X ein Wert außerhalb des Bereichs [-1, 1] ist.

ACOSH

ACOSH(X)

Beschreibung

Berechnet den inversen hyperbolischen Kosinus von X. Erzeugt einen Fehler, wenn X ein Wert kleiner als 1 ist.

SIN

SIN(X)

Beschreibung

Berechnet den Sinus von X, wobei X als Radiant angegeben wird. Schlägt niemals fehl.

SINH

SINH(X)

Beschreibung

Berechnet den hyperbolischen Sinus von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn ein Überlauf auftritt.

ASIN

ASIN(X)

Beschreibung

Berechnet den Hauptwert des inversen Sinus von X. Der zurückgegebene Wert liegt im Bereich [-π/2,π/2]. Erzeugt einen Fehler, wenn X außerhalb des Bereichs [-1, 1] liegt.

ASINH

ASINH(X)

Beschreibung

Berechnet den inversen hyperbolischen Sinus von X. Schlägt nie fehl.

TAN

TAN(X)

Beschreibung

Berechnet den Tangens von X, wobei X als Radiant angegeben wird. Erzeugt einen Fehler, wenn das Ergebnis überläuft.

TANH

TANH(X)

Beschreibung

Berechnet den hyperbolischen Tangens von X, wobei X als Radiant angegeben wird. Schlägt nie fehl.

ATAN

ATAN(X)

Beschreibung

Berechnet den Hauptwert des inversen Tangens von X. Der zurückgegebene Wert liegt im Bereich [-π/2,π/2]. Schlägt nie fehl.

ATANH

ATANH(X)

Beschreibung

Berechnet den inversen hyperbolischen Tangens von X. Erzeugt einen Fehler, wenn X außerhalb des Bereichs [-1, 1] liegt.

ATAN2

ATAN2(Y, X)

Beschreibung

Berechnet den Hauptwert des inversen Tangens von Y/X unter Verwendung der Vorzeichen der beiden Argumente, um den Quadranten zu bestimmen. Der zurückgegebene Wert liegt im Bereich [-π, π].

Das Verhalten dieser Funktion wird in nachfolgender Tabelle weiter veranschaulicht.

Sonderfälle für ATAN2()

Y X ATAN2(Y, X)
NaN Beliebiger Wert NaN
Beliebiger Wert NaN NaN
0 0 0, π oder -π, je nach Vorzeichen von X und Y
Endlicher Wert -inf π oder -π, je nach Vorzeichen von Y
Endlicher Wert +inf 0
+/-inf Endlicher Wert π/2 oder -π/2, je nach Vorzeichen von Y
+/-inf -inf ¾π oder -¾π, je nach Vorzeichen von Y
+/-inf +inf π/4 oder -π/4, je nach Vorzeichen von Y

Sonderfälle für trigonometrische und hyperbolische Rundungsfunktionen

X COS(X) COSH(X) ACOS(X) ACOSH(X) SIN(X) SINH(X) ASIN(X) ASINH(X) TAN(X) TANH(X) ATAN(X) ATANH(X)
+/-inf NaN =+inf NaN =+inf NaN =+inf NaN =+inf NaN =+1,0 π/2 NaN
-inf NaN =+inf NaN NaN NaN -inf NaN -inf NaN -1,0 -π/2 NaN
NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN

RANGE_BUCKET

RANGE_BUCKET(point, boundaries_array)

Beschreibung

RANGE_BUCKET scannt ein sortiertes Array und gibt die 0-basierte Position der oberen Grenze des Punkts zurück. Dies kann nützlich sein, wenn Sie Ihre Daten gruppieren müssen, um Partitionen, Histogramme, unternehmensspezifische Regeln usw. zu erstellen.

RANGE_BUCKET folgt diesen Regeln:

  • Wenn der Punkt im Array vorhanden ist, wird der Index des nächstgrößeren Werts zurückgegeben.

    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
    
  • Wenn der Punkt nicht im Array vorhanden ist, aber zwischen zwei Werten liegt, wird der Index des größeren Werts zurückgegeben.

    RANGE_BUCKET(25, [0, 10, 20, 30, 40]) -- 3 is return value
    
  • Wenn der Punkt kleiner als der erste Wert im Array ist, wird 0 zurückgegeben.

    RANGE_BUCKET(-10, [5, 10, 20, 30, 40]) -- 0 is return value
    
  • Wenn der Punkt größer oder gleich dem letzten Wert im Array ist, wird die Länge des Arrays zurückgegeben.

    RANGE_BUCKET(80, [0, 10, 20, 30, 40]) -- 5 is return value
    
  • Wenn das Array leer ist, wird 0 zurückgegeben.

    RANGE_BUCKET(80, []) -- 0 is return value
    
  • Wenn der Punkt NULL oder NaN ist, wird NULL zurückgegeben.

    RANGE_BUCKET(NULL, [0, 10, 20, 30, 40]) -- NULL is return value
    
  • Der Datentyp für den Punkt und das Array muss kompatibel sein.

    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
    

Ein Ausführungsfehler tritt in folgenden Fällen auf:

  • Das Array enthält einen NaN- oder NULL-Wert.

    RANGE_BUCKET(80, [NULL, 10, 20, 30, 40]) -- execution failure
    
  • Das Array ist nicht in aufsteigender Reihenfolge sortiert.

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

Parameter

  • point: Ein generischer Wert.
  • boundaries_array: Ein generisches Array von Werten.

Rückgabewert

INT64

Beispiele

Prüfen Sie in einer Tabelle mit dem Namen students, wie viele Datensätze in jedem age_group-Bucket auf Basis des Alters eines Schülers/Studenten vorhanden wären:

  • age_group 0 (Alter < 10)
  • age_group 1 (Alter >= 10, Alter < 20)
  • age_group 2 (Alter >= 20, Alter < 30)
  • age_group 3 (Alter >= 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     |
+--------------+-------+