Operators

ZetaSQL supports operators. 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 ZetaSQL operators from highest to lowest precedence, i.e., the order in which they will be evaluated within a statement.

<tr>
  <td>&nbsp;</td>
  <td>Array elements field access operator</td>
  <td><code>ARRAY</code></td>
  <td>Field access operator for elements in an array</td>
  <td>Binary</td>
</tr>

<tr>
  <td>&nbsp;</td>
  <td>Array subscript operator</td>
  <td><code>ARRAY</code></td>
  <td>Array position. Must be used with <code>OFFSET</code> or <code>ORDINAL</code>&mdash;see
  <a href="https://github.com/google/zetasql/blob/master/docs/array_functions.md">Array Functions</a>

.

<tr>
  <td>&nbsp;</td>
  <td>JSON subscript operator</td>
  <td><code>JSON</code></td>
  <td>Field name or array position in JSON.</td>
  <td>Binary</td>
</tr>

<tr>
  <td>2</td>
  <td><code>+</code></td>
  <td>All numeric types</td>
  <td>Unary plus</td>
  <td>Unary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>-</code></td>
  <td>All numeric types</td>
  <td>Unary minus</td>
  <td>Unary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>~</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise not</td>
  <td>Unary</td>
</tr>
<tr>
  <td>3</td>
  <td><code>*</code></td>
  <td>All numeric types</td>
  <td>Multiplication</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>/</code></td>
  <td>All numeric types</td>
  <td>Division</td>
  <td>Binary</td>
</tr>

<tr>
  <td>&nbsp;</td>
  <td><code>||</code></td>
  <td><code>STRING</code>, <code>BYTES</code>, or <code>ARRAY&#60;T&#62;</code></td>
  <td>Concatenation operator</td>
  <td>Binary</td>
</tr>

<tr>
  <td>4</td>
  <td><code>+</code></td>
  <td>
    All numeric types, <code>DATE</code> with
    <code>INT64</code>
    , <code>INTERVAL</code>
  </td>
  <td>Addition</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>-</code></td>
  <td>
    All numeric types, <code>DATE</code> with
    <code>INT64</code>
    , <code>INTERVAL</code>
  </td>
  <td>Subtraction</td>
  <td>Binary</td>
</tr>
<tr>
  <td>5</td>
  <td><code>&lt;&lt;</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise left-shift</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>&gt;&gt;</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise right-shift</td>
  <td>Binary</td>
</tr>
<tr>
  <td>6</td>
  <td><code>&amp;</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise and</td>
  <td>Binary</td>
</tr>
<tr>
  <td>7</td>
  <td><code>^</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise xor</td>
  <td>Binary</td>
</tr>
<tr>
  <td>8</td>
  <td><code>|</code></td>
  <td>Integer or <code>BYTES</code></td>
  <td>Bitwise or</td>
  <td>Binary</td>
</tr>
<tr>
  <td>9 (Comparison Operators)</td>
  <td><code>=</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Equal</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>&lt;</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Less than</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>&gt;</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Greater than</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>&lt;=</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Less than or equal to</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>&gt;=</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Greater than or equal to</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>!=</code>, <code>&lt;&gt;</code></td>
  <td>Any comparable type. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Not equal</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>[NOT] LIKE</code></td>
  <td><code>STRING</code> and <code>BYTES</code></td>
  <td>Value does [not] match the pattern specified</td>
  <td>Binary</td>
</tr>

<tr>
  <td>&nbsp;</td>
  <td><code>[NOT] BETWEEN</code></td>
  <td>Any comparable types. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Value is [not] within the range specified</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>[NOT] IN</code></td>
  <td>Any comparable types. See
  <a href="https://github.com/google/zetasql/blob/master/docs/data-types.md">Data Types</a>

  for a complete list.</td>
  <td>Value is [not] in the set of values specified</td>
  <td>Binary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>IS [NOT] NULL</code></td>
  <td>All</td>
  <td>Value is [not] <code>NULL</code></td>
  <td>Unary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>IS [NOT] TRUE</code></td>
  <td><code>BOOL</code></td>
  <td>Value is [not] <code>TRUE</code>.</td>
  <td>Unary</td>
