Filtering and Boosting¶
Filtering¶
In filtering, the expression must return boolean value for each item. If the returned value is true
, the item passed the filter; if the value is false
, the item does not pass and will be discarded. The value is computed from set property values of the individual items.
Consider the following table of items in sample movierecommendation domain:
Name: 
Year: 
Director: 
Genres: 
ParentalAdvisory: 


Pulp Fiction 
1994 
Quentin Tarantino 
{“Crime Fiction”,”Drama”
“Thriller” }



King Kong 
2005 
Peter Jackson 
{“Action”, “Drama”,
“Adventure” }



Fight Club 
1999 
David Fincher 
{“Drama”, “Existentialism”}



The Lord of the Rings: The Return of the King 
2003 
Peter Jackson 
{ “Adventure”, “Fantasy”,
“Action” }



The Dark Knight 
2008 
Christopher Nolan 
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}



Silence of the Lambs 
1991 
Jonathan Demme 
{“Crime Fiction”, “Drama”,
“Thriller”, “Horror” }



Dead Alive 
1992 
Peter Jackson 
{“Horror”, “Comedy”}



… and 10000 other movies 
Example 1¶
By default, when items are to be recommended to a given user, the recommender selects any items which seem relevant to the user. 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 from the following movies:
Name: 
Year: 
Director: 
Genres: 
ParentalAdvisory: 


King Kong 
2005 
Peter Jackson 
{“Action”, “Drama”,
“Adventure” }



The Lord of the Rings: The Return of the King 
2003 
Peter Jackson 
{ “Adventure”, “Fantasy”,
“Action” }



The Dark Knight 
2008 
Christopher Nolan 
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}



… and 5926 other movies 
Example 2¶
If you want to allow only items without ParentalAdvisory
which were directed by Peter Jackson (for example because a user selected such a filter at your site) you can do it by:
(not 'ParentalAdvisory') and ('Director' == "Peter Jackson")
Note
You can access value of a property by putting name of the property into the single quotes. Strings are enclosed in double quotes.
Only following items can be recommended:
Name: 
Year: 
Director: 
Genres: 
ParentalAdvisory: 

King Kong 
2005 
Peter Jackson 
{“Action”, “Drama”,
“Adventure” }


The Lord of the Rings: The Return of the King 
2003 
Peter Jackson 
{ “Adventure”, “Fantasy”,
“Action” }


Example 3¶
As another example, consider that user entered the Thriller section of your system’s catalog. Then you sure wish to recommend thrillers, ignoring the fact that usually, the user likes comedies.
As the Genres is a set
property, you can use the in
operator for checking whether Thriller is listed in the item’s genres:
"Thriller" in 'Genres'
Only the following items pass the filter:
Name: 
Year: 
Director: 
Genres: 
ParentalAdvisory: 


Pulp Fiction 
1994 
Quentin Tarantino 
{“Crime Fiction”,”Drama”
“Thriller” }



The Dark Knight 
2008 
Christopher Nolan 
{“Superhero”,”Drama”
,”Action”,”Adventure”,
“Thriller”,”Crime Fiction”}



Silence of the Lambs 
1991 
Jonathan Demme 
{“Crime Fiction”, “Drama”,
“Thriller”, “Horror” }



… and 3141 other movies 
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 available. 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 typeboolean
(the implicit value for all items will benull
, which is OK).For deleted items, set the value of
deleted
true
.For recommendations, use the following filter:
not 'deleted'
If the item becomes available again, you may set
deleted
tofalse
.
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: 
Year: 
Boosting 

Pulp Fiction 
1994 

King Kong 
2005 

Fight Club 
1999 

The Lord of the Rings: The Return of the King 
2003 

The Dark Knight 
2008 

Silence of the Lambs 
1991 

Dead Alive 
1992 

… and 10000 other movies 
Examples¶
Exclude some items from recommendations using their IDs¶
Use
filter
:'itemId' not in {"item127", "item756", "item568"}The three items will not be recommended.
Boost items that were published in last 24 hours¶
Suppose that the items have a timestamp property
published_date
. Then you can use thisbooster
:if 'published_date' >= now()  24 * 60 * 60 then 2 else 1now returns current UTC timestamp in seconds.
24 * 60 * 60
is the number of seconds in 24 hours.
Upsell¶
Suppose that the items have a double property
price
. Slightly boost items that are more expensive then the currently viewed one with followingbooster
in Recommend Items to Item:if 'price' > context_item["price"] then 1.2 else 1
Recommend only items available in user’s city¶
Suppose that the items have a set property
cities
. It contains cities in which the items are available.Suppose that the users have a string property
city
giving the city where each user live.To recommend only items available in a user’s city, use
filter
:context_user["city"] in 'cities'context_user function is used for retrieving property values of the user for which you request the recommendations.
Recommend only items from subscribed topics¶
Assume your site contains articles about various topics. The users can choose which topics are interesting for them in order to receive personalized newsletters with articles from these topics.
The subscribed topics are stored for each user in a User property of type set called
subscribed_topics
.Each article can belong to multiple topics, stored in the
topics
item property of the type set.
The following filter
allows only items that contain at least one matching topic to be recommended:
size(context_user["subscribed_topics"] & 'topics') > 0
The &
operator returns the intersection of the two sets, which must be nonempty.
Value Types and Operators¶
ReQL support following value types:
int
– signed integer (currently 64bit),
double
– doubleprecision floatingpoint number (IEEE 754 compliant),
timestamp
– UTC timestamp, similar todouble
,
string
– sequence of Unicode characters,
boolean
– binary data type of two possible values:true
orfalse
,
set
– unordered collection of values.
array
– ordered collection of values.
Except for set
and aray
types, 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 item / user property values in the API.
Numbers¶
Notation¶
Expression 
Equivalent 
Comment 



Leading and trailing zeros are ignored. 


Exponential notation may be used. 


Using simple exponential notation for huge numbers. 


Negative exponents may also be used. Case of the 
Operations¶
Expression 
Result 
Comment 



Addition. 


Chain of additions. 


Subtraction. 


Chain of subtractions. 


Unary minus. 


Multiplication. 


Standard operator precedence. 


Bracketing. 


Division. 


Division always results in double, event if the operands are integers! 


If the divisor is 


Modulo division. 


Modulo division also works for doubles. 


If the divisor is 
Comparison¶
Expression 
Result 
Comment 



Integers, doubles, and timestamps may be compared using standard comparison operators. 


Comparison operators may be arbitrarily chained. 


Chain of comparisons returns 


In comparison, there is no difference between integers, doubles, and timestamps. 
Strings¶
Notation¶
Expression 
Comment 


Strings constants are enclosed in double quotes. 

Empty string. 

Double quotes must be escaped. 

Single quotes needn’t be escaped. 
Comparison¶
Expression 
Result 
Comment 



Strings are compared for equality with 


Strings can be compared to 


Strings are ordered in lexicographic order 


Comparisons may be chained arbitrarily. 


Comparisons in the chain may be of different types. 


All the comparisons must hold for the chain to return 

error 
Strings are only comparable with strings. 


Strings can be matched with regular expressions (regex). 
Containment¶
Expression 
Result 
Comment 






Containment test is case sensitive. 





Empty string is contained in every string. 


No nonempty string is contained in empty string. 

error 
Both operands must be strings for string containment testing. 
Concatenation¶
Expression 
Result 
Comment 



Strings can be concatenated using the 


Empty string is neutral element for concatenation. 


Strings can be concatenated with integers. 


Strings can be concatenated with numbers. 
Indexing and Slicing¶
Expression 
Result 
Comment 



A character in the string can be accessed by its index (starting from 


Requesting an index outside the array boundaries results in an empty string. 


Negative indices are interpreted as counting from the end of the string. 


It is possible to get a substring between two indices 


If the second index is omitted, all characters until the end of the string are returned. 
Sets¶
Notation¶
Expression 
Comment 


Empty set. 

Set containing three integers. 

Sets may contain values of different types. This is an extension to sets in the API, which may only contain strings. 

Sets may be nested. 
Properties¶
Expression 
Result 
Comment 



Sets only contain unique elements. 


Integers, doubles, and timestamps, are merged. 


Merging also works for nested sets. 
Value Containment¶
Expression 
Result 
Comment 



Using 


The 


There is no difference between integers, doubles, and timestamps when testing containment. 


There is a difference between numbers and strings. 






Comparison¶
Expression 
Result 
Comment 



Using 


No set is a proper subset of itself. 


Empty set is a proper subset of every nonempty set. 


Empty set is not a proper subset of itself. 


Using 


Every set is a subset of itself. 











Every set is a superset of itself. 





A nonempty set in not a proper superset of itself. 


Every nonempty set is a proper superset of an empty set. 


Empty set is not a proper subset of itself. 
Union¶
Expression 
Result 
Comment 



Sets may be unified using the 


Integers, doubles, and timestamps are merged when unifying sets. 


Unions may be chained. 


Unification with empty set has no effect on the original set. 


Strings and numbers are handled as different values. 
Difference¶
Expression 
Result 
Comment 



Set difference may be obtained using the 


Integers, doubles, and timestamps are considered equal if they equal in values. 


Subtracting an empty set has no effect. 


Chaining of set subtractions works from left to rights. 


Parenthesizing also works. 
Intersection¶
Expression 
Result 
Comment 



Set intersection may be obtained using the 


Integers, doubles, and timestamps are considered equal if they equal in values. 


Strings and numbers are handled as different values. 


Works with subsets. 
Symmetric difference¶
Expression 
Result 
Comment 



Symmetric difference of sets may be obtained using the 


Integers, doubles, and timestamps are considered equal if they equal in values. 


Strings and numbers are handled as different values. 


Works with subsets. 
Arrays¶
Notation¶
Expression 
Comment 


Empty array. 

Array containing three integers. 

Arrays may contain values of different types. 

Arrays may be nested. 
Value Containment¶
Expression 
Result 
Comment 



Using the 


The 


There is no difference between integers, doubles, and timestamps when testing containment. 


There is a difference between numbers and strings. 
Comparison¶
Expression 
Result 
Comment 









Order of the elements must be the same in both arrays for equality 
Concatenation¶
Expression 
Result 
Comment 



Arrays may be concatenated using the 


Concatenations may be chained. 


Concatenating an empty array has no effect on the original array. 
Indexing and Slicing¶
Expression 
Result 
Comment 



Value can be accessed by their index (starting from 


Requesting an index outside the array boundaries results in null. 


Negative indices are interpreted as counting from the end of the array. 


It is possible to get a subarray between two indices 


If the second index is omitted, all elements until the end of the array are returned. 
Logical Operators¶
Negation (NOT)¶
Expression 
Comment 









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



Negative numbers are truthy. 


Zero numbers are falsy. 


Positive numbers are truthy. 


Empty strings are falsy. 


Nonempty strings are truthy. 


Empty sets are falsy. 


Nonempty sets are truthy. 



Disjunction (OR)¶
Expression 



Result 
Comment 






If both operands are 





If at least one of boolean operands is 





If at least one of boolean operands is 





If both the operands are 
Advanced uses: Implicit conversion to boolean.
Expression 
Result 
Comment 



If the first operand truthy, it is returned. 


If the first operand is falsy, the second operand is returned. 


If the first operand is falsy, the second operand is returned. 
Conjunction (AND)¶
Expression 



Result 
Comment 






If both operands are 





If at least one of boolean operands is 





If at least one of boolean operands is 





If both the operands are 
Advanced uses: Implicit conversion to boolean.
Expression 
Result 
Comment 



If the first operand truthy, the second operand is returned. 


If the first operand is falsy, it is returned. 


If the first operand is falsy, it is returned. 
Conditional Operator¶
Expression 


Result 
Comment 












error 







Expression 
Result 
Comment 



Negative numbers are truthy. 


Zero numbers are falsy. 


Positive numbers are truthy. 


Empty strings are falsy. 


Nonempty strings are truthy. 


Empty sets are falsy. 


Nonempty sets are truthy. 


