SPARQLSyntax

SPARQL 1.1 Parser and Abstract Syntax

• Features
• Building
• Swift Package Manager
• Command Line Usage
• API
  • Term
  • Triple, Quad, TriplePattern and QuadPattern
  • Algebra
  • Expression
  • Query
  • SPARQLParser
  • SPARQLSerializer
• Extensions
  • Window Functions

Features

• SPARQL 1.1 Parser, Tokenizer, and Serializer available via both API and command line tool
• Abstract syntax representation of SPARQL queries, aligned with the SPARQL Algebra
• Supported extensions:
  • Window Functions

Building

% swift build -c release

Swift Package Manager

To use SPARQLSyntax with projects using the Swift Package Manager, add the following to your project's Package.swift file:

dependencies: [
  .package(url: "https://github.com/kasei/swift-sparql-syntax.git", .upToNextMinor(from: "0.0.91"))
]

Command Line Usage

A command line tool, sparql-parser, is provided to parse a SPARQL query and print its parsed query algebra, its tokenization, or a pretty-printed SPARQL string:

% ./.build/release/sparql-parser 
Usage: ./.build/release/sparql-parser [-v] COMMAND [ARGUMENTS]
       ./.build/release/sparql-parser parse query.rq
       ./.build/release/sparql-parser lint query.rq
       ./.build/release/sparql-parser tokens query.rq

To "lint", or "pretty print", a SPARQL query:

% cat examples/messy.rq
prefix geo: <http://www.w3.org/2003/01/geo/wgs84_pos#>
select    ?s
where{
?s geo:lat ?lat ;geo:long ?long   ;
	FILTER(?long < -117.0)
FILTER(?lat >= 31.0)
  FILTER(?lat <= 33.0)
} ORDER BY ?s

% ./.build/release/sparql-parser lint examples/messy.rq 
PREFIX geo: <http://www.w3.org/2003/01/geo/wgs84_pos#>
SELECT ?s WHERE {
    ?s geo:lat ?lat ;
        geo:long ?long ;
    FILTER (?long < - 117.0)
    FILTER (?lat >= 31.0)
    FILTER (?lat <= 33.0)
}
ORDER BY ?s

To parse the query and print the resulting query algebra:

% ./.build/release/sparql-parser parse examples/messy.rq
Query
  Select { ?s }
        Project { ?s }
          OrderBy { ?s }
            Filter (((?long < -117.0) && (?lat >= 31.0)) && (?lat <= 33.0))
              BGP
                ?s <http://www.w3.org/2003/01/geo/wgs84_pos#lat> ?lat .
                ?s <http://www.w3.org/2003/01/geo/wgs84_pos#long> ?long .

API

The SPARQLSyntax library provides an API for parsing SPARQL queries and accessing the resulting abstract data structures. The primary components of this API are:

• struct Term - A representation of an RDF Term (IRI, Literal, or Blank node)
• enum Algebra - A representation of the query pattern closely aligned with the formal SPARQL Algebra
• enum Expression - A representation of a logical expression
• struct Query - A representation of a SPARQL query including: a query form (SELECT, ASK, DESCRIBE, or CONSTRUCT), a query Algebra, and optional base URI and dataset specification
• struct SPARQLParser - Parses a SPARQL query String/Data and returns a Query
• struct SPARQLSerializer - Provides the ability to serialize a query, optionally applying "pretty printing" formatting

Term

struct Term represents an RDF Term (an IRI, a blank node, or an RDF Literal). Term also provides some support for XSD numeric types, bridging between Terms and enum NumericValue which provides numeric functions and type-promoting operators.

Triple, Quad, TriplePattern, and QuadPattern

struct Triple and struct Quad combine Terms into RDF triples and quads. struct TriplePattern and struct QuadPattern represent patterns which can be matched by concrete Triples and Quads. Instead of Terms, patterns are comprised of a enum Node which can be either a bound Term, or a named variable.

Algebra

enum Algebra is an representation of a query pattern aligned with the SPARQL Algebra. Cases include simple graph pattern matching such as triple, quad, and bgp, and more complex operators that can be used to join other Algebra values (e.g. innerJoin, union, project, distinct).

Algebra provides functions and properties to access features of graph patterns including: variables used; and in-scope, projectable, and "necessarily bound" variables. The structure of Algebra values can be modified using a rewriting API that can: bind values to specific variables; replace entire Algebra sub-trees; and rewrite Expressions used within the Algebra.

Expression

enum Expression represents a logical expression of variables, values, operators, and functions that can be evaluated within the context of a query result to produce a Term value. Expressions are used in the following Algebra operations: filter, left outer join ("OPTIONAL"), extend ("BIND"), and aggregate.

Expressions may be modified using a similar rewriting API to that provided by Algebra that can: bind values to specific variables; and replace entire Expression sub-trees.

Query

struct Query represents a SPARQL Query and includes:

• a query form (SELECT, ASK, DESCRIBE, or CONSTRUCT, and any associated data such as projected variables, or triple patterns used to CONSTRUCT a result graph)
• a graph pattern (Algebra)
• an optional base URI
• an optional dataset specification

SPARQLParser

struct SPARQLParser provides an API for parsing a SPARQL 1.1 query string and producing a Query.

SPARQLSerializer

struct SPARQLSerializer provides an API for serializing SPARQL 1.1 queries, optionally applying "pretty printing" rules to produce consistently formatted output. It can serialize both structured queries (Query and Algebra) and unstructured queries (a query String). In the latter case, serialization can be used even if the query contains syntax errors (with data after the error being serialized as-is).

Extensions

Window Functions

Parsing of window functions is supported as an extension to the SPARQL 1.1 syntax. A SQL-like syntax is supported for projecting window functions in a SELECT clause, as well as in a HAVING clause. In addition to the built-in aggregate functions, the following window functions are supported: RANK, ROW_NUMBER.

Shown below are some examples of the supported syntax.

# "Limit By Resource"
# This query limits results to two name/school pairs per person
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?name ?school WHERE {
	?s a foaf:Person ;
		foaf:name ?name ;
		foaf:schoolHomepage ?school
}
HAVING (RANK() OVER (PARTITION BY ?s) < 2)

# Use window framing to compute a moving average over the trailing four results
PREFIX : <http://example.org/>
SELECT (AVG(?value) OVER (ORDER BY ?date ROWS BETWEEN 3 PRECEDING AND CURRENT ROW) AS ?movingAverage) WHERE {
	VALUES (?date ?value) {
		(1 1.0)
		(2 2.0)
		(3 3.0)
		(4 2.0)
		(5 0.0)
		(6 0.0)
		(7 1.0)
	}
}