Introduction

A Magic Property is a predicate in a SPARQL query that produces bindings using something other than simple subgraph matching. See the SPARQL Magic Properties document.

In this document we describe the Magic Properties for the 2D geospatial facility. This facility has been replaced by the newer nD Geospatial facility. The 2D facility is maintained for backward compatibility only and will be removed in a future release.

The 2D geospatial facility itself has an original interface and a revised interface (with differences such as Magic Property names). The 2D Geospatial Tutorial has general geospatial examples which use the original 2D interface. There is no tutorial using the revised 2D interface.

2D Magic Properties

AllegroGraph's 2D geospatial extensions to SPARQL have a number of Magic Properties. These are listed in the Magic Properties list. Note that the nD geospatial Magic Properties do not work on 2D-encoded data, and vice versa. 2D geospatial Magic Properties are defined for determining points in a bounding box and points within a circle. Each comes in several variants to accommodate different usages.

The definitions that follow use these prefix definitions: 

PREFIX geofn: <http://franz.com/ns/allegrograph/3.0/geospatial/fn/>   
PREFIX geo:   <http://franz.com/ns/allegrograph/3.0/geospatial/>

To use a geospatial Magic Property, you must ensure that the query engine can determine the geospatial subtype based on the predicate. This can be done by creating a predicate type mapping between the predicate and the subtype. The mechanics of this varies with the client. For example, we could create a predicate mapping between and the spherical geospatial subtype with a strip width of 1 kilometer in the Python client using code like: 

geoSubtype = conn.createURI("http://franz.com/ns/allegrograph/3.0/geospatial/spherical/km/-180.0/180.0/-90.0/90.0/1")   
latlon = conn.createURI("http://example.com/pointLatLong")   
conn.registerDatatypeMapping(datatype=geoSubtype, predicate=latLon, nativeType="int")

In the following examples, we assume that the predicate ex:location is registered and mapped to a geospatial subtype. Given this, we can ask for subjects whose objects are in the bounding box defined by the two points ?lowerLeftPoint and ?upperRightPoint using: 

?subject geo:inBoundingBox (ex:location ?lowerLeftPoint ?upperRightPoint) .

The points are assumed to be AllegroGraph 2D geospatial UPIs (Unique Part Identifiers, see here in the AllegroGraph Introduction). They can come from other variables in the query or be constructed using BIND. For example: 

BIND( geofn:toPointXY( ex:location, 4.3, 12.6 ) AS ?lowerLeft )   
BIND( geofn:toPointXY( ex:location, 10, 20.1 ) AS ?upperRight )   
(?subject ?where) geo:inBoundingBox (ex:location ?lowerLeft ?upperRight)

This second example shows that you can bind the object of the triples found by using a list of variables on the left hand side of the geospatial Magic Property.

If you have X, Y coordinates rather than points, you can either use the BIND form shown above or use the X, Y version of the 2D Magic Property. For example, this query returns the same results as the one above: 

(?subject ?where) geo:inBoundingBoxXY (ex:location 4.3 12.6 10 20.1)

The other 2D Magic Properties are: 

# triples in a circle using cartesian coordinates   
?subject geo:inCircle (ex:location centerPoint radius)   
?subject geo:inCircleXY (ex:location x y radius)   
 
# triples in a circle using spherical coordinates (with different units)   
?subject geo:inCircleMiles (ex:location centerPoint radius)   
?subject geo:inCircleMilesXY (ex:location centerPoint radius)   
?subject geo:inCircleKilometers (ex:location centerPoint radius)   
?subject geo:inCircleKilometersXY (ex:location centerPoint radius)

As above, all of these assume that ex:location is mapped to a registered 2D geospatial subtype. For all of these properties, centerPoint must be bound to a geospatial point (either via other triple-patterns that produce bindings to geospatial data or via helper functions like geofn:toPointXY or geofn:toPointLonLat).

Note that all of the properties require that their arguments be bound before they can be evaluated. AllegroGraph will attempt to re-order patterns in BGPs such that this holds.

2D Helper Functions

The following functions are defined to help evaluate 2D geospatial queries:

The functions toPointXY and toPointLonLat require the predicate argument so that AllegroGraph can determine which geospatial subtype should be used to construct the point. 1

See the Magic Properties list for a list of all SPARQL Magic Properties including those for 2D geospatial, along with associated SPARQL functions.

Footnotes

  1. Note that many of the functions were defined previously with slightly different names. For example, cartesian-distance-squared instead of cartesianDistanceSquared. The new names are added for consistency; the old names will eventually be deprecated and removed. ↩