Operators in Google Standard SQL

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 Google Standard SQL 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	Addition	Binary
	-	All numeric types	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 byte	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 types

• 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 location.

Input types

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

Return type

T where array_expression is ARRAY<T>.

Examples

In this example, the array subscript operator is used to return values at specific locations in item_array. This example 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(1)] 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]              | tea          | coffee       | NULL             |
+----------------------------------+--------------+--------------+------------------+

In the following example, when you reference an index in an array that is out of range and the SAFE prefix is not included, an error is produced.

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

-- Error. OFFSET(6) is out of range.

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 types

• 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't represent a JSON array, a SQL NULL is returned.
• [field_name]: A STRING expression that represents the name of a field in JSON. If the field name is not found, or the JSON expression is not a JSON object, a SQL NULL is returned.

Return type

JSON

Example

In the following example:

• json_value is a JSON expression.
• .class is a JSON field access.
• .students is a JSON field access.
• [0] is a JSON subscript expression with an element offset that accesses the zeroth element of an array in the JSON value.
• ['name'] is a JSON subscript expression with a field name that accesses a field.

SELECT json_value.class.students[0]['name'] AS first_student
FROM
  UNNEST(
    [
      JSON '{"class" : {"students" : [{"name" : "Jane"}]}}',
      JSON '{"class" : {"students" : []}}',
      JSON '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'])
    AS json_value;

+-----------------+
| first_student   |
+-----------------+
| "Jane"          |
| NULL            |
| "John"          |
+-----------------+

Arithmetic operators

All arithmetic operators accept input of numeric type T, and the result type has type T unless otherwise indicated in the description below:

Name	Syntax
Addition	X + Y
Subtraction	X - Y
Multiplication	X * Y
Division	X / Y
Unary Plus	+ X
Unary Minus	- X

NOTE: Divide by zero operations return an error. To return a different result, consider the IEEE_DIVIDE or SAFE_DIVIDE functions.

Result types for Addition, Subtraction and Multiplication:

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Result types for Division:

INPUT	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Result types for Unary Plus:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Result types for Unary Minus:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Bitwise operators

All bitwise operators return the same type and the same length as the first operand.

Name	Syntax	Input Data Type	Description
Bitwise not	~ X	Integer or BYTES	Performs logical negation on each bit, forming the ones' complement of the given binary value.
Bitwise or	X | Y	X: Integer or BYTES Y: Same type as X	Takes two bit patterns of equal length and performs the logical inclusive OR operation on each pair of the corresponding bits. This operator throws an error if X and Y are BYTES of different lengths.
Bitwise xor	X ^ Y	X: Integer or BYTES Y: Same type as X	Takes two bit patterns of equal length and performs the logical exclusive OR operation on each pair of the corresponding bits. This operator throws an error if X and Y are BYTES of different lengths.
Bitwise and	X & Y	X: Integer or BYTES Y: Same type as X	Takes two bit patterns of equal length and performs the logical AND operation on each pair of the corresponding bits. This operator throws an error if X and Y are BYTES of different lengths.
Left shift	X << Y	X: Integer or BYTES Y: INT64	Shifts the first operand X to the left. This operator returns 0 or a byte sequence of b'\x00' if the second operand Y is greater than or equal to the bit length of the first operand X (for example, 64 if X has the type INT64). This operator throws an error if Y is negative.
Right shift	X >> Y	X: Integer or BYTES Y: INT64	Shifts the first operand X to the right. This operator does not do sign bit extension with a signed type (i.e. it fills vacant bits on the left with 0). This operator returns 0 or a byte sequence of b'\x00' if the second operand Y is greater than or equal to the bit length of the first operand X (for example, 64 if X has the type INT64). This operator throws an error if Y is negative.

Logical operators

Google Standard SQL supports the AND, OR, and NOT logical operators. Logical operators allow only BOOL or NULL input and use three-valued logic to produce a result. The result can be TRUE, FALSE, or NULL:

x	y	x AND y	x OR y
TRUE	TRUE	TRUE	TRUE
TRUE	FALSE	FALSE	TRUE
TRUE	NULL	NULL	TRUE
FALSE	TRUE	FALSE	TRUE
FALSE	FALSE	FALSE	FALSE
FALSE	NULL	FALSE	NULL
NULL	TRUE	NULL	TRUE
NULL	FALSE	FALSE	NULL
NULL	NULL	NULL	NULL

x	NOT x
TRUE	FALSE
FALSE	TRUE
NULL	NULL

Examples

The examples in this section reference a table called entry_table:

+-------+
| entry |
+-------+
| a     |
| b     |
| c     |
| NULL  |
+-------+

SELECT 'a' FROM entry_table WHERE entry = 'a'

-- a => 'a' = 'a' => TRUE
-- b => 'b' = 'a' => FALSE
-- NULL => NULL = 'a' => NULL

+-------+
| entry |
+-------+
| a     |
+-------+

SELECT entry FROM entry_table WHERE NOT (entry = 'a')

