Expressions, Functions and Operators
Hazelcast supports a subset of standard SQL expressions, functions, and operators as well as non-standard functions for special cases such as windowed aggregation.
For information about input and return data types, see Data Types.
Operators
Operators are used to evaluate and/or compare one or more operands. For example, in the expression (X + Y), the +
operator evaluates the addition of the X
and Y
operands.
Hazelcast supports the following SQL operators.
Logical Operators
Hazelcast supports the AND
, OR
, and NOT
logical operators. Logical operators allow only BOOL
or NULL
data types as input. The result can be TRUE
, FALSE
, or NULL
:
X | Y | X AND Y | X OR Y |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
X | NOT Y |
---|---|
|
|
|
|
|
|
Comparison Operators
Comparison operators compare two or more operands, and always return a BOOL
. Comparisons require operands to be of comparable type.
Operator name | Syntax | Description |
---|---|---|
Less Than |
|
Returns |
Less Than or Equal To |
|
Returns |
Greater Than |
|
Returns |
Greater Than or Equal To |
|
Returns |
Equal |
|
Returns |
Not Equal |
|
Returns |
|
Returns |
|
|
|
Returns
To escape a special character, use the |
|
See |
EXISTS
Operator
The EXISTS
operator returns TRUE
if a given subquery returns one or more records.
The NOT
keyword inverts the result.
Syntax
The EXISTS
operator supports the following syntax:
[NOT] EXISTS (<query>)
IS
Operator
The IS
operator returns TRUE
or FALSE
for a given condition. This operator never returns NULL
.
The NOT
keyword inverts the result.
Syntax | Description |
---|---|
|
Returns |
|
Returns |
|
Returns |
IN
Operator
The IN
operator allows you to check for a certain value in a given set of values, and returns TRUE
if an equal value is found.
The NOT
keyword inverts the result.
At the moment, Hazelcast does not support subqueries in IN clauses. For example, you cannot do SELECT column_names FROM table_name
WHERE column_name IN (SELECT STATEMENT);
|
Syntax
The IN
operator supports the following syntax:
<search_value> [NOT] IN (<value_set>)
UNION
and UNION ALL
Operators
The UNION
operator is used to combine the result set of two or more SELECT
statements, excluding any duplicate values.
The UNION ALL
operator is used to combine the result set of two or more SELECT
statements, including any duplicate values.
UNION ALL typically performs much better, because duplicate elimination is an expensive operation. Use UNION only if you actually need to remove duplicates.
|
Syntax
The UNION
and UNION ALL
Operators support the following syntax:
<query> UNION [ALL] <query>
Conditional Expressions
Conditional expressions allow you to evaluate only certain output values, depending on given conditions.
CASE
The CASE
expression evaluates the condition of each WHEN
clause and returns the first result where the condition is TRUE
. If all conditions are FALSE
or NULL
, the result of the ELSE
clause is returned.
Each condition
must be a boolean expression.
Syntax
The CASE
expression has two forms:
CASE value
WHEN value1 THEN result1
WHEN value2 THEN result2
...
ELSE elseResult
END
This form for returns result1
, when value = value1
, result2
when value = value2
and elseResult
, if value
isn’t equal to any of the values in the WHEN
clause.
CASE
WHEN condition1 THEN result1
WHEN condition2 THEN result2
...
ELSE elseResult
END
This form returns result1
when condition1
is TRUE
, result2
when condition2
is TRUE
and elseResult
, if no condition evaluated to TRUE
.
NULLIF
The NULLIF
expression returns NULL
if the two operands are equal and returns the first operand, if operands are not equal. The data type of the returned NULL
value is the same as the X
expression.
Syntax
NULLIF(X, Y)
Examples
sql> SELECT NULLIF('foo', 'bar');
+--------------------+
|EXPR$0 |
+--------------------+
|foo |
+--------------------+
1 row(s) selected
sql> SELECT NULLIF('foo', 'foo');
+--------------------+
|EXPR$0 |
+--------------------+
|NULL |
+--------------------+
Aggregate Functions
Aggregate functions perform calculations such as returning the mean of all data in a particular row.
Function :: Returns | Description |
---|---|
|
Calculates the number of input rows. |
|
Calculates the number of input rows in which the field is not null. |
|
Calculates the number of distinct values of the given field (ignores the |
|
Calculates the sum of the non-null input values. |
|
Calculates the mean of all the non-null input values. |
|
Calculates the minimum of the non-null input values. Applicable also to |
|
Calculates the maximum of the non-null input values. Applicable also to |
You can use DISTINCT keyword with all aggregate functions. It causes that before calculating the aggregate, duplicates are removed from the set of input values. For example, SUM(DISTINCT) applied to input values 1, 1, 2 will produce 3 , because it will add the 1 only once.
|
For examples of how to use aggregate functions, see the SELECT
statement documentation.
Conversion Functions
Conversion functions allow you to convert the result type of one expression to another explicit type.
Function | Description | Example | Result |
---|---|---|---|
|
Converts the result type of |
|
|
Date and Time Functions
Function | Description | Example | Result |
---|---|---|---|
|
Returns the Supported elements: Supported temporal types: |
|
24 |
|
Converts a The actual time unit of the conversion is determined by the magnitude of the input value:
This logic causes that any time value between years 1971 up to year 2968 is converted using the correct time unit. Negative values are always converted as seconds. |
|
1970-01-01T03:00:01+03:00 1970-01-01T03:00:02+03:00 1970-01-01T03:00:03+03:00 |
|
Converts |
|
1645484400000 |
|
Converts a number or date to a string |
|
|
File Table Functions
To execute an ad-hoc query against data in files you can use one of the following table functions:
-
csv_file
-
json_flat_file
-
avro_file
-
parquet_file
File table functions create a temporary mapping to a file, which is valid for the duration of the query. These functions accept the same options as those available for the file connector.
To configure the temporary mapping, you can use either positional arguments or named arguments:
SELECT * FROM TABLE(
CSV_FILE('/path/to/directory', '*.csv', MAP['key', 'value'])
);
SELECT * FROM TABLE(
CSV_FILE(path => '/path/to/directory', options => MAP['key', 'value'])
);
JSON Functions
Hazelcast supports the following functions, which can retrieve JSON data.
JSON_QUERY
The JSON_QUERY()
function extracts a JSON value from a JSON document or a JSON-formatted string that matches a given JsonPath expression.
Syntax
JSON_QUERY(jsonArg:{VARCHAR | JSON}, jsonPath:VARCHAR [<wrapperBehavior>] [<onClauseArg> ON ERROR] [<onClauseArg> ON EMPTY])` :: JSON
-
jsonArg
: JSON value or a JSON-formatted string. -
jsonPath
: A JsonPath expression that identifies the data that you want to get from thejsonArg
parameter. -
wrapperBehavior
: What to do with return results.-
WITHOUT [ARRAY] WRAPPER
(default): Up to one matched value is returned without wrapping in an array. Fails, if multiple values match. -
WITH [CONDITIONAL] [ARRAY] WRAPPER
: Returns a single match directly without wrapping. If there are multiple matches, they are returned as a JSON array. -
WITH UNCONDITIONAL [ARRAY] WRAPPER
: Always wrap matched values in a JSON array.
-
-
onClauseArg
: A value to return in case of the givenON
condition:-
EMPTY ARRAY
-
EMPTY OBJECT
-
ERROR
-
NULL
-
Examples
SELECT
JSON_QUERY('{"company" : {"employees" : [{"id" : "1"}]}}', '$.company.employees[0]');
-- Result
-- {"id":"1"}
SELECT
JSON_QUERY('[1,2,3]', '$[*]?(@ > 1)' WITH CONDITIONAL ARRAY WRAPPER);
-- Result
-- [2,3]
SELECT
JSON_QUERY('[1,2,3]', '$[*]?(@ > 1)' WITHOUT ARRAY WRAPPER);
-- Result
-- This example throws an error because you cannot return multiple values without an array wrapper.
SELECT
JSON_QUERY('[1,"rainbow",3]', '$[1]' WITH UNCONDITIONAL ARRAY WRAPPER);
-- Result
-- ["rainbow"]
JSON_VALUE
The JSON_VALUE()
function extracts a primitive value, such as a string, number, or boolean that matches a given JsonPath expression. This function returns NULL
if a non-primitive value is matched, unless the ON ERROR
behavior is changed.
Syntax
JSON_VALUE(jsonArg:{VARCHAR | JSON}, jsonPath:VARCHAR [RETURNING dataType] [<onClauseArg> ON ERROR] [<onClauseArg> ON EMPTY])` :: VARCHAR
-
jsonArg
: JSON value or a JSON-formatted string -
jsonPath
: A JsonPath expression that identifies the data that you want to get from thejsonArg
parameter. -
RETURNING
: Converts the result to thedataType
(VARCHAR
by default). If the value cannot be converted to the target type, throws an error. -
onClauseArg
: What to return in case of theON
condition:-
DEFAULT <literal | column | parameter>
-
ERROR
-
NULL
-
Examples
SELECT
JSON_VALUE('{"company" : {"employees" : [{"id" : "1","name":"jake"}]}}', '$.company.employees[0].id');
-- Returns
-- 1 (as a VARCHAR)
JSON_ARRAY
The JSON_ARRAY()
function returns a JSON array from a list of input data.
Syntax
JSON_ARRAY([columnOrParameterOrLiteral:ANY], [...more columns/parameters/literals:ANY] [{ABSENT|NULL} ON NULL]) :: JSON
-
columnOrParameterOrLiteral
: A list of input data. -
ON NULL
: What to do with null values:-
ABSENT ON NULL
(default): Do not includeNULL
values in the array. -
NULL ON NULL
: IncludeNULL
values in the array.
-
Examples
SELECT
JSON_ARRAY(1, null, 3);
-- Result
-- [1,3]
JSON_OBJECT
The JSON_OBJECT()
function returns a JSON object from the given key/value pairs.
Syntax
JSON_OBJECT([key : value] [, ...] [{ABSENT|NULL} ON NULL]) :: JSON
Or
JSON_OBJECT([[KEY] key VALUE value] [{ABSENT|NULL} ON NULL]) :: JSON
-
key
: A name for the key, must be a VARCHAR -
value
: A value for the key, can be any type. -
ON NULL
: What to do withNULL
values.-
NULL ON NULL (default): Include `NULL
values in the array. -
ABSENT ON NULL
: Do not includeNULL
values in the array.
-
Examples
SELECT JSON_OBJECT(KEY 'id' VALUE 1, 'name' VALUE null ABSENT ON NULL)
-- Result
-- {"id": 1}
SELECT JSON_OBJECT('id': 1, 'name': 'jake')
-- Result
-- {"id": 1, "name":"jake"}
JSON_ARRAYAGG
The JSON_ARRAYAGG()
returns a JSON array containing an element for each value in a given set of SQL values. It takes as its input a column of SQL expressions, converts each expression to a JSON value, and returns a single JSON array that contains those JSON values.
Syntax
JSON_ARRAY(value [ORDER BY value {ASC|DESC}] [{ABSENT|NULL} ON NULL]) :: JSON
-
value
: A value for the key, can be any type. -
ON NULL
: What to do with null values:-
ABSENT ON NULL
(default): Do not includeNULL
values in the array. -
NULL ON NULL
: IncludeNULL
values in the array.
-
Examples
Assuming you have the following table:
name, number
--------
Alice, 1
Bob, 2
Alice, 3
Bob, 6
null, 7
SELECT name, JSON_ARRAYAGG(number ORDER BY number ASC) arr_no
FROM test GROUP BY name
-- Result
-- name, arr_no
-- ------------
-- Alice, [1, 3]
-- Bob, [2, 6]
-- null, [7]
JSON_OBJECTAGG
The JSON_OBJECTAGG()
function constructs an object member for each key-value pair and returns a single JSON object that contains those object members. It takes as
its input a property key-value pair. Typically, the property key, the property value, or both are columns of SQL expressions.
Syntax
JSON_OBJECTAGG([key : value] [, ...] [{ABSENT|NULL} ON NULL]) :: JSON
Or
JSON_OBJECTAGG([[KEY] key VALUE value] [{ABSENT|NULL} ON NULL]) :: JSON
-
key
: A name for the key, must be a VARCHAR -
value
: A value for the key, can be any type. -
ON NULL
: What to do withNULL
values.-
NULL ON NULL (default): Include `NULL
values in the array. -
ABSENT ON NULL
: Do not includeNULL
values in the array.
-
Examples
SELECT JSON_OBJECTAGG(KEY 'name' VALUE age) "Names"
FROM employees
WHERE age <= 30;
--Result
--{"Mary":28,"John":29,"Jake":27}
Mathematical Functions
Function | Description | Example | Result |
---|---|---|---|
|
Absolute value of the argument |
|
|
|
Returns the cube root of the input |
|
|
|
Returns the nearest integer greater than or equal to argument |
|
|
|
Converts radians to degrees |
|
|
|
Exponential |
|
|
|
Returns the nearest integer less than or equal to argument |
|
|
|
Natural logarithm |
|
|
|
Base 10 logarithm |
|
|
|
Returns the remainder of x / y |
|
|
|
Returns x to the power of y |
|
|
|
Converts degrees to radians |
|
|
|
Random value in the range [0.0; 1.0) |
|
|
|
Random value in the range [0.0; 1.0) using the given seed |
|
|
|
Rounds to an integer |
|
|
|
Rounds to |
|
|
|
Returns -1, 0 or 1 for negative, zero or positive argument, respectively |
|
|
|
Squares the input |
|
|
|
Returns the square root of the input |
|
|
|
Truncates to an integer |
|
|
|
Truncates to |
|
|
|
Converts a number or date to a string |
|
|
String Functions
Function | Description | Example | Result |
---|---|---|---|
|
Concatenates two strings |
|
|
|
Returns the ASCII code of the first character of the argument |
|
|
|
Equivalent to |
||
|
Returns a string that consists of the arguments |
|
John-Doe |
|
Converts the first letter of each word to upper case, and the rest to lower case |
|
|
|
Length of the string |
|
|
|
Converts the string to lower case |
|
|
|
Removes the empty spaces from the left-hand side of |
|
|
|
Returns the position of the first occurrence of |
|
|
|
Replaces all occurrences of |
|
|
|
Removes the empty spaces from the right-hand side of |
|
|
|
Extracts a substring starting with the given position |
|
|
|
Extracts a substring starting with the given position for the given length |
|
|
|
Removes |
|
|
|
Equivalent to |
|
|
|
Equivalent to |
|
|
|
Converts a string to upper case |
|
|
Table-Valued Functions
Table-valued functions return tables of batch or streaming sources that you can use in SQL statements.
Function | Description |
---|---|
|
Returns a table that contains a series of numbers, starting from the |
|
Returns a table that contains a stream of numbers, starting from 0 at a rate of |
To use a table-valued function in FROM clause, you must wrap it in a TABLE
keyword. For example:
SELECT *
FROM TABLE(generate_series(1, 3));
Trigonometric Functions
Function | Description |
---|---|
|
Inverse cosine |
|
Inverse sine |
|
Inverse tangent |
|
Arc tangent |
|
Cosine |
|
Cotangent |
|
Sine |
|
Tangent |
Windowing Table-Valued Functions
Windowing functions assign input records from the input table into windows. Their output contains all the input columns, with two added columns: window_start
and window_end
. You can use the added columns in the GROUP BY
expression when doing streaming aggregation.
For a guide about streaming windowed aggregations in SQL, see Stream Processing in SQL.
Function | Description |
---|---|
|
Assigns input records to tumbling windows. |
|
Assigns input records to hopping windows. |