We've reorganized our documentation navigation structure to align directly with your operational workflows. See the release notes and the walkthrough video for more information.

Operators

GoogleSQL for SecOps supports operators. Operators are represented by special characters or keywords; they don't 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	`STRUCT`	Field access operator	Binary
	Array subscript operator	`ARRAY`	Array position. Must be used with `OFFSET` or `ORDINAL`—see Array Functions .	Binary
2	`+`	All numeric types	Unary plus	Unary
3	`*`	All numeric types	Multiplication	Binary
	`/`	All numeric types	Division	Binary
4	`+`	All numeric types	Addition	Binary
	`-`	All numeric types	Subtraction	Binary
5 (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] DISTINCT FROM`	All	Value is [not] `DISTINCT FROM`	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
6	`NOT`	`BOOL`	Logical `NOT`	Unary
7	`AND`	`BOOL`	Logical `AND`	Binary
8	`OR`	`BOOL`	Logical `OR`	Binary

For example, the logical expression:

x OR y AND z

is interpreted as:

( x OR ( y AND z ) )

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 aren't associative. Therefore, parentheses are required to resolve ambiguity. For example:

(x < y) IS FALSE

Operator list

Name	Summary
Field access operator	Gets the value of a field.
Array subscript operator	Gets a value from an array at a specific position.
Arithmetic operators	Performs arithmetic operations.
Logical operators	Tests for the truth of some condition and produces `TRUE`, `FALSE`, or `NULL`.
Comparison operators	Compares operands and produces the results of the comparison as a `BOOL` value.
`EXISTS` operator	Checks if a subquery produces one or more rows.
`IN` operator	Checks for an equal value in a set of values.
`IS` operators	Checks for the truth of a condition and produces either `TRUE` or `FALSE`.
`IS DISTINCT FROM` operator	Checks if values are considered to be distinct from each other.
`LIKE` operator	Checks if values are like or not like one another.

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

Return type

For STRUCT: SQL data type of fieldname. If a field isn't found in the struct, an error is thrown.

Example

In the following example, the field access operations are .address and .country.

SELECT
  STRUCT(
    STRUCT('Yonge Street' AS street, 'Canada' AS country)
      AS address).address.country

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

Array subscript operator

array_expression "[" array_subscript_specifier "]"

array_subscript_specifier:
  { index | position_keyword(index) }

position_keyword:
  { OFFSET | SAFE_OFFSET | ORDINAL | SAFE_ORDINAL }

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. To produce NULL instead of an error, use SAFE_OFFSET(index). This position keyword produces the same result as index by itself.
- 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. To produce NULL instead of an error, use SAFE_ORDINAL(index).
- SAFE_ORDINAL(index): 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. If used by itself without a position keyword, the index starts at zero and produces an error if the index is out of range. To produce NULL instead of an error, use the SAFE_OFFSET(index) or SAFE_ORDINAL(index) position keyword.

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's out of range. If the SAFE prefix is included, NULL is returned, otherwise an error is produced.

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

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

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

-- Error. Array index 6 is out of bounds.
SELECT ["coffee", "tea", "milk"][6] AS item_offset

-- Error. Array index 6 is out of bounds.
SELECT ["coffee", "tea", "milk"][OFFSET(6)] AS item_offset

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`

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`

Logical operators

GoogleSQL 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`

The order of evaluation of operands to AND and OR can vary, and evaluation can be skipped if unnecessary.

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

Compares operands and produces the results of the comparison as a BOOL value. These comparison operators are available:

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` isn't 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`	See the `LIKE` operator for details.
`IN`	Multiple	See the `IN` operator for details.
`IS DISTINCT FROM`	`x IS [NOT] DISTINCT FROM y`	See the `IS DISTINCT FROM` operator for details.

The following rules apply to operands in a comparison operator:

The operands must be comparable.
A comparison operator generally requires both operands to be of the same type.
If the operands are of different types, and the values of those types can be converted to a common type without loss of precision, they are generally coerced to that common type for the comparison.
A literal operand is generally coerced to the same data type of a non-literal operand that's part of the comparison.
Struct operands support only these 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: Any operation with a NULL input returns NULL.

STRUCT: When testing a struct 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 aren't 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's 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 TRUE if value_set contains a value equal to search_value.
Returns NULL if the equality comparison between search_value and any value in value_set produces NULL.
Returns FALSE.

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

