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