Conversion functions

GoogleSQL for Bigtable supports conversion functions. These data type conversions are explicit, but some conversions can happen implicitly. You can learn more about implicit and explicit conversion here.

Function list

Name	Summary
CAST	Convert the results of an expression to the given type.
SAFE_CAST	Similar to the CAST function, but returns NULL when a runtime error is produced.

CAST

CAST(expression AS typename)

Description

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

When using CAST, a query can fail if GoogleSQL is unable to perform the cast. If you want to protect your queries from these types of errors, you can use SAFE_CAST.

Casts between supported types that do not successfully map from the original value to the target domain produce runtime errors. For example, casting BYTES to STRING where the byte sequence is not valid UTF-8 results in a runtime error.

Examples

The following query results in "true" if x is 1, "false" for any other non-NULL value, and NULL if x is NULL.

CAST(x=1 AS STRING)

CAST AS ARRAY

CAST(expression AS ARRAY<element_type>)

Description

GoogleSQL supports casting to ARRAY. The expression parameter can represent an expression for these data types:

• ARRAY

Conversion rules

From	To	Rule(s) when casting x
ARRAY	ARRAY	Must be the exact same array type.

CAST AS BOOL

CAST(expression AS BOOL)

Description

GoogleSQL supports casting to BOOL. The expression parameter can represent an expression for these data types:

• INT64
• BOOL
• STRING

Conversion rules

From	To	Rule(s) when casting x
INT64	BOOL	Returns FALSE if x is 0, TRUE otherwise.
STRING	BOOL	Returns TRUE if x is "true" and FALSE if x is "false" All other values of x are invalid and throw an error instead of casting to a boolean. A string is case-insensitive when converting to a boolean.

CAST AS BYTES

CAST(expression AS BYTES)

Description

GoogleSQL supports casting to BYTES. The expression parameter can represent an expression for these data types:

• BYTES
• STRING

Conversion rules

From	To	Rule(s) when casting x
STRING	BYTES	Strings are cast to bytes using UTF-8 encoding. For example, the string "©", when cast to bytes, would become a 2-byte sequence with the hex values C2 and A9.

CAST AS DATE

CAST(expression AS DATE)

Description

GoogleSQL supports casting to DATE. The expression parameter can represent an expression for these data types:

• STRING
• TIMESTAMP

Conversion rules

From	To	Rule(s) when casting x
STRING	DATE	When casting from string to date, the string must conform to the supported date literal format, and is independent of time zone. If the string expression is invalid or represents a date that is outside of the supported min/max range, then an error is produced.
TIMESTAMP	DATE	Casting from a timestamp to date effectively truncates the timestamp as of the default time zone.

CAST AS FLOAT64

CAST(expression AS FLOAT64)

CAST(expression AS FLOAT32)

Description

GoogleSQL supports casting to floating point types. The expression parameter can represent an expression for these data types:

• INT64
• FLOAT32
• FLOAT64
• STRING

Conversion rules

From	To	Rule(s) when casting x
INT64	FLOAT64	Returns a close but potentially not exact floating point value.
STRING	FLOAT64	Returns x as a floating point value, interpreting it as having the same form as a valid floating point literal. Also supports casts from "[+,-]inf" to [,-]Infinity, "[+,-]infinity" to [,-]Infinity, and "[+,-]nan" to NaN. Conversions are case-insensitive.

CAST AS INT64

CAST(expression AS INT64)

Description

GoogleSQL supports casting to integer types. The expression parameter can represent an expression for these data types:

• INT64
• FLOAT32
• FLOAT64
• ENUM
• BOOL
• STRING

Conversion rules

From	To	Rule(s) when casting x
FLOAT64	INT64	Returns the closest integer value. Halfway cases such as 1.5 or -0.5 round away from zero.
BOOL	INT64	Returns 1 if x is TRUE, 0 otherwise.
STRING	INT64	A hex string can be cast to an integer. For example, 0x123 to 291 or -0x123 to -291.

Examples

If you are working with hex strings (0x123), you can cast those strings as integers:

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 AS MAP

CAST(expression AS MAP)

Description

GoogleSQL supports casting to MAP. The expression parameter can represent an expression for these data types:

• MAP

Conversion rules

From	To	Rule(s) when casting x
MAP	MAP	The key-value types of the input map must be castable to the key-value types of the target map. For example, casting from type MAP<STRING,INT64> to MAP<STRING,FLOAT64> or MAP<STRING,STRING> is valid; casting from type MAP<STRING,INT64> to MAP<STRING,BYTES> is not valid.

Examples

SELECT
  CAST(input_map AS MAP<BYTES, INT64>) AS results
FROM
  MAP_FROM_ARRAY([('x', 1), ('y', 2), ('z', 3)]) AS input_map;

/*-----------------------------*
 | results                     |
 +-----------------------------+
 | {b'x': 1, b'y': 2, b'z': 3} |
 *-----------------------------*/

SELECT
  CAST(input_map AS MAP<STRING, STRING>) AS results
FROM
  MAP_FROM_ARRAY([(b'x', b'\x41'), (b'y', b'\x42')]) AS input_map;

/*----------------------------*
 | results                    |
 +----------------------------+
 | {"x": "\x41", "y": "\x42"} |
 *----------------------------*/

CAST AS STRING

CAST(expression AS STRING)

Description

GoogleSQL supports casting to STRING. The expression parameter can represent an expression for these data types:

• INT64
• FLOAT32
• FLOAT64
• ENUM
• BOOL
• BYTES
• DATE
• TIMESTAMP
• STRING

Conversion rules

From	To	Rule(s) when casting x
FLOAT64	STRING	Returns an approximate string representation. A returned NaN or 0 will not be signed.
BOOL	STRING	Returns "true" if x is TRUE, "false" otherwise.
BYTES	STRING	Returns x interpreted as a UTF-8 string. For example, the bytes literal b'\xc2\xa9', when cast to a string, is interpreted as UTF-8 and becomes the unicode character "©". An error occurs if x is not valid UTF-8.
ENUM	STRING	Returns the canonical enum value name of x. If an enum value has multiple names (aliases), the canonical name/alias for that value is used.
DATE	STRING	Casting from a date type to a string is independent of time zone and is of the form YYYY-MM-DD.
TIMESTAMP	STRING	When casting from timestamp types to string, the timestamp is interpreted using the default time zone, UTC. The number of subsecond digits produced depends on the number of trailing zeroes in the subsecond part: the CAST function will truncate zero, three, or six digits.

Examples

SELECT CAST(CURRENT_DATE() AS STRING) AS current_date

/*---------------*
 | current_date  |
 +---------------+
 | 2021-03-09    |
 *---------------*/

CAST AS TIMESTAMP

CAST(expression AS TIMESTAMP)

Description

GoogleSQL supports casting to TIMESTAMP. The expression parameter can represent an expression for these data types:

• STRING
• TIMESTAMP

Conversion rules

From	To	Rule(s) when casting x
STRING	TIMESTAMP	When casting from string to a timestamp, string_expression must conform to the supported timestamp literal formats, or else a runtime error occurs. The string_expression may itself contain a time zone. If there is a time zone in the string_expression, that time zone is used for conversion, otherwise the default time zone, UTC, is used. If the string has fewer than six digits, then it is implicitly widened. An error is produced if the string_expression is invalid, has more than six subsecond digits (i.e., precision greater than microseconds), or represents a time outside of the supported timestamp range.
DATE	TIMESTAMP	Casting from a date to a timestamp interprets date_expression as of midnight (start of the day) in the default time zone, UTC.

Examples

The following example casts a string-formatted timestamp as a timestamp:

SELECT CAST("2020-06-02 17:00:53.110+00:00" AS TIMESTAMP) AS as_timestamp

-- Results depend upon where this query was executed.
/*-----------------------------*
 | as_timestamp                |
 +-----------------------------+
 | 2020-06-03 00:00:53.110 UTC |
 *-----------------------------*/

SAFE_CAST

SAFE_CAST(expression AS typename)

Description

When using CAST, a query can fail if GoogleSQL is unable to perform the cast. For example, the following query generates an error:

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

If you want to protect your queries from these types of errors, you can use SAFE_CAST. SAFE_CAST replaces runtime errors with NULLs. However, during static analysis, impossible casts between two non-castable types still produce an error because the query is invalid.

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

/*--------------*
 | not_a_number |
 +--------------+
 | NULL         |
 *--------------*/

If you are casting from bytes to strings, you can also use the function, SAFE_CONVERT_BYTES_TO_STRING. Any invalid UTF-8 characters are replaced with the unicode replacement character, U+FFFD.

Other conversion functions

You can learn more about these conversion functions elsewhere in the documentation:

Conversion function	From	To
ARRAY_TO_STRING	ARRAY	STRING
BIT_CAST_TO_INT64	UINT64	INT64
DATE	Various data types	DATE
DATE_FROM_UNIX_DATE	INT64	DATE
FROM_BASE32	STRING	BYTEs
FROM_BASE64	STRING	BYTES
FROM_HEX	STRING	BYTES
PARSE_DATE	STRING	DATE
PARSE_TIMESTAMP	STRING	TIMESTAMP
SAFE_CONVERT_BYTES_TO_STRING	BYTES	STRING
STRING	TIMESTAMP	STRING
TIMESTAMP	Various data types	TIMESTAMP
TIMESTAMP_FROM_UNIX_MICROS	INT64	TIMESTAMP
TIMESTAMP_FROM_UNIX_MILLIS	INT64	TIMESTAMP
TIMESTAMP_FROM_UNIX_SECONDS	INT64	TIMESTAMP
TIMESTAMP_MICROS	INT64	TIMESTAMP
TIMESTAMP_MILLIS	INT64	TIMESTAMP
TIMESTAMP_SECONDS	INT64	TIMESTAMP
TO_BASE32	BYTES	STRING
TO_BASE64	BYTES	STRING
TO_HEX	BYTES	STRING
TO_INT64	BYTES	INT64
TO_VECTOR32	BYTES	ARRAY<FLOAT32>
TO_VECTOR64	BYTES	ARRAY<FLOAT64>
TO_JSON_STRING	All data types	STRING