Funções matemáticas no SQL padrão

Todas as funções matemáticas têm os seguintes comportamentos:

  • Elas retornam NULL se algum dos parâmetros de entrada for NULL.
  • Elas retornam NaN se algum dos argumentos for NaN.

ABS

ABS(X)

Descrição

Calcula o valor absoluto. Retornará um erro caso o argumento seja um número inteiro e o valor de saída não possa ser representado como o mesmo tipo. Isso acontece apenas com o maior valor negativo da entrada, sem representação positiva. Retorna +inf para um argumento +/-inf.

SIGN

SIGN(X)

Descrição

Retorna -1, 0 ou +1 para argumentos negativo, zero e positivo, respectivamente. Para argumentos de ponto flutuante, essa função não faz distinção entre zero positivo e negativo. Retorna NaN para um argumento NaN.

IS_INF

IS_INF(X)

Descrição

Retornará TRUE se o valor for um infinito positivo ou negativo. Retorna NULL para entradas NULL.

IS_NAN

IS_NAN(X)

Descrição

Retorna TRUE se o valor for NaN. Retorna NULL para entradas NULL.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Descrição

Divide X por Y e nunca falha. Ela retorna FLOAT64. Ao contrário do operador de divisão (/), não gera erros de divisão por zero ou estouro.

Casos especiais:

  • Se o resultado estourar, retorna +/-inf.
  • Se Y=0 e X=0, retorna NaN.
  • Se Y=0 e X!=0, retorna +/-inf.
  • Se X=+/-inf e Y=+/-inf, retorna NaN.

O comportamento de IEEE_DIVIDE é ilustrado com mais detalhes na tabela abaixo.

Casos especiais de IEEE_DIVIDE

A tabela a seguir lista os casos especiais de IEEE_DIVIDE.

Tipos de dados do numerador (X) Tipos de dados do denominador (Y) Valor do resultado
Qualquer um, exceto 0 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

RAND

RAND()

Descrição

Gera um valor pseudoaleatório do tipo FLOAT64 no intervalo de [0, 1), incluindo 0 e excluindo 1.

SQRT

SQRT(X)

Descrição

Calcula a raiz quadrada de X. Gera um erro se X for menor que 0. Retorna +inf se X for +inf.

POW

POW(X, Y)

Descrição

Retorna o valor de X elevado à potência de Y. Se o resultado estourar e não for representável, a função retornará um valor zero. Retornará um erro se uma das seguintes condições for verdadeira:

  • X é um valor finito menor que 0, e Y é um número não inteiro.
  • X é 0, e Y é um valor finito menor que 0

O comportamento de POW() é ilustrado com mais detalhes na tabela abaixo.

POWER

POWER(X, Y)

Descrição

Sinônimo de POW().

Casos especiais para POW(X, Y) e POWER(X, Y)

Veja a seguir casos especiais para POW(X, Y) e POWER(X, Y).

X Y POW(X, Y) ou POWER(X, Y)
1,0 Qualquer valor, incluindo NaN 1,0
qualquer um, incluindo 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 se Y for um número inteiro ímpar, +inf caso contrário
+inf Y < 0 0
+inf Y > 0 +inf

EXP

EXP(X)

Descrição

Calcula e à potência de X, também chamada de função exponencial natural. Se ocorrer um estouro negativo, essa função retornará zero. Um erro será gerado se o resultado estourar. Se X for +/-inf, essa função retorna +inf ou 0.

LN

LN(X)

Descrição

Calcula o logaritmo natural de X. Um erro será gerado se X for menor ou igual a zero. Se X for +inf, essa função retorna +inf.

LOG

LOG(X [, Y])

Descrição

Se apenas X estiver presente, LOG será um sinônimo de LN. Se Y também estiver presente, LOG calculará o logaritmo de X na base Y. A função gera um erro nos seguintes casos:

  • X é menor ou igual a zero
  • Y é 1,0
  • Y é menor ou igual a zero.

