Regras de conversão no SQL padrão

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

  • Cast é conversão explícita e usa a função CAST().
  • Coerção é conversão implícita, realizada automaticamente pelo BigQuery nas condições descritas abaixo.
  • Há um terceiro grupo de funções de conversão que tem seus próprios nomes de função, 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 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)

Usa-se a sintaxe de cast em uma consulta para indicar que é preciso converter o tipo do resultado de uma expressão em algum outro tipo.

Exemplo:

CAST(x=1 AS STRING)

Isso resulta em "true" se x for 1, "false" para qualquer outro valor que não seja 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 ambiente 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 ambiente de execução.

Quando realizar o cast de uma expressão x dos tipos a seguir, essas regras se aplicam:

De Até 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 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 FLOAT64 literal válido.
Também aceita casts de "inf", "+inf", "-inf", e "nan".
As conversões não diferenciam maiúsculas de minúsculas.
STRING NUMERIC O literal numérico contido em STRING não pode 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 resultando NUMERIC 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 lançam 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 uma STRING UTF-8.
Por exemplo, o literal BYTES b'\xc2\xa9', quando convertido para STRING, é interpretado como UTF-8 e se torna o caractere unicode “©”.
Um erro ocorre se x não é um UTF-8 válido.
ARRAY ARRAY Precisa ser exatamente do mesmo tipo ARRAY.
STRUCT STRUCT Permitido, se as condições a seguir 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 você estiver fazendo o cast de bytes para strings, também poderá usar a função SAFE_CONVERT_BYTES_TO_STRING. Todos os caracteres UTF-8 inválidos são substituídos pelo caractere de substituição unicode, U+FFFD. Consulte SAFE_CONVERT_BYTES_TO_STRING para mais informações.

Cast de strings hexadecimais em inteiros

Se não estiver trabalhando com strings hex (0x123), faça o cast dessas strings como inteiras:

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 maneira a seguir:

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 aceito, ocorrerá um erro.

Cast de tipos de carimbo de data/hora

O BigQuery é compatível com o cast de tipos de carimbo de data/hora para/de strings da maneira a seguir:

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

No cast de tipos de carimbo de data/hora para string, o carimbo é interpretado com o fuso horário padrão, que é o UTC. 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 carimbo de data/horastring_expression precisa seguir os formatos compatíveis de literal do carimbo de data/hora. Caso contrário, ocorrerá um erro no ambiente de execução. O próprio string_expression pode conter os time_zone. Consulte fusos horários. Se houver um fuso horário no string_expression, ele será usado para conversão. Caso contrário, será usado o fuso horário padrão, UTC. Se a string tiver menos de seis dígitos, ela será ampliada implicitamente.

Um erro será produzido se string_expression for inválido, tiver mais de seis dígitos de subsegundos (isto é, precisão maior que microssegundos) ou representar um horário fora do intervalo aceito do carimbo de data/hora.

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 carimbo de data/hora para uma data trunca efetivamente o carimbo de data/hora 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 e, em seguida, a expressão func("2014-09-27") for válida porque o literal STRING "2014-09-27" for 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: