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 isNULL
. - All operators will throw an error if the computation result overflows.
- For all floating point operations,
+/-inf
andNaN
may only be returned if one of the operands is+/-inf
orNaN
. 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 offieldname
. 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 SQLNULL
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 }
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. ReturnsNULL
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. ReturnsNULL
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]
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
: TheJSON
expression that contains an array element or field to return.[array_element_id]
: AnINT64
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 SQLNULL
is returned.[field_name]
: ASTRING
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 SQLNULL
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 aNULL
input returnsNULL
.
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:
|
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)
When using the IN
operator, the following semantics apply in this order:
- Returns
FALSE
ifvalue_set
is empty. - Returns
NULL
ifsearch_value
isNULL
. - Returns
TRUE
ifvalue_set
contains a value equal tosearch_value
. - Returns
NULL
ifvalue_set
contains aNULL
. - Returns
FALSE
.
When using the NOT IN
operator, the following semantics apply in this order:
- Returns
TRUE
ifvalue_set
is empty. - Returns
NULL
ifsearch_value
isNULL
. - Returns
FALSE
ifvalue_set
contains a value equal tosearch_value
. - Returns
NULL
ifvalue_set
contains aNULL
. - 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> |