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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Equal | Binary |
|   | `<` | Any comparable type. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Less than | Binary |
|   | `>` | Any comparable type. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Greater than | Binary |
|   | `<=` | Any comparable type. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Less than or equal to | Binary |
|   | `>=` | Any comparable type. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Greater than or equal to | Binary |
|   | `!=`, `<>` | Any comparable type. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Value is \[not\] within the range specified | Binary |
|   | `[NOT] IN` | Any comparable types. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Value is \[not\] in the set of values specified | Binary |
|   | General quantified comparisons | Any comparable types. See [Data Types](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types) for a complete list. | Compares a search value to a set of values. | 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#field_access_operator) | Gets the value of a field. |
| [Array subscript operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#array_subscript_operator) | Gets a value from an array at a specific position. |
| [Arithmetic operators](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#arithmetic_operators) | Performs arithmetic operations. |
| [Logical operators](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#logical_operators) | Tests for the truth of some condition and produces `TRUE`, `FALSE`, or `NULL`. |
| [Comparison operators](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#comparison_operators) | Compares operands and produces the results of the comparison as a `BOOL` value. |
| [`EXISTS` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#exists_operator) | Checks if a subquery produces one or more rows. |
| [`IN` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#in_operators) | Checks for an equal value in a set of values. |
| [`IS` operators](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#is_operators) | Checks for the truth of a condition and produces either `TRUE` or `FALSE`. |
| [`IS DISTINCT FROM` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#is_distinct) | Checks if values are considered to be distinct from each other. |
| [`LIKE` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#like_operator) | Checks if values are like or not like one another. |
| [General quantified comparisons](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#general_quantified_comparisons) | Compares a search value to a set of values. |

### 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

> [!NOTE]
> **Note:** Syntax characters enclosed in double quotes (`""`) are literal and required.

    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.

> [!TIP]
> **Tip:** To access the first or last element in an array, use the [`ARRAY_FIRST`](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/array_functions#array_first) or [`ARRAY_LAST`](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/array_functions#array_last) function.

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

> [!NOTE]
> **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` |
|---|---|---|---|

### Logical operators

GoogleSQL supports the `AND`, `OR`, and `NOT` logical operators.
Logical operators allow only `BOOL` or `NULL` input
and use [three-valued logic](https://en.wikipedia.org/wiki/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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#like_operator) for details. |
| `IN` | Multiple | See the [`IN` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#in_operator) for details. |
| `IS DISTINCT FROM` | `x IS [NOT] DISTINCT FROM y` | See the [`IS DISTINCT FROM` operator](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#is_distinct) for details. |

The following rules apply to operands in a comparison operator:

- The operands must be [comparable](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types#comparable_data_types).
- 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/subqueries#exists_subquery_concepts).

**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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#semantic_rules_in) 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/subqueries#about_subqueries) 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/query-syntax#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`](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/query-syntax#from_clause) 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/arrays#filtering_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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/data-types#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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/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`](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/query-syntax#group_by_clause) 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.  |
     +---*/

### General quantified comparisons

General quantified comparisons support the following syntax:

    expression comparison_operator quantifier value_set

    comparison_operator:
      { = | != | <> | < | <= | > | >= }

    quantifier:
      { ANY | SOME | ALL }

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

**Description**

Compares an expression to a set of values using a comparison operator and a
quantifier.

[Semantic rules](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/operators#semantic_rules_general_quantified_comparisons) apply, but in
general, the quantifiers behave as follows:

- An `ANY` or `SOME` comparison returns `TRUE` if the comparison evaluates to `TRUE` for at least one value in `value_set`, `FALSE` if the comparison evaluates to `FALSE` for all values in `value_set`, or otherwise `NULL`.
- An `ALL` comparison returns `TRUE` if the comparison evaluates to `TRUE` for all values in `value_set`, `FALSE` if the comparison evaluates to `FALSE` for at least one value in `value_set`, or otherwise `NULL`.

**Definitions**

- `expression`: The value that's compared to a set of values.
- `comparison_operator`: The comparison operator used to compare `expression` to each value in `value_set`. Supported operators include `=`, `!=`, `<>`, `<`, `<=`, `>`, and `>=`.
- `quantifier`: Condition for the comparison:
  - `ANY`: Checks if the comparison evaluates to `TRUE` for at least one value in `value_set`.
  - `SOME`: Synonym for `ANY`.
  - `ALL`: Checks if the comparison evaluates to `TRUE` for all values in `value_set`.
- `value_set`: One or more values to compare to `expression`. Supported forms:
  - `(expression[, ...])`: A list of expressions.
  - `(subquery)`: A [subquery](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/subqueries#about_subqueries) 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](https://docs.cloud.google.com/chronicle/docs/reference/standard-sql/query-syntax#unnest_operator) that returns a column of values from an array expression.

**Semantic rules**

When using a general quantified comparison with `ANY` or `SOME`, the following
semantics apply in this order:

1. Returns `FALSE` if `value_set` is empty.
2. Returns `TRUE` if `expression comparison_operator value` evaluates to `TRUE` for at least one value in `value_set`.
3. Returns `FALSE` if `expression comparison_operator value` evaluates to `FALSE` for all values in `value_set`.
4. Returns `NULL`.

When using a general quantified comparison with `ALL`, the following semantics
apply in this order:

1. Returns `TRUE` if `value_set` is empty.
2. Returns `TRUE` if `expression comparison_operator value` evaluates to `TRUE` for all values in `value_set`.
3. Returns `FALSE` if `expression comparison_operator value` evaluates to `FALSE` for at least one value in `value_set`.
4. Returns `NULL`.

Conceptually, `ANY` (or `SOME`) behaves like a chain of `OR` expressions, and
`ALL` behaves like a chain of `AND` expressions.

The semantics of:

    x comparison_operator { ANY | SOME } (y, z, ...)

are defined as equivalent to:

    FALSE OR (x comparison_operator y) OR (x comparison_operator z) OR ...

The semantics of:

    x comparison_operator ALL (y, z, ...)

are defined as equivalent to:

    TRUE AND (x comparison_operator y) AND (x comparison_operator z) AND ...

The subquery and array forms are defined similarly.

**Return data type**

`BOOL`

**Examples**

You can use this `WITH` clause to emulate a temporary table for `Numbers` in the
following examples:

    WITH Numbers AS (
      SELECT 1 AS x UNION ALL
      SELECT 2 UNION ALL
      SELECT 3 UNION ALL
      SELECT 4 UNION ALL
      SELECT 5
    )
    SELECT * FROM Numbers;

    /*---+
     | x |
     +---+
     | 1 |
     | 2 |
     | 3 |
     | 4 |
     | 5 |
     +---*/

Example with `= ANY` and an expression list:

    SELECT x FROM Numbers WHERE x = ANY (2, 4);

    /*---+
     | x |
     +---+
     | 2 |
     | 4 |
     +---*/

Example with `> ALL` and an expression list:

    SELECT x FROM Numbers WHERE x > ALL (2, 3);

    /*---+
     | x |
     +---+
     | 4 |
     | 5 |
     +---*/

Example with `< ANY` and a subquery:

    WITH
      Numbers AS (
        SELECT 1 AS x UNION ALL
        SELECT 2 UNION ALL
        SELECT 3 UNION ALL
        SELECT 4 UNION ALL
        SELECT 5
      ),
      Targets AS (
        SELECT 3 AS target
      )
    SELECT x FROM Numbers WHERE x < ANY (SELECT target FROM Targets);

    /*---+
     | x |
     +---+
     | 1 |
     | 2 |
     +---*/

Example with `!= ALL` and an `UNNEST` operation:

    SELECT x FROM Numbers WHERE x != ALL UNNEST([1, 2, 3, 4]);

    /*---+
     | x |
     +---+
     | 5 |
     +---*/

The following queries illustrate the semantic rules and three-valued logic for
general quantified comparisons:

    SELECT
      5 = ANY (1, 5, 10) AS a,    -- TRUE: At least one comparison (5 = 5) is TRUE.
      5 = ANY (1, 2, 3) AS b,     -- FALSE: All comparisons evaluate to FALSE.
      5 = ANY (1, NULL, 5) AS c,  -- TRUE: 5 = 5 is TRUE, regardless of NULL.
      5 = ANY (1, NULL, 2) AS d,  -- NULL: No comparison is TRUE and 5 = NULL is NULL.

      5 = ALL (5, 5) AS e,        -- TRUE: All comparisons evaluate to TRUE.
      5 = ALL (5, 10) AS f,       -- FALSE: At least one comparison (5 = 10) is FALSE.
      5 = ALL (5, NULL) AS g,     -- NULL: No comparison is FALSE and 5 = NULL is NULL.
      5 = ALL (1, NULL) AS h;     -- FALSE: 5 = 1 is FALSE, regardless of NULL.

The following queries illustrate the behavior of empty value sets:

    SELECT
      5 = ANY UNNEST([]) AS any_empty,  -- FALSE
      5 = ALL UNNEST([]) AS all_empty;  -- TRUE