Conversion functions in GoogleSQL

GoogleSQL for Spanner 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
`ARRAY_TO_STRING`	Produces a concatenation of the elements in an array as a `STRING` value. For more information, see Array functions .
`BOOL`	Converts a JSON boolean to a SQL `BOOL` value. For more information, see JSON functions .
`BOOL_ARRAY`	Converts a JSON array of booleans to a SQL `ARRAY<BOOL>` value. For more information, see JSON functions .
`CAST`	Convert the results of an expression to the given type.
`CODE_POINTS_TO_BYTES`	Converts an array of extended ASCII code points to a `BYTES` value. For more information, see String aggregate functions .
`CODE_POINTS_TO_STRING`	Converts an array of extended ASCII code points to a `STRING` value. For more information, see String aggregate functions .
`DATE_FROM_UNIX_DATE`	Interprets an `INT64` expression as the number of days since 1970-01-01. For more information, see Date functions .
`FROM_BASE32`	Converts a base32-encoded `STRING` value into a `BYTES` value. For more information, see String functions .
`FROM_BASE64`	Converts a base64-encoded `STRING` value into a `BYTES` value. For more information, see String functions .
`FROM_HEX`	Converts a hexadecimal-encoded `STRING` value into a `BYTES` value. For more information, see String functions .
`INT64`	Converts a JSON number to a SQL `INT64` value. For more information, see JSON functions .
`INT64_ARRAY`	Converts a JSON array of numbers to a SQL `ARRAY<INT64>` value. For more information, see JSON functions .
`LAX_BOOL`	Attempts to convert a JSON value to a SQL `BOOL` value. For more information, see JSON functions .
`LAX_FLOAT64`	Attempts to convert a JSON value to a SQL `FLOAT64` value. For more information, see JSON functions .
`LAX_INT64`	Attempts to convert a JSON value to a SQL `INT64` value. For more information, see JSON functions .
`LAX_STRING`	Attempts to convert a JSON value to a SQL `STRING` value. For more information, see JSON functions .
`PARSE_DATE`	Converts a `STRING` value to a `DATE` value. For more information, see Date functions .
`PARSE_JSON`	Converts a JSON-formatted `STRING` value to a `JSON` value. For more information, see JSON functions .
`PARSE_TIMESTAMP`	Converts a `STRING` value to a `TIMESTAMP` value. For more information, see Timestamp functions .
`SAFE_CAST`	Similar to the `CAST` function, but returns `NULL` when a runtime error is produced.
`SAFE_CONVERT_BYTES_TO_STRING`	Converts a `BYTES` value to a `STRING` value and replace any invalid UTF-8 characters with the Unicode replacement character, `U+FFFD` . For more information, see String functions .
`STRING` (JSON)	Converts a JSON string to a SQL `STRING` value. For more information, see JSON functions .
`STRING_ARRAY`	Converts a JSON array of strings to a SQL `ARRAY<STRING>` value. For more information, see JSON functions .
`STRING` (Timestamp)	Converts a `TIMESTAMP` value to a `STRING` value. For more information, see Timestamp functions .
`TIMESTAMP_MICROS`	Converts the number of microseconds since 1970-01-01 00:00:00 UTC to a `TIMESTAMP` . For more information, see Timestamp functions .
`TIMESTAMP_MILLIS`	Converts the number of milliseconds since 1970-01-01 00:00:00 UTC to a `TIMESTAMP` . For more information, see Timestamp functions .
`TIMESTAMP_SECONDS`	Converts the number of seconds since 1970-01-01 00:00:00 UTC to a `TIMESTAMP` . For more information, see Timestamp functions .
`TO_BASE32`	Converts a `BYTES` value to a base32-encoded `STRING` value. For more information, see String functions .
`TO_BASE64`	Converts a `BYTES` value to a base64-encoded `STRING` value. For more information, see String functions .
`TO_CODE_POINTS`	Converts a `STRING` or `BYTES` value into an array of extended ASCII code points. For more information, see String functions .
`TO_HEX`	Converts a `BYTES` value to a hexadecimal `STRING` value. For more information, see String functions .
`TO_JSON`	Converts a SQL value to a JSON value. For more information, see JSON functions .
`TO_JSON_STRING`	Converts a `JSON` value to a SQL JSON-formatted `STRING` value. For more information, see JSON functions .
`UNIX_DATE`	Converts a `DATE` value to the number of days since 1970-01-01. For more information, see Date functions .
`UNIX_MICROS`	Converts a `TIMESTAMP` value to the number of microseconds since 1970-01-01 00:00:00 UTC. For more information, see Timestamp functions .
`UNIX_MILLIS`	Converts a `TIMESTAMP` value to the number of milliseconds since 1970-01-01 00:00:00 UTC. For more information, see Timestamp functions .
`UNIX_SECONDS`	Converts a `TIMESTAMP` value to the number of seconds since 1970-01-01 00:00:00 UTC. For more information, see Timestamp functions .