</tr>
<tr>
  <td>&nbsp;</td>
  <td><code>IS [NOT] FALSE</code></td>
  <td><code>BOOL</code></td>
  <td>Value is [not] <code>FALSE</code>.</td>
  <td>Unary</td>
</tr>
<tr>
  <td>10</td>
  <td><code>NOT</code></td>
  <td><code>BOOL</code></td>
  <td>Logical <code>NOT</code></td>
  <td>Unary</td>
</tr>
<tr>
  <td>11</td>
  <td><code>AND</code></td>
  <td><code>BOOL</code></td>
  <td>Logical <code>AND</code></td>
  <td>Binary</td>
</tr>
<tr>
  <td>12</td>
  <td><code>OR</code></td>
  <td><code>BOOL</code></td>
  <td>Logical <code>OR</code></td>
  <td>Binary</td>
</tr>

Order of Precedence	Operator	Input Data Types	Name	Operator Arity
1	Field access operator	`STRUCT` `PROTO` `JSON`	Field access operator	Binary
Binary
	Quantified LIKE	`STRING` and `BYTES`	Checks a search value for matches against several patterns.	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 are not 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.
Struct subscript operator	Gets the value of a field at a selected position in a struct.
JSON subscript operator	Gets a value of an array element or field in a JSON expression.
Protocol buffer map subscript operator	Gets the value in a protocol buffer map for a given key.
Array elements field access operator	Traverses through the levels of a nested data type inside an array.
Arithmetic operators	Performs arithmetic operations.
Date arithmetics operators	Performs arithmetic operations on dates.
Datetime subtraction	Computes the difference between two datetimes as an interval.
Interval arithmetic operators	Adds an interval to a datetime or subtracts an interval from a datetime.
Bitwise operators	Performs bit manipulation.
Logical operators	Tests for the truth of some condition and produces `TRUE`, `FALSE`, or `NULL`.
Graph concatenation operator	Combines multiple graph paths into one and preserves the original order of the nodes and edges.
Graph logical operators	Tests for the truth of a condition in a graph and produces either `TRUE` or `FALSE`.
Graph predicates	Tests for the truth of a condition for a graph element and produces `TRUE`, `FALSE`, or `NULL`.
`IS DESTINATION` predicate	In a graph, checks to see if a node is or isn't the destination of an edge.
`IS SOURCE` predicate	In a graph, checks to see if a node is or isn't the source of an edge.
`PROPERTY_EXISTS` predicate	In a graph, checks to see if a property exists for an element.
`SAME` predicate	In a graph, determines if all graph elements in a list bind to the same node or edge.
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.
Quantified `LIKE` operator	Checks a search value for matches against several patterns.
`NEW` operator	Creates a protocol buffer.
Concatenation operator	Combines multiple values into one.
`WITH` expression	Creates variables for re-use and produces a result expression.

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
PROTO
JSON
GRAPH_ELEMENT

Note: If the field to access is within a STRUCT, you can use the struct subscript operator to access the field by its position within the STRUCT instead of by its name. Accessing by a field by position is useful when fields are un-named or have ambiguous names.

Return type

For STRUCT: SQL data type of fieldname. If a field is not found in the struct, an error is thrown.
For PROTO: SQL data type of fieldname. If a field is not found in the protocol buffer, an error is thrown.
For JSON: JSON. If a field is not found in a JSON value, a SQL NULL is returned.
For GRAPH_ELEMENT: SQL data type of fieldname. If a field (property) is not found in the graph element, an error is produced.

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: Syntax wrapped in double quotes ("") is 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.

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 is 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 is out of range in an array, and a positional keyword that begins with SAFE is not 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

Struct subscript operator

Note: Syntax wrapped in double quotes ("") is required.

struct_expression "[" struct_subscript_specifier "]"

struct_subscript_specifier:
  { index | position_keyword(index) }

position_keyword:
  { OFFSET | ORDINAL }

Description

Gets the value of a field at a selected position in a struct.

Input types

