Introduction

The SPARQL Tree tools digest SPARQL results for your convenience.

A "SPARQL tree" is a processed SPARQL query result which combines bound variables into trees of data. It processes regular results from queries using variables named according to a specific convention (designating "tree structure").

Example:

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX dct: <http://purl.org/dc/terms/>
PREFIX : <http://xmlns.com/foaf/0.1/>

SELECT * WHERE {
    ?person a :Person;
        :name ?person__1_name .
    OPTIONAL {
        ?person :givenName ?person__1_givenName;
            :surname ?person__1_surname .
    }
    OPTIONAL { ?person rdfs:comment ?person__1_comment }
    OPTIONAL {
        ?person :interest ?person__interest .
        ?person__interest dct:title ?person__interest__1_title .
    }
}

Results for the above are automatically turned into something like the following JSON:

{
  "person": [
    {
      "$uri": "http://purl.org/NET/dust/foaf#self",
      "name": "Niklas Lindstr\u00f6m",
      "givenName": null, "surname": null,
      "comment": {"@en": "Does stuff with RDF."},
      "interest": [
        {
          "$uri": "http://en.wikipedia.org/wiki/Resource_Description_Framework",
          "title": {"@en": "Resource Description Framework"}
        },
        {
          "$uri": "http://python.org/",
          "title": {"@en": "Python Programming Language"}
        }
      ]
    }
  ]
}

Details

The naming convention inspects the query variable names (in the result head). Variables containing '__' as "key separators" are interpreted as "tree" variables. This tells SparqlTree to combine the results for these as parent-child keys (splitting on '__').

The values for these keys become lists of all bound combinations (at the given "tree level"), including:

• plain strings
• other "native json types" (boolean, int and float)
• non-coerced "typed literals" as dictionaries with the special keys "$datatype" and "$value"
• "language literals" as dictionaries with language tag keys (using the locale, prefixed by ''@')
• dictionaries of "nested objects" (who, along with "regular node keys" may contain the special "$uri" or "$id" keys if the SPARQL result binding is of type URI or BNode).

Furthermore, if a "child" key starts with '1_', SparqlTree instead expects the result to hold either one value, or that any bound values are language literals. The effect of this is to produce single values (that is, instead of lists of values). It also merges lists of language literals into a single dictionary with language tag keys.

Note: these conventions are currently idiomatic for "SparqlTree-JSON", but there is great opportunity in standardizing this (or something like it).. Along the lines of what has been done for "JSON with references", and what Google has done with the JSON format for GData-Atom.. Please get in touch if you want to be involved in such a venture!

Installation

The repository holds an initial inplementation in Python, along with some examples.

If you have setuptools (includes the easy_install cmdline tool) installed (fairly common), you can install from the latest trunk by invoking:

$ sudo easy_install http://oort.googlecode.com/svn/SparqlTree/trunk/python#egg=OortSparqlTree-dev

(Note: If this fails you may have an old version of setuptools. To do a (self-)update of it, try:

$ sudo easy_install -U setuptools

)

Or manually by checking out the source code (you only need SparqlTree/trunk/python) and do either:

$ python setup.py install

or (to be able to do svn update and automatically having the latest code importable):

$ sudo python setup.py develop

Usage

The python implementation can be used both programmatically and from the cmdline. Use it to run sparqltrees against any sparql endpoints (currently any that support the (optional) SPARQL result JSON serialization format).

Auto-trees

The oort.sparqltree.autotree module uses regular SPARQL queries as detailed above.

POSIX-compliant command-line example

Example of using a regular query, as per the example above. To do this, you need to:

• install oort.sparqltree (see above)
• have a copy of the examples/ directory from the repository locally (e.g. by checking it out)
• set up a SPARQL endpoint and load it with the example data.

One way to set up a SPARQL endpoint is to use Joseki. The examples include a configuration for loading a simple example. To get this going:

1. Download Joseki from <http://www.joseki.org/>.
2. Unpack the distribution and define a JOSEKIROOT environment variable pointing to it.
3. Go to the unpacked directory and run:

   $ chmod u+x:a bin/*
   $ bin/rdfserver <path-to-SparqlTree-examples>/data/joseki-config.ttl

Go to the examples directory and run:

    $ python -m oort.sparqltree.run http://localhost:2020/sparql person.rq

Tree-lenses

The oort.sparqltree.treelens module contains a TreeLens. It is a wrapper for turning the resulting object tree into an even more usable object (for further code or template processing). It takes a result tree and a locale value, which it "massages" to:

1. localization of language literals.
2. turn the tree into a graph (with cyclic references) by merging any properties of an object with the same URI and making each reference point to the same object.

Note that any kind of object tree following the "json-isomorphic" form examplified above will do (making it useful for e.g. having localized labels as language literals in auxiliary JSON data).