-- a => NOT('a' = 'a') => NOT(TRUE) => FALSE
-- b => NOT('b' = 'a') => NOT(FALSE) => TRUE
-- NULL => NOT(NULL = 'a') => NOT(NULL) => NULL

+-------+
| entry |
+-------+
| b     |
| c     |
+-------+

SELECT entry FROM entry_table WHERE entry IS NULL

-- a => 'a' IS NULL => FALSE
-- b => 'b' IS NULL => FALSE
-- NULL => NULL IS NULL => TRUE

+-------+
| entry |
+-------+
| NULL  |
+-------+

Comparison operators

Comparisons always return BOOL. Comparisons generally require both operands to be of the same type. If operands are of different types, and if Google Standard SQL can convert the values of those types to a common type without loss of precision, Google Standard SQL will generally coerce them to that common type for the comparison; Google Standard SQL will generally coerce literals to the type of non-literals, where present. Comparable data types are defined in Data Types.

STRUCTs support only 4 comparison operators: equal (=), not equal (!= and <>), and IN.

The following rules apply when comparing these data types:

• FLOAT64: All comparisons with NaN return FALSE, except for != and <>, which return TRUE.
• BOOL: FALSE is less than TRUE.
• STRING: Strings are compared codepoint-by-codepoint, which means that canonically equivalent strings are only guaranteed to compare as equal if they have been normalized first.
• NULL: The convention holds here: any operation with a NULL input returns NULL.

Name	Syntax	Description
Less Than	X < Y	Returns TRUE if X is less than Y.
Less Than or Equal To	X <= Y	Returns TRUE if X is less than or equal to Y.
Greater Than	X > Y	Returns TRUE if X is greater than Y.
Greater Than or Equal To	X >= Y	Returns TRUE if X is greater than or equal to Y.
Equal	X = Y	Returns TRUE if X is equal to Y.
Not Equal	X != Y X <> Y	Returns TRUE if X is not equal to Y.
BETWEEN	X [NOT] BETWEEN Y AND Z	Returns TRUE if X is [not] within the range specified. The result of "X BETWEEN Y AND Z" is equivalent to "Y <= X AND X <= Z" but X is evaluated only once in the former.
LIKE	X [NOT] LIKE Y	Checks if the STRING in the first operand X matches a pattern specified by the second operand Y. Expressions can contain these characters: A percent sign "%" matches any number of characters or bytes An underscore "_" matches a single character or byte You can escape "\", "_", or "%" using two backslashes. For example, "\\%". If you are using raw strings, only a single backslash is required. For example, r"\%".
IN	Multiple - see below	Returns FALSE if the right operand is empty. Returns NULL if the left operand is NULL. Returns TRUE or NULL, never FALSE, if the right operand contains NULL. Arguments on either side of IN are general expressions. Neither operand is required to be a literal, although using a literal on the right is most common. X is evaluated only once.

When testing values that have a STRUCT data type for equality, it's possible that one or more fields are NULL. In such cases:

• If all non-NULL field values are equal, the comparison returns NULL.
• If any non-NULL field values are not equal, the comparison returns false.

The following table demonstrates how STRUCT data types are compared when they have fields that are NULL valued.

Struct1	Struct2	Struct1 = Struct2
STRUCT(1, NULL)	STRUCT(1, NULL)	NULL
STRUCT(1, NULL)	STRUCT(2, NULL)	FALSE
STRUCT(1,2)	STRUCT(1, NULL)	NULL

EXISTS operator

EXISTS ( subquery )

Description

Returns TRUE if the subquery produces one or more rows. Returns FALSE if the subquery produces zero rows. Never returns NULL. To learn more about how you can use a subquery with EXISTS, see EXISTS subqueries.

Examples

In this example, the EXISTS operator returns FALSE because there are no rows in Words where the direction is south:

WITH Words AS (
  SELECT 'Intend' as value, 'east' as direction UNION ALL
  SELECT 'Secure', 'north' UNION ALL
  SELECT 'Clarity', 'west'
 )
SELECT EXISTS ( SELECT value FROM Words WHERE direction = 'south' ) as result;

+--------+
| result |
+--------+
| FALSE  |
+--------+

IN operator

The IN operator supports the following syntax:

search_value [NOT] IN value_set

value_set:
  {
    (expression[, ...])
    | (subquery)
    | UNNEST(array_expression)
  }

Description

Checks for an equal value in a set of values. Semantic rules apply, but in general, IN returns TRUE if an equal value is found, FALSE if an equal value is excluded, otherwise NULL. NOT IN returns FALSE if an equal value is found, TRUE if an equal value is excluded, otherwise NULL.

• search_value: The expression that is compared to a set of values.

• value_set: One or more values to compare to a search value.

  • (expression[, ...]): A list of expressions.
  • (subquery): A subquery that returns a single column. The values in that column are the set of values. If no rows are produced, the set of values is empty.

  • UNNEST(array_expression): An UNNEST operator that returns a column of values from an array expression. This is equivalent to:

    IN (SELECT element FROM UNNEST(array_expression) AS element)
    

Semantic rules

When using the IN operator, the following semantics apply in this order:

