Recombee Query Language (ReQL)

Recombee Query Language (ReQL) allows expressions to be evaluated on sets of items, telling the recommender how to handle each item based on the values of the item’s attributes.

Introduction

Each recommendation request has two parameters, which take ReQL:

  • filter – for selecting a subset of items which can be used in recommendation
  • booster – for preferring some items over the others

Definition of the attributes and their values for individual items is done through API methods (see Item Properties and Item Property Values) and is left to the user. Different properties may be defined for different recommendation domains. All the items have one automatically created property itemId.

Filtering

In filtering, the expression must return boolean value for each item. If the value returned is true, the item passed the filter; if the value is false, the item does not pass and will be discarded.

Consider the following table of items in sample movie-recommendation domain:

Name: string Year:int Genres: set Parental-Advisory:boolean
Pulp Fiction 1994
{“Crime Fiction”,”Drama”
“Thriller” }
true
The Matrix 1999
{“Science Fiction”,”Action”,
“Adventure” }
false
Fight Club 1999
{“Drama”, “Existentialism”}
true
The Lord of the Rings: The Return of the King 2003
{ “Adventure”, “Fantasy”,
“Action” }
false
The Dark Knight 2008
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}
false
Silence of the Lambs 1991
{“Crime Fiction”, “Drama”,
“Thriller”, “Horror” }
true
American Beauty 1999
{ “Romance”, “Comedy”,
“Drama”, “Satire”,
“Existentialism” }
true
... and 10000 other movies

By default, when items are to be recommended to a given user, the recommender will select any items which seem relevant for her. However, it may be your policy not to recommend items with Parental-Advisory flag set on. Hence you may use the following simple ReQL filtering expression:

not 'Parental-Advisory'

Then the recommender may only choose one of the following movies:

Name: string Year:int Genres: set Parental-Advisory:boolean
The Matrix 1999
{“Science Fiction”,”Action”,
“Adventure” }
false
The Lord of the Rings: The Return of the King 2003
{ “Adventure”, “Fantasy”,
“Action” }
false
The Dark Knight 2008
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}
false
... and 5926 others

As another example, consider that user entered the “Drama” section of your system’s catalog. Then you sure wish to recommend her dramas, ignoring the fact that usually, she likes comedies. You may do this using another ReQL filtering expression:

"Drama" in 'Genres'

Then only the following items will pass the filter:

Name: string Year:int Genres: set Parental-Advisory:boolean
Pulp Fiction 1994
{“Crime Fiction”,”Drama”
“Thriller” }
true
Fight Club 1999
{ “Drama”, “Existentialism” }
true
The Dark Knight 2008
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}
false
Silence of the Lambs 1991
{“Crime Fiction”, “Drama”,
“Thriller”, “Horror” }
true
American Beauty 1999
{ “Romance”, “Comedy”,
“Drama”, “Satire”,
“Existentialism” }
true
... and 3141 other movies

See more examples of language usage below.

Handling deleted items

Filtering offers you an elegant way of handling deleted/obsolete items in the catalog. In many situations, it may happen that some items become unavailable and hence should not be recommended anymore. Considering interaction data, however, such items may still be important for the recommender. For example, the recommender may find out that users who liked a no more available item, x, will probably like another item, y, which is still actual. Therefore, it is undesirable to simply delete x, deleting also all the related interactions in cascade.

With filtering, you may handle item deletes using the following scheme:
  • Create a dedicated item property, such as deleted, of type boolean (the implicit value for all items will be null, which is OK).
  • For deleted items, set the value of deleted true.
  • For recommendations, use the following filter:
not 'deleted'
  • Occasionally, if the item becomes available again, you may set deleted false.

Such a mechanism cay easily be extended to control availability over different regions, customer licenses, etc.

Boosting

In advanced applications, besides filtering, you may wish to boost recommendation rates of some items. In contrast to filtering, where items may be completely blocked, in boosting, you may tell the recommender to prefer some items among others. Indeed, by default, it is a task of the recommender itself to select the items which are the most relevant. However, it may be your policy to purposefully bias the recommender toward your business goals.

