Regras de conversão no SQL padrão

A "conversão" inclui, entre outros tipos, cast e coerção.

  • "Cast" é a conversão explícita e usa a função CAST().
  • "Coerção" é a conversão implícita realizada automaticamente pelo BigQuery nas condições descritas abaixo.
  • Há um terceiro grupo de funções de conversão com seus próprios nomes, como UNIX_DATE() .

A tabela a seguir resume todas as possibilidades de CAST e coerção dos tipos de dados do BigQuery. A coluna "Coerção para" aplica todas as expressões de um determinado tipo de dados (como uma coluna), mas literais e parâmetros também podem ser forçados. Consulte Coerção de literal e Coerção de parâmetro para ver mais detalhes.

Do tipo CAST para Coerção para
INT64 BOOL
INT64
NUMERIC
FLOAT64
STRING
FLOAT64
NUMERIC
NUMERIC INT64
NUMERIC
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
NUMERIC
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
NUMERIC
FLOAT64
STRING
BYTES
DATE
DATETIME
TIME
TIMESTAMP
 
BYTES BYTES
STRING
 
DATE DATE
DATETIME
STRING
TIMESTAMP
 
DATETIME DATE
DATETIME
STRING
TIME
TIMESTAMP
 
TIME STRING
TIME
 
TIMESTAMP DATE
DATETIME
STRING
TIME
TIMESTAMP
 
ARRAY ARRAY  
STRUCT STRUCT  

Cast

Sintaxe:

CAST(expr AS typename)

Cast syntax is used in a query to indicate that the result type of an expression should be converted to some other type.

Exemplo:

CAST(x=1 AS STRING)

O resultado será "true" se x for 1, "false" para outro valor não NULL e NULL se x for NULL.

Os casts entre tipos compatíveis que não são mapeados com sucesso do valor original para o domínio de destino produzem erros de tempo de execução. Por exemplo, o cast de BYTES para STRING em que a sequência de bytes não é um UTF-8 válido resulta em um erro de tempo de execução.

Quando é feito o cast de uma expressão x dos tipos a seguir, estas regras são aplicadas:

De Para Regras ao fazer o cast x
INT64 FLOAT64 Retorna um valor aproximado de FLOAT64, mas potencialmente inexato.
INT64 BOOL Retorna FALSE, se x for 0. Caso contrário, retorna TRUE.
NUMERIC Ponto flutuante NUMERIC será convertido no número de ponto flutuante mais próximo com uma possível perda de precisão.
FLOAT64 INT64 Retorna o valor mais próximo de INT64.
Casos em que haja metades, como 1,5 ou -0,5, são arredondados para longe de zero.
FLOAT64 STRING Retorna uma representação de string aproximada.
FLOAT64 NUMERIC Se o número de ponto flutuante tiver mais de nove dígitos depois do ponto decimal, ele será arredondado para metade de zero. Fazer cast de um NaN, +inf ou -inf retornará um erro. Fazer cast de um valor fora do intervalo de NUMERIC retornará um erro de estouro.
BOOL INT64 Retorna 1, se x for TRUE. Caso contrário, retorna 0.
BOOL STRING Retorna "true", se x for TRUE. Caso contrário, retorna "false".
STRING FLOAT64 Retorna x como um valor de FLOAT64, interpretando-o como tendo a mesma forma de um literal FLOAT64 válido.
Também é compatível com casts de "inf", "+inf", "-inf" e "nan".
As conversões são indiferentes a minúsculas.
STRING NUMERIC O literal numérico contido no STRING não precisa exceder a precisão máxima ou o intervalo do tipo NUMERIC, ou ocorrerá um erro. Se o número de dígitos depois do ponto decimal exceder nove, o valor NUMERIC resultante será arredondado para metade de zero para ter nove dígitos depois do ponto decimal.
STRING BOOL Retorna TRUE, se x for "true", e FALSE, se x for "false"
Todos os outros valores de x são inválidos e geram um erro em vez de fazer o cast para BOOL.
As STRINGs não diferenciam maiúsculas de minúsculas durante a conversão para BOOL.
STRING BYTES As STRINGs são convertidas em BYTES usando a codificação UTF-8. Por exemplo, a STRING "©", quando convertida em BYTES, torna-se uma sequência de dois bytes com os valores hexadecimais C2 e A9.
BYTES STRING Retorna x, interpretado como STRING UTF-8.
Por exemplo, o literal BYTES b'\xc2\xa9', quando convertido em STRING, é interpretado como UTF-8 e se torna o caractere unicode "©".
Ocorrerá um erro, se x não for um UTF-8 válido.
ARRAY ARRAY Precisa ser exatamente do mesmo tipo ARRAY.
STRUCT STRUCT Permitido, se as seguintes condições forem atendidas:
  1. Os dois STRUCTs têm o mesmo número de campos.
  2. Os tipos originais de campos STRUCT são convertidos explicitamente para os tipos de campos de destino STRUCT correspondentes (definidos pela ordem e não pelo nome do campo).