`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 don't successfully map from the original value to the target domain produce runtime errors. For example, casting BYTES to STRING where the byte sequence isn't 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
PROTO

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.
`PROTO`	`BYTES`	Returns the proto2 wire format bytes of `x` .

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's 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 ENUM

  CAST 
 ( 
 expression 
  
 AS 
  
 ENUM 
 )

Description

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

INT64
STRING
ENUM

Conversion rules

From	To	Rule(s) when casting `x`
`ENUM`	`ENUM`	Must have the same enum name.

CAST AS Floating Point

  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
NUMERIC
STRING

Conversion rules

From	To	Rule(s) when casting `x`
INT64	Floating Point	Returns a close but potentially not exact floating point value.
`NUMERIC`	Floating Point	`NUMERIC` will convert to the closest floating point number with a possible loss of precision.
`STRING`	Floating Point	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
NUMERIC
ENUM
BOOL
STRING

Conversion rules

From	To	Rule(s) when casting `x`
Floating Point	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 INTERVAL

  CAST 
 ( 
 expression 
  
 AS 
  
 INTERVAL 
 )

Description

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

STRING

Conversion rules

From	To	Rule(s) when casting `x`
`STRING`	`INTERVAL`	When casting from string to interval, the string must conform to either ISO 8601 Duration standard or to interval literal format 'Y-M D H:M:S.F'. Partial interval literal formats are also accepted when they aren't ambiguous, for example 'H:M:S'. If the string expression is invalid or represents an interval that is outside of the supported min/max range, then an error is produced.

Examples

  SELECT 
  
 input 
 , 
  
 CAST 
 ( 
 input 
  
 AS 
  
 INTERVAL 
 ) 
  
 AS 
  
 output 
 FROM 
  
 UNNEST 
 ( 
 [ 
  
 '1-2 3 10:20:30.456' 
 , 
  
 '1-2' 
 , 
  
 '10:20:30' 
 , 
  
 'P1Y2M3D' 
 , 
  
 'PT10H20M30,456S' 
 ] 
 ) 
  
 input 
 /*--------------------+--------------------* 
 | input              | output             | 
 +--------------------+--------------------+ 
 | 1-2 3 10:20:30.456 | 1-2 3 10:20:30.456 | 
 | 1-2                | 1-2 0 0:0:0        | 
 | 10:20:30           | 0-0 0 10:20:30     | 
 | P1Y2M3D            | 1-2 3 0:0:0        | 
 | PT10H20M30,456S    | 0-0 0 10:20:30.456 | 
 *--------------------+--------------------*/

CAST AS NUMERIC

  CAST 
 ( 
 expression 
  
 AS 
  
 NUMERIC 
 )

Description

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

INT64
FLOAT32
FLOAT64
NUMERIC
STRING

Conversion rules

From	To	Rule(s) when casting `x`
`Floating Point`	`NUMERIC`	The floating point number will round half away from zero . Casting a `NaN` , `+inf` or `-inf` will return an error. Casting a value outside the range of `NUMERIC` returns an overflow error.
`STRING`	`NUMERIC`	The numeric literal contained in the string must not exceed the maximum precision or range of the `NUMERIC` type, or an error will occur. If the number of digits after the decimal point exceeds nine, then the resulting `NUMERIC` value will round half away from zero . to have nine digits after the decimal point.

CAST AS PROTO

  CAST 
 ( 
 expression 
  
 AS 
  
 PROTO 
 )

Description

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

STRING
BYTES
PROTO

Conversion rules

From	To	Rule(s) when casting `x`
`STRING`	`PROTO`	Returns the protocol buffer that results from parsing from proto2 text format. Throws an error if parsing fails, e.g., if not all required fields are set.
`BYTES`	`PROTO`	Returns the protocol buffer that results from parsing `x` from the proto2 wire format. Throws an error if parsing fails, e.g., if not all required fields are set.
`PROTO`	`PROTO`	Must have the same protocol buffer name.

Example

This example references a protocol buffer called Award .

  message 
  
 Award 
  
 { 
  
 required 
  
 int32 
  
 year 
  
 = 
  
 1 
 ; 
  
 optional 
  
 int32 
  
 month 
  
 = 
  
 2 
 ; 
  
 repeated 
  
 Type 
  
 type 
  
 = 
  
 3 
 ; 
  
 message 
  
 Type 
  
 { 
  
 optional 
  
 string 
  
 award_name 
  
 = 
  
 1 
 ; 
  
 optional 
  
 string 
  
 category 
  
 = 
  
 2 
 ; 
  
 } 
 }

  SELECT 
  
 CAST 
 ( 
  
 ' 
 '' 
 year: 2001 
 month: 9 
 type { award_name: ' 
 Best 
  
 Artist 
 ' category: ' 
 Artist 
 ' } 
 type { award_name: ' 
 Best 
  
 Album 
 ' category: ' 
 Album 
 ' } 
  
 '' 
 ' 
  
 AS 
  
 googlesql 
 . 
 examples 
 . 
 music 
 . 
 Award 
 ) 
  
 AS 
  
 award_col 
 /*---------------------------------------------------------* 
 | award_col                                               | 
 +---------------------------------------------------------+ 
 | {                                                       | 
 |   year: 2001                                            | 
 |   month: 9                                              | 
 |   type { award_name: "Best Artist" category: "Artist" } | 
 |   type { award_name: "Best Album" category: "Album" }   | 
 | }                                                       | 
 *---------------------------------------------------------*/

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
NUMERIC
ENUM
BOOL
BYTES
PROTO
DATE
TIMESTAMP
INTERVAL
STRING

Conversion rules

From	To	Rule(s) when casting `x`
Floating Point	`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` isn't 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.
`PROTO`	`STRING`	Returns the proto2 text format representation of `x` .
`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, America/Los_Angeles. 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.
`INTERVAL`	`STRING`	Casting from an interval to a string is of the form `Y-M D H:M:S` .

Examples

  SELECT 
  
 CAST 
 ( 
 CURRENT_DATE 
 () 
  
 AS 
  
 STRING 
 ) 
  
 AS 
  
 current_date 
 /*---------------* 
 | current_date  | 
 +---------------+ 
 | 2021-03-09    | 
 *---------------*/

  SELECT 
  
 CAST 
 ( 
 INTERVAL 
  
 3 
  
 DAY 
  
 AS 
  
 STRING 
 ) 
  
 AS 
  
 interval_to_string 
 /*--------------------* 
 | interval_to_string | 
 +--------------------+ 
 | 0-0 3 0:0:0        | 
 *--------------------*/

  SELECT 
  
 CAST 
 ( 
  
 INTERVAL 
  
 "1-2 3 4:5:6.789" 
  
 YEAR 
  
 TO 
  
 SECOND 
  
 AS 
  
 STRING 
 ) 
  
 AS 
  
 interval_to_string 
 /*--------------------* 
 | interval_to_string | 
 +--------------------+ 
 | 1-2 3 4:5:6.789    | 
 *--------------------*/

CAST AS STRUCT

  CAST 
 ( 
 expression 
  
 AS 
  
 STRUCT 
 )

Description

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

STRUCT

Conversion rules

From

Rule(s) when casting x

STRUCT

Allowed if the following conditions are met:

The two structs have the same number of fields.
The original struct field types can be explicitly cast to the corresponding target struct field types (as defined by field order, not field name).

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, America/Los_Angeles, is used. If the string has fewer than six digits, then it's 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, America/Los_Angeles.

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-03T00:00:53.11Z | 
 *-------------------------*/

`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 NULL s. 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 .

Conversion functions in GoogleSQL Stay organized with collections Save and categorize content based on your preferences.

Function list

CAST

CAST AS ARRAY

CAST AS BOOL

CAST AS BYTES

CAST AS DATE

CAST AS ENUM

CAST AS Floating Point

CAST AS INT64

CAST AS INTERVAL

CAST AS NUMERIC

CAST AS PROTO

CAST AS STRING

CAST AS STRUCT

CAST AS TIMESTAMP

SAFE_CAST

Conversion functions in GoogleSQL

`CAST`

`SAFE_CAST`