Conversion functions

GoogleSQL for BigQuery supports conversion functions. These data typeconversions are explicit, but some conversions can happen implicitly. You canlearn more about implicit and explicit conversionhere.

Function list

NameSummary
ARRAY_TO_STRING Produces a concatenation of the elements in an array as aSTRING value.
For more information, seeArray functions.
BOOL Converts a JSON boolean to a SQLBOOL value.
For more information, seeJSON functions.
CAST Convert the results of an expression to the given type.
CHR Converts a Unicode code point to a character.
For more information, seeString functions.
CODE_POINTS_TO_BYTES Converts an array of extended ASCII code points to aBYTES value.
For more information, seeString aggregate functions.
CODE_POINTS_TO_STRING Converts an array of extended ASCII code points to aSTRING value.
For more information, seeString aggregate functions.
DATE_FROM_UNIX_DATE Interprets anINT64 expression as the number of days since 1970-01-01.
For more information, seeDate functions.
FROM_BASE32 Converts a base32-encodedSTRING value into aBYTES value.
For more information, seeString functions.
FROM_BASE64 Converts a base64-encodedSTRING value into aBYTES value.
For more information, seeString functions.
FROM_HEX Converts a hexadecimal-encodedSTRING value into aBYTES value.
For more information, seeString functions.
INT64 Converts a JSON number to a SQLINT64 value.
For more information, seeJSON functions.
LAX_BOOL Attempts to convert a JSON value to a SQLBOOL value.
For more information, seeJSON functions.
LAX_FLOAT64 Attempts to convert a JSON value to a SQLFLOAT64 value.
For more information, seeJSON functions.
LAX_INT64 Attempts to convert a JSON value to a SQLINT64 value.
For more information, seeJSON functions.
LAX_STRING Attempts to convert a JSON value to a SQLSTRING value.
For more information, seeJSON functions.
PARSE_BIGNUMERIC Converts aSTRING value to aBIGNUMERIC value.
PARSE_DATE Converts aSTRING value to aDATE value.
For more information, seeDate functions.
PARSE_DATETIME Converts aSTRING value to aDATETIME value.
For more information, seeDatetime functions.
PARSE_JSON Converts a JSON-formattedSTRING value to aJSON value.
For more information, seeJSON functions.
PARSE_NUMERIC Converts aSTRING value to aNUMERIC value.
PARSE_TIME Converts aSTRING value to aTIME value.
For more information, seeTime functions.
PARSE_TIMESTAMP Converts aSTRING value to aTIMESTAMP value.
For more information, seeTimestamp functions.
SAFE_CAST Similar to theCAST function, but returnsNULL when a runtime error is produced.
SAFE_CONVERT_BYTES_TO_STRING Converts aBYTES value to aSTRING value and replace any invalid UTF-8 characters with the Unicode replacement character,U+FFFD.
For more information, seeString functions.
STRING (JSON) Converts a JSON string to a SQLSTRING value.
For more information, seeJSON functions.
STRING (Timestamp) Converts aTIMESTAMP value to aSTRING value.
For more information, seeTimestamp functions.
TIMESTAMP_MICROS Converts the number of microseconds since 1970-01-01 00:00:00 UTC to aTIMESTAMP.
For more information, seeTimestamp functions.
TIMESTAMP_MILLIS Converts the number of milliseconds since 1970-01-01 00:00:00 UTC to aTIMESTAMP.
For more information, seeTimestamp functions.
TIMESTAMP_SECONDS Converts the number of seconds since 1970-01-01 00:00:00 UTC to aTIMESTAMP.
For more information, seeTimestamp functions.
TO_BASE32 Converts aBYTES value to a base32-encodedSTRING value.
For more information, seeString functions.
TO_BASE64 Converts aBYTES value to a base64-encodedSTRING value.
For more information, seeString functions.
TO_CODE_POINTS Converts aSTRING orBYTES value into an array of extended ASCII code points.
For more information, seeString functions.
TO_HEX Converts aBYTES value to a hexadecimalSTRING value.
For more information, seeString functions.
TO_JSON Converts a SQL value to a JSON value.
For more information, seeJSON functions.
TO_JSON_STRING Converts a SQL value to a JSON-formattedSTRING value.
For more information, seeJSON functions.
UNIX_DATE Converts aDATE value to the number of days since 1970-01-01.
For more information, seeDate functions.
UNIX_MICROS Converts aTIMESTAMP value to the number of microseconds since 1970-01-01 00:00:00 UTC.
For more information, seeTimestamp functions.
UNIX_MILLIS Converts aTIMESTAMP value to the number of milliseconds since 1970-01-01 00:00:00 UTC.
For more information, seeTimestamp functions.
UNIX_SECONDS Converts aTIMESTAMP value to the number of seconds since 1970-01-01 00:00:00 UTC.
For more information, seeTimestamp functions.

CAST

CAST(expressionAStypename[format_clause])

Description

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

When usingCAST, a query can fail if GoogleSQL is unable to performthe cast. If you want to protect your queries from these types of errors, youcan useSAFE_CAST.

Casts between supported types that don't successfully map from the originalvalue to the target domain produce runtime errors. For example, castingBYTES toSTRING where the byte sequence isn't valid UTF-8 results in aruntime error.

Some casts can include aformat clause, which providesinstructions for how to conduct thecast. For example, you couldinstruct a cast to convert a sequence of bytes to a BASE64-encoded stringinstead of a UTF-8-encoded string.

The structure of the format clause is unique to each type of cast and moreinformation is available in the section for that cast.

Examples

The following query results in"true" ifx is1,"false" for any othernon-NULL value, andNULL ifx isNULL.

CAST(x=1ASSTRING)

CAST AS ARRAY

CAST(expressionASARRAY<element_type>)

Description

GoogleSQL supportscasting toARRAY. Theexpression parameter can represent an expression for these data types:

  • ARRAY

Conversion rules

FromToRule(s) when castingx
ARRAYARRAY Must be the exact same array type.

CAST AS BIGNUMERIC

CAST(expressionASBIGNUMERIC)

Description

GoogleSQL supportscasting toBIGNUMERIC. Theexpression parameter can represent an expression for these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • STRING

Conversion rules

FromToRule(s) when castingx
FLOAT64BIGNUMERIC The floating point number will roundhalf away from zero. Casting aNaN,+inf or-inf will return an error. Casting a value outside the range ofBIGNUMERIC returns an overflow error.
STRINGBIGNUMERIC The numeric literal contained in the string must not exceed the maximum precision or range of theBIGNUMERIC type, or an error will occur. If the number of digits after the decimal point exceeds 38, then the resultingBIGNUMERIC value will roundhalf away from zero to have 38 digits after the decimal point.

CAST AS BOOL

CAST(expressionASBOOL)

Description

GoogleSQL supportscasting toBOOL. Theexpression parameter can represent an expression for these data types:

  • INT64
  • BOOL
  • STRING

Conversion rules

FromToRule(s) when castingx
INT64BOOL ReturnsFALSE ifx is0,TRUE otherwise.
STRINGBOOL ReturnsTRUE ifx is"true" andFALSE ifx is"false"
All other values ofx 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(expressionASBYTES[format_clause])

Description

GoogleSQL supportscasting toBYTES. Theexpression parameter can represent an expression for these data types:

  • BYTES
  • STRING

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is aSTRING.

Conversion rules

FromToRule(s) when castingx
STRINGBYTES 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(expressionASDATE[format_clause])

Description

GoogleSQL supportscasting toDATE. Theexpressionparameter can represent an expression for these data types:

  • STRING
  • DATETIME
  • TIMESTAMP

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is aSTRING.

Conversion rules

FromToRule(s) when castingx
STRINGDATE 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.
TIMESTAMPDATE Casting from a timestamp to date effectively truncates the timestamp as of the default time zone.

CAST AS DATETIME

CAST(expressionASDATETIME[format_clause])

Description

GoogleSQL supportscasting toDATETIME. Theexpression parameter can represent an expression for these data types:

  • STRING
  • DATETIME
  • TIMESTAMP

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is aSTRING.

Conversion rules

FromToRule(s) when castingx
STRINGDATETIME When casting from string to datetime, the string must conform to the supported datetime literal format, and is independent of time zone. If the string expression is invalid or represents a datetime that's outside of the supported min/max range, then an error is produced.
TIMESTAMPDATETIME Casting from a timestamp to datetime effectively truncates the timestamp as of the default time zone.

CAST AS FLOAT64

CAST(expressionASFLOAT64)

Description

GoogleSQL supportscasting to floating point types.Theexpression parameter can represent an expression for these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • STRING

Conversion rules

FromToRule(s) when castingx
INT64FLOAT64 Returns a close but potentially not exact floating point value.
NUMERICFLOAT64NUMERIC will convert to the closest floating point number with a possible loss of precision.
BIGNUMERICFLOAT64BIGNUMERIC will convert to the closest floating point number with a possible loss of precision.
STRINGFLOAT64 Returnsx 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" toNaN. Conversions are case-insensitive.

CAST AS INT64

CAST(expressionASINT64)

Description

GoogleSQL supportscasting to integer types.Theexpression parameter can represent an expression for these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • BOOL
  • STRING

Conversion rules

FromToRule(s) when castingx
FLOAT64 INT64 Returns the closest integer value.
Halfway cases such as 1.5 or -0.5 round away from zero.
BOOLINT64 Returns1 ifx isTRUE,0 otherwise.
STRINGINT64 A hex string can be cast to an integer. For example,0x123 to291 or-0x123 to-291.

Examples

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

SELECT'0x123'ashex_value,CAST('0x123'asINT64)ashex_to_int;/*-----------+------------+ | hex_value | hex_to_int | +-----------+------------+ | 0x123     | 291        | +-----------+------------*/
SELECT'-0x123'ashex_value,CAST('-0x123'asINT64)ashex_to_int;/*-----------+------------+ | hex_value | hex_to_int | +-----------+------------+ | -0x123    | -291       | +-----------+------------*/

CAST AS INTERVAL

CAST(expressionASINTERVAL)

Description

GoogleSQL supportscasting toINTERVAL. Theexpression parameter can represent an expression for these data types:

  • STRING

Conversion rules

FromToRule(s) when castingx
STRINGINTERVAL When casting from string to interval, the string must conform to eitherISO 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

SELECTinput,CAST(inputASINTERVAL)ASoutputFROMUNNEST(['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(expressionASNUMERIC)

Description

GoogleSQL supportscasting toNUMERIC. Theexpression parameter can represent an expression for these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • STRING

Conversion rules

FromToRule(s) when castingx
FLOAT64NUMERIC The floating point number will roundhalf away from zero. Casting aNaN,+inf or-inf will return an error. Casting a value outside the range ofNUMERIC returns an overflow error.
STRINGNUMERIC The numeric literal contained in the string must not exceed the maximum precision or range of theNUMERIC type, or an error will occur. If the number of digits after the decimal point exceeds nine, then the resultingNUMERIC value will roundhalf away from zero. to have nine digits after the decimal point.

CAST AS RANGE

CAST(expressionASRANGE)

Description

GoogleSQL supportscasting toRANGE. Theexpression parameter can represent an expression for these data types:

  • STRING

Conversion rules

FromToRule(s) when castingx
STRINGRANGE When casting from string to range, the string must conform to the supported range literal format. If the string expression is invalid or represents a range that's outside of the supported subtype min/max range, then an error is produced.

Examples

SELECTCAST('[2020-01-01, 2020-01-02)'ASRANGE<DATE>)ASstring_to_range/*----------------------------------------+ | string_to_range                        | +----------------------------------------+ | [DATE '2020-01-01', DATE '2020-01-02') | +----------------------------------------*/
SELECTCAST('[2014-09-27 12:30:00.45, 2016-10-17 11:15:00.33)'ASRANGE<DATETIME>)ASstring_to_range/*------------------------------------------------------------------------+ | string_to_range                                                        | +------------------------------------------------------------------------+ | [DATETIME '2014-09-27 12:30:00.45', DATETIME '2016-10-17 11:15:00.33') | +------------------------------------------------------------------------*/
SELECTCAST('[2014-09-27 12:30:00+08, 2016-10-17 11:15:00+08)'ASRANGE<TIMESTAMP>)ASstring_to_range-- Results depend upon where this query was executed./*---------------------------------------------------------------------------+ | string_to_range                                                           | +---------------------------------------------------------------------------+ | [TIMESTAMP '2014-09-27 12:30:00+08', TIMESTAMP '2016-10-17 11:15:00 UTC') | +---------------------------------------------------------------------------*/
SELECTCAST('[UNBOUNDED, 2020-01-02)'ASRANGE<DATE>)ASstring_to_range/*--------------------------------+ | string_to_range                | +--------------------------------+ | [UNBOUNDED, DATE '2020-01-02') | +--------------------------------*/
SELECTCAST('[2020-01-01, NULL)'ASRANGE<DATE>)ASstring_to_range/*--------------------------------+ | string_to_range                | +--------------------------------+ | [DATE '2020-01-01', UNBOUNDED) | +--------------------------------*/

CAST AS STRING

CAST(expressionASSTRING[format_clause[ATTIMEZONEtimezone_expr]])

Description

GoogleSQL supportscasting toSTRING. Theexpression parameter can represent an expression for these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • BOOL
  • BYTES
  • TIME
  • DATE
  • DATETIME
  • TIMESTAMP
  • RANGE
  • INTERVAL
  • STRING

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is oneof these data types:

  • INT64
  • FLOAT64
  • NUMERIC
  • BIGNUMERIC
  • BYTES
  • TIME
  • DATE
  • DATETIME
  • TIMESTAMP

The format clause forSTRING has an additional optional clause calledAT TIME ZONE timezone_expr, which you can use to specify a specific time zoneto use during formatting of aTIMESTAMP. If this optional clause isn'tincluded when formatting aTIMESTAMP, the default time zone,UTC, is used.

For more information, see the following topics:

Conversion rules

FromToRule(s) when castingx
FLOAT64STRINGReturns an approximate string representation. A returnedNaN or0 will not be signed.
BOOLSTRING Returns"true" ifx isTRUE,"false" otherwise.
BYTESSTRING Returnsx interpreted as a UTF-8 string.
For example, the bytes literalb'\xc2\xa9', when cast to a string, is interpreted as UTF-8 and becomes the unicode character "©".
An error occurs ifx isn't valid UTF-8.
TIMESTRING Casting from a time type to a string is independent of time zone and is of the formHH:MM:SS.
DATESTRING Casting from a date type to a string is independent of time zone and is of the formYYYY-MM-DD.
DATETIMESTRING Casting from a datetime type to a string is independent of time zone and is of the formYYYY-MM-DD HH:MM:SS.
TIMESTAMPSTRING 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.
INTERVALSTRING Casting from an interval to a string is of the formY-M D H:M:S.

Examples

SELECTCAST(CURRENT_DATE()ASSTRING)AScurrent_date/*---------------+ | current_date  | +---------------+ | 2021-03-09    | +---------------*/
SELECTCAST(CURRENT_DATE()ASSTRINGFORMAT'DAY')AScurrent_day/*-------------+ | current_day | +-------------+ | MONDAY      | +-------------*/
SELECTCAST(TIMESTAMP'2008-12-25 00:00:00+00:00'ASSTRINGFORMAT'YYYY-MM-DD HH24:MI:SS TZH:TZM')ASdate_time_to_string-- Results depend upon where this query was executed./*------------------------------+ | date_time_to_string          | +------------------------------+ | 2008-12-24 16:00:00 -08:00   | +------------------------------*/
SELECTCAST(TIMESTAMP'2008-12-25 00:00:00+00:00'ASSTRINGFORMAT'YYYY-MM-DD HH24:MI:SS TZH:TZM'ATTIMEZONE'Asia/Kolkata')ASdate_time_to_string-- Because the time zone is specified, the result is always the same./*------------------------------+ | date_time_to_string          | +------------------------------+ | 2008-12-25 05:30:00 +05:30   | +------------------------------*/
SELECTCAST(INTERVAL3DAYASSTRING)ASinterval_to_string/*--------------------+ | interval_to_string | +--------------------+ | 0-0 3 0:0:0        | +--------------------*/
SELECTCAST(INTERVAL"1-2 3 4:5:6.789"YEARTOSECONDASSTRING)ASinterval_to_string/*--------------------+ | interval_to_string | +--------------------+ | 1-2 3 4:5:6.789    | +--------------------*/

CAST AS STRUCT

CAST(expressionASSTRUCT)

Description

GoogleSQL supportscasting toSTRUCT. Theexpression parameter can represent an expression for these data types:

  • STRUCT

Conversion rules

FromToRule(s) when castingx
STRUCTSTRUCT Allowed if the following conditions are met:
  1. The two structs have the same number of fields.
  2. 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 TIME

CAST(expressionASTIME[format_clause])

Description

GoogleSQL supportscasting to TIME. Theexpressionparameter can represent an expression for these data types:

  • STRING
  • TIME
  • DATETIME
  • TIMESTAMP

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is aSTRING.

Conversion rules

FromToRule(s) when castingx
STRINGTIME When casting from string to time, the string must conform to the supported time literal format, and is independent of time zone. If the string expression is invalid or represents a time that's outside of the supported min/max range, then an error is produced.

CAST AS TIMESTAMP

CAST(expressionASTIMESTAMP[format_clause[ATTIMEZONEtimezone_expr]])

Description

GoogleSQL supportscasting toTIMESTAMP. Theexpression parameter can represent an expression for these data types:

  • STRING
  • DATETIME
  • TIMESTAMP

Format clause

When an expression of one type is cast to another type, you can use theformat clause to provide instructions for how to conductthe cast. You can use the format clause in this section ifexpression is aSTRING.

The format clause forTIMESTAMP has an additional optional clause calledAT TIME ZONE timezone_expr, which you can use to specify a specific time zoneto use during formatting. If this optional clause isn't included, the defaulttime zone, UTC, is used.

Conversion rules

FromToRule(s) when castingx
STRINGTIMESTAMP When casting from string to a timestamp,string_expression must conform to the supported timestamp literal formats, or else a runtime error occurs. Thestring_expression may itself contain a time zone.

If there is a time zone in thestring_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's implicitly widened.

An error is produced if thestring_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.
DATETIMESTAMP Casting from a date to a timestamp interpretsdate_expression as of midnight (start of the day) in the default time zone, UTC.
DATETIMETIMESTAMP Casting from a datetime to a timestamp interpretsdatetime_expression in the default time zone, UTC.

Most valid datetime values have exactly one corresponding timestamp in each time zone. However, there are certain combinations of valid datetime values and time zones that have zero or two corresponding timestamp values. This happens in a time zone when clocks are set forward or set back, such as for Daylight Savings Time. When there are two valid timestamps, the earlier one is used. When there is no valid timestamp, the length of the gap in time (typically one hour) is added to the datetime.

Examples

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

SELECTCAST("2020-06-02 17:00:53.110+00:00"ASTIMESTAMP)ASas_timestamp-- Results depend upon where this query was executed./*-----------------------------+ | as_timestamp                | +-----------------------------+ | 2020-06-03 00:00:53.110 UTC | +-----------------------------*/

The following examples cast a string-formatted date and time as a timestamp.These examples return the same output as the previous example.

SELECTCAST('06/02/2020 17:00:53.110'ASTIMESTAMPFORMAT'MM/DD/YYYY HH24:MI:SS.FF3'ATTIMEZONE'UTC')ASas_timestamp
SELECTCAST('06/02/2020 17:00:53.110'ASTIMESTAMPFORMAT'MM/DD/YYYY HH24:MI:SS.FF3'ATTIMEZONE'+00')ASas_timestamp
SELECTCAST('06/02/2020 17:00:53.110 +00'ASTIMESTAMPFORMAT'MM/DD/YYYY HH24:MI:SS.FF3 TZH')ASas_timestamp

PARSE_BIGNUMERIC

PARSE_BIGNUMERIC(string_expression)

Description

Converts aSTRING to aBIGNUMERIC value.

The numeric literal contained in the string must not exceed themaximum precision or range of theBIGNUMERIC type, or anerror occurs. If the number of digits after the decimal point exceeds 38, thenthe resultingBIGNUMERIC value roundshalf away from zero to have 38 digits after thedecimal point.

-- This example shows how a string with a decimal point is parsed.SELECTPARSE_BIGNUMERIC("123.45")ASparsed;/*--------+ | parsed | +--------+ | 123.45 | +--------*/-- This example shows how a string with an exponent is parsed.SELECTPARSE_BIGNUMERIC("123.456E37")ASparsed;/*-----------------------------------------+ | parsed                                  | +-----------------------------------------+ | 123400000000000000000000000000000000000 | +-----------------------------------------*/-- This example shows the rounding when digits after the decimal point exceeds 38.SELECTPARSE_BIGNUMERIC("1.123456789012345678901234567890123456789")asparsed;/*------------------------------------------+ | parsed                                   | +------------------------------------------+ | 1.12345678901234567890123456789012345679 | +------------------------------------------*/

This function is similar to using theCAST AS BIGNUMERICfunction except that thePARSE_BIGNUMERIC function only accepts string inputsand allows the following in the string:

  • Spaces between the sign (+/-) and the number
  • Signs (+/-) after the number

Rules for valid input strings:

RuleExample InputOutput
The string can only contain digits, commas, decimal points and signs. "- 12,34567,89.0"-123456789
Whitespaces are allowed anywhere except between digits. " - 12.345 "-12.345
Only digits and commas are allowed before the decimal point. " 12,345,678"12345678
Only digits are allowed after the decimal point. "1.234 "1.234
UseE ore for exponents. After thee, digits and a leading sign indicator are allowed." 123.45e-1"12.345
If the integer part isn't empty, then it must contain at least one digit." 0,.12 -"-0.12
If the string contains a decimal point, then it must contain at least one digit." .1"0.1
The string can't contain more than one sign." 0.5 +"0.5

Return Data Type

BIGNUMERIC

Examples

This example shows an input with spaces before, after, and between thesign and the number:

SELECTPARSE_BIGNUMERIC("  -  12.34 ")asparsed;/*--------+ | parsed | +--------+ | -12.34 | +--------*/

This example shows an input with an exponent as well as the sign after thenumber:

SELECTPARSE_BIGNUMERIC("12.34e-1-")asparsed;/*--------+ | parsed | +--------+ | -1.234 | +--------*/

This example shows an input with multiple commas in the integer part of thenumber:

SELECTPARSE_BIGNUMERIC("  1,2,,3,.45 + ")asparsed;/*--------+ | parsed | +--------+ | 123.45 | +--------*/

This example shows an input with a decimal point and no digits in the wholenumber part:

SELECTPARSE_BIGNUMERIC(".1234  ")asparsed;/*--------+ | parsed | +--------+ | 0.1234 | +--------*/

Examples of invalid inputs

This example is invalid because the whole number part contains no digits:

SELECTPARSE_BIGNUMERIC(",,,.1234  ")asparsed;

This example is invalid because there are whitespaces between digits:

SELECTPARSE_BIGNUMERIC("1  23.4 5  ")asparsed;

This example is invalid because the number is empty except for an exponent:

SELECTPARSE_BIGNUMERIC("  e1 ")asparsed;

This example is invalid because the string contains multiple signs:

SELECTPARSE_BIGNUMERIC("  - 12.3 - ")asparsed;

This example is invalid because the value of the number falls outside the rangeofBIGNUMERIC:

SELECTPARSE_BIGNUMERIC("12.34E100 ")asparsed;

This example is invalid because the string contains invalid characters:

SELECTPARSE_BIGNUMERIC("$12.34")asparsed;

PARSE_NUMERIC

PARSE_NUMERIC(string_expression)

Description

Converts aSTRING to aNUMERIC value.

The numeric literal contained in the string must not exceed themaximum precision or range of theNUMERIC type, or an erroroccurs. If the number of digits after the decimal point exceeds nine, then theresultingNUMERIC value roundshalf away from zero to have nine digits after thedecimal point.

-- This example shows how a string with a decimal point is parsed.SELECTPARSE_NUMERIC("123.45")ASparsed;/*--------+ | parsed | +--------+ | 123.45 | +--------*/-- This example shows how a string with an exponent is parsed.SELECTPARSE_NUMERIC("12.34E27")asparsed;/*-------------------------------+ | parsed                        | +-------------------------------+ | 12340000000000000000000000000 | +-------------------------------*/-- This example shows the rounding when digits after the decimal point exceeds 9.SELECTPARSE_NUMERIC("1.0123456789")asparsed;/*-------------+ | parsed      | +-------------+ | 1.012345679 | +-------------*/

This function is similar to using theCAST AS NUMERIC functionexcept that thePARSE_NUMERIC function only accepts string inputs and allowsthe following in the string:

  • Spaces between the sign (+/-) and the number
  • Signs (+/-) after the number

Rules for valid input strings:

RuleExample InputOutput
The string can only contain digits, commas, decimal points and signs. "- 12,34567,89.0"-123456789
Whitespaces are allowed anywhere except between digits. " - 12.345 "-12.345
Only digits and commas are allowed before the decimal point. " 12,345,678"12345678
Only digits are allowed after the decimal point. "1.234 "1.234
UseE ore for exponents. After thee, digits and a leading sign indicator are allowed." 123.45e-1"12.345
If the integer part isn't empty, then it must contain at least one digit." 0,.12 -"-0.12
If the string contains a decimal point, then it must contain at least one digit." .1"0.1
The string can't contain more than one sign." 0.5 +"0.5

Return Data Type

NUMERIC

Examples

This example shows an input with spaces before, after, and between thesign and the number:

SELECTPARSE_NUMERIC("  -  12.34 ")asparsed;/*--------+ | parsed | +--------+ | -12.34 | +--------*/

This example shows an input with an exponent as well as the sign after thenumber:

SELECTPARSE_NUMERIC("12.34e-1-")asparsed;/*--------+ | parsed | +--------+ | -1.234 | +--------*/

This example shows an input with multiple commas in the integer part of thenumber:

SELECTPARSE_NUMERIC("  1,2,,3,.45 + ")asparsed;/*--------+ | parsed | +--------+ | 123.45 | +--------*/

This example shows an input with a decimal point and no digits in the wholenumber part:

SELECTPARSE_NUMERIC(".1234  ")asparsed;/*--------+ | parsed | +--------+ | 0.1234 | +--------*/

Examples of invalid inputs

This example is invalid because the whole number part contains no digits:

SELECTPARSE_NUMERIC(",,,.1234  ")asparsed;

This example is invalid because there are whitespaces between digits:

SELECTPARSE_NUMERIC("1  23.4 5  ")asparsed;

This example is invalid because the number is empty except for an exponent:

SELECTPARSE_NUMERIC("  e1 ")asparsed;

This example is invalid because the string contains multiple signs:

SELECTPARSE_NUMERIC("  - 12.3 - ")asparsed;

This example is invalid because the value of the number falls outside the rangeofBIGNUMERIC:

SELECTPARSE_NUMERIC("12.34E100 ")asparsed;

This example is invalid because the string contains invalid characters:

SELECTPARSE_NUMERIC("$12.34")asparsed;

SAFE_CAST

SAFE_CAST(expressionAStypename[format_clause])

Description

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

SELECTCAST("apple"ASINT64)ASnot_a_number;

If you want to protect your queries from these types of errors, you can useSAFE_CAST.SAFE_CAST replaces runtime errors withNULLs. However, duringstatic analysis, impossible casts between two non-castable types still producean error because the query is invalid.

SELECTSAFE_CAST("apple"ASINT64)ASnot_a_number;/*--------------+ | not_a_number | +--------------+ | NULL         | +--------------*/

Some casts can include aformat clause, which providesinstructions for how to conduct thecast. For example, you couldinstruct a cast to convert a sequence of bytes to a BASE64-encoded stringinstead of a UTF-8-encoded string.

The structure of the format clause is unique to each type of cast and moreinformation is available in the section for that cast.

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-24 UTC.