Cast seguro

Quando CAST é usado, pode ocorrer falha na consulta se o BigQuery não conseguir executar o cast. Por exemplo, a consulta a seguir gera um erro:

SELECT CAST("apple" AS INT64) AS not_a_number;

Caso queira proteger as consultas contra esses tipos de erros, use SAFE_CAST. SAFE_CAST é idêntico a CAST, exceto que retorna NULL em vez de gerar um erro.

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

Se estiver fazendo o cast de bytes em strings, você também poderá usar a função SAFE_CONVERT_BYTES_TO_STRING. Todo caractere UTF-8 inválido é substituído pelo caractere unicode U+FFFD. Consulte SAFE_CONVERT_BYTES_TO_STRING para mais informações.

Cast de strings hexadecimais em inteiros

No caso das strings hexadecimais (0x123), faça o cast delas como números inteiros:

SELECT '0x123' as hex_value, CAST('0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | 291        |
+-----------+------------+

SELECT '0x123' as hex_value, CAST('-0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | -291       |
+-----------+------------+

Cast de tipos de data

O BigQuery é compatível com o cast de tipos de data para/de strings da seguinte maneira:

CAST(date_expression AS STRING)
CAST(string_expression AS DATE)

O cast de um tipo de data para uma string segue o formato YYYY-MM-DD, independentemente do fuso horário. No caso do cast da string para a data, a string precisa seguir o formato literal da data compatível, independentemente do fuso horário. Se a expressão da string for inválida ou representar uma data fora do intervalo mínimo/máximo compatível, ocorrerá um erro.

Cast de tipos de carimbo de data/hora

O BigQuery é compatível com o cast de tipos de timestamp para/de strings da seguinte maneira:

CAST(timestamp_expression AS STRING)
CAST(string_expression AS TIMESTAMP)

No cast de tipos de timestamp para string, o timestamp é interpretado com o fuso horário UTC padrão. O número de dígitos de subsegundos produzidos depende do número de zeros à direita na parte de subsegundo. A função CAST truncará nenhum, três ou seis dígitos.

No cast de string para timestamp, string_expression precisa seguir os formatos compatíveis com literal de timestamp. Caso contrário, ocorrerá um erro de tempo de execução. O próprio string_expression pode conter um time_zone. Consulte fusos horários. Se houver um fuso horário em string_expression, ele será usado para a conversão. Caso contrário, o fuso horário UTC padrão será usado. Se a string tiver menos de seis dígitos, ela será ampliada implicitamente.

Ocorrerá um erro se string_expression for inválido, tiver mais de seis dígitos de subsegundos (isto é, se a precisão for maior que microssegundos) ou representar uma hora fora do intervalo do carimbo de data/hora compatível.

Cast entre tipos de data e carimbo de data/hora

O BigQuery é compatível com cast entre tipos de data e timestamp da seguinte maneira:

CAST(date_expression AS TIMESTAMP)
CAST(timestamp_expression AS DATE)

O cast de uma data para um timestamp interpreta date_expression a partir da meia-noite (início do dia) no fuso horário UTC padrão. O cast de um timestamp para uma data trunca efetivamente o timestamp a partir do fuso horário padrão.

Coerção

Se necessário, o BigQuery força o tipo de resultado de uma expressão para outro tipo, para corresponder às assinaturas da função. Por exemplo, se a função func() for definida para ter um único argumento do tipo INT64 e uma expressão for usada como um argumento que tenha um tipo de resultado FLOAT64, então o resultado da expressão será forçado para o tipo INT64 antes de func() ser calculado.

Coerção de literal

O BigQuery é compatível com as seguintes coerções de literal:

Tipo de dados de entrada Tipo de dados de resultado Notas
Literal STRING DATE
TIMESTAMP

A coerção de literal é necessária quando o tipo de literal real é diferente do tipo esperado pela função em questão. Por exemplo, se a função func() tiver um argumento DATE, a expressão func("2014-09-27") será válida porque o literal STRING "2014-09-27" é forçado para DATE.

A conversão de literal é avaliada no momento da análise. Se o literal da entrada não for convertido com sucesso para o tipo de destino, ocorrerá um erro.

Observação: os literais de string não são forçados para tipos numéricos.

Coerção de parâmetro

O BigQuery é compatível com as seguintes coerções de parâmetro:

Tipo de dados de entrada Tipo de dados de resultado
Parâmetro STRING

Se o valor do parâmetro não puder ser forçado com sucesso para o tipo de destino, ocorrerá um erro.

Funções de conversão adicionais

O BigQuery oferece as seguintes funções adicionais de conversão:

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.