Functions, operators, and conditionals

GoogleSQL is the new name for Google Standard SQL! New name, same great SQL dialect.

This topic is a compilation of functions, operators, and conditional expressions.

To learn more about how to call functions, function call rules, the SAFE prefix, and special types of arguments, see Function calls.

---

OPERATORS AND CONDITIONALS

Operators

GoogleSQL for BigQuery supports operators. Operators are represented by special characters or keywords; they do not use function call syntax. An operator manipulates any number of data inputs, also called operands, and returns a result.

Common conventions:

• Unless otherwise specified, all operators return NULL when one of the operands is NULL.
• All operators will throw an error if the computation result overflows.
• For all floating point operations, +/-inf and NaN may only be returned if one of the operands is +/-inf or NaN. In other cases, an error is returned.

Operator precedence

The following table lists all GoogleSQL operators from highest to lowest precedence, i.e. the order in which they will be evaluated within a statement.

Order of Precedence	Operator	Input Data Types	Name	Operator Arity
1	Field access operator	JSON STRUCT	Field access operator	Binary
	Array subscript operator	ARRAY	Array position. Must be used with OFFSET or ORDINAL—see Array Functions .	Binary
	JSON subscript operator	JSON	Field name or array position in JSON.	Binary
2	+	All numeric types	Unary plus	Unary
	-	All numeric types	Unary minus	Unary
	~	Integer or BYTES	Bitwise not	Unary
3	*	All numeric types	Multiplication	Binary
	/	All numeric types	Division	Binary
	||	STRING, BYTES, or ARRAY<T>	Concatenation operator	Binary
4	+	All numeric types, DATE with INT64 , INTERVAL	Addition	Binary
	-	All numeric types, DATE with INT64 , INTERVAL	Subtraction	Binary
5	<<	Integer or BYTES	Bitwise left-shift	Binary
	>>	Integer or BYTES	Bitwise right-shift	Binary
6	&	Integer or BYTES	Bitwise and	Binary
7	^	Integer or BYTES	Bitwise xor	Binary
8	|	Integer or BYTES	Bitwise or	Binary
9 (Comparison Operators)	=	Any comparable type. See Data Types for a complete list.	Equal	Binary
	<	Any comparable type. See Data Types for a complete list.	Less than	Binary
	>	Any comparable type. See Data Types for a complete list.	Greater than	Binary
	<=	Any comparable type. See Data Types for a complete list.	Less than or equal to	Binary
	>=	Any comparable type. See Data Types for a complete list.	Greater than or equal to	Binary
	!=, <>	Any comparable type. See Data Types for a complete list.	Not equal	Binary
	[NOT] LIKE	STRING and BYTES	Value does [not] match the pattern specified	Binary
	[NOT] BETWEEN	Any comparable types. See Data Types for a complete list.	Value is [not] within the range specified	Binary
	[NOT] IN	Any comparable types. See Data Types for a complete list.	Value is [not] in the set of values specified	Binary
	IS [NOT] NULL	All	Value is [not] NULL	Unary
	IS [NOT] TRUE	BOOL	Value is [not] TRUE.	Unary
	IS [NOT] FALSE	BOOL	Value is [not] FALSE.	Unary
10	NOT	BOOL	Logical NOT	Unary
11	AND	BOOL	Logical AND	Binary
12	OR	BOOL	Logical OR	Binary

Operators with the same precedence are left associative. This means that those operators are grouped together starting from the left and moving right. For example, the expression:

x AND y AND z

is interpreted as

( ( x AND y ) AND z )

The expression:

x * y / z

is interpreted as:

( ( x * y ) / z )

All comparison operators have the same priority, but comparison operators are not associative. Therefore, parentheses are required in order to resolve ambiguity. For example:

(x < y) IS FALSE

Field access operator

expression.fieldname[. ...]

Description

Gets the value of a field. Alternatively known as the dot operator. Can be used to access nested fields. For example, expression.fieldname1.fieldname2.

Input values:

• STRUCT
• JSON

Return type

• For STRUCT: SQL data type of fieldname. If a field is not found in the struct, an error is thrown.
• For JSON: JSON. If a field is not found in a JSON value, a SQL NULL is returned.

Example

In the following example, the expression is t.customer and the field access operations are .address and .country. An operation is an application of an operator (.) to specific operands (in this case, address and country, or more specifically, t.customer and address, for the first operation, and t.customer.address and country for the second operation).

WITH orders AS (
  SELECT STRUCT(STRUCT('Yonge Street' AS street, 'Canada' AS country) AS address) AS customer
)
SELECT t.customer.address.country FROM orders AS t;

/*---------*
 | country |
 +---------+
 | Canada  |
 *---------*/

Array subscript operator

array_expression[array_subscript_specifier]

array_subscript_specifier:
  position_keyword(index)

position_keyword:
  { OFFSET | SAFE_OFFSET | ORDINAL | SAFE_ORDINAL }

Note: The brackets ([]) around array_subscript_specifier are part of the syntax; they do not represent an optional part.

Description

Gets a value from an array at a specific position.

Input values:

• array_expression: The input array.
• position_keyword(index): Determines where the index for the array should start and how out-of-range indexes are handled. The index is an integer that represents a specific position in the array.
  • OFFSET(index): The index starts at zero. Produces an error if the index is out of range.
  • SAFE_OFFSET(index): The index starts at zero. Returns NULL if the index is out of range.
  • ORDINAL(index): The index starts at one. Produces an error if the index is out of range.
  • SAFE_ORDINAL(index): The index starts at one. Returns NULL if the index is out of range.

Return type

T where array_expression is ARRAY<T>.

Examples

In following query, the array subscript operator is used to return values at specific position in item_array. This query also shows what happens when you reference an index (6) in an array that is out of range. If the SAFE prefix is included, NULL is returned, otherwise an error is produced.

WITH Items AS (SELECT ["coffee", "tea", "milk"] AS item_array)
SELECT
  item_array,
  item_array[OFFSET(0)] AS item_offset,
  item_array[ORDINAL(1)] AS item_ordinal,
  item_array[SAFE_OFFSET(6)] AS item_safe_offset
FROM Items

/*---------------------+-------------+--------------+------------------*
 | item_array          | item_offset | item_ordinal | item_safe_offset |
 +---------------------+-------------+--------------+------------------+
 | [coffee, tea, milk] | coffee      | coffee       | NULL             |
 *---------------------+-------------+--------------+------------------*/

When you reference an index that is out of range in an array, and a positional keyword that begins with SAFE is not included, an error is produced. For example:

WITH Items AS (SELECT ["coffee", "tea", "milk"] AS item_array)
SELECT
  item_array[OFFSET(6)] AS item_offset
FROM Items

-- Error. Array index 6 is out of bounds.

JSON subscript operator

json_expression[array_element_id]

json_expression[field_name]

Note: The brackets ([]) around array_element_id and field_name are part of the syntax; they do not represent an optional part.

Description

Gets a value of an array element or field in a JSON expression. Can be used to access nested data.

Input values:

• JSON expression: The JSON expression that contains an array element or field to return.
• [array_element_id]: An INT64 expression that represents a zero-based index in the array. If a negative value is entered, or the value is greater than or equal to the size of the array, or the JSON expression doesn&#