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¶

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"]`

Miscellaneous functions
Name of the function	Description	Example
now	Returns current timestamp	`now() > timestamp("2015-06-24T17:35:50Z")`
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`
item_values	Returns property values of a particular item as a dictionary	`item_values("item-42")["description"]`
reduce	Reduces a set into a single value using an operator	`reduce("+", {1, 2, 3}) == 6`

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}`
exists	Returns true if lambda expression is satisfied for at least one element of the input set	`exists(lambda 'x': 'x' > 5, {2, 13, 4})`

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

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

String functions
Name of the function	Description	Example
upper	Converts all letters to the capital letters	`upper("AbCdefG") == "ABCDEFG"`
lower	Converts all letters to the small letters	`lower("AbCdefG") == "abcdefg`
split	Splits a string into sub-strings using a separator	`split("abc,def,ghi", ",") == ["abc", "def", "ghi"]`

Interactions handling functions
Name of the function	Description	Example
user_interactions	Returns list of interactions by a particular user	`user_interactions(context_user["userId"], {"purchases"})`
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`
num_item_ratings	Returns the number of ratings of an item	`num_item_ratings('itemId', "negative") < 10`

Geographical 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`
geo_polygon	Creates a spherical polygon represented by points with geographical coordinates	`geo_polygon([[40.800, -73.957], [40.767, -73.981], [40.764, -73.972], [40.796, -73.949]])`
geo_radius	Creates a spherical cap represented by a center with geographical coordinates and a radius in km	`geo_radius([40.689167, -74.044444], 10)`

Context functions¶

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 Recommend Items 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.

Miscellaneous functions¶

Name of the function	Description	Example
now	Returns current timestamp	`now() > timestamp("2015-06-24T17:35:50Z")`
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`
item_values	Returns property values of a particular item as a dictionary	`item_values("item-42")["description"]`
reduce	Reduces a set into a single value using an operator	`reduce("+", {1, 2, 3}) == 6`

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	Meaning
value	`string` `set`

Examples¶

All the following expressions result in true:

size("Recombee") == 8

size("") == 0

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

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

Item Values¶

Returns property values of a particular item as a dictionary

Definition¶

item_values(item_id)

Argument	Type	Meaning
item_id	`string`	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	`string`	One of `+`, `*`, `&`, `and`, `or`
input_set	`set`	Set that will be reduced
initial_value	Same type as members of `input_set`	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 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}`
exists	Returns true if lambda expression is satisfied for at least one element of the input set	`exists(lambda 'x': 'x' > 5, {2, 13, 4})`

Map¶

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

Definition¶

map(lambda 'x': EXPRESSION, input_set)

Argument	Type	Meaning
lambda expression	`lambda expression`
input_set	`set`

Examples¶

All the following expressions result in true:

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

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

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

Select¶

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

Definition¶

select(lambda 'x': EXPRESSION, input_set)

Argument	Type	Meaning
lambda expression	`lambda expression` returning boolean
input_set	`set`

Examples¶

All the following expressions result in true:

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

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

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

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

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	Meaning
lambda expression	`lambda expression` returning boolean
input_set	`set`

Examples¶

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 of the function	Description	Example
boolean	Converts the argument to boolean	`boolean("") == False`
number	Converts the argument to number	`number("456") == 456`
string	Converts the argument to string	`string(123) == "123"`
timestamp	Converts the argument to timestamp	`timestamp("2015-06-25T11:08:44Z") == timestamp(1435230524)`

Boolean conversion function¶

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

Definition¶

boolean(value_to_be_converted)

Argument	Type	Meaning
value_to_be_converted	`any type`	Value to be converted into a boolean

Examples¶

All the following expressions result in true:

boolean("Recombee") == true

boolean("") == False

boolean(42) == true

boolean(0) == False

boolean({""}) == true

boolean({}) == False

Number conversion function¶

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

Definition¶

number(value_to_be_converted)

Argument	Type	Meaning
value_to_be_converted	`string` `boolean` `timestamp` `number`	Value to be converted into a number

Examples¶

All the following expressions result in true:

number("456") == 456

number("1E4") == 10000

number(true) == 1

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

String conversion function¶

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

Definition¶

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

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

Examples¶

All the following expressions result in true:

string(123) == "123"

string(true) == "true"

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

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

Timestamp conversion function¶

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