O comportamento de LOG(X, Y) é ilustrado com mais detalhes na tabela abaixo.

Casos especiais de LOG(X, Y)

X Y LOG(X, Y)
-inf Qualquer valor NaN
Qualquer valor +inf NaN
+inf 0,0 Y < 1,0 -inf
+inf Y > 1,0 +inf

LOG10

LOG10(X)

Descrição

Semelhante a LOG, mas calcula o logaritmo de base 10.

GREATEST

GREATEST(X1,...,XN)

Descrição

Retorna NULL se alguma das entradas for NULL. Caso contrário, retorna NaN se alguma das entradas for NaN. Caso contrário, retorna o maior valor entre X1,…, XN de acordo com a comparação.

LEAST

LEAST(X1,...,XN)

Descrição

Retorna NULL se alguma das entradas for NULL. Retorna NaN se alguma das entradas for NaN. Caso contrário, retorna o menor valor entre X1,…, XN de acordo com a comparação.

DIV

DIV(X, Y)

Descrição

Retorna o resultado da divisão de inteiros de X por Y. Divisão por zero retorna um erro. Divisão por -1 pode estourar. Consulte a tabela abaixo para ver possíveis tipos de resultados.

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Descrição

Equivalente ao operador de divisão (/), mas retorna NULL se ocorrer um erro como o de divisão por zero.

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Descrição

Equivalente ao operador de multiplicação (*), mas retorna NULL se ocorrer um estouro.

SAFE_NEGATE

SAFE_NEGATE(X)

Descrição

Equivalente ao operador de menos unário (-), mas retorna NULL se ocorrer um estouro.

SAFE_ADD

SAFE_ADD(X, Y)

Descrição

Equivalente ao operador de adição (+), mas retorna NULL se ocorrer um estouro.

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Descrição

Equivalente ao operador de subtração (-), mas retorna NULL se ocorrer um estouro.

MOD

MOD(X, Y)

Descrição

Função módulo: retorna o restante da divisão de X por Y. O valor retornado tem o mesmo sinal que X. Um erro será gerado se Y for 0. Consulte a tabela abaixo para ver possíveis tipos de resultados.

ROUND

ROUND(X [, N])

Descrição

Se apenas X estiver presente, ROUND arredondará X para o inteiro mais próximo. Se N estiver presente, ROUND arredondará X para N casas decimais após a vírgula decimal. Se N for negativo, ROUND arredondará os dígitos à esquerda da vírgula decimal. Casos em que haja metades são arredondados para longe de zero. Se ocorrer um estouro, será gerado um erro.

TRUNC

TRUNC(X [, N])

Descrição

Se apenas X estiver presente, TRUNC arredondará X para o inteiro mais próximo cujo valor absoluto não seja maior que o valor absoluto de X. Se N também estiver presente, TRUNC se comportará como ROUND(X, N), mas sempre arredondará para zero e nunca haverá estouro.

CEIL

CEIL(X)

Descrição

Retorna o menor valor integral (com o tipo FLOAT64) que não é inferior a X.

CEILING

CEILING(X)

Descrição

Sinônimo de CEIL(X)

FLOOR

FLOOR(X)

Descrição

Retorna o maior valor integral (com o tipo FLOAT64) que não é superior a X.

Exemplo de comportamento da função de arredondamento

Exemplo de comportamento de funções de arredondamento do BigQuery:

Entrada "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)

Descrição

Calcula o cosseno de X onde X é especificado em radianos. Nunca falha.

COSH

COSH(X)

Descrição

Calcula o cosseno hiperbólico de X onde X é especificado em radianos. Gera um erro se ocorrer um estouro.

ACOS

ACOS(X)

Descrição

Calcula o valor principal do cosseno inverso de X. O valor retornado está no intervalo [0,π]. Um erro será gerado se X for um valor fora do intervalo [-1, 1].

ACOSH

ACOSH(X)

Descrição

Calcula o cosseno hiperbólico inverso de X. Se X for um valor menor que 1, gera um erro.

SIN

SIN(X)

