Introduction

See the Defining Magic Properties Tutorial for more information on how to define your own magic properites using Lisp.

A Magic Property (also called a Computed Property by W3C) is a predicate in a SPARQL query that produces bindings using something other than simple subgraph matching. These extensions provide a much richer query environment at the cost of non-portability. AllegroGraph has long supported a Magic Property to enable freetext queries and to interface to Solr and MongoDB. For example, when a query contains a pattern like 

?subject fti:match 'baseball' .

AllegroGraph does not look at the triples in the triple-store to find matching patterns; rather, it uses the freetext index to find the triples that have objects with baseball in their text.

AllegroGraph includes both enhanced Magic Properties for freetext queries and new properties to enable SPARQL queries to access Geospatial, Temporal and Social Network Analysis.

Note that Magic Properties can use patterns with multiple inputs and outputs. SPARQL's list notation provides a syntactic sugar to make this quite readable. Here is an example that looks for text matching willows in the freetext index named titles and then binds ?book to the matches it finds: 

select * {  
  ?book fti:match ('willows' 'titles' ) .  
}

This parenthetical notation uses SPARQL's (and Turtle's) syntactic sugar for the longer (and harder to read!) but equivalent query: 

SELECT * {  
  ?book fti:match _:b0 .  
  _:b0 rdf:first "willows" .  
  _:b0 rdf:rest _:b1 .  
  _:b1 rdf:first "titles" .  
  _:b1 rdf:rest rdf:nil  
}

Freetext

AllegroGraph supports freetext queries with enhancements that allow the selection of the index to use and the easy retrieval of the object of any matching triples. Both fti:match and fti:matchExpression provide the same four pattern forms:

  1. ?subject fti:match 'text to query' .
  2. (?subject ?object) fti:match 'text to query' .
  3. ?subject fti:match ('text to query' 'index name') .
  4. (?subject ?object) fti:match ('text to query' 'index name') .

The second and fourth forms bind the second variable on the subject side to the object of any matching triples.

Note that both the query text and the index name must be constants. You can, however, specify a particular subject or object to have the Magic Property act as a filter. For example, 

<ex:wind_in_the_williows> fti:match ('toad' 'characters') .

would succeed if and only if the freetext index named characters indexed a triple with subject <ex:wind_in_the_williows> whose object contained toad.

n-Dimensional (nD) Geospatial

The nD geospatial facility is described generally in nD Geospatial Overview. A tutorial is in the nD Geospatial Usage Guide. The magic properties for making nD geospatial queries are listed below in the Magic properties list.

The Lisp interface to nD geospatial is described here in the Lisp Reference.

The nD 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/>  
PREFIX nd:    <http://franz.com/ns/allegrograph/5.0/geo/nd#>   
PREFIX ndfn:  <http://franz.com/ns/allegrograph/5.0/geo/nd/fn#>   
PREFIX :      <http://franz.com/ns/keyword#>

The several SPARQL Magic Predicates in both systems (nD and 2D) find triples in the store based on their encoded data. To use a geospatial Magic Property in either system you must ensure that the query engine can determine the geospatial subtype based on the triple predicate. This can be done by creating a predicate type mapping between the predicate and the subtype. The mechanics of this vary with the client. For example, in the Python client we could create a predicate mapping between <http://example.com/pointLatLong> and the spherical geospatial subtype with a strip width of 1 kilometer 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")

These links document establishing a predicate mapping in HTTP, Lisp, Java, and Python.

2D Geospatial

2D SPARQL Magic Properties are no longer supported.

SNA

AllegroGraph now provides Magic Properties that work with its Social Networking Analysis (SNA) Library. They are described in the SNA Magic Properties document.

Temporal

There is a tutorial using an older interface here. The older interface is also described here.

AllegroGraph supports efficient storage and retrieval of temporal data including:

In the following, the namespace prefix t is short for http://franz.com/ns/allegrograph/3.0/temporal/. AllegroGraph also requires that time points are defined using the t:time predicate and that intervals are defined using either t:starttime and t:endtime or t:startpoint and t:endpoint. Starting in version 4.11 of AllegroGraph, the t:time, t:starttime, and t:endtime predicates are automatically mapped to xsd:dateTimes (see predicate type mapping for more details).

Once data has been encoded, you can query for:

The temporal reasoning tutorial describes all of these capabilities in detail and also functions as a general reference guide. Below, we will quickly outline the various SPARQL Magic Properties. To illustrate them, we'll use a triple-store with intervals defined for days and months of 2013 like: 

:day1Start t:time "2013-01-01T00:00:00"^^xsd:dateTime .  
:day1End t:time "2013-01-01T12:59:59"^^xsd:dateTime .  
:day1 t:startpoint :day1Start ;  
   t:endpoint :day1End ;  
   rdfs:label "January 1st" .  
:day2Start t:time "2013-01-02T00:00:00"^^xsd:dateTime .  
:day2End t:time "2013-01-02T12:59:59"^^xsd:dateTime .  
:day2 t:startpoint :day2Start ;  
   t:endpoint :day2End ;  
   rdfs:label "January 2nd" .  
...  
:month1 t:startpoint :day1Start ;  
  t:endpoint :day31End ;  
  rdfs:label "January" .  
...

We will also include an interesting date in the store: 

:earthDay t:startpoint :day110Start .

relations between points

We can ask for all the points before the month of January ends using 

select * {  
   ?month rdfs:label 'January' .  
   ?month t:endpoint ?monthEnds .  
   ?point t:pointBefore ?monthEnds .  
}

This will return the start and end of each day in January (though it will not return the end of January 31st because that point is simultaneous with the end of the month and not before it).

relation between intervals

For example, we can find the number of days 1 in January by querying: 

select (count(?day) as ?days) {  
   ?month rdfs:label 'January' .  
   ?day t:intervalDuring ?month .  
} group by ?month

relations between points and intervals

For example, we can ask for the month during which Earth Day falls using: 

select ?month ?label {  
  :earthday t:startpoint ?start .  
  ?start t:pointDuringInterval ?month .  
  ?month rdfs:label ?label .  
}

relations between points and datetimes

relations between intervals and datetimes

Large Language Models (LLMagic)

See Large Language Models (LLM) LLMagic and Vector Databases for information on Large Language Model support in AllegroGraph. LLM magic properties support support interfacing with GPT and creation and use of embedding vectors. There are examples in the LLM document and in the LLM embedding document. There are also some SPARQL magic functions, listed here.

Magic properties list

nD Geospatial

Attributes

GeoSPARQL

Large Language Model

Reification

Social Network Analysis

Temporal

Text Indexing

Validation

2D Geospatial

Footnotes

  1. Actually this will be two less than the number of days in January because January 1st starts the month and January 31st finishes it. I.e. they are not during the month. ↩