Geospatial operators

You can write rules to reason over geographic locations.

The following table lists geospatial operators. <a geometry> refers to any type of geometry that is defined in the business model, such as a point, a polygon, or a line string. For example, the position of a flight is a geometry, where the position is an attribute of type point that belongs to a flight entity.

For more information about geospatial concepts, see Geographic location and data.

Table 1. Geospatial operators
Construct	Definition	Example
`<a geometry> contains <a geometry>`	Checks whether a geometry contains another geometry. Returns a boolean.	`'the landing area' contains the position of 'the flight'`
`the geometries among <geometries> contained in <a geometry>`	Returns the geometries that are contained in a geometry.	`the geometries among 'points of interest' contained in 'market area'`
`the geometries among <geometries> containing <a geometry>`	Returns the geometries that contain a geometry.	`the geometries among the trajectories of 'the flight' containing the position of 'the flight'`
`the distance between <a geometry> and <a geometry> in <a length unit>`	Calculates the distance between two geometries in the specified unit of length.	`the distance between 'the car' and 'the destination' in kilometers`
`the geometries among <geometries> within distance of <a number> <a length unit> to <a geometry>`	Returns all the geometries that are at the specified distance or closer to the specified geometry.	`the geometries among 'points of interest' within distance of 3 kilometers to 'my location'`
`<a geometry> intersects <a geometry>`	Checks whether a geometry crosses another geometry.	`'the ship route' intersects 'the restricted area'`
`the nearest geometries among <geometries> to <a geometry>`	Returns the geometry in a collection of geometries that is closest to another geometry. Important: This operator returns a geometry of type `geometry`. If you need more specific return types such as point, polygon, and line string, use the operators specific to these types.	`the nearest geometries among the car parks of the town to the location of 'the customer'`
`the nearest point among <points> to <a geometry>`	Returns the point in a collection of points that is closest to a geometry.	`the nearest point among the banks of the town to the location of 'the customer'`
`the nearest polygon among <polygons> to <a geometry>`	Returns the polygon in a collection of polygons that is closest to a geometry.	`the nearest polygon among the car parks of the town to the location of 'the customer'`
`the nearest line string among <line strings> to <a geometry>`	Returns the line string in a collection of line strings that is closest to a geometry.	`the nearest line string among the highways of the area to the location of 'the customer'`
`the <a number> nearest geometries among <geometries> to <a geometry>`	Returns a maximum number of `N` geometries that are closest to the specified geometry.	`the 3 nearest geometries among the car parks of the town to the location of 'the customer'`
`the <a number> nearest line strings among <line strings> to <a geometry>`	Returns a maximum number of `N` line strings that are closest to the specified geometry.	`the 3 nearest line strings among the roads of the town to the location of 'the customer'`
`the <a number> nearest polygons among <polygons> to <a geometry>`	Returns a maximum number of `N` polygons that are closest to the specified geometry.	`the 2 nearest polygons among the car parks of the town to the location of 'the customer'`
`the <a number> nearest points among <points> to <a geometry>`	Returns a maximum number of `N` points that are closest to the specified geometry.	`the 4 nearest points among the interest points of the town to the location of 'the customer'`

