Fonctions mathématiques en SQL standard

Toutes les fonctions mathématiques se comportent de la façon suivante :

  • Elles renvoient NULL si l'un des paramètres d'entrée est NULL.
  • Elles renvoient NaN si l'un des arguments est NaN.

ABS

ABS(X)

Description

Calcule la valeur absolue. Renvoie une erreur si l'argument est un entier et que la valeur de sortie ne peut pas être représentée avec le même type. Cela ne peut se produire que pour la plus grande valeur d'entrée négative, qui n'a pas de représentation positive. Renvoie +inf pour un argument +/-inf.

SIGN

SIGN(X)

Description

Renvoie respectivement -1, 0 ou +1 pour les arguments "négatif", "zéro" et "positif". Pour les arguments à virgule flottante, cette fonction ne fait pas la distinction entre zéro positif et zéro négatif. Renvoie NaN pour un argument NaN.

IS_INF

IS_INF(X)

Description

Renvoie TRUE si la valeur correspond à l'infini positif ou négatif.

Renvoie NULL pour les entrées NULL.

IS_NAN

IS_NAN(X)

Description

Renvoie TRUE si la valeur est une valeur NaN.

Renvoie NULL pour les entrées NULL.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Description

Divise X par Y ; cette fonction n'échoue jamais. Renvoie une valeur FLOAT64. Contrairement à l'opérateur de division (/), cette fonction ne génère pas d'erreur en cas de division par zéro ou de débordement.

Cas particuliers :

  • Si le résultat déborde, elle renvoie +/-inf.
  • Si Y=0 et X=0, elle renvoie NaN.
  • Si Y=0 et X!=0, elle renvoie +/-inf.
  • Si X=+/-inf et Y=+/-inf, elle renvoie NaN.

Le comportement de IEEE_DIVIDE est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour IEEE_DIVIDE

Le tableau suivant répertorie les cas particuliers pour IEEE_DIVIDE.

Type de données du numérateur (X) Type de données du dénominateur (Y) Valeur du résultat
Tout sauf 0 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

RAND

RAND()

Description

Génère une valeur pseudo-aléatoire de type FLOAT64 dans la plage [0, 1), 0 étant inclus et 1 étant exclu.

SQRT

SQRT(X)

Description

Calcule la racine carrée de X. Génère une erreur si X est inférieur à 0.

Renvoie +inf si X est +inf.

POW

POW(X, Y)

Description

Renvoie la valeur de X élevée à la puissance Y. Si le résultat est insuffisant et qu'il n'est pas représentable, la fonction renvoie une valeur "zéro". Elle renvoie une erreur si l'une des conditions suivantes est vraie :

  • X est une valeur finie inférieure à 0 et Y n'est pas un entier.
  • X est égal à 0 et Y est une valeur finie inférieure à 0.

Le comportement de POW() est illustré plus en détail dans le tableau ci-dessous.

POWER

POWER(X, Y)

Description

Synonyme de POW().

Cas particuliers pour POW(X, Y) et POWER(X, Y)

Voici des cas particuliers pour POW(X, Y) et POWER(X, Y).

X Y POW(X, Y) ou POWER(X, Y)
1,0 Toute valeur, y compris NaN 1,0
Tout, y compris 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 si Y est un entier impair, +inf dans le cas contraire
+inf Y < 0 0
+inf Y > 0 +inf

EXP

EXP(X)

Description

Calcule e à la puissance X. Cette fonction est également appelée "fonction exponentielle naturelle". Si le résultat est insuffisant, cette fonction renvoie un zéro. Elle génère une erreur si le résultat déborde. Si X est égal à +/-inf, cette fonction renvoie +inf ou 0.

LN

LN(X)

Description

Calcule le logarithme népérien de X. Génère une erreur si X est inférieur ou égal à zéro. Si X est égal à +inf, cette fonction renvoie +inf.

LOG

LOG(X [, Y])

Description

Si seul X est présent, LOG est un synonyme de LN. Si Y est également présent, LOG calcule le logarithme de X en base Y. Cette fonction génère une erreur dans les cas suivants :

  • X est inférieur ou égal à zéro.
  • Y est égal à 1,0.
  • Y est inférieur ou égal à zéro.

Le comportement de LOG(X, Y) est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour LOG(X, Y)