struct_expression: The input struct.
position_keyword(index): Determines where the index for the struct should start and how out-of-range indexes are handled. The index is an integer literal or constant that represents a specific position in the struct.
- OFFSET(index): The index starts at zero. Produces an error if the index is out of range. Produces the same result as index by itself.
- ORDINAL(index): The index starts at one. Produces an error if the index is out of range.
index: An integer literal or constant that represents a specific position in the struct. If used by itself without a position keyword, the index starts at zero and produces an error if the index is out of range.

Note: The struct subscript operator doesn't support SAFE positional keywords at this time.

Examples

In following query, the struct subscript operator is used to return values at specific locations in item_struct using position keywords. This query also shows what happens when you reference an index (6) in an struct that is out of range.

SELECT
  STRUCT<INT64, STRING, BOOL>(23, "tea", FALSE)[0] AS field_index,
  STRUCT<INT64, STRING, BOOL>(23, "tea", FALSE)[OFFSET(0)] AS field_offset,
  STRUCT<INT64, STRING, BOOL>(23, "tea", FALSE)[ORDINAL(1)] AS field_ordinal

/*-------------+--------------+---------------*
 | field_index | field_offset | field_ordinal |
 +-------------+--------------+---------------+
 | 23          | 23           | 23            |
 *-------------+--------------+---------------*/

When you reference an index that is out of range in a struct, an error is produced. For example:

-- Error: Field ordinal 6 is out of bounds in STRUCT
SELECT STRUCT<INT64, STRING, BOOL>(23, "tea", FALSE)[6] AS field_offset

-- Error: Field ordinal 6 is out of bounds in STRUCT
SELECT STRUCT<INT64, STRING, BOOL>(23, "tea", FALSE)[OFFSET(6)] AS field_offset

JSON subscript operator

Note: Syntax wrapped in double quotes ("") is required.

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 values:

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"          |
 *-----------------*/

Protocol buffer map subscript operator

proto_map_field_expression[proto_subscript_specifier]

proto_subscript_specifier:
  key_name | key_keyword(key_name)

key_keyword:
  { KEY | SAFE_KEY }

Description

Returns the value in a protocol buffer map for a given key.

Input values:

proto_map_field_expression: A protocol buffer map field.
key_keyword(key_name): Determines whether to produce NULL or an error if the key is not present in the protocol buffer map field.
- KEY(key_name): Returns an error if the key is not present in the protocol buffer map field.
- SAFE_KEY(key_name): Returns NULL if the key is not present in the protocol buffer map field.
- key_name: When key_name is provided without a wrapping keyword, it is the same as KEY(key_name).
key_name: The key in the protocol buffer map field. This operator returns NULL if the key is NULL.

Return type

In the input protocol buffer map field, V as represented in map<K,V>.

Examples

To illustrate the use of this function, we use the protocol buffer message Item.

message Item {
  optional map<string, int64> purchased = 1;
};

In the following example, the subscript operator returns the value when the key is present.

SELECT
  m.purchased[KEY('A')] AS map_value
FROM
  (SELECT AS VALUE CAST("purchased { key: 'A' value: 2 }" AS Item)) AS m;

/*-----------*
 | map_value |
 +-----------+
 | 2         |
 *-----------*/

When the key does not exist in the map field and you use KEY, an error is produced. For example:

-- ERROR: Key not found in map: 2
SELECT
  m.purchased[KEY('B')] AS value
FROM
  (SELECT AS VALUE CAST("purchased { key: 'A' value: 2 }" AS Item)) AS m;

When the key does not exist in the map field and you use SAFE_KEY, the subscript operator returns NULL. For example:

