Skip to content

SQWRLQueryAPI

Jump to bottom
Martin O'Connor edited this page Apr 30, 2015 · 42 revisions

The SQWRL Query API is a subsystem of SWRLAPI that provides a JDBC-like Java interface to execute SQWRL queries and to process the results of SQWRL queries.

SQWRL queries effectively return a two dimensional table containing the results of the query.

For example, if we have an OWL ontology containing a class Person with data properties hasName and hasSalary we can write the following SQWRL query to query the names and salaries for all persons in an ontology: 

 Person(?p) ^ hasName(?p, ?name) ^ hasSalary(?p, ?salary) 
   -> sqwrl:select(?name, ?salary)

If this query generates a result it will return a table with two columns and a row for each name/salary pair matched by the query.

The active OWL ontology is not modified when queries are executed using this API.

Table of Contents

Creating a SQWRL Query Engine

We can run create a SQWRL query engine and run SQWRL queries on an ontology using the SQWRLQueryEngine interface, an implementation of which can be created using the SWRLAPIFactory class. We must first have an OWLAPI-based instance of that ontology, which is represented by the OWLOntology interface. (Instructions for creating an OWLOntology instance using the OWLAPI can be found here.) 

 OWLOntology ontology = ... // Create using OWLAPI
 
 SQWRLQueryEngine queryEngine = SWRLAPIFactory.createSQWRLQueryEngine(ontology);

Creating and Running SQWRL Queries

A named query can be generated using the query engine's createSQWRLQuery method. 

 queryEngine.createSQWRLQuery("Q1", "Person(?p) -> sqwrl:select(?p)");

Once created, the query can be referred to by name and executed using the runSQWRLQuery method: 

 SQWRLResult result = queryEngine.runSQWRLQuery("Q1");

If the named query does not return any results, this method will return null. If an errors occurs during execution of this method, a SQWRLException will be thrown.

A query can also be generated and executed in one step using the runSQWRLQuery method with a second parameter containing the query text: 

 SQWRLResult result = queryEngine.runSQWRLQuery("Q1", 
                                                "Person(?p) -> sqwrl:select(?p)");

Note that when a query is executed, the enabled SWRL rules in the ontology are also executed and any inferences made by those rules are available for querying. However, unlike the SWRLTab's rule engine, the SQWRL query engine does not modify the underlying OWL ontology.

Processing SQWRL Query Results

The interface SQWRLResult defines methods for processing query results. As mentioned, results for a particular query can be retrieved from the query engine by using the method getSQWRLResult on a query engine.

A SQWRLResult object contains one or more rows that in turn contain a list of objects defined by the interface SQWRLResultValue. There are two types of values that can be returned by a SQWRL query: (1) an g OWL literal value, represented a SQWRLLiteralValue, and (2) an OWL entity, which will represented by a SQWRLClassResultValue, a SQWRLIndividualResultValue, SQWRLObjectPropertyResultValue, a SQWRLDataPropertyResultValue, or a SQWRLAnnotationPropertyResultValue.

Rows in a SQWRLResult object can be iterated through using the next method. The contents of each column in a row can then be retrieved using appropriate accessor method for each result type. The methods are: getLiteral, getClassValue, getObjectPropertyValue, getDataPropertyValue, and getAnnotationPropertyValue. Either column names or indexes can be supplied to these methods. Associated methods that can be used to determine the types of elements are also provided by the SQWRLResult interface.

For example, to process the results of the previous query, we can write: 

 while (result.next()) {
  SQWRLLiteralResultValue nameValue = result.getLiteral("name");
  SQWRLLiteralResultValue salaryValue = result.getLiteral("salary");
  System.out.println("Name: " + nameValue.getString());
  System.out.println("Salary: " + salaryValue.getInt());
 }

If an error occurs during result processing, a SQWRLException will be thrown. Attempts to retrieve values of an incorrect type will generate a SQWRLLiteralException, which is a sub exception of SQWRLException. So, for example, the previous query processing code can safely be shortened to 

 while (result.next()) {
  System.out.println("Name: " + result.getLiteral("name").getString());
  System.out.println("Salary: " + result.getLiteral("salary").getInt()); 
 }

A SQWRLLiteralException will be thrown if an invalid conversion is attempted during result process.

Processing Result Columns

The SQWRL columnNames operator can also be used to assign user-defined names to columns in a query result. We can thus rewrite the previous query to supply these names: 

 Person(?p) ^ hasName(?p, ?name) ^ hasSalary(?p, ?salary) 
  -> sqwrl:select(?name, ?salary) ^ sqwrl:columnNames("Name", "Salary")

The code to access these columns can then be rewritten as: 

 System.out.println("Name: " + result.getLiteralValue("Name").getString());
 System.out.println("Salary: " + result.getLiteralValue("Salary").getInt());

Complete Example

So, a complete example to create a query and execute it using a SQWRL query engine can be written as follows: 

 OWLOntology ontology = ... // Create using OWLAPI 
 SQWRLQueryEngine queryEngine = SWRLAPIFactory.createSQWRLQueryEngine(ontology);
 SQWRLResult result = queryEngine.runSQWRLQuery("Q1", 
   "Person(?p) ^ hasName(?p, ?name) ^ hasSalary(?p, ?salary) -> sqwrl:select(?name, ?salary)");
 
 while (result.next()) {
  System.out.println("Name: " + result.getLiteral("name").getString());
  System.out.println("Salary: " + result.getLiteral("salary").getInt());
 }

A reset method is provided by the SQWRLResult class that can be called if the user wishes to process a result more than once.

Executing queries using this API does not modify the underlying OWL ontology: query results are maintained inside the query engine only. As mentioned in the SQWRL language FAQ, SQWRL queries can run in conjunction with SWRL rules. Any inferences made by those rules are also stored in the query engine and are not saved in the underlying ontology. SQWRL queries, however, can access this inferred knowledge.

Clone this wiki locally