For example, considering the above table of movies, one may wish to promote the movies which are new and were filmed after 2000, especially if they were filmed after 2005. Then the following boosting query can handle that:

if 'Year' <= 2000 then 1 else (if 'Year' <= 2005 then 1.5 else 2)

As you can see, boosting expressions return numbers rather than booleans as in case of filtering. Specifically, they provide the items with coefficients by which the internal scores determined by the recommender will be multiplied.

The boosting coefficients assigned by the query are shown in the following table:

Name: string Year:int Genres: set Parental-Advisory:boolean Boosting
Pulp Fiction 1994
{“Crime Fiction”,”Drama”
“Thriller” }
true 1.0
The Matrix 1999
{“Science Fiction”,”Action”,
“Adventure” }
false 1.0
Fight Club 1999
{ “Drama”, “Existentialism” }
true 1.0
The Lord of the Rings: The Return of the King 2003
{ “Adventure”, “Fantasy”,
“Action” }
false 1.5
The Dark Knight 2008
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}
false 2.0
Silence of the Lambs 1991
{“Crime Fiction”, “Drama”,
“Thriller”, “Horror” }
true 1.0
American Beauty 1999
{ “Romance”, “Comedy”,
“Drama”, “Satire”,
“Existentialism” }
true 1.0
... and 10000 other movies  

It is noteworthy that boosting does not block any items nor guarantee the boosted items to appear in the recommendations. Instead, boosting works as a kind of tie-breaking mechanism: if an item is highly irrelevant to the user, it will not be recommended even if boosted. If you insist on some specific items being recommended, use filtering instead.

Value Types

In compliance with Recombee Recommender API, there are 6 value types which correspond to possible domains of item properties:

  • int – signed integer (currently 64bit),
  • double – double-precision floating-point number (IEEE 754 compliant),
  • timestamp – UTC timestamp, similar to double,
  • string – sequence of Unicode characters,
  • boolean – binary data type of two possible values: true or false,
  • set – unordered collection of values.

Except for set, all of the types include special value of null, which, again, corresponds to the fact that null is an allowed and also default value for the property values in the API.

Learn from Examples

Here are some examples to help you quickly learn the ReQL language.

Numbers

Notation

Expression Equivalent Comment
0123.000 123.0 Leading and trailing zeros are ignored.
1.23e+3 1230.0 Exponential notation may be used.
1e9 1000000000 Using simple exponential notation for huge numbers.
123E-2 1.23 Negative exponents may also be used. Case of the e character does not matter.

Operations

Expression Result Comment
1 + 2 3 Addition.
1 + 2 + 3 + 4 10 Chain of additions.
1 - 2 -1 Subtraction.
1 - 2 - 3 - 4 -9 Chain of subtractions.
-(1 + 2) -3 Unary minus.
2 * 3 6 Multiplication.
1 + 2 * 3 - 4 3 Standard operator precedence.
(1 + 2) * (3 - (4 + 5)) -18 Bracketing.
10 / 5 2.0 Division.
1 / 2 0.5 Division always results in double, event if the operands are integers!
5 / 0 NaN If the divisor is 0, the result is NaN.
9 % 4 1 Modulo division.
3.14 % 2.5 0.64 Modulo division also works for doubles.
5 % 0 NaN If the divisor is 0, the result is NaN.

Comparison

Expression Result Comment
1 < 2.0 true Integers, doubles, and timestamps may be compared using standard comparison operators.
1 < 2 <= 2 == 2 != 1 >= 1 > 0 true Comparison operators may be arbitrarily chained.
1 < 2 <= 2 == 3 != 1 >= 1 > 0 false Chain of comparisons returns true if and only if all the individual comparisons are true.
2 == 2.0 true In comparison, there is no difference between integers, doubles, and timestamps.

Strings

Notation

Expression Comment
"foo" Strings constants are enclosed in double quotes.
"" Empty string.
"she said \"hello\"" Double quotes must be escaped.
"she said 'hello'" Single quotes needn’t be escaped.

Comparison

