Swish.RDF.Query

This module defines functions for querying an RDF graph to obtain a set of variable substitutions, and to apply a set of variable substitutions to a query pattern to obtain a new graph.

It also defines a few primitive graph access functions.

A minimal example is shown below, where we query a very simple graph:

>>> :set -XOverloadedStrings
>>> import Swish.RDF
>>> import Swish.RDF.Parser.N3 (parseN3fromText)
>>> import Swish.RDF.Query
>>> import Swish.VarBinding (VarBinding(vbMap))
>>> import Network.URI (parseURI)
>>> import Data.Maybe (fromJust, mapMaybe)
>>> let qparse = either error id . parseN3fromText
>>> let igr = qparse "@prefix a: <http://example.com/>. a:a a a:A ; a:foo a:bar. a:b a a:B ; a:foo a:bar."
>>> let qgr = qparse "?node a ?type."
>>> let ans = rdfQueryFind qgr igr
>>> :t ans
ans :: [Swish.RDF.VarBinding.RDFVarBinding]
>>> ans
[[(?node,a:a),(?type,a:A)],[(?node,a:b),(?type,a:B)]]
>>> let bn = toRDFLabel . fromJust . parseURI $ "http://example.com/B"
>>> let arcs = rdfFindArcs (rdfObjEq bn) igr
>>> :t arcs
arcs :: [RDFTriple]
>>> arcs
[(a:b,rdf:type,a:B)]
>>> let lbls = mapMaybe (`vbMap` (Var "type")) ans
>>> :t lbls
lbls :: [RDFLabel]
>>> lbls
[a:A,a:B]

Documentation

rdfQueryFind

Arguments

:: RDFGraph

The query graph.

-> RDFGraph

The target graph.

-> [RDFVarBinding]

Each element represents a set of variable bindings that make the query graph a subgraph of the target graph. The list can be empty.

Basic graph-query function.

The triples of the query graph are matched sequentially against the target graph, each taking account of any variable bindings that have already been determined, and adding new variable bindings as triples containing query variables are matched against the graph.

rdfQueryFilter :: RDFVarBindingFilter -> [RDFVarBinding] -> [RDFVarBinding]

RDF query filter.

This function applies a supplied query binding filter to the result from a call of rdfQueryFind.

If none of the query bindings found satisfy the filter, a null list is returned (which is what rdfQueryFind returns if the query cannot be satisfied).

(Because of lazy evaluation, this should be as efficient as applying the filter as the search proceeds. I started to build the filter logic into the query function itself, with consequent increase in complexity, until I remembered lazy evaluation lets me keep things separate.)

rdfQueryBack

Arguments

:: RDFGraph

Query graph

-> RDFGraph

Target graph

-> [[RDFVarBinding]]

Reverse graph-query function.

Similar to rdfQueryFind, but with different success criteria. The query graph is matched against the supplied graph, but not every triple of the query is required to be matched. Rather, every triple of the target graph must be matched, and substitutions for just the variables thus bound are returned. In effect, these are subsitutions in the query that entail the target graph (where rdfQueryFind returns substitutions that are entailed by the target graph).

Multiple substitutions may be used together, so the result returned is a list of lists of query bindings. Each inner list contains several variable bindings that must all be applied separately to the closure antecendents to obtain a collection of expressions that together are antecedent to the supplied conclusion. A null list of bindings returned means the conclusion can be inferred without any antecedents.

Note: in back-chaining, the conditions required to prove each target triple are derived independently, using the inference rule for each such triple, so there are no requirements to check consistency with previously determined variable bindings, as there are when doing forward chaining. A result of this is that there may be redundant triples generated by the back-chaining process. Any process using back-chaining should deal with the results returned accordingly.

An empty outer list is returned if no combination of substitutions can infer the supplied target.

rdfQueryBackFilter :: RDFVarBindingFilter -> [[RDFVarBinding]] -> [[RDFVarBinding]]

RDF back-chaining query filter. This function applies a supplied query binding filter to the result from a call of rdfQueryBack.

Each inner list contains bindings that must all be used to satisfy the backchain query, so if any query binding does not satisfy the filter, the entire corresponding row is removed

rdfQueryBackModify :: VarBindingModify a b -> [[VarBinding a b]] -> [[VarBinding a b]]

RDF back-chaining query modifier. This function applies a supplied query binding modifier to the result from a call of rdfQueryBack.

Each inner list contains bindings that must all be used to satisfy a backchaining query, so if any query binding does not satisfy the filter, the entire corresponding row is removed

rdfQueryInstance :: RDFGraph -> RDFGraph -> [RDFVarBinding]

Simple entailment (instance) graph query.

This function queries a graph to find instances of the query graph in the target graph. It is very similar to the normal forward chaining query rdfQueryFind, except that blank nodes rather than query variable nodes in the query graph are matched against nodes in the target graph. Neither graph should contain query variables.