SELECT
  CAST(m.purchased[SAFE_KEY('B')] AS safe_key_missing
FROM
  (SELECT AS VALUE CAST("purchased { key: 'A' value: 2 }" AS Item)) AS m;

/*------------------*
 | safe_key_missing |
 +------------------+
 | NULL             |
 *------------------*/

The subscript operator returns NULL when the map field or key is NULL. For example:

SELECT
  CAST(NULL AS Item).purchased[KEY('A')] AS null_map,
  m.purchased[KEY(NULL)] AS null_key
FROM
  (SELECT AS VALUE CAST("purchased { key: 'A' value: 2 }" AS Item)) AS m;

/*-----------------------*
 | null_map  | null_key  |
 +-----------------------+
 | NULL      | NULL      |
 *-----------------------*/

When a key is used without KEY() or SAFE_KEY(), it has the same behavior as if KEY() had been used. For example:

SELECT
  m.purchased['A'] AS map_value
FROM
  (SELECT AS VALUE CAST("purchased { key: 'A' value: 2 }" AS Item)) AS m;

/*-----------*
 | map_value |
 +-----------+
 | 2         |
 *-----------*/

Array elements field access operator

Note: Syntax wrapped in double quotes ("") is required.

array_expression.field_or_element[. ...]

field_or_element:
  { fieldname | array_element }

array_element:
  array_fieldname "[" array_subscript_specifier "]"

Description

The array elements field access operation lets you traverse through the levels of a nested data type inside an array.

Input values:

array_expression: An expression that evaluates to an array value.
field_or_element[. ...]: The field to access. This can also be a position in an array-typed field.
fieldname: The name of the field to access.

For example, this query returns all values for the items field inside of the my_array array expression:
```
WITH MyTable AS ( SELECT [STRUCT(['foo', 'bar'] AS items)] AS my_array )
SELECT FLATTEN(my_array.items)
FROM MyTable
```
These data types have fields:
- STRUCT
- PROTO
- JSON
array_element: If the field to access is an array field (array_field), you can additionally access a specific position in the field with the array subscript operator ([array_subscript_specifier]). This operation returns only elements at a selected position, rather than all elements, in the array field.

For example, this query only returns values at position 0 in the items array field:
```
WITH MyTable AS ( SELECT [STRUCT(['foo', 'bar'] AS items)] AS my_array )
SELECT FLATTEN(my_array.items[OFFSET(0)])
FROM MyTable
```

Details:

The array elements field access operation is not a typical expression that returns a typed value; it represents a concept outside the type system and can only be interpreted by the following operations:

FLATTEN operation: Returns an array. For example:
```
FLATTEN(my_array.sales.prices)
```
UNNEST operation: Returns a table. array_expression must be a path expression. Implicitly implements the FLATTEN operator. For example, these do the same thing:
```
UNNEST(my_array.sales.prices)
```
```
UNNEST(FLATTEN(my_array.sales.prices))
```

FROM clause: Returns a table. array_expression must be a path expression. Implicitly implements the UNNEST operator and the FLATTEN operator. For example, these unnesting operations produce the same values for results:

SELECT results FROM SalesTable, SalesTable.my_array.sales.prices AS results;

SELECT results FROM SalesTable, UNNEST(my_array.sales.prices) AS results;

SELECT results FROM SalesTable, UNNEST(FLATTEN(my_array.sales.prices)) AS results;

If NULL array elements are encountered, they are added to the resulting array.

Common shapes of this operation

This operation can take several shapes. The right-most value in the operation determines what type of array is returned. Here are some example shapes and a description of what they return:

The following shapes extract the final non-array field from each element of an array expression and return an array of those non-array field values.

array_expression.non_array_field_1
array_expression.non_array_field_1.array_field.non_array_field_2

The following shapes extract the final array field from each element of the array expression and concatenate the array fields together. An empty array or a NULL array contributes no elements to the resulting array.

array_expression.non_array_field_1.array_field_1
array_expression.non_array_field_1.array_field_1.non_array_field_2.array_field_2
array_expression.non_array_field_1.non_array_field_2.array_field_1

The following shapes extract the final array field from each element of the array expression at a specific position. Then they return an array of those extracted elements. An empty array or a NULL array contributes no elements to the resulting array.

array_expression.non_array_field_1.array_field_1[OFFSET(1)]
array_expression.non_array_field_1.array_field_1[SAFE_OFFSET(1)]
array_expression.non_array_field_1.non_array_field_2.array_field_1[ORDINAL(2)]
array_expression.non_array_field_1.non_array_field_2.array_field_1[SAFE_ORDINAL(2)]

Return Value

FLATTEN of an array element access operation returns an array.
UNNEST of an array element access operation, whether explicit or implicit, returns a table.

Examples

The next examples in this section reference a table called SalesTable, that contains a nested struct in an array called my_array:

WITH
  SalesTable AS (
    SELECT
      [
        STRUCT(
          [
            STRUCT([25.0, 75.0] AS prices),
            STRUCT([30.0] AS prices)
          ] AS sales
        )
      ] AS my_array
  )
SELECT * FROM SalesTable;

/*----------------------------------------------*
 | my_array                                     |
 +----------------------------------------------+
 | [{[{[25, 75] prices}, {[30] prices}] sales}] |
 *----------------------------------------------*/

This is what the array elements field access operator looks like in the FLATTEN operator:

SELECT FLATTEN(my_array.sales.prices) AS all_prices FROM SalesTable;

/*--------------*
 | all_prices   |
 +--------------+
 | [25, 75, 30] |
 *--------------*/

This is how you use the array subscript operator to only return values at a specific index in the prices array:

SELECT FLATTEN(my_array.sales.prices[OFFSET(0)]) AS first_prices FROM SalesTable;

/*--------------*
 | first_prices |
 +--------------+
 | [25, 30]     |
 *--------------*/

This is an example of an explicit UNNEST operation that includes the array elements field access operator:

SELECT all_prices FROM SalesTable, UNNEST(my_array.sales.prices) AS all_prices

/*------------*
 | all_prices |
 +------------+
 | 25         |
 | 75         |
 | 30         |
 *------------*/

This is an example of an implicit UNNEST operation that includes the array elements field access operator:

SELECT all_prices FROM SalesTable, SalesTable.my_array.sales.prices AS all_prices

/*------------*
 | all_prices |
 +------------+
 | 25         |
 | 75         |
 | 30         |
 *------------*/

This query produces an error because one of the prices arrays does not have an element at index 1 and OFFSET is used:

SELECT FLATTEN(my_array.sales.prices[OFFSET(1)]) AS second_prices FROM SalesTable;

-- Error

This query is like the previous query, but SAFE_OFFSET is used. This produces a NULL value instead of an error.

SELECT FLATTEN(my_array.sales.prices[SAFE_OFFSET(1)]) AS second_prices FROM SalesTable;

/*---------------*
 | second_prices |
 +---------------+
 | [75, NULL]    |
 *---------------*/

In this next example, an empty array and a NULL field value have been added to the query. These contribute no elements to the result.

WITH
  SalesTable AS (
    SELECT
      [
        STRUCT(
          [
            STRUCT([25.0, 75.0] AS prices),
            STRUCT([30.0] AS prices),
            STRUCT(ARRAY<DOUBLE>[] AS prices),
            STRUCT(NULL AS prices)
          ] AS sales
        )
      ] AS my_array
  )
SELECT FLATTEN(my_array.sales.prices) AS first_prices FROM SalesTable;

/*--------------*
 | first_prices |
 +--------------+
 | [25, 75, 30] |
 *--------------*/

The next examples in this section reference a protocol buffer called Album that looks like this:

message Album {
  optional string album_name = 1;
  repeated string song = 2;
  oneof group_name {
    string solo = 3;
    string duet = 4;
    string band = 5;
  }
}

Nested data is common in protocol buffers that have data within repeated messages. The following example extracts a flattened array of songs from a table called AlbumList that contains a column called Album of type PROTO.

WITH
  AlbumList AS (
    SELECT
      [
        NEW Album(
          'One Way' AS album_name,
          ['North', 'South'] AS song,
          'Crossroads' AS band),
        NEW Album(
          'After Hours' AS album_name,
          ['Snow', 'Ice', 'Water'] AS song,
          'Sunbirds' AS band)]
        AS albums_array
  )
SELECT FLATTEN(albums_array.song) AS songs FROM AlbumList

/*------------------------------*
 | songs                        |
 +------------------------------+
 | [North,South,Snow,Ice,Water] |
 *------------------------------*/

The following example extracts a flattened array of album names, one album name per row. The data comes from a table called AlbumList that contains a proto-typed column called Album.

WITH
  AlbumList AS (
    SELECT
      [
        (
          SELECT
            NEW Album(
              'One Way' AS album_name,
              ['North', 'South'] AS song,
              'Crossroads' AS band) AS album_col
        ),
        (
          SELECT
            NEW Album(
              'After Hours' AS album_name,
              ['Snow', 'Ice', 'Water'] AS song,
              'Sunbirds' AS band) AS album_col
        )]
        AS albums_array
  )
SELECT names FROM AlbumList, UNNEST(albums_array.album_name) AS names

/*----------------------*
 | names                |
 +----------------------+
 | One Way              |
 | After Hours          |
 *----------------------*/

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 and Multiplication:

INPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`
`INT32`	`INT64`	`INT64`	`INT64`	ERROR	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`INT64`	`INT64`	`INT64`	`INT64`	ERROR	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT32`	`INT64`	`INT64`	`UINT64`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT64`	ERROR	ERROR	`UINT64`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`FLOAT`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`
`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`

Result types for Subtraction:

INPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`
`INT32`	`INT64`	`INT64`	`INT64`	ERROR	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`INT64`	`INT64`	`INT64`	`INT64`	ERROR	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT32`	`INT64`	`INT64`	`INT64`	`INT64`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT64`	ERROR	ERROR	`INT64`	`INT64`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`FLOAT`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`
`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`

Result types for Division:

INPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`
`INT32`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`INT64`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT32`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`UINT64`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`NUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`BIGNUMERIC`	`DOUBLE`	`DOUBLE`
`FLOAT`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`
`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`	`DOUBLE`

Result types for Unary Plus:

INPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`
OUTPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`

Result types for Unary Minus:

INPUT	`INT32`	`INT64`	`UINT32`	`UINT64`	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`
OUTPUT	`INT32`	`INT64`	ERROR	ERROR	`NUMERIC`	`BIGNUMERIC`	`FLOAT`	`DOUBLE`

Date arithmetics operators

Operators '+' and '-' can be used for arithmetic operations on dates.

date_expression + int64_expression
int64_expression + date_expression
date_expression - int64_expression

Description

Adds or subtracts int64_expression days to or from date_expression. This is equivalent to DATE_ADD or DATE_SUB functions, when interval is expressed in days.

Return Data Type

DATE

Example

SELECT DATE "2020-09-22" + 1 AS day_later, DATE "2020-09-22" - 7 AS week_ago

/*------------+------------*
 | day_later  | week_ago   |
 +------------+------------+
 | 2020-09-23 | 2020-09-15 |
 *------------+------------*/

Datetime subtraction

date_expression - date_expression
timestamp_expression - timestamp_expression
datetime_expression - datetime_expression

Description

Computes the difference between two datetime values as an interval.

Return Data Type

INTERVAL

Example

SELECT
  DATE "2021-05-20" - DATE "2020-04-19" AS date_diff,
  TIMESTAMP "2021-06-01 12:34:56.789" - TIMESTAMP "2021-05-31 00:00:00" AS time_diff

/*-------------------+------------------------*
 | date_diff         | time_diff              |
 +-------------------+------------------------+
 | 0-0 396 0:0:0     | 0-0 0 36:34:56.789     |
 *-------------------+------------------------*/

Interval arithmetic operators

Addition and subtraction

date_expression + interval_expression = DATETIME
date_expression - interval_expression = DATETIME
timestamp_expression + interval_expression = TIMESTAMP
timestamp_expression - interval_expression = TIMESTAMP
datetime_expression + interval_expression = DATETIME
datetime_expression - interval_expression = DATETIME

Description

Adds an interval to a datetime value or subtracts an interval from a datetime value.

Example

SELECT
  DATE "2021-04-20" + INTERVAL 25 HOUR AS date_plus,
  TIMESTAMP "2021-05-02 00:01:02.345" - INTERVAL 10 SECOND AS time_minus;

/*-------------------------+--------------------------------*
 | date_plus               | time_minus                     |
 +-------------------------+--------------------------------+
 | 2021-04-21 01:00:00     | 2021-05-02 00:00:52.345+00     |
 *-------------------------+--------------------------------*/

Multiplication and division

interval_expression * integer_expression = INTERVAL
interval_expression / integer_expression = INTERVAL

Description

Multiplies or divides an interval value by an integer.

Example

SELECT
  INTERVAL '1:2:3' HOUR TO SECOND * 10 AS mul1,
  INTERVAL 35 SECOND * 4 AS mul2,
  INTERVAL 10 YEAR / 3 AS div1,
  INTERVAL 1 MONTH / 12 AS div2

/*----------------+--------------+-------------+--------------*
 | mul1           | mul2         | div1        | div2         |
 +----------------+--------------+-------------+--------------+
 | 0-0 0 10:20:30 | 0-0 0 0:2:20 | 3-4 0 0:0:0 | 0-0 2 12:0:0 |
 *----------------+--------------+-------------+--------------*/

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

ZetaSQL 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  |
 *-------*/

Graph concatenation operator

graph_path || graph_path [ || ... ]

Description

Combines multiple graph paths into one and preserves the original order of the nodes and edges.

Arguments:

graph_path: A GRAPH_PATH value that represents a graph path to concatenate.

Details

This operator produces an error if the last node in the first path isn't the same as the first node in the second path.

-- This successfully produces the concatenated path called `full_path`.
MATCH
  p=(src:Account)-[t1:Transfers]->(mid:Account),
  q=(mid)-[t2:Transfers]->(dst:Account)
LET full_path = p || q

-- This produces an error because the first node of the path to be concatenated
-- (mid2) is not equal to the last node of the previous path (mid1).
MATCH
  p=(src:Account)-[t1:Transfers]->(mid1:Account),
  q=(mid2:Account)-[t2:Transfers]->(dst:Account)
LET full_path = p || q

The first node in each subsequent path is removed from the concatenated path.

-- The concatenated path called `full_path` contains these elements:
-- src, t1, mid, t2, dst.
MATCH
  p=(src:Account)-[t1:Transfers]->(mid:Account),
  q=(mid)-[t2:Transfers]->(dst:Account)
LET full_path = p || q

If any graph_path is NULL, produces NULL.

Example

In the following query, a path called p and q are concatenated. Notice that mid is used at the end of the first path and at the beginning of the second path. Also notice that the duplicate mid is removed from the concatenated path called full_path:

GRAPH FinGraph
MATCH
  p=(src:Account)-[t1:Transfers]->(mid:Account),
  q = (mid)-[t2:Transfers]->(dst:Account)
LET full_path = p || q
RETURN
  JSON_QUERY(TO_JSON(full_path)[0], '$.labels') AS element_a,
  JSON_QUERY(TO_JSON(full_path)[1], '$.labels') AS element_b,
  JSON_QUERY(TO_JSON(full_path)[2], '$.labels') AS element_c,
  JSON_QUERY(TO_JSON(full_path)[3], '$.labels') AS element_d,
  JSON_QUERY(TO_JSON(full_path)[4], '$.labels') AS element_e,
  JSON_QUERY(TO_JSON(full_path)[5], '$.labels') AS element_f

/*-------------------------------------------------------------------------------------*
 | element_a   | element_b     | element_c   | element_d     | element_e   | element_f |
 +-------------------------------------------------------------------------------------+
 | ["Account"] | ["Transfers"] | ["Account"] | ["Transfers"] | ["Account"] |           |
 | ...         | ...           | ...         | ...           | ...         | ...       |
 *-------------------------------------------------------------------------------------/*

The following query produces an error because the last node for p must be the first node for q:

-- Error: `mid1` and `mid2` are not equal.
GRAPH FinGraph
MATCH
  p=(src:Account)-[t1:Transfers]->(mid1:Account),
  q=(mid2:Account)-[t2:Transfers]->(dst:Account)
LET full_path = p || q
RETURN TO_JSON(full_path) AS results

The following query produces an error because the path called p is NULL:

-- Error: a graph path is NULL.
GRAPH FinGraph
MATCH
  p=NULL,
  q=(mid:Account)-[t2:Transfers]->(dst:Account)
LET full_path = p || q
RETURN TO_JSON(full_path) AS results

Graph logical operators

ZetaSQL supports the following logical operators in element pattern label expressions:

Name	Syntax	Description
`NOT`	`!X`	Returns `TRUE` if `X` is not included, otherwise, returns `FALSE`.
`OR`	`X \| Y`	Returns `TRUE` if either `X` or `Y` is included, otherwise, returns `FALSE`.
`AND`	`X & Y`	Returns `TRUE` if both `X` and `Y` are included, otherwise, returns `FALSE`.

Graph predicates

ZetaSQL supports the following graph-specific predicates in graph expressions. A predicate can produce TRUE, FALSE, or NULL.

PROPERTY_EXISTS predicate
IS SOURCE predicate
IS DESTINATION predicate
SAME predicate

`IS DESTINATION` predicate

node IS [ NOT ] DESTINATION [ OF ] edge

Description

In a graph, checks to see if a node is or isn't the destination of an edge. Can produce TRUE, FALSE, or NULL.

Arguments:

node: The graph pattern variable for the node element.
edge: The graph pattern variable for the edge element.

Examples

GRAPH FinGraph
MATCH (a:Account)-[transfer:Transfers]-(b:Account)
WHERE a IS DESTINATION of transfer
RETURN a.id AS a_id, b.id AS b_id

/*-------------+
 | a_id | b_id |
 +-------------+
 | 16   | 7    |
 | 16   | 7    |
 | 20   | 16   |
 | 7    | 20   |
 | 16   | 20   |
 +-------------*/

GRAPH FinGraph
MATCH (a:Account)-[transfer:Transfers]-(b:Account)
WHERE b IS DESTINATION of transfer
RETURN a.id AS a_id, b.id AS b_id

/*-------------+
 | a_id | b_id |
 +-------------+
 | 7    | 16   |
 | 7    | 16   |
 | 16   | 20   |
 | 20   | 7    |
 | 20   | 16   |
 +-------------*/

`IS SOURCE` predicate

node IS [ NOT ] SOURCE [ OF ] edge

Description

In a graph, checks to see if a node is or isn't the source of an edge. Can produce TRUE, FALSE, or NULL.

Arguments:

node: The graph pattern variable for the node element.
edge: The graph pattern variable for the edge element.

Examples

GRAPH FinGraph
MATCH (a:Account)-[transfer:Transfers]-(b:Account)
WHERE a IS SOURCE of transfer
RETURN a.id AS a_id, b.id AS b_id

/*-------------+
 | a_id | b_id |
 +-------------+
 | 20   | 7    |
 | 7    | 16   |
 | 7    | 16   |
 | 20   | 16   |
 | 16   | 20   |
 +-------------*/

GRAPH FinGraph
MATCH (a:Account)-[transfer:Transfers]-(b:Account)
WHERE b IS SOURCE of transfer
RETURN a.id AS a_id, b.id AS b_id

/*-------------+
 | a_id | b_id |
 +-------------+
 | 7    | 20   |
 | 16   | 7    |
 | 16   | 7    |
 | 16   | 20   |
 | 20   | 16   |
 +-------------*/

`PROPERTY_EXISTS` predicate

PROPERTY_EXISTS(element, element_property)

Description

In a graph, checks to see if a property exists for an element. Can produce TRUE, FALSE, or NULL.

Arguments:

element: The graph pattern variable for a node or edge element.
element_property: The name of the property to look for in element. The property name must refer to a property in the graph. If the property does not exist in the graph, an error is produced. The property name is resolved in a case-insensitive manner.

Example

GRAPH FinGraph
MATCH (n:Person|Account WHERE PROPERTY_EXISTS(n, name))
RETURN n.name

/*------+
 | name |
 +------+
 | Alex |
 | Dana |
 | Lee  |
 +------*/

`SAME` predicate

SAME (element, element[, element])

Description

In a graph, determines if all graph elements in a list bind to the same node or edge. Can produce TRUE, FALSE, or NULL.

Arguments:

element: The graph pattern variable for a node or edge element.

Example

The following query checks to see if a and b are not the same person.

GRAPH FinGraph
MATCH (src:Account)<-[transfer:Transfers]-(dest:Account)
WHERE NOT SAME(src, dest)
RETURN src.id AS source_id, dest.id AS destination_id

/*----------------------------+
 | source_id | destination_id |
 +----------------------------+
 | 7         | 20             |
 | 16        | 7              |
 | 16        | 7              |
 | 16        | 20             |
 | 20        | 16             |
 +----------------------------*/

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.