Descrição

Calcula o seno de X onde X é especificado em radianos. Nunca falha.

SINH

SINH(X)

Descrição

Calcula o seno hiperbólico de X, onde X é especificado em radianos. Gera um erro se ocorrer um estouro.

ASIN

ASIN(X)

Descrição

Calcula o valor principal do seno inverso de X. O valor retornado está no intervalo [-π/2, π/2]. Um erro será gerado se X estiver fora do intervalo [-1, 1].

ASINH

ASINH(X)

Descrição

Calcula o seno hiperbólico inverso de X. Não falha.

TAN

TAN(X)

Descrição

Calcula a tangente de X onde X é especificado em radianos. Gera um erro se ocorrer um estouro.

TANH

TANH(X)

Descrição

Calcula a tangente hiperbólica de X, onde X é especificado em radianos. Não falha.

ATAN

ATAN(X)

Descrição

Calcula o valor principal da tangente inversa de X. O valor retornado está no intervalo [-π/2, π/2]. Não falha.

ATANH

ATANH(X)

Descrição

Calcula a tangente hiperbólica inversa de X. Gera um erro se X estiver fora do intervalo [-1, 1].

ATAN2

ATAN2(Y, X)

Descrição

Calcula o valor principal da tangente inversa de Y/X usando os sinais dos dois argumentos para determinar o quadrante. O valor de retorno está no intervalo [-π, π]. O comportamento dessa função é ilustrado com mais detalhes na tabela abaixo.

Casos especiais de ATAN2()

S X ATAN2(Y, X)
NaN Qualquer valor NaN
Qualquer valor NaN NaN
0 0 0, π ou -π, dependendo do sinal de X e Y
Valor finito -inf π ou -π, dependendo do sinal de Y
Valor finito +inf 0
+/-inf Valor finito π/2 ou π/2, dependendo do sinal de Y
+/-inf -inf ¾π ou -¾π, dependendo do sinal de Y
+/-inf +inf π/4 ou -π/4, dependendo do sinal de Y

Casos especiais de funções trigonométricas e hiperbólicas de arredondamento

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)

Descrição

RANGE_BUCKET verifica uma matriz classificada e retorna a posição 0 do limite superior do ponto. Isso pode ser útil se você precisar agrupar seus dados para criar partições, histogramas, regras definidas pelo negócio e muito mais.

RANGE_BUCKET segue as seguintes regras:

  • Se o ponto existir na matriz, o índice do próximo valor maior será retornado.

    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
    
  • Se o ponto não existir na matriz, mas ficar entre dois valores, o índice do valor maior será retornado.

    RANGE_BUCKET(25, [0, 10, 20, 30, 40]) -- 3 is return value
    
  • Se o ponto for menor que o primeiro valor na matriz, será retornado 0.

    RANGE_BUCKET(-10, [5, 10, 20, 30, 40]) -- 0 is return value
    
  • Se o ponto for maior ou igual ao último valor na matriz, o comprimento da matriz será retornado.

    RANGE_BUCKET(80, [0, 10, 20, 30, 40]) -- 5 is return value
    
  • Se a matriz estiver vazia, será retornado 0.

    RANGE_BUCKET(80, []) -- 0 is return value
    
  • Se o ponto for NULL ou NaN, será retornado NULL.

    RANGE_BUCKET(NULL, [0, 10, 20, 30, 40]) -- NULL is return value
    
  • O tipo de dados do ponto e da matriz deve ser compatível.

    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
    

A falha na execução ocorre quando:

  • A matriz tem um valor NaN ou NULL.

    RANGE_BUCKET(80, [NULL, 10, 20, 30, 40]) -- execution failure
    
  • A matriz não é classificada em ordem crescente.

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

Parâmetros

  • point: um valor genérico.
  • boundaries_array: uma matriz genérica de valores.

Valor de retorno

INT64

Exemplos

Em uma tabela chamada students, verifique quantos registros existiriam em cada intervalo de age_group, com base na idade de um aluno:

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