• Returns FALSE if value_set is empty.
• Returns NULL if search_value is NULL.
• Returns TRUE if value_set contains a value equal to search_value.
• Returns NULL if value_set contains a NULL.
• Returns FALSE.

When using the NOT IN operator, the following semantics apply in this order:

• Returns TRUE if value_set is empty.
• Returns NULL if search_value is NULL.
• Returns FALSE if value_set contains a value equal to search_value.
• Returns NULL if value_set contains a NULL.
• Returns TRUE.

This operator generally supports collation, however, x [NOT] IN UNNEST is not supported.

The semantics of:

x IN (y, z, ...)

are defined as equivalent to:

(x = y) OR (x = z) OR ...

and the subquery and array forms are defined similarly.

x NOT IN ...

is equivalent to:

NOT(x IN ...)

The UNNEST form treats an array scan like UNNEST in the FROM clause:

x [NOT] IN UNNEST(<array expression>)

This form is often used with ARRAY parameters. For example:

x IN UNNEST(@array_parameter)

See the Arrays topic for more information on how to use this syntax.

IN can be used with multi-part keys by using the struct constructor syntax. For example:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

See the Struct Type for more information.

Return Data Type

BOOL

Examples

You can use these WITH clauses to emulate temporary tables for Words and Items in the following examples:

WITH Words AS (
  SELECT 'Intend' as value UNION ALL
  SELECT 'Secure' UNION ALL
  SELECT 'Clarity' UNION ALL
  SELECT 'Peace' UNION ALL
  SELECT 'Intend'
 )
SELECT * FROM Words;

+----------+
| value    |
+----------+
| Intend   |
| Secure   |
| Clarity  |
| Peace    |
| Intend   |
+----------+

WITH
  Items AS (
    SELECT STRUCT('blue' AS color, 'round' AS shape) AS info UNION ALL
    SELECT STRUCT('blue', 'square') UNION ALL
    SELECT STRUCT('red', 'round')
  )
SELECT * FROM Items;

+----------------------------+
| info                       |
+----------------------------+
| {blue color, round shape}  |
| {blue color, square shape} |
| {red color, round shape}   |
+----------------------------+

Example with IN and an expression:

SELECT * FROM Words WHERE value IN ('Intend', 'Secure');

+----------+
| value    |
+----------+
| Intend   |
| Secure   |
| Intend   |
+----------+

Example with NOT IN and an expression:

SELECT * FROM Words WHERE value NOT IN ('Intend');

+----------+
| value    |
+----------+
| Secure   |
| Clarity  |
| Peace    |
+----------+

Example with IN, a scalar subquery, and an expression:

SELECT * FROM Words WHERE value IN ((SELECT 'Intend'), 'Clarity');

+----------+
| value    |
+----------+
| Intend   |
| Clarity  |
| Intend   |
+----------+

Example with IN and an UNNEST operation:

SELECT * FROM Words WHERE value IN UNNEST(['Secure', 'Clarity']);

+----------+
| value    |
+----------+
| Secure   |
| Clarity  |
+----------+

Example with IN and a STRUCT:

SELECT
  (SELECT AS STRUCT Items.info) as item
FROM
  Items
WHERE (info.shape, info.color) IN (('round', 'blue'));

+------------------------------------+
| item                               |
+------------------------------------+
| { {blue color, round shape} info } |
+------------------------------------+

IS operators

IS operators return TRUE or FALSE for the condition they are testing. They never return NULL, even for NULL inputs, unlike the IS_INF and IS_NAN functions defined in Mathematical Functions. If NOT is present, the output BOOL value is inverted.

Function Syntax	Input Data Type	Result Data Type	Description
X IS TRUE	BOOL	BOOL	Evaluates to TRUE if X evaluates to TRUE. Otherwise, evaluates to FALSE.
X IS NOT TRUE	BOOL	BOOL	Evaluates to FALSE if X evaluates to TRUE. Otherwise, evaluates to TRUE.
X IS FALSE	BOOL	BOOL	Evaluates to TRUE if X evaluates to FALSE. Otherwise, evaluates to FALSE.
X IS NOT FALSE	BOOL	BOOL	Evaluates to FALSE if X evaluates to FALSE. Otherwise, evaluates to TRUE.
X IS NULL	Any value type	BOOL	Evaluates to TRUE if X evaluates to NULL. Otherwise evaluates to FALSE.
X IS NOT NULL	Any value type	BOOL	Evaluates to FALSE if X evaluates to NULL. Otherwise evaluates to TRUE.
X IS UNKNOWN	BOOL	BOOL	Evaluates to TRUE if X evaluates to NULL. Otherwise evaluates to FALSE.
X IS NOT UNKNOWN	BOOL	BOOL	Evaluates to FALSE if X evaluates to NULL. Otherwise, evaluates to TRUE.

Concatenation operator

The concatenation operator combines multiple values into one.

Function Syntax	Input Data Type	Result Data Type
STRING || STRING [ || ... ]	STRING	STRING
BYTES || BYTES [ || ... ]	BYTES	STRING
ARRAY<T> || ARRAY<T> [ || ... ]	ARRAY<T>	ARRAY<T>