X Y LOG(X, Y)
-inf Toute valeur NaN
Toute valeur +inf NaN
+inf 0,0 Y < 1,0 -inf
+inf Y > 1,0 +inf

LOG10

LOG10(X)

Description

Identique à LOG, mais calcule le logarithme en base 10.

GREATEST

GREATEST(X1,...,XN)

Description

Renvoie NULL si l'une des entrées est NULL. Autrement, la fonction renvoie NaN si l'une des entrées est NaN. Sinon, elle renvoie la plus grande valeur parmi "X1, ..., XN" (identifiée à l'aide de la comparaison "<").

LEAST

LEAST(X1,...,XN)

Description

Renvoie NULL si l'une des entrées est NULL. Cette fonction renvoie NaN si l'une des entrées est NaN. Sinon, elle renvoie la plus petite valeur parmi "X1, ..., XN" (identifiée à l'aide de la comparaison ">").

DIV

DIV(X, Y)

Description

Renvoie le résultat de la division d'un entier X par un entier Y. Une division par zéro renvoie une erreur. Une division par -1 peut entraîner un débordement. Pour découvrir les types de résultats possibles, consultez la section Types de résultats pour DIV(X, Y) et MOD(X, Y).

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Description

Équivaut à l'opérateur de division (/), mais renvoie NULL si une erreur se produit, par exemple une erreur de division par zéro.

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Description

Équivaut à l'opérateur de multiplication (*), mais renvoie NULL si un débordement se produit.

SAFE_NEGATE

SAFE_NEGATE(X)

Description

Équivaut à l'opérateur moins unaire (-), mais renvoie NULL en cas de débordement.

SAFE_ADD

SAFE_ADD(X, Y)

Description

Équivaut à l'opérateur d'addition (+), mais renvoie NULL en cas de débordement.

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Description

Renvoie le résultat de Y soustrait de X. Équivaut à l'opérateur de soustraction (-), mais renvoie NULL en cas de débordement.

MOD

MOD(X, Y)

Description

Fonction modulo : renvoie le reste de la division de X par Y. La valeur renvoyée a le même signe que X. Une erreur est générée si Y est égal à 0. Pour découvrir les types de résultats possibles, consultez la section Types de résultats pour DIV(X, Y) et MOD(X, Y).

Types de résultats pour DIV(X, Y) et MOD(X, Y)

 FLOAT64INT64NUMERIC
FLOAT64FLOAT64ERREURFLOAT64
INT64FLOAT64INT64NUMERIC
NUMERICFLOAT64NUMERICNUMERIC

ROUND

ROUND(X [, N])

Description

Si seul X est présent, ROUND arrondit X au nombre entier le plus proche. Si N est présent, ROUND arrondit X à N décimales après la virgule. Si N est négatif, ROUND arrondit les chiffres à gauche de la virgule. Cette fonction arrondit les cas à mi-chemin à la valeur la plus éloignée de zéro. Cette fonction génère une erreur en cas de débordement.

TRUNC

TRUNC(X [, N])

Description

Si seul X est présent, TRUNC arrondit X au nombre entier le plus proche dont la valeur absolue n'est pas supérieure à celle de X. Si N est également présent, la fonction TRUNC se comporte comme ROUND(X, N), mais elle arrondit toujours en direction de zéro et ne déborde jamais.

CEIL

CEIL(X)

Description

Renvoie la plus petite valeur intégrale (avec le type FLOAT64) parmi celles qui ne sont pas inférieures à X.

CEILING

CEILING(X)

Description

Synonyme de CEIL(X)

FLOOR

FLOOR(X)

Description

Renvoie la plus grande valeur intégrale (avec le type FLOAT64) parmi celles qui ne sont pas supérieures à X.

Exemple de comportement de la fonction d'arrondi

Exemple de comportement des fonctions d'arrondi dans BigQuery :

Entrée "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)

Description

Calcule le cosinus de X où X est spécifié en radians. Cette fonction n'échoue jamais.

COSH

COSH(X)

Description

Calcule le cosinus hyperbolique de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

ACOS

ACOS(X)

Description

Calcule la valeur principale du cosinus inverse de X. La valeur renvoyée est comprise dans l'intervalle [0, π]. Cette fonction génère une erreur si X se situe en dehors de la plage [-1, 1].

ACOSH

ACOSH(X)

Description

Calcule le cosinus hyperbolique inverse de X. Cette fonction génère une erreur si X est une valeur inférieure à 1.

SIN

SIN(X)

Description

Calcule le sinus de X où X est spécifié en radians. Cette fonction n'échoue jamais.

SINH

SINH(X)

Description

Calcule le sinus hyperbolique de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

ASIN

ASIN(X)

Description

Calcule la valeur principale du sinus inverse de X. La valeur renvoyée se situe dans la plage [-π/2, π/2]. Cette fonction génère une erreur si X se situe en dehors de la plage [-1, 1].

ASINH

ASINH(X)

Description

Calcule le sinus hyperbolique inverse de X. Cette fonction n'échoue pas.

TAN

TAN(X)

Description

Calcule la tangente de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

TANH

TANH(X)

Description

Calcule la tangente hyperbolique de X où X est spécifié en radians. Cette fonction n'échoue pas.

ATAN

ATAN(X)

Description

Calcule la valeur principale de la tangente inverse de X. La valeur renvoyée se situe dans la plage [-π/2, π/2]. Cette fonction n'échoue pas.

ATANH

ATANH(X)

Description

Calcule la tangente hyperbolique inverse de X. Génère une erreur si X se situe en dehors de la plage [-1, 1].

ATAN2

ATAN2(Y, X)

Description

Calcule la valeur principale de la tangente inverse de Y/X en utilisant les signes des deux arguments pour déterminer le quadrant. La valeur renvoyée se situe dans la plage [-π,π].

Le comportement de cette fonction est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour ATAN2()

Y X ATAN2(Y, X)
NaN Toute valeur NaN
Toute valeur NaN NaN
0 0 0, π ou -π en fonction du signe de X et Y
Valeur finie -inf π ou -π en fonction du signe de Y
Valeur finie +inf 0
+/-inf Valeur finie π/2 ou -π/2 en fonction du signe de Y
+/-inf -inf ¾π ou -¾π en fonction du signe de Y
+/-inf +inf π/4 ou -π/4 en fonction du signe de Y

Cas particuliers pour les fonctions d'arrondi trigonométriques et hyperboliques

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)

Description

RANGE_BUCKET analyse un tableau trié et renvoie la position en base 0 de la limite supérieure du point. Cela peut être utile si vous devez regrouper vos données pour créer des partitions, des histogrammes, des règles définies par l'entreprise, etc.

RANGE_BUCKET respecte les règles suivantes :

  • Si le point existe dans le tableau, cette fonction renvoie l'index de la prochaine valeur la plus élevée.

    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
    
  • Si le point n'existe pas dans le tableau, mais qu'il se trouve entre deux valeurs, elle renvoie l'index de la valeur la plus élevée.

    RANGE_BUCKET(25, [0, 10, 20, 30, 40]) -- 3 is return value
    
  • Si le point est inférieur à la première valeur du tableau, la fonction renvoie 0.

    RANGE_BUCKET(-10, [5, 10, 20, 30, 40]) -- 0 is return value
    
  • Si le point est supérieur ou égal à la dernière valeur du tableau, la fonction renvoie la longueur du tableau.

    RANGE_BUCKET(80, [0, 10, 20, 30, 40]) -- 5 is return value
    
  • Si le tableau est vide, la fonction renvoie 0.

    RANGE_BUCKET(80, []) -- 0 is return value
    
  • Si le point est NULL ou NaN, elle renvoie NULL.

    RANGE_BUCKET(NULL, [0, 10, 20, 30, 40]) -- NULL is return value
    
  • Le type de données pour le point et le tableau doivent être compatibles.

    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
    

L'exécution échoue dans les cas suivants :

  • Le tableau contient une valeur NaN ou NULL.

    RANGE_BUCKET(80, [NULL, 10, 20, 30, 40]) -- execution failure
    
  • Le tableau n'est pas trié par ordre croissant.

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

Paramètres

  • point : une valeur générique.
  • boundaries_array : un tableau générique de valeurs.

Valeur renvoyée

INT64

Exemples

Dans une table nommée students, vérifiez le nombre d'enregistrements présents dans chaque ensemble age_group, en fonction de l'âge des élèves :

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