RDF API for PHP

Using the SPARQL Client

This tutorial is part of the RAP - Rdf API for PHP documentation.

Tobias Gauss <tobias.gauss@web.de>, Chris Bizer <chris@bizer.de>
June 2006


RAP's SPARQL client allows you to execute SPARQL queries against remote SPARQL endpoints using the SPARQL protocol. Query results are returned as array of variable bindings, RAP MemModel or boolean, depending on the type of SPARQL query.

Using the SPARQL Client

The SPARQL client package consists of two classes: SparqlClient which represents a connection to a SPARQL endpoint, and ClientQuery which represents a SPARQL query.

A SparqlClient is created using RAP's ModelFactory:

$client = ModelFactory::getSparqlClient("http://www.exampleSparqlService.net:2020/example");

This line creates a new SparqlClient object $client for executing queries against the SPARQL endpoint http://www.exampleSparqlService.net:2020/example.

Then we create a ClientQuery object:

$query = new ClientQuery();

The ClientQuery object has three methods:

$query->query($queryString);

sets the query string of the ClientQuery object.

If the query string doesn't specify the data set to be queried and if the endpoint supports querying custom data sets, you can use following two methods to define the data set to be queried:

$query->addDefaultGraph($default);

sets the default graph of the data set to be queried.

$query->addNamedGraph($named);

adds a named graph the data set to be queried.

A query is executed by calling the query() method of the client object:

$result = $client->query($query);

The type of the variable $result depends on the SPARQL query. For SELECT queries, the result is an two dimension array of variable bindings ($result[]['?varname'] ). The values of these variables are RAP objects (Resource, Literal or BlankNode) or an empty string if the variable is unbound. The result of a CONSTRUCT query is a RAP MemModel. The result of a ASK query a variable of the type boolean.

You can also retrieve the query result in the SPARQL Query Results XML Format by calling the method setOutputFormat() before executing a query.

$client->setOutputFormat("xml");


Usage Example

We start with including the RAP toolkit and creating a SPARQL client linked to a SPARQL endpoint:

// Include all RAP classes
define("RDFAPI_INCLUDE_DIR", "C:/Apache/htdocs/rdfapi-php/api/");
include(RDFAPI_INCLUDE_DIR . "RdfAPI.php");

// Create a SPARQL client
$client = ModelFactory::getSparqlClient("http://www.exampleSparqlService.net:2020/example");

Once the client has been created, we can perform our first query which will be: "Find the full name of all employees". We create a $querystring containing the corresponding SPARQL query:

$querystring = '
PREFIX vcard: <http://www.w3.org/2001/vcard-rdf/3.0#>
SELECT ?fullName
WHERE { ?x vcard:FN ?fullName }';

To execute the query, we create a new ClientQuery object and pass it to the SPARQL client:

$query = new ClientQuery();
$query->query($querystring);
$result = $client->query($query);

The following code loops over the result set and prints out all bindings of the variable ?fullName.

foreach($result as $line){
  $value = $line['?fullName'];
    if($value != "")
      echo $value->toString()."<br>";
    else
      echo "undbound<br>";
}

Another, even more convenient way to display the results of a query is to use the writeQueryResultAsHtmlTable() method of the SPARQL engine. All we have to do is to pass the query result to this method:

SPARQLEngine::writeQueryResultAsHtmlTable($result);

Which will result in the following output in the browser window:

No. ?fullName
1.

Literal: Bill Parker
2.

Literal: George Simpson
3.

Literal: Monica Murphy

For more SPARQL query examples please refer to the W3C SPARQL specification.