Expression Result Comment
"Alice" < "Bob" true Strings are ordered lexicographically.
"Alice" < "Bob" < "Carol" < "Dan" true Comparisons may be chained arbitrarily.
"Alice" < "Bob" <= "Carol" != "Dan" true Comparisons in the chain may be of different types.
"Alice" < "Bob" >= "Carol" != "Dan" false All the comparisons must hold for the chain to return true.
"Alice" < 5 error Strings are only comparable with strings.
"Alice" ~ "A[a-z]+" true Strings can be matched with regular expressions (regex).

Containment

Expression Result Comment
"ice" in "Alice" true in operator between strings tests whether the first string is contained in the second string.
"Ice" in "Alice" false Containment test is case sensitive.
"ice" not in "Alice" false in operator may be negated for better readability.
"" in "abc" true Empty string is contained in every string.
"abc" in "" false No non-empty string is contained in empty string.
5 in "abc" error Both operands must be strings for string containment testing.

Concatenation

Expression Result Comment
"foo" + "bar" "foobar" Strings can be concatenated using the + operator.
"" + "foo" + "" "foo" Empty string is neutral element for concatenation.
"foo" + 123 "foo123" Strings can be concatenated with integers.
"foo" + 123.0 "foo123.0" Strings can be concatenated with numbers.

Sets

Notation

Expression Comment
{} Empty set.
{1, 2, 3} Set containing three integers.
{1, 2.0, false, "foo", null} Sets may contain values of different types. This is an extension to sets in the API, which may only contain strings.
{{1,2}, {2,3}} Sets may be nested.

Properties

Expression Result Comment
{ 1, 1, 1, 2 } { 1, 2 } Sets only contain unique elements.
{ 1, 1.0 } { 1.0 } Integers, doubles, and timestamps, are merged.
{ {1,2}, {2,1} } { {1,2} } Merging also works for nested sets.

Value Containment

Expression Result Comment
2 in { 1, 2, 3 } true Using in operator, you may test whether a value is contained in given set (the ∈ relation)
4 not in { 1, 2, 3 } true The in operator may be negated for better readability (the ∉ relation).
2.0 in { 1, 2, 3 } true There is no difference between integers, doubles, and timestamps when testing containment.
"2" in { 1, 2, 3 } false There is a difference between numbers and strings.
{ 1, 2 } in { 1, 2, 3 } false in stays for ∈, not ⊆!
{ 1, 2 } in { {1,2}, {3,4} } true in stays for ∈.

Comparison

Expression Result Comment
{ 1, 2 } < { 1, 2, 3 } true Using < operator, you may test whether one test is a proper subset of another set (⊂ operator in set algebra).
{ 1, 2 } < { 1, 2 } false No set is a proper subset of itself.
{} < { 1, 2 } true Empty set is a proper subset of every non-empty set.
{} < {} false Empty set is not a proper subset of itself.
{ 1, 2 } <= { 1, 2, 3 } true Using <= operator, you may test whether one set is a subset of another set (⊆ operator is set algebra).
{ 1, 2 } <= { 1, 2 } true Every set is a subset of itself.
{ 1, 2 } == { 1, 2 } true == tests whether two sets are identical.
{ 1, 2 } != { 1, 2 } false != tests whether two sets are different.
{ 1, 2, 3 } >= { 1, 2 } true >= operator tests whether one set is a superset of another set (⊇ operator in set algebra).
{ 1, 2 } >= { 1, 2 } true Every set is a superset of itself.
{ 1, 2, 3 } > { 1, 2 } true > operator tests whether one set is a proper superset of another set (⊃ operator in set algebra).
{ 1, 2 } > { 1, 2 } false A non-empty set in not a proper superset of itself.
{ 1, 2 } > {} true Every non-empty set is a proper superset of an empty set.
{} > {} false Empty set is not a proper subset of itself.

Union

