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.
- Unless otherwise specified, all operators return
NULLwhen one of the operands is
- All operators will throw an error if the computation result overflows.
- For all floating point operations,
NaNmay only be returned if one of the operands is
NaN. In other cases, an error is returned.
The following table lists all Cloud Spanner 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|
||Member field access operator||Binary|
|[ ]||ARRAY||Array position. Must be used with OFFSET or ORDINAL—see Array Functions .||Binary|
|2||-||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|
||All||Value is [not]
|IS [NOT] TRUE||BOOL||Value is [not] TRUE.||Unary|
|IS [NOT] FALSE||BOOL||Value is [not] FALSE.||Unary|
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 )
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
Element access operators
|Operator||Syntax||Input Data Types||Result Data Type||Description|
||Type T stored in fieldname1||Dot operator. Can be used to access nested fields, e.g.expression.fieldname1.fieldname2...|
|[ ]||array_expression [position_keyword (int_expression ) ]||See ARRAY Functions.||Type T stored in ARRAY||position_keyword is either OFFSET or ORDINAL. See Array Functions for the two functions that use this operator.|
All arithmetic operators accept input of numeric type T, and the result type has type T unless otherwise indicated in the description below:
|Addition||X + Y|
|Subtraction||X - Y|
|Multiplication||X * Y|
|Division||X / Y|
|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 and Multiplication:
Result types for Subtraction:
Result types for Division:
Result types for Unary Minus:
|Input Data Type||Result Data Type|
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
|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
|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.|
All logical operators allow only BOOL input.
|Logical NOT||NOT X||Returns FALSE if input is TRUE. Returns TRUE if input is FALSE. Returns
|Logical AND||X AND Y||Returns FALSE if at least one input is FALSE. Returns TRUE if both X and Y
are TRUE. Returns
|Logical OR||X OR Y||Returns FALSE if both X and Y are FALSE. Returns TRUE if at least one input
is TRUE. Returns
Comparisons always return BOOL. Comparisons generally require both operands to be of the same type. If operands are of different types, and if Cloud Spanner SQL can convert the values of those types to a common type without loss of precision, Cloud Spanner SQL will generally coerce them to that common type for the comparison; Cloud Spanner 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:
: All comparisons with NaN return FALSE,
<>, 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
|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
|IN||Multiple - see below||Returns FALSE if the right operand is empty. Returns
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
|Struct1||Struct2||Struct1 = Struct2|
IN operator supports the following syntaxes:
x [NOT] IN (y, z, ... ) # Requires at least one element x [NOT] IN (<subquery>) x [NOT] IN UNNEST(<array expression>) # analysis error if the expression # does not return an ARRAY type.
Arguments on either side of the
IN operator are general expressions.
It is common to use literals on the right side expression; however, this is not
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
x [NOT] IN UNNEST(<array expression>)
This form is often used with ARRAY parameters. For example:
x IN UNNEST(@array_parameter)
NULL ARRAY will be treated equivalently to an empty ARRAY.
See the Arrays topic for more information on how to use this syntax.
When using the
IN operator, the following semantics apply:
INwith an empty right side expression is always FALSE
NULLleft side expression and a non-empty right side expression is always
IN-list can only return TRUE or
NULL, never FALSE
NULL IN (NULL)returns
IN UNNEST(<NULL array>)returns FALSE (not
NOT INwith a
IN-list can only return FALSE or
NULL, never TRUE
IN can be used with multi-part keys by using the struct constructor syntax.
(Key1, Key2) IN ( (12,34), (56,78) ) (Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )
See the Struct Type section of the Data Types topic for more information on this syntax.
IS operators return TRUE or FALSE for the condition they are testing. They never
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 [NOT] NULL
|Any value type||BOOL||Returns TRUE if the operand X evaluates to
X IS [NOT] TRUE
|BOOL||BOOL||Returns TRUE if the BOOL operand evaluates to TRUE. Returns FALSE otherwise.|
X IS [NOT] FALSE
|BOOL||BOOL||Returns TRUE if the BOOL operand evaluates to FALSE. Returns FALSE otherwise.|
The concatenation operator combines multiple values into one.
|Function Syntax||Input Data Type||Result Data Type|
STRING || STRING [ || ... ]
BYTES || BYTES [ || ... ]
ARRAY<T> || ARRAY<T> [ || ... ]