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 movierecommendation domain:
Name: string  Year:int  Genres: set  ParentalAdvisory: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 ParentalAdvisory flag set on. Hence you may use the following simple ReQL filtering expression:
not 'ParentalAdvisory'
Then the recommender may only choose one of the following movies:
Name: string  Year:int  Genres: set  ParentalAdvisory: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  ParentalAdvisory: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  ParentalAdvisory: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 tiebreaking 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 – doubleprecision floatingpoint 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. 
123E2  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[az]+"  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 nonempty 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 nonempty 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 nonempty set in not a proper superset of itself. 
{ 1, 2 } > {}  true  Every nonempty 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. 
Intersection¶
Expression  Result  Comment 

{ 1, 2 } & { 2, 3 }  { 2 }  Set intersection may be obtained using the & operator. 
{ 1, 2 } & { 2.0, 3.0 }  { 2 }  Integers, doubles, and timestamps are considered equal if they equal in values. 
{ 1, 2 } & {"1", "2"}  {}  Strings and numbers are handled as different values. 
{"a", { 1, 2 }} & {"b", { 1, 2 }}  {{1,2}}  Works with subsets. 
Symmetric difference¶
Expression  Result  Comment 

{ 1, 2 } / { 2, 3 }  { 1, 3 }  Symmetric difference of sets may be obtained using the / operator. 
{ 1, 2 } / { 2.0, 3.0 }  { 1, 3 }  Integers, doubles, and timestamps are considered equal if they equal in values. 
{ 1, 2 } / {"1", "2"}  {1, 2, "1", "2"}  Strings and numbers are handled as different values. 
{"a", { 1, 2 }} / {"b", { 1, 2 }}  {"a", "b"}  Works with subsets. 
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  Nonempty strings are truthy. 
not {}  true  Empty sets are falsy. 
not {1,2,3}  false  Nonempty 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"  thenvalue is returned if the condition is satisfied. 
if 'a' < 'b' then "foo" else "bar"  10  5  "bar"  elsevalue 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"  ifelse 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"  Nonempty strings are truthy. 
if {} then "foo" else "bar"  "bar"  Empty sets are falsy. 
if {1,2,3} then "foo" else "bar"  "foo"  Nonempty 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 upsell or crosssell 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("20150625T11: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 nonnegative 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("20150624T17: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 

“television42”  369  “television” 
“television49”  449  “television” 
“remotecontrol13”  25  “remotecontrol” 
Example 1¶
Suppose that the user is currently viewing television42. Then the following expression returns 369, because that is the price of the context item.
context_item["price"]
Example 2: upsell¶
Suppose that the user is currently viewing television42. 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 television49 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: crosssell¶
Suppose that the user is currently viewing television42. You may want to suggest him some additional product from a different category. The filter is very simple:
'category' != context_item["category"]
remotecontrol13 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 

“user27”  [“EN”] 
“user29”  [“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 user27 (which can speak only english) Pulp Fiction or Fight Club can be recommended.
For user29 (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("20150625T11: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') == "20150625T11: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("20150625T11: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 nonnegative 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¶
Floor¶
Ceil¶
Absolute value¶
Definition¶
abs(x)
Argument  Type  Meaning 

x  number  
Return value  number  Nonnegative value of x without regard to its sign 
Square root¶
Definition¶
sqrt(x)
Argument  Type  Meaning 

x  Nonnegative 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 nonnegative 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  Nonnegative number  
base  Nonnegative 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 nonnegative 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 
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("20150624T17:35:50Z") 
num_item_bookmarks  Returns the number of bookmarks of an item  num_item_bookmarks('itemId') < 10 
num_item_detail_views  Returns the number of detail views of an item  num_item_detail_views('itemId') < 10 
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 >.
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 <.
Example¶
min(147,42,81.9) == 42
min("abc", "bac") == "abc"
min({5}, {}) == {}
Number of bookmarks¶
Returns number of bookmarks of an item specified by its id.
Note
This function is not enabled by default due to its higher resource consumption. Contact administrator at support@recombee.com if you need to use it.
Example¶
num_item_bookmarks('itemId') < 5 # Only items with less than 5 bookmarks pass the filter
Number of detail views¶
Returns number of detail views of an item specified by its id.
Note
This function is not enabled by default due to its higher resource consumption. Contact administrator at support@recombee.com if you need to use it.
Example¶
num_item_detail_views('itemId') < 5 # Only items with less than 5 detail views pass the filter
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 at support@recombee.com if you need to use it.
Example¶
num_item_purchases('itemId') < 5 # Only items with less than 5 purchases pass the filter
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
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.
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