Expression Result Comment
{ 1, 2 } + { 2, 3 } { 1, 2, 3 } Sets may be unified using the + operator (∪ in set algebra).
{ 1, 2.0 } + { 2, 3 } { 1, 2.0, 3 } Integers, doubles, and timestamps are merged when unifying sets.
{ 1, 2 } + { 2, 3 } + { 4 } { 1, 2, 3, 4 } Unions may be chained.
{ 1, 2 } + {} { 1, 2 } Unification with empty set has no effect on the original set.
{ 1, 2 } + { "2", "3" } { 1, 2, "2", "3" } Strings and numbers are handled as different values.

Difference

Expression Result Comment
{ 1, 2 } - { 2, 3 } { 1 } Set difference may be obtained using the - operator (operator is set algebra).
{ 1, 2 } - { 2.0, 3.0 } { 1 } Integers, doubles, and timestamps are considered equal if they equal in values.
{ 1, 2 } - {} { 1, 2 } - {} Subtracting an empty set has no effect.
{ 1, 2 } - { 1 } - { 2 } {} Chaining of set subtractions works from left to rights.
{ 1, 2 } - ({ 1, 2 } - { 2 }) { 2 } Parenthesizing also works.

Logical Operators

Negation (NOT)

Expression Comment
not 'a' == 'b' 'a' != 'b'
not 'a' > 'b' 'a' <= 'b'
not true false
not false true

Implicit conversion to boolean (for advanced uses only!):

Expression Result Comment
not -1 false Negative numbers are truthy.
not 0 true Zero numbers are falsy.
not 1.23 false Positive numbers are truthy.
not "" true Empty strings are falsy.
not "foo" false Non-empty strings are truthy.
not {} true Empty sets are falsy.
not {1,2,3} false Non-empty sets are truthy.
not null true null is falsy.

Disjunction (OR)

Expression a b c Result Comment
'a' > 'b' or 'a' > 'c' 1 2 3 false If both operands are false, false is returned.
'a' > 'b' or 'a' > 'c' 2 1 3 true If at least one of boolean operands is true, the result is true.
'a' > 'b' or 'a' > 'c' 2 3 1 true If at least one of boolean operands is true, the result is true.
'a' > 'b' or 'a' > 'c' 3 1 2 true If- both the operands are true, the result is true.

Advanced uses: Implicit conversion to boolean.

Expression Result Comment
"foo" or "bar" "foo" If the first operand truthy, it is returned.
"" or false false If the first operand is falsy, the second operand is returned.
false or "" "" If the first operand is falsy, the second operand is returned.

Conjunction (AND)

Expression a b c Result Comment
'a' > 'b' and 'a' > 'c' 1 2 3 false If both operands are false, false is returned.
'a' > 'b' and 'a' > 'c' 2 1 3 false If at least one of boolean operands is false, the result is false.
'a' > 'b' and 'a' > 'c' 2 3 1 false If at least one of boolean operands is false, the result is false.
'a' > 'b' and 'a' > 'c' 3 1 2 true If both the operands are true, the result is true.

Advanced uses: Implicit conversion to boolean.

Expression Result Comment
"foo" and "bar" "bar" If the first operand truthy, the second operand is returned.
"" and false "" If the first operand is falsy, it is returned.
false and "" false If the first operand is falsy, it is returned.

Conditional Operators

Expression a b Result Comment
if 'a' > 'b' then "foo" else "bar" 10 5 "foo" then-value is returned if the condition is satisfied.
if 'a' < 'b' then "foo" else "bar" 10 5 "bar" else-value is returned if the condition is not satisfied.
if 'a' < 'b' then "foo"     error else clause must always be present.
if 'a' < 'b' then "foo" else (if 'a' > 'b' then "bar" else "bah") 5 5 "bah" if-else statements may be nested using parentheses.
Expression Result Comment
if -1 then "foo" else "bar" "foo" Negative numbers are truthy.
if 0 then "foo" else "bar" "bar" Zero numbers are falsy.
if 1.23 then "foo" else "bar" "foo" Positive numbers are truthy.
if "" then "foo" else "bar" "bar" Empty strings are falsy.
if "bah" then "foo" else "bar" "foo" Non-empty strings are truthy.
if {} then "foo" else "bar" "bar" Empty sets are falsy.
if {1,2,3} then "foo" else "bar" "foo" Non-empty sets are truthy.
if null then "foo" else "bar" "bar" null is falsy.