Definition¶

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

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

Examples¶

All the following expressions result in true:

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

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

Math functions¶

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

Max¶

Returns the maximum of n arguments.

The arguments must be comparable using >.

Definition¶

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

Argument	Type	Meaning
val1	`any`
val2	`any`
…

Example¶

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

Min¶

Returns the minimum of n arguments.

The arguments must be comparable using <.

Definition¶

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

Argument	Type	Meaning
val1	`any`
val2	`any`
…

Example¶

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

Round¶

Definition¶

round(x)

Argument	Type	Meaning
x	`number`

Return value

number

Integer closest to x

Examples¶

All the following expressions result in true:

round(4.3) == 4

round(4.5) == 5

Floor¶

Definition¶

floor(x)

Argument	Type	Meaning
x	`number`

Return value

number

Largest integer preceding x

Examples¶

All the following expressions result in true:

floor(4.3) == 4

floor(4.5) == 4

Ceil¶

Definition¶

ceil(x)

Argument	Type	Meaning
x	`number`
Return value	`number`	Smallest integer following x

Examples¶

All the following expressions result in true:

ceil(4.3) == 5

ceil(4.5) == 5

Absolute value¶

Definition¶

abs(x)

Argument	Type	Meaning
x	`number`
Return value	`number`	Non-negative value of x without regard to its sign

Examples¶

All the following expressions result in true:

abs(-4.3) == 4.3

abs(4.3) == 4.3

Square root¶

Definition¶

sqrt(x)

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

Examples¶

All the following expressions result in true:

sqrt(4) == 2

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

Power function¶

Definition¶

pow(base, exponent)

Argument	Type	Meaning
base	`number`
exponent	`number`
Return value	`number`	Base raised to the power exponent (\({base}^{exponent}\))

Examples¶

All the following expressions result in true:

pow(10,3) == 1000

pow(5,-2) == 0.04

pow(-2,5) == -32

Logarithm¶

Definition¶

log(x [, base])

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

Examples¶

All the following expressions result in true:

log(1000) == 3

log(16,2) == 4

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

String functions¶

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`
split	Splits a string into sub-strings using a separator	`split("abc,def,ghi", ",") == ["abc", "def", "ghi"]`

Convert to upper case¶

Converts all letters to the capital letters

Definition¶

upper(str)

Argument	Type	Meaning
str	`string`

Examples¶

All the following expressions result in true:

upper("AbCdefG") == "ABCDEFG"

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

Convert to lower case¶

Converts all letters to small letters

Definition¶

lower(str)

Argument	Type	Meaning
str	`string`

Examples¶

All the following expressions result in true:

lower("AbCdefG") == "abcdefg"

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

Split string¶

Splits a string into sub-strings using a separator

Definition¶

split(str, separator)

Argument	Type	Meaning
str	`string`	String to be split
separator	`string`	Separator

Examples¶

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

Interactions handling functions¶

Note

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

Name of the function	Description	Example
user_interactions	Returns list of interactions by a particular user	`user_interactions(context_user["userId"], {"purchases"})`
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`
num_item_ratings	Returns the number of ratings of an item	`num_item_ratings('itemId', "negative") < 10`

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	`string`	Id of a user
interaction_types	`set`	Interaction types that should be returned
num_interactions	Non negative `integer`	Optional. Return only that number of latest interactions.

Examples¶

# 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"}))

Number of bookmarks¶

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

Definition¶

num_item_bookmarks(id)

Argument	Type	Meaning
id	`string`	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	`string`	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	`string`	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	`string`	Id of an item
rating_type	`string`	Optional. Take into consideration only `positive` or `negative` ratings.

Example¶

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

Geographical 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`
geo_polygon	Creates a spherical polygon represented by points with geographical coordinates	`geo_polygon([[40.800, -73.957], [40.767, -73.981], [40.764, -73.972], [40.796, -73.949]])`
geo_radius	Creates a spherical cap represented by a center with geographical coordinates and a radius in km	`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¶

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)

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	`array` of points	The boundary of the polygon
strict	`boolean`	Optional. Boolean specifying if any non-valid polygon results in an error. Default if not provided: `false`

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.

Examples¶

# 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¶

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	point	Coordinates of the center of the `geo_radius`
radius	`number`	Length of the `geo_radius` radius in km

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.

Examples¶

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