ReQL 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 Functions

context_item["price"]

context_user["country"]

context_segment["segmentId"]

Miscellaneous Functions

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

1>=random()>=0

size("Recombee") == 8

item_values("item-42")["description"]

reduce("+", {1, 2, 3}) == 6

Lambda Functions

map(lambda 'x': 2*'x', {1, 2, 3}) == {2, 4, 6}

select(lambda 'x': 'x' > 5, {10, 2, 13, 1}) == {10, 13}

exists(lambda 'x': 'x' > 5, {2, 13, 4})

Type Conversion Functions

boolean("") == False

number("456") == 456

string(123) == "123"

timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)

Math Functions

max(147,42,81.9) == 147

min(147,42,81.9) == 42

avg(2, 4) == 3

round(4.5) == 5

floor(4.3) == 4

ceil(4.3) == 5

abs(-4.3) == 4.3

sqrt(4) == 2

pow(10,3) == 1000

log(1000) == 3

String Functions

upper("AbCdefG") == "ABCDEFG"

lower("AbCdefG") == "abcdefg

split("abc,def,ghi", ",") == ["abc", "def", "ghi"]

Interactions Listing Functions

user_interactions(context_user["userId"], {"purchases"})

Interactions Statistics Functions

num_item_bookmarks('itemId') < 10

num_item_detail_views('itemId') < 10

num_item_purchases('itemId') < 10

num_item_ratings('itemId', "negative") < 10

Item Segments Handling Functions

'itemId' in segment_items("genres", "thriller")

"thriller" in item_segments("genres", 'itemId')

Geographical Functions

earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000

geo_polygon([[40.800, -73.957], [40.767, -73.981], [40.764, -73.972], [40.796, -73.949]])

geo_radius([40.689167, -74.044444], 10)

Context Functions

context_item["price"]

context_user["country"]

context_segment["segmentId"]

Context Item Function

Definition

context_item[property_name]

(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.

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"] then 0.1 else if  'price' > context_item["price"] then 1 else 0.5

Context User Function

Definition

context_user[property_name]

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

And sample items, which are some movies:

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.

Context Segment Function

Definition

context_segment[property_name]

Examples

// If the context Segment is "fairy tales"
// then explicitly disallow "tabloid news" Segment to be ever recommended

if context_segment["segmentId"] == "fairy tales"
	then 'segmentId' != "tabloid news"
	else true

Miscellaneous Functions

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

1>=random()>=0

size("Recombee") == 8

item_values("item-42")["description"]

reduce("+", {1, 2, 3}) == 6

Now

Definition

now()

Example

The following expression results in true:

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

Random

Definition

random()

Size

Definition

size(value)

Examples

All the following expressions result in true:

size("Recombee") == 8

size("") == 0

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

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

Item Values

Definition

item_values(item_id)

Example

// Returns value of property "category" for item with ID "item-42"
item_values("item-42")["category"]

Reduce

Definition

reduce(operator, input_set, initial_value)

Example

All the following expressions result in true:

reduce("+", {2, 3, 4}) == 9

reduce("+", {2, 3, 4}, 1) == 10

reduce("*", {2, 3, 4}) == 24

reduce("and", {true, false, true}) == false

reduce("or", {true, false, true}) == true

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.

map(lambda 'x': 2*'x', {1, 2, 3}) == {2, 4, 6}

select(lambda 'x': 'x' > 5, {10, 2, 13, 1}) == {10, 13}

exists(lambda 'x': 'x' > 5, {2, 13, 4})

Map

Definition

map(lambda 'x': EXPRESSION, input_set)

Examples

All the following expressions result in true:

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

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

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

Select

Definition

select(lambda 'x': EXPRESSION, input_set)

Examples

All the following expressions result in true:

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

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

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

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

Exists

exists(lambda 'x': ...) can be though as shorthand for size(select(lambda 'x': ...)) > 0.

Definition

exists(lambda 'x': EXPRESSION, input_set)

Examples

All the following expressions result in true:

// Returns true, as 13 > 5
exists(lambda 'x': 'x'>5, {2, 13, 4})

// None of the elements is larger than 5
exists(lambda 'x': 'x'>5, {2, 1, 4}) == false

Type Conversion Functions

boolean("") == False

number("456") == 456

string(123) == "123"

timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)

Boolean conversion function

Definition

boolean(value_to_be_converted)

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

Definition

number(value_to_be_converted)

Examples

All the following expressions result in true:

number("456") == 456

number("1E4") == 10000

number(true) == 1

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

String conversion function

Definition

string(value_to_be_converted [, date_time_format (only if value_to_be_converted is a timestamp)])

Examples

All the following expressions result in true:

string(123) == "123"

string(true) == "true"

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

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

Timestamp conversion function

Definition

timestamp(value_to_be_converted [, date_time_format (only if value_to_be_converted is a string) ] )

Examples

All the following expressions result in true:

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

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

Math Functions

max(147,42,81.9) == 147

min(147,42,81.9) == 42

avg(2, 4) == 3

round(4.5) == 5

floor(4.3) == 4

ceil(4.3) == 5

abs(-4.3) == 4.3

sqrt(4) == 2

pow(10,3) == 1000

log(1000) == 3

Max

Alternatively, if you provide a single set/array, it returns the maximum of its values.

The arguments must be comparable using >.

Definition

max(val1, val2, [val3, val4 ...])

max(set/array value)

Example

max(147,42,81.9) == 147
max("abc", "bac") == "bac"
max({5}, {}) == {5}

max({147,42,81.9}) == 147

Min

Alternatively, if you provide a single set/array, it returns the minimum of its values.

The arguments must be comparable using <.

Definition

min(val1, val2, [val3, val4 ...])

min(set/array value)

Example

min(147,42,81.9) == 42
min("abc", "bac") == "abc"
min({5}, {}) == {}

min({147,42,81.9}) == 42

Avg

Alternatively, if you provide a single set/array of values, it returns the average of its values.

Definition

avg(val1, val2, [val3, val4 ...])

avg(set/array value)

Example

avg(2, 1, 5) == 4
avg({2, 1, 5}) == 4

Round

Definition

round(x)

Example

All the following expressions result in true:

round(4.3) == 4

round(4.5) == 5

Floor

Definition

floor(x)

Example

All the following expressions result in true:

floor(4.3) == 4

floor(4.5) == 4

Ceil

Definition

ceil(x)

Example

All the following expressions result in true:

ceil(4.3) == 5

ceil(4.5) == 5

Absolute value

Definition

abs(x)

Example

All the following expressions result in true:

abs(-4.3) == 4.3

abs(4.3) == 4.3

Square root

Definition

sqrt(x)

Example

All the following expressions result in true:

sqrt(4) == 2

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

Power function

Definition

pow(base, exponent)

Example

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])

Example

All the following expressions result in true:

log(1000) == 3

log(16,2) == 4

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

String Functions

upper("AbCdefG") == "ABCDEFG"

lower("AbCdefG") == "abcdefg

split("abc,def,ghi", ",") == ["abc", "def", "ghi"]

Convert to upper case

Definition

upper(str)

Example

All the following expressions result in true:

upper("AbCdefG") == "ABCDEFG"

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

Convert to lower case

Definition

lower(str)

Example

All the following expressions result in true:

lower("AbCdefG") == "abcdefg"

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

Split string

Definition

split(str, separator)

Example

All the following expressions result in true:

split("abc,def,ghi", ",") == ["abc", "def", "ghi"]

Interactions Listing Functions

Note

These functions are not enabled by default due to higher resource consumption. Contact support@recombee.com if you need to enable them, and please specify the types of interactions needed in your request.

user_interactions(context_user["userId"], {"purchases"})

User Interactions

These interactions are of given interaction_types and are ordered by timestamp from the oldest to the most recent.

Each interaction is a dictionary with following fields:

{
  "userId": string,
  "itemId": string,
  "timestamp": timestamp,
  "type": string
}

Definition

user_interactions(user_id, interaction_types, num_interactions)

Example

// Get IDs of items that the user purchased or viewed
map(lambda 'it': 'it'["itemId"], user_interactions(context_user["userId"], {"detail_views", "purchases"}))


// Returns true if the user consumed some content in French
exists(lambda 'it': item_values('it'["itemId"])["language"] == "FR",
			user_interactions(context_user["userId"], {"purchases"}))

Interactions Statistics Functions

Note

These functions are not enabled by default due to higher resource consumption.. Contact support@recombee.com if you need to enable them.

num_item_bookmarks('itemId') < 10

num_item_detail_views('itemId') < 10

num_item_purchases('itemId') < 10

num_item_ratings('itemId', "negative") < 10

Number of bookmarks

Definition

num_item_bookmarks(id)

Example

// Only items with less than 5 bookmarks pass the filter
num_item_bookmarks('itemId') < 5

Number of detail views

Definition

num_item_detail_views(id)

Example

// Only items with less than 5 detail views pass the filter
num_item_detail_views('itemId') < 5

Number of purchases

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

Definition

num_item_purchases(id)

Example

// Only items with less than 5 purchases pass the filter
num_item_purchases('itemId') < 5

Number of ratings

Optionally you can get number of only the positive ratings (> 0) or negative (< 0) ratings.

You can use this function for example for recommending only items that have already a certain number of positive ratings.

Definition

num_item_ratings(id, rating_type)

Example

// Only items with more than 5 positive ratings pass the filter
num_item_ratings('itemId', "positive") > 5

Item Segments Handling Functions

'itemId' in segment_items("genres", "thriller")

"thriller" in item_segments("genres", 'itemId')

Items in a Segment

Definition

segment_items(segmentation_id, segment_id)

Example

// Allow only thrillers
'itemId' in segment_items("genres", "thriller")

Item Segments of an Item

Definition

item_segments(segmentation_id, item_id)

Example

// Allow only thrillers
"thriller" in item_segments("genres", 'itemId')

Geographical Functions

earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000

geo_polygon([[40.800, -73.957], [40.767, -73.981], [40.764, -73.972], [40.796, -73.949]])

geo_radius([40.689167, -74.044444], 10)

Geographical functions geo_polygon and geo_radius construct geographical values, on which queries for testing geographic containment may be applied. For a detailed description and examples of usage, see the Geographical Containment section.

Earth Distance

Definition

earth_distance(lat1,lon1,lat2,lon2)

Example

All the following expressions result in true:

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

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

Geographical Point

// Geographical coordinates of One World Trade Center
[40.713056, -74.013333]

Geographical Polygon

Definition

geo_polygon(polygon points, strict)

• A polygon is specified as an array of geographical coordinates of at least 3 points
• The points of a polygon can be specified in both CW and CCW orders
• The interior of a polygon is such that the polygon encloses at most half of the sphere (from two possible interpretations of a polygon, the one with the smaller area is considered). The interior does not include the boundary, except for the points

To avoid ambiguity of the requests, the following requirements should be kept:

• No two points of a polygon may share coordinates (the first and the last point are presumed to be connected automatically),
• Edges of a polygon may not cross anywhere but in the points

By default, if any of the requirements above are not fulfilled, the geo containment query will be handled on a best-effort basis.

Should you want to enable strict checking, set the boolean parameter strict to true. In that case, any failure to comply with the requirements will result in an error.

Example

// A geo_polygon roughly encompassing NYC's Manhattan
geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]])

// A geo_polygon roughly encompassing NYC's Manhattan with strict checking
geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]], true)

Geographical Radius

Definition

geo_radius(center point, radius)

Everything that is within the orthodromic distance of a given radius to the center point is contained within the geo_radius (inclusively).

Nothing is contained within a geo_radius with a negative radius, and everything is contained within a geo_radius with a radius larger than half of the Earth Equator’s length.

Example

// A geo_radius of 10km around Statue of Liberty
geo_radius([40.689167, -74.044444], 10)

Geographical Containment

Geographical values geo_polygon and geo_radius support the in operator for checking containtment of a geographical point. The result of the operator is truthy if the point is contained within the given geographical value. The syntax of such a query is: point in geographical value.

Examples

All the following expressions result in true:

// One World Trade Center is contained within a geo_polygon roughly encompassing NYC's Manhattan
[40.713056, -74.013333] in geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]])

// One World Trade Center is contained within a geo_radius of 10km around Statue of Liberty
[40.713056, -74.013333] in geo_radius([40.689167, -74.044444], 10)