ReQL functions

Functions may be used to enhance your ReQL queries – for example up-sell or cross-sell can be achieved easily by functions.

There are various functions like math functions (rounding, computing square root ...), string functions (converting case), function for getting size of set or string, getting current timestamp, functions for conversions between types (for example conversion between date in a text representation and timestamp) or even lambda functions. If you are missing some function that you would like to use, please let us know.

ReQL function can take arguments and returns a single value. Arguments are placed between parentheses and are separated by commas – for example computing base 2 logarithm of 8 looks like this: log(8,2). If the function takes no arguments the parentheses may be omitted (for e.g. now). If the function is given wrong number of arguments, or the arguments have unsupported type, an error is produced. If any of the arguments is null, then result is also a null value.

Quick overview

Context item function    
Name of the function Description Example
context_item Retrieves property value of the item, that is currently viewed by the user context_item["price"]
context_user Retrieves property value of the user, that is about to obtain the recommendations context_user["country"]

   
Type conversion functions    
Name of the function Description Example
boolean Converts the argument to boolean boolean("") == False
number Converts the argument to number number("456") == 456
string Converts the argument to string string(123) == "123"
timestamp Converts the argument to timestamp timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)

   
Math functions    
Name of the function Description Example
round Returns closest integer round(4.5) == 5
floor Returns largest preceding integer floor(4.3) == 4
ceil Returns smallest following integer ceil(4.3) == 5
abs Returns non-negative value of the argument without regard to its sign abs(-4.3) == 4.3
sqrt Returns the square root of the argument sqrt(4) == 2
pow Returns \({first\_argument}^{second\_argument}\) pow(10,3) == 1000
log Returns the logarithm of the argument log(1000) == 3

   
String functions    
Name of the function Description Example
upper Converts all letters to the capital letters upper("AbCdefG") == "ABCDEFG"
lower Converts all letters to the small letters lower("AbCdefG") == "abcdefg

   
Other functions    
Name of the function Description Example
earth_distance Returns the orthodromic distance between two points (given as their latitude and longitude in degrees) in meters earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000
max Returns the maximum of n arguments max(147,42,81.9) == 147
min Returns the minimum of n arguments min(147,42,81.9) == 42
now Returns current timestamp now() > timestamp("2015-06-24T17:35:50Z")
num_item_purchases Returns the number of purchases of an item num_item_purchases('itemId') < 10
random Returns a random number between 0 and 1 1>=random()>=0
size Returns the length of a string or number of objects in a set size("Recombee") == 8

   
Lambda functions    
Name of the function Description Example
map Applies the lambda expression to every member of a set map(lambda 'x': 2*'x', {1, 2, 3}) == {2, 4, 6}
select Returns only those values of input set for which the lambda expression returns true select(lambda 'x': 'x' > 5, {10, 2, 13, 1}) == {10, 13}

Context functions

Quick overview

Context item function    
Name of the function Description Example
context_item Retrieves property value of the item, that is currently viewed by the user context_item["price"]
context_user Retrieves property value of the user, that is about to obtain the recommendations context_user["country"]

Context item function

Context item function is used in Item based recommendation for retrieving property values of the item, that is currently viewed by the user.

Definition
context_item[property_name]
Key Type Meaning
property_name string Name of property to be retrieved. If property of this name does not exist, an error is produced.

(Note that Context item function is a bit special function – it takes no arguments and returns a map name of property -> value representing the context item. property_name placed in square brackets is the key to this map.)

Examples

Consider following sample items:

name: string price: number category: string
“television-42” 369 “television”
“television-49” 449 “television”
“remote-control-13” 25 “remote-control”
Example 1

Suppose that the user is currently viewing television-42. Then the following expression returns 369, because that is the price of the context item.

context_item["price"]
Example 2: up-sell

Suppose that the user is currently viewing television-42. You can recommend him products from the same category with higher price. The filter would look like this:

'price' > context_item["price"] and 'category' == context_item["category"]

Considering the sample items above, only television-49 will pass the filter.

If you don’t want to be so restrictive about the cheaper products, you shall use booster instead of filter and boost the products with higher price. The booster could look like this:

if 'category' != context_item["category"] 0.1 else if  'price' > context_item["price"] 1 else 0.5
Example 3: cross-sell

Suppose that the user is currently viewing television-42. You may want to suggest him some additional product from a different category. The filter is very simple:

'category' != context_item["category"]

remote-control-13 will pass the filter. Of course, in real life situation you may have to make the query a bit more complicated, for example to ensure the compatibility between the TV and the remote control.

Context user function

Context user function is used for retrieving property values of the user that the recommendations are for. It can be used in User based recommendation or in Item based recommendation, in case that targetUserId is specified.

Definition
context_user[property_name]
Key Type Meaning
property_name string Name of property to be retrieved. If property of this name does not exist, an error is produced.

(Note that Context user function is a bit special function – it takes no arguments and returns a map name of property -> value representing the context user. property_name placed in square brackets is the key to this map.)

Example

Consider following sample users, which have specified languages they understand:

userId: string languages: set
“user-27” [“EN”]
“user-29” [“EN”, “FR”]

And sample items, which are some movies:

itemId: string language: string
“Pulp Fiction” “EN”
“Le fabuleux destin d Amelie Poulain” “FR”
“Fight Club” “EN”
“Kolja” “CS”

Suppose that I want to recommend movies to users, but only such movies, that the users can understand them. I can use following filter:

'language' in context_user["languages"]

For user-27 (which can speak only english) Pulp Fiction or Fight Club can be recommended.

For user-29 (which can speak english and french) Pulp Fiction, Fight Club or Le fabuleux destin d Amelie Poulain can be recommended.

Type conversion functions

Quick overview

Name of the function Description Example
boolean Converts the argument to boolean boolean("") == False
number Converts the argument to number number("456") == 456
string Converts the argument to string string(123) == "123"
timestamp Converts the argument to timestamp timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)

Boolean conversion function

Boolean conversion function is used for getting the truth value of any expression.

Definition
boolean(value_to_be_converted)
Argument Type Meaning
value_to_be_converted any type Value to be converted into a boolean
Examples

All the following expressions result in true:

boolean("Recombee") == true

boolean("") == False

boolean(42) == true

boolean(0) == False

boolean({""}) == true

boolean({}) == False

Number conversion function

Number conversion function is used for converting strings, booleans and timestamps into numbers.

Definition
number(value_to_be_converted)
Argument Type Meaning
value_to_be_converted string boolean timestamp number Value to be converted into a number
Examples

All the following expressions result in true:

number("456") == 456

number("1E4") == 10000

number(true) == 1

number("Recombee") == null #String "Recombee" cannot be converted into a number

String conversion function

String conversion function is used for converting numbers, booleans, sets and timestamps into their textual representations.

Definition
string(value_to_be_converted [, date_time_format (only if value_to_be_converted is a timestamp)])
Argument Type Meaning
value_to_be_converted string boolean timestamp set number Value to be converted into a string
date_time_format string (Optional and only if value_to_be_converted is a timestamp) String specifying the format of textual representation of the timestamp after conversion. See supported date and time format specifiers. If date_time_format is not specified, ISO 8601 format is used.
Examples

All the following expressions result in true:

string(123) == "123"

string(true) == "true"

string('time') == "2015-06-25T11:08:44Z" # Suppose that 'time' is a timestamp with value 1435230524. No format string is specified, so ISO 8601 is used.

string('time', "%d.%m.%Y %H:%M:%S") == "25.06.2015 11:08:44" # Suppose that 'time' is a timestamp with value 1435230524.

Timestamp conversion function

Timestamp conversion function is used for converting numbers and strings into timestamps.