Table 2. Geospatial operators for moving geometries
Construct	Description	Example
`set <a moving geometry attribute> to a new moving geometry [ tracked for <calendar duration> ]`	Initializes a moving geometry attribute. The optional `tracked for <calendar duration>` construct keeps the history of timestamped geometries for the specified time period. If this construct is not specified, the history limit of timestamped geometries is kept for 24 hours.	`set 'the location of the car' to a new moving geometry tracked for 2 days`
`move <moving geometry attribute> to <geometry value>`	Updates the location of a moving geometry to its current location, which corresponds to the value of `now`.	`move 'the location of the car' to the position of this car position update event`
`move <moving geometry attribute> to <geometry value> at <date & time>`	Updates the location of a moving entity to its new location at a specific time.	`move 'the location of the car' to the location of the gas station at the timestamp of the fueling report`
`observed <moving geometry attribute> at <date & time>`	Returns the geometry value that represents the location of the entity at a given timestamp. If no specific value is reported at that timestamp with the `move` operator, the `observed` operator uses a linear interpolation if the geometry is a point, otherwise it returns the latest geometry reported before the timestamp.	`set 'location at report time' to observed position of the cas at 2 minutes after the timestamp of the fueling report`
`the maximal \| minimal \| average speed of <moving geometry> in <speed unit> over <time period>`	Calculates the maximal, minimal, or average speed of a moving geometry over a time period.	`set 'average speed' to the average speed of 'moving car' in kilometers per hour over the last period of 10 minutes`
`<moving geometry> is leaving <geometry>`	Checks that the distance between the two geometries is increasing with time, based on the recent history. If the history has less than 2 available timestamps, the operator returns false.	`if the position of the car is leaving the area of the mall then...`
`<moving geometry> is approaching <geometry>`	Checks that the distance between the two geometries is decreasing with time, based on the recent history. If the history has less than 2 available timestamps, the operator returns false.	`if the train is approaching the crossing then...`
`acceleration of <moving geometry> in <acceleration unit>`	Calculates the acceleration rate of a moving geometry, based on the recent history. If the history has less than 3 available timestamps, the operator returns 0.	`set 'acceleration' to acceleration of the car in meters per second squared`
`<moving geometry> is accelerating`	Checks that a moving geometry is accelerating, based on the recent history. If the history has less than 3 available timestamps, the operator returns 0.	`if it is true that the car is accelerating then...`
`<moving geometry> is decelerating`	Checks that a moving geometry is decelerating, based on the recent history. If the history has less than 3 available timestamps, the construct returns 0.	`if it is true that the car is decelerating then...`
`<moving geometry> has been located in <a polygon> during <time period>`	Checks that a moving geometry was located inside a polygon during the specified time period, based on the recent history. The construct returns true if the geometry is in the polygon at some of its timestamps, namely all those timestamps that are included in the time period as well as the latest timestamp before or at the start of the time period. If the earliest timestamp is after the start of the required time period, the construct returns false.	`if the car has been located in the parking area during the last period of 1 hour then...`
`<moving geometry> has been located in <a polygon> since <date & time>`	Checks that a moving geometry was located inside a polygon since the specified time point, based on the recent history.	`if the car has been located in the area of the parking since 10/04/2015 then...`
`<moving geometry> has been located within <number> <length unit> from <a geometry> during <time period>`	Checks that a moving geometry was located within a specific distance of a geometry during the specified time period, based on the recent history. If the earliest timestamp is after the start of the required time period, the construct returns false.	`if the person has been located within 100 meters from the area of the mall during the last period of 1 hour then...`
`<moving geometry> has been located within <number> <length unit> of <a geometry> since <date & time>`	Checks that a moving geometry was located within a specific distance of a geometry since the specified time point, based on the recent history.	`if the person has been located within 100 meters of the area of the mall since 10/04/2015 then...`
`encounters between <moving geometry> and <geometry> [ within proximity of <number> <length unit> ]`	Returns a list of time intervals for all encounters between the two geometries.	`set 'visits' to encounters between the position of the person and the mall within proximity of 100 meters`
`the latest encounter between <moving geometry> and <geometry> [ within proximity of <number> <length unit> ]`	Returns the time of the latest encounter between the two geometries.	`set 'latest visit' to the latest encounter between the person and the park`
`the earliest encounter between <moving geometry> and <geometry> [ within proximity of <number> <length unit> ]`	Returns the time of the earliest encounter within the specified range between the two geometries.	`set 'first visit' to the earliest encounter between the person and the park`
`<moving geometry> has entered <a polygon> [ since <date & time> ]`	Checks whether the moving geometry entered a polygon. If no `since` construct is specified, the result is based on the last 2 available timestamps. If the `since` construct is specified, the result compares the latest available timestamps before or at the specified timestamp to all the subsequent timestamps until the first match.	`if the car has entered the area of the shopping center since 14/04/2015 then...`
`<moving geometry> has exited <a polygon> [ since <date & time> ]`	Checks whether the moving geometry exited a polygon. If no `since` construct is specified, the result is based on the last 2 available timestamps. If the `since` construct is specified, the result compares the latest available timestamps before or at the specified timestamp to all the subsequent timestamps until the first match.	`if the car has exited the area of the shopping center then...`

Table 3. Line string constructs
Construct	Description	Example
`<a line string> intersects itself`	Checks whether the line string crosses itself. Returns a boolean.	`if 'the ship route' intersects itself then ...`
`the vertices of <a line string>`	Returns a collection of points.	`then add the position of 'the ship' to the vertices of 'the ship route'`
`the number of elements in the vertices of <a line string>`	Returns the number of vertices of a line string.	`if the number of elements in the vertices of the border of 'the town' is at least 1 then...`

Construct Description Example

Table 4. Point construct
Construct	Description	Example
`the coordinates of <a point>`	Returns an array of doubles.	`if the coordinates of 'the event location' contain the latitude of the position of 'the ship' then...`
`the point with <a number> as longitude and <a number> as latitude`	Returns a point.	`if the geometry of the track of the flight observed at now is the point with 7.215 as longitude and 43.665278 as latitude then emit a new flight arrival event where the airport is "NCE"`
`add <a point> to the vertices of <a line string>`	Adds a point to a line string.	`then add the current position of 'the person' to the vertices of the trajectory of 'the person'`

the coordinates of <a point>

Returns an array of doubles.

if
the coordinates of 'the event location' contain the latitude of the position of 'the ship'
then...

the point with <a number> as longitude and <a number> as latitude

Returns a point.

if
the geometry of the track of the flight observed at now is the point with 7.215 as longitude and 43.665278 as latitude
then
emit a new flight arrival event where the airport is "NCE"

add <a point> to the vertices of <a line string>

Adds a point to a line string.

then
add the current position of 'the person' to the vertices of the trajectory of 'the person'

Construct Description Example

Table 5. Polygon constructs
Construct	Description	Example
`the border of <a polygon>`	Returns a linear ring.	`if the border of 'the restricted area' intersects 'the ship route' then...`
`the holes of <a polygon>`	Returns a collection of linear rings.	`definitions set 'the visited places' to all the holes of the polygon where each linear ring intersects the route of 'the ship'; if...`

the border of <a polygon>

Returns a linear ring.

if
the border of 'the restricted area' intersects 'the ship route'
then...

the holes of <a polygon>

Returns a collection of linear rings.

definitions
 set 'the visited places' to all the holes of the polygon where each linear ring intersects the route of 'the ship';
if...