An instance is defined by the RDF semantics specification, per http://www.w3.org/TR/rdf-mt/, and is obtained by replacing blank nodes with URIs, literals or other blank nodes. RDF simple entailment can be determined in terms of instances. This function looks for a subgraph of the target graph that is an instance of the query graph, which is a necessary and sufficient condition for RDF entailment (see the Interpolation Lemma in RDF Semantics, section 1.2).

It is anticipated that this query function can be used in conjunction with backward chaining to determine when the search for sufficient antecendents to determine some goal has been concluded.

rdfQuerySubs :: [RDFVarBinding] -> RDFGraph -> [RDFGraph]

Graph substitution function.

Uses the supplied variable bindings to substitute variables in a supplied graph, returning a list of result graphs corresponding to each set of variable bindings applied to the input graph. This function is used for formward chaining substitutions, and returns only those result graphs for which all query variables are bound.

rdfQueryBackSubs :: [[RDFVarBinding]] -> RDFGraph -> [[(RDFGraph, [RDFLabel])]]

Graph back-substitution function.

Uses the supplied variable bindings from rdfQueryBack to perform a series of variable substitutions in a supplied graph, returning a list of lists of result graphs corresponding to each set of variable bindings applied to the input graphs.

The outer list of the result contains alternative antecedent lists that satisfy the query goal. Each inner list contains graphs that must all be inferred to satisfy the query goal.

rdfQuerySubsAll :: [RDFVarBinding] -> RDFGraph -> [(RDFGraph, [RDFLabel])]

Graph substitution function.

This function performs the substitutions and returns a list of result graphs each paired with a list unbound variables in each.

rdfQuerySubsBlank :: [RDFVarBinding] -> RDFGraph -> [RDFGraph]

Graph substitution function.

This function performs each of the substitutions in vars, and replaces any nodes corresponding to unbound query variables with new blank nodes.

rdfQueryBackSubsBlank :: [[RDFVarBinding]] -> RDFGraph -> [[RDFGraph]]

Graph back-substitution function, replacing variables with bnodes.

Uses the supplied variable bindings from rdfQueryBack to perform a series of variable substitutions in a supplied graph, returning a list of lists of result graphs corresponding to each set of variable bindings applied to the input graphs.

The outer list of the result contains alternative antecedent lists that satisfy the query goal. Each inner list contains graphs that must all be inferred to satisfy the query goal.

rdfFindArcs :: (RDFTriple -> Bool) -> RDFGraph -> [RDFTriple]

Take a predicate on an RDF statement and a graph, and returns all statements in the graph satisfying that predicate.

Use combinations of these as follows:

• find all statements with given subject: rdfFindArcs (rdfSubjEq s)
• find all statements with given property: rdfFindArcs (rdfPredEq p)
• find all statements with given object: rdfFindArcs (rdfObjEq o)
• find all statements matching conjunction of these conditions: rdfFindArcs (allp [...])
• find all statements matching disjunction of these conditions: rdfFindArcs (anyp [...])

Custom predicates can also be used.

rdfSubjEq :: RDFLabel -> RDFTriple -> Bool

Test if statement has given subject

rdfPredEq :: RDFLabel -> RDFTriple -> Bool

Test if statement has given predicate

rdfObjEq :: RDFLabel -> RDFTriple -> Bool

Test if statement has given object

rdfFindPredVal

Arguments

:: RDFLabel

subject

-> RDFLabel

predicate

-> RDFGraph

-> [RDFLabel]

Find values of given predicate for a given subject

rdfFindPredInt

Arguments

:: RDFLabel

subject

-> RDFLabel

predicate

-> RDFGraph

-> [Integer]

Find integer values of a given predicate for a given subject

rdfFindValSubj

Arguments

:: RDFLabel

predicate

-> RDFLabel

object

-> RDFGraph

-> [RDFLabel]

Find all subjects that match (subject, predicate, object) in the graph.

rdfFindList :: RDFGraph -> RDFLabel -> [RDFLabel]

Return a list of nodes that comprise an rdf:collection value, given the head element of the collection. If the list is ill-formed then an arbitrary value is returned.

Utility routines

allp :: [a -> Bool] -> a -> Bool

Test if a value satisfies all predicates in a list

anyp :: [a -> Bool] -> a -> Bool

Test if a value satisfies any predicate in a list

Exported for testing

rdfQuerySubs2 :: RDFVarBinding -> RDFGraph -> (RDFGraph, [RDFLabel])

This function applies a substitution for a single set of variable bindings, returning the result and a list of unbound variables. It uses a state transformer monad to collect the list of unbound variables.

Adding an empty graph forces elimination of duplicate arcs.