Definition
timestamp(value_to_be_converted [, date_time_format (only if value_to_be_converted is a string) ] )
Argument Type Meaning
value_to_be_converted string number timestamp Value to be converted into a string
date_time_format string (Optional and only if value_to_be_converted is a string) String specifying the format of value_to_be_converted. See supported date and time format specifiers. If date_time_format is not specified, ISO 8601 format is used.
Examples

All the following expressions result in true:

timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)  # No format string is specified, so ISO 8601 is used.

timestamp("25.06.2015 11:08:44", "%d.%m.%Y %H:%M:%S") == timestamp(1435230524)

Math functions

Quick overview

Name of the function Description Example
round Returns closest integer round(4.5) == 5
floor Returns largest preceding integer floor(4.3) == 4
ceil Returns smallest following integer ceil(4.3) == 5
abs Returns non-negative value of the argument without regard to its sign abs(-4.3) == 4.3
sqrt Returns the square root of the argument sqrt(4) == 2
pow Returns \({first\_argument}^{second\_argument}\) pow(10,3) == 1000
log Returns the logarithm of the argument log(1000) == 3

Round

Definition
round(x)
Argument Type Meaning
x number  
Return value number Integer closest to x
Examples

All the following expressions result in true:

round(4.3) == 4

round(4.5) == 5

Floor

Definition
floor(x)
Argument Type Meaning
x number  
Return value number Largest integer preceding x
Examples

All the following expressions result in true:

floor(4.3) == 4

floor(4.5) == 4

Ceil

Definition
ceil(x)
Argument Type Meaning
x number  
Return value number Smallest integer following x
Examples

All the following expressions result in true:

ceil(4.3) == 5

ceil(4.5) == 5

Absolute value

Definition
abs(x)
Argument Type Meaning
x number  
Return value number Non-negative value of x without regard to its sign
Examples

All the following expressions result in true:

abs(-4.3) == 4.3

abs(4.3) == 4.3

Square root

Definition
sqrt(x)
Argument Type Meaning
x Non-negative number  
Return value number Number \(a\), such that \(a^2 = x\)
Examples

All the following expressions result in true:

sqrt(4) == 2

sqrt(-16) == null # Square root is defined only for non-negative numbers

Power function

Definition
pow(base, exponent)
Argument Type Meaning
base number  
exponent number  
Return value number Base raised to the power exponent (\({base}^{exponent}\))
Examples

All the following expressions result in true:

pow(10,3) == 1000

pow(5,-2) == 0.04

pow(-2,5) == -32

Logarithm

Definition
log(x [, base])
Argument Type Meaning
x Non-negative number  
base Non-negative number Optional. Default base is decadic.
Return value number Number \(y\), such that \({base}^{y} = x\)
Examples

All the following expressions result in true:

log(1000) == 3

log(16,2) == 4

log(-2) == null # Logarithm is defined only for non-negative numbers

String functions

Quick overview

Name of the function Description Example
upper Converts all letters to the capital letters upper("AbCdefG") == "ABCDEFG"
lower Converts all letters to the small letters lower("AbCdefG") == "abcdefg

Convert to upper case

Converts all letters to the capital letters

Definition
upper(str)
Argument Type Meaning
str string  
Examples

All the following expressions result in true:

upper("AbCdefG") == "ABCDEFG"

upper("7b&*#č汉字") == "7B&*#Č汉字"

Convert to lower case

Converts all letters to small letters

Definition
lower(str)
Argument Type Meaning
str string  
Examples

All the following expressions result in true:

lower("AbCdefG") == "abcdefg"

lower("7B&*#Č汉字") == "7b&*#č汉字"

Other functions

Quick overview

Name of the function Description Example
earth_distance Returns the orthodromic distance between two points (given as their latitude and longitude in degrees) in meters earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000
max Returns the maximum of n arguments max(147,42,81.9) == 147
min Returns the minimum of n arguments min(147,42,81.9) == 42
now Returns current timestamp now() > timestamp("2015-06-24T17:35:50Z")
num_item_purchases Returns the number of purchases of an item num_item_purchases('itemId') < 10
random Returns a random number between 0 and 1 1>=random()>=0
size Returns the length of a string or number of objects in a set size("Recombee") == 8

Earth Distance

Returns the orthodromic distance in meters between two points specified by their latitude and longitude in degrees

Definition
earth_distance(lat1,lon1,lat2,lon2)
Argument Type Meaning
lat1 number Latitude of the first point in degrees
lon1 number Longitude of the first point in degrees
lat2 number Latitude of the second point in degrees
lon2 number Longitude of the second point in degrees
Examples

All the following expressions result in true:

earth_distance(10,10,10,10) == 0

281000 < earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000  # Distance between Prague (50.075538,14.437800) and Berlin (52.520007,13.404954)

Max

Returns the maximum of n arguments.

The arguments must be comparable using >.

Definition
max(val1, val2, [val3, val4 ...])
Argument Type Meaning
val1 any  
val2 any  
...    
Example
max(147,42,81.9) == 147
max("abc", "bac") == "bac"
max({5}, {}) == {5}

Min

Returns the minimum of n arguments.

The arguments must be comparable using <.

Definition
min(val1, val2, [val3, val4 ...])
Argument Type Meaning
val1 any  
val2 any  
...    
Example
min(147,42,81.9) == 42
min("abc", "bac") == "abc"
min({5}, {}) == {}

Now

Returns current timestamp

Definition
now()
Example

The following expression results in true:

now() > timestamp("2015-06-24T17:35:50Z")

Number of purchases

Returns number of purchases of an item specified by its id.

You can use this function for example for recommending only items that have just few purchases and you need to sell them.

Note

This function is not enabled by default due to its higher resource consumption. Contact administrator if you need to use it.

Definition
num_item_purchases(id)
Argument Type Meaning
id string Id of an item
Example
num_item_purchases('itemId') < 5 # Only items with less than 5 purchases pass the filter

Random

Returns a random number between 0 and 1

Definition
random()

Size

Returns the length of a string or number of objects in a set

Definition
size(value)
Argument Type Meaning
value string set  
Examples

All the following expressions result in true:

size("Recombee") == 8

size("") == 0

size({"abc", 4, {} } ) == 3

size({ {1,2,3} } ) == 1   # Objects in nested set are not counted

Lambda functions

ReQL Lambda functions can be used for computations on sets of values.

Lambda functions take two arguments: a lambda expression and a set.

Lambda functions evaluate the lambda expression on every element of the set. The lambda expression can be any valid ReQL expression, and therefore can contain for example item properties or functions.

Quick overview

Name of the function Description Example
map Applies the lambda expression to every member of a set map(lambda 'x': 2*'x', {1, 2, 3}) == {2, 4, 6}
select Returns only those values of input set for which the lambda expression returns true select(lambda 'x': 'x' > 5, {10, 2, 13, 1}) == {10, 13}

Map

Map applies the expression to every element and returns the result as set

Definition
map(lambda 'x': EXPRESSION, input_set)
Argument Type Meaning
input_set set  
Examples

All the following expressions result in true:

map(lambda 'x': 2*'x', {1, 2, 3}) == {2, 4, 6}   # Multiplies every element of the input set by two

map(lambda 'x': number('x'), {"1", "2", "3"}) == {1, 2, 3}   # Converts every element from the input set to number

map(lambda 'x': 'x'*'x', {}) == {}   # Map applied on empty set is empty set

Select

Select returns only those values of input set for which the lambda expression returns true. The lambda expression have to return a boolean.

Definition
select(lambda 'x': EXPRESSION, input_set)
Argument Type Meaning
input_set set  
Examples

All the following expressions result in true:

select(lambda 'x': 'x'>5, {10, 2, 13, 8, 3, 4, 7}) == {10, 13, 8, 7}   # Selects only the values that are greater than five

select(lambda 'x': true , {1, "a", {}}) == {1, "a", {}}   #''true'' is satisfied for every element

select(lambda 'x': lower('x') == 'x', {"HELLO", "hello", "Hello", "a"}) == {"hello", "a"}   # Selects only the strings, that are lowercase

select(lambda 'x': number('x')<100 , {"125", "123", "251"}) == {}   # No element represents a number with value less then 100