Returns TRUE if value_set is empty.
Returns FALSE if value_set contains a value equal to search_value.
Returns NULL if the equality comparison between search_value and any value in value_set produces NULL.
Returns TRUE.

For example:

1 IN UNNEST([NULL, 1]) returns TRUE
1 IN UNNEST([2, 3]) returns FALSE
1 [NOT] IN UNNEST([NULL]) returns NULL
(NULL, 1) [NOT] IN UNNEST([(NULL, 1)]) returns NULL
(NULL, 2) IN UNNEST([(NULL, 1)]) returns FALSE
(NULL, 2) NOT IN UNNEST([(NULL, 1)]) returns TRUE

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 topic 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
  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`.

`IS DISTINCT FROM` operator

expression_1 IS [NOT] DISTINCT FROM expression_2

Description

IS DISTINCT FROM returns TRUE if the input values are considered to be distinct from each other by the GROUP BY clause. Otherwise, returns FALSE.

a IS DISTINCT FROM b being TRUE is equivalent to:

SELECT * FROM UNNEST([a,b]) x GROUP BY x returning 2 rows.

a IS DISTINCT FROM b is equivalent to NOT (a = b), except for the following cases:

This operator never returns NULL so NULL values are considered to be distinct from non-NULL values, not other NULL values.
NaN values are considered to be distinct from non-NaN values, but not other NaN values.

You can use this operation with fields in a complex data type, but not on the complex data types themselves. These complex data types can't be compared directly:

STRUCT
ARRAY

Input values:

expression_1: The first value to compare. This can be a groupable data type, NULL or NaN.
expression_2: The second value to compare. This can be a groupable data type, NULL or NaN.
NOT: If present, the output BOOL value is inverted.

Return type

BOOL

Examples

These return TRUE:

SELECT 1 IS DISTINCT FROM 2

SELECT 1 IS DISTINCT FROM NULL

SELECT 1 IS NOT DISTINCT FROM 1

SELECT NULL IS NOT DISTINCT FROM NULL

These return FALSE:

SELECT NULL IS DISTINCT FROM NULL

SELECT 1 IS DISTINCT FROM 1

SELECT 1 IS NOT DISTINCT FROM 2

SELECT 1 IS NOT DISTINCT FROM NULL

`LIKE` operator

expression [NOT] LIKE pattern

Description

LIKE returns TRUE if the string in the first operand expression matches a pattern specified by the second operand pattern, otherwise returns FALSE.

NOT LIKE returns TRUE if the string in the first operand expression doesn't match a pattern specified by the second operand pattern, otherwise returns FALSE.

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'\%'.

Return type

BOOL

Examples

The following examples illustrate how you can check to see if the string in the first operand matches a pattern specified by the second operand.

-- Returns TRUE
SELECT 'apple' LIKE 'a%';

-- Returns FALSE
SELECT '%a' LIKE 'apple';

-- Returns FALSE
SELECT 'apple' NOT LIKE 'a%';

-- Returns TRUE
SELECT '%a' NOT LIKE 'apple';

-- Produces an error
SELECT NULL LIKE 'a%';

-- Produces an error
SELECT 'apple' LIKE NULL;

The following example illustrates how to search multiple patterns in an array to find a match with the LIKE operator:

WITH Words AS
 (SELECT 'Intend with clarity.' as value UNION ALL
  SELECT 'Secure with intention.' UNION ALL
  SELECT 'Clarity and security.')
SELECT value
FROM Words WHERE
  EXISTS(
    SELECT value FROM UNNEST(['%ity%', '%and%']) AS pattern
    WHERE value LIKE pattern
  );

/*------------------------+
 | value                  |
 +------------------------+
 | Intend with clarity.   |
 | Clarity and security.  |
 +------------------------*/

Operators Stay organized with collections Save and categorize content based on your preferences.

Operator precedence

Operator list

Field access operator

Array subscript operator

Arithmetic operators

Logical operators

Comparison operators

EXISTS operator

IN operator

IS operators

IS DISTINCT FROM operator

LIKE operator

Operators

`EXISTS` operator

`IN` operator

`IS` operators

`IS DISTINCT FROM` operator

`LIKE` operator