ReQL Functions
Functions may be used to enhance your ReQL queries β for example up-sell or getting nearby items 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#
Name | Description | Example |
---|---|---|
context_item | Retrieves property value of the item, that is currently viewed by the user. |
|
context_user | Retrieves property value of the user, that is about to obtain the recommendations. |
|
context_segment | Retrieves the Segment on which the recommendations are based. |
|
Name | Description | Example |
---|---|---|
now | Returns current timestamp |
|
random | Returns a random number between 0 and 1 |
|
size | Returns the length of a string or number of objects in a set |
|
item_values | Returns property values of a particular item as a dictionary |
|
reduce | Reduces a set into a single value using an operator |
|
Name | Description | Example |
---|---|---|
map | Applies the lambda expression to every member of a set |
|
select | Returns only those values of input set for which the lambda expression returns true |
|
exists | Returns true if lambda expression is satisfied for at least one element of the input set |
|
Name | Description | Example |
---|---|---|
boolean | Converts the argument to boolean |
|
number | Converts the argument to number |
|
string | Converts the argument to string |
|
timestamp | Converts the argument to timestamp |
|
Name | Description | Example |
---|---|---|
max | Returns the maximum of n arguments |
|
min | Returns the minimum of n arguments |
|
avg | Returns the average of n numbers |
|
round | Returns closest integer |
|
floor | Returns largest preceding integer |
|
ceil | Returns smallest following integer |
|
abs | Returns non-negative value of the argument without regard to its sign |
|
sqrt | Returns the square root of the argument |
|
pow | Returns ππππ π‘_ππππ’ππππ‘π πππππ_ππππ’ππππ‘ |
|
log | Returns the logarithm of the argument |
|
Name | Description | Example |
---|---|---|
upper | Converts all letters to the capital letters |
|
lower | Converts all letters to the small letters |
|
split | Splits a string into sub-strings using a separator |
|
Interactions Listing Functions
Name | Description | Example |
---|---|---|
user_interactions | Returns list of interactions by a particular user |
|
Interactions Statistics Functions
Name | Description | Example |
---|---|---|
num_item_bookmarks | Returns the number of bookmarks of an item |
|
num_item_detail_views | Returns the number of detail views of an item |
|
num_item_purchases | Returns the number of purchases of an item |
|
num_item_ratings | Returns the number of ratings of an item |
|
Item Segments Handling Functions
Name | Description | Example |
---|---|---|
segment_items | Get items in a Segment |
|
item_segments | Get Item Segments to which the item belongs |
|
Name | Description | Example |
---|---|---|
earth_distance | Returns the orthodromic distance between two points (given as their latitude and longitude in degrees) in meters |
|
geo_polygon | Creates a spherical polygon represented by points with geographical coordinates |
|
geo_radius | Creates a spherical cap represented by a center with geographical coordinates and a radius in km |
|
Context Functions#
Name | Description | Example |
---|---|---|
context_item | Retrieves property value of the item, that is currently viewed by the user. |
|
context_user | Retrieves property value of the user, that is about to obtain the recommendations. |
|
context_segment | Retrieves the Segment on which the recommendations are based |
|
Context Item Function#
Context item function is used in Recommend Items to Item and Recommend Item Segments to Item 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"] then 0.1 else if 'price' > context_item["price"] then 1 else 0.5
Context User Function#
Context user function is used for retrieving property values of the user that the recommendations are for.
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.
Context Segment Function#
Context Segment function is used in Recommend Item Segments to Item Segment for retrieving the Item Segment to which is being recommended.
Definition#
context_segment[property_name]
Key | Type | Meaning |
---|---|---|
property_name | string | Name of property to be retrieved. Currently only |
Examples#
# If the context Segment is "fairy tales" then explicitly dissalow "tabloid news" Segment to be ever recommended
if context_segment["segmentId"] == "fairy tales" then 'segmentId' != "tabloid news" else true
Miscellaneous Functions#
Name | Description | Example |
---|---|---|
now | Returns current timestamp |
|
random | Returns a random number between 0 and 1 |
|
size | Returns the length of a string or number of objects in a set |
|
item_values | Returns property values of a particular item as a dictionary |
|
reduce | Reduces a set into a single value using an operator |
|
Now#
Returns current timestamp.
Definition#
now()
Example#
The following expression results in true
:
now() > timestamp("2015-06-24T17:35:50Z")
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 |
---|---|
value |
|
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
Item Values#
Returns property values of a particular item as a dictionary.
Definition#
item_values(item_id)
Argument | Type | Meaning |
---|---|---|
value |
| ID of an item |
Example#
# Returns value of property "category" for item with ID "item-42"
item_values("item-42")["category"]
Reduce#
Reduces a set into a single value using an operator.
Definition#
reduce(operator, input_set, initial_value)
Argument | Type | Meaning |
---|---|---|
operator |
| One of |
input_set |
| Set that will be reduced |
initial_value | Same type as members of | Optional. Value used as left operand for the first operation. |
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.
Name | Description | Example |
---|---|---|
map | Applies the lambda expression to every member of a set |
|
select | Returns only those values of input set for which the lambda expression returns true |
|
exists | Returns true if lambda expression is satisfied for at least one element of the input set |
|
Map#
Map applies the expression to every element and returns the result as set.
Definition#
map(lambda 'x': EXPRESSION, input_set)
Argument | Type |
---|---|
lambda expression |
|
input_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 |
---|---|
lambda expression |
|
input_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
Exists#
Exists returns true if lambda expression returns true for at least one element of the input set. Otherwise returns false.
exists(lambda 'x': ...)
can be though as shorthand for size(select(lambda 'x': ...)) > 0.
Definition#
exists(lambda 'x': EXPRESSION, input_set)
Argument | Type |
---|---|
lambda expression |
|
input_set |
|
Examples#
All the following expressions result in true
:
exists(lambda 'x': 'x'>5, {2, 13, 4}) # Returns true, as 13 > 5
exists(lambda 'x': 'x'>5, {2, 1, 4}) == false # None of the elements is larger than 5
Type Conversion Functions#
Name | Description | Example |
---|---|---|
boolean | Converts the argument to boolean |
|
number | Converts the argument to number |
|
string | Converts the argument to string |
|
timestamp | Converts the argument to timestamp |
|
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 |
| 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 |
| 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 |
| Value to be converted into a string |
date_time_format |
| (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 |
| Value to be converted into a string |
date_time_format |
| (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#
Name | Description | Example |
---|---|---|
max | Returns the maximum of n arguments |
|
min | Returns the minimum of n arguments |
|
avg | Returns the average of n numbers |
|
round | Returns closest integer |
|
floor | Returns largest preceding integer |
|
ceil | Returns smallest following integer |
|
abs | Returns non-negative value of the argument without regard to its sign |
|
sqrt | Returns the square root of the argument |
|
pow | Returns ππππ π‘_ππππ’ππππ‘π πππππ_ππππ’ππππ‘ |
|
log | Returns the logarithm of the argument |
|
Max#
Returns the maximum of n arguments.
The arguments must be comparable using >
.
Definition#
max(val1, val2, [val3, val4 ...])
max(set/array value)
Argument | Type |
---|---|
val1 |
|
val2 |
|
... |
Example#
max(147,42,81.9) == 147
max("abc", "bac") == "bac"
max({5}, {}) == {5}
max({147,42,81.9}) == 147
Min#
The arguments must be comparable using <
.
Definition#
min(val1, val2, [val3, val4 ...])
min(set/array value)
Argument | Type |
---|---|
val1 |
|
val2 |
|
... |
Example#
min(147,42,81.9) == 42
min("abc", "bac") == "abc"
min({5}, {}) == {}
min({147,42,81.9}) == 42
Avg#
Definition#
avg(val1, val2, [val3, val4 ...])
avg(set/array value)
Argument | Type |
---|---|
val1 |
|
val2 |
|
... |
Example#
avg(2, 1, 5) == 4
avg({2, 1, 5}) == 4
Round#
Definition#
round(x)
Argument | Type | Meaning |
---|---|---|
x |
| |
Return value |
| Integer closest to x |
Example#
All the following expressions result in true
:
round(4.3) == 4
round(4.5) == 5
Floor#
Definition#
floor(x)
Argument | Type | Meaning |
---|---|---|
x |
| |
Return value |
| Largest integer preceding x |
Example#
All the following expressions result in true
:
floor(4.3) == 4
floor(4.5) == 4
Ceil#
Definition#
ceil(x)
Argument | Type | Meaning |
---|---|---|
x |
| |
Return value |
| Smallest integer following x |
Example#
All the following expressions result in true
:
ceil(4.3) == 5
ceil(4.5) == 5
Absolute value#
Definition#
abs(x)
Argument | Type | Meaning |
---|---|---|
x |
| |
Return value |
| Non-negative value of x without regard to its sign |
Example#
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 | |
Return value |
| Number π, such that π2=π₯ |
Example#
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 |
| |
exponent |
| |
Return value |
| Base raised to the power 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])
Argument | Type | Meaning |
---|---|---|
x | Non-negative | |
base | Non-negative | Optional. Default base is decadic. |
Return value |
| Number π¦, such that πππ ππ¦=π₯ |
Example#
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#
Name | Description | Example |
---|---|---|
upper | Converts all letters to the capital letters |
|
lower | Converts all letters to the small letters |
|
split | Splits a string into sub-strings using a separator |
|
Convert to upper case#
Converts all letters to the capital letters.
Definition#
upper(str)
Argument | Type |
---|---|
str |
|
Example#
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 |
---|---|
str |
|
Example#
All the following expressions result in true
:
lower("AbCdefG") == "abcdefg"
lower("7B&*#Δζ±ε") == "7b&*#Δζ±ε"
Split string#
Splits a string into sub-strings using a separator.
Definition#
split(str, separator)
Argument | Type | Meaning |
---|---|---|
str |
| String to be split |
separator |
| Separator |
Example#
All the following expressions result in true
:
split("abc,def,ghi", ",") == ["abc", "def", "ghi"]
Interactions Listing Functions#
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.
Name | Description | Example |
---|---|---|
user_interactions | Returns list of interactions by a particular user |
|
User Interactions#
Returns a list of interactions by a particular user.
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)
Argument | Type | Meaning |
---|---|---|
user_id |
| Id of a user |
interaction_types |
| Interaction types that should be returned |
num_interactions | Non negative | Optional. Return only that number of latest 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#
These functions are not enabled by default due to higher resource consumption.. Contact support@recombee.com if you need to enable them.
Name | Description | Example |
---|---|---|
num_item_bookmarks | Returns the number of bookmarks of an item |
|
num_item_detail_views | Returns the number of detail views of an item |
|
num_item_purchases | Returns the number of purchases of an item |
|
num_item_ratings | Returns the number of ratings of an item |
|
Number of bookmarks#
Returns number of bookmarks of an item specified by its ID.
Definition#
num_item_bookmarks(id)
Argument | Type | Meaning |
---|---|---|
id |
| ID of an item |
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.
Definition#
num_item_detail_views(id)
Argument | Type | Meaning |
---|---|---|
id |
| ID of an item |
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.
Definition#
num_item_purchases(id)
Argument | Type | Meaning |
---|---|---|
id |
| ID of an item |
Example#
num_item_purchases('itemId') < 5 # Only items with less than 5 purchases pass the filter
Number of ratings#
Returns number of ratings of an item specified by its ID.
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)
Argument | Type | Meaning |
---|---|---|
id |
| ID of an item |
rating_type |
| Optional. Take into consideration only |
Example#
num_item_ratings('itemId', "positive") > 5 # Only items with more than 5 positive ratings pass the filter
Item Segments Handling Functions#
Name | Description | Example |
---|---|---|
segment_items | Get items in a Segment |
|
item_segments | Get Item Segments to which the item belongs |
|
Items in a Segment#
Definition#
segment_items(segmentation_id, segment_id)
Argument | Type | Meaning |
---|---|---|
segmentation_id |
| ID of an Item Segmentation |
segment_id |
| ID of a Segment from the given Segmentation |
Example#
'itemId' in segment_items("genres", "thriller") # Allow only thrillers
Item Segments of an Item#
Definition#
item_segments(segmentation_id, item_id)
Argument | Type | Meaning |
---|---|---|
segmentation_id |
| ID of an Item Segmentation |
item_id |
| ID of an Item |
Example#
"thriller" in item_segments("genres", 'itemId') # Allow only thrillers
Geographical Functions#
Name | Description | Example |
---|---|---|
earth_distance | Returns the orthodromic distance between two points (given as their latitude and longitude in degrees) in meters |
|
geo_polygon | Creates a spherical polygon represented by points with geographical coordinates |
|
geo_radius | Creates a spherical cap represented by a center with geographical coordinates and a radius in km |
|
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#
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 |
| Latitude of the first point in degrees |
lon1 |
| Longitude of the first point in degrees |
lat2 |
| Latitude of the second point in degrees |
lon2 |
| Longitude of the second point in degrees |
Example#
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)
Geographical Point#
To specify a point with geographical coordinates, use an array of length two, which contains number values latitude and longitude as its elements, respectively:
[40.713056, -74.013333] # Geographical coordinates of One World Trade Center
Geographical Polygon#
Creates a spherical polygon represented by points with geographical coordinates, on which queries of testing for geographical containment may be applied.
Definition#
geo_polygon(polygon points, strict)
Argument | Type | Meaning |
---|---|---|
polygon points |
| The boundary of the polygon |
strict |
| Optional. Boolean specifying if any non-valid polygon results in an error. Default if not provided: |
- 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]], tru
Geographical Radius#
Creates a spherical cap represented by a center point with geographical coordinates and a radius in km, on which queries of testing for geographical containment may be applied.
Definition#
geo_radius(center point, radius)
Argument | Type | Meaning |
---|---|---|
center point | Coordinates of the center of the | |
radius |
| Length of the |
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)