Awesome
sparqlClient
A SPARQL client library for the rdfInterface ecosystem with the API inspired by the PDO.
- It can work with any PSR-17 / PSR-18 compliant HTTP libraries.
- It can work with huge query results.
The response is parsed in a lazy way as a stream (the next row is parsed only when you try to read it). This assures iterating through results without acumulating them in an array, which has neglectable memory footprint.
Installation
- Obtain the Composer
- Run
composer require sweetrdf/sparql-client
- Run
composer require guzzlehttp/guzzle
to install an HTTP client (but you can use any client supporting PSR-18). - Run
composer require http-interop/http-factory-guzzle
to install PSR-17 bindinds for Guzzle (but you can use any PSR-17 implementation) - Run
composer require sweetrdf/quick-rdf
to install RDF terms factory (you can use any terms factory compatible with the rdfInterface).
Automatically generated documentation
https://sweetrdf.github.io/sparqlClient/namespaces/sparqlclient.html
It's very incomplete but better than nothing.
RdfInterface documentation is included which provides documentation for terms (objects representing RDF named nodes, literals, etc.).
Usage
include 'vendor/autoload.php';
$connection = new \sparqlClient\StandardConnection('https://query.wikidata.org/sparql', new \quickRdf\DataFactory());
$results = $connection->query('select * where {?a ?b ?c} limit 10');
foreach ($results as $i) {
print_r($i);
}
Parameterized queries
The StandardConnection
class provides a PDO-like API for parameterized queries (aka prepared statements).
Parameterized queries:
- Are the right way to assure all named nodes/blank nodes/literals/quads/etc. in the SPARQL query are properly escaped.
- Protect against SPARQL injections.
- Don't provide any speedup (in contrary to SQL parameterized queries).
include 'vendor/autoload.php';
$factory = new \quickRdf\DataFactory();
$connection = new \sparqlClient\StandardConnection('https://query.wikidata.org/sparql', $factory);
// pass parameters using execute()
// the single `?` is a positional parameter while the `:sf` is a named parameter
$query = $connection->prepare('SELECT * WHERE {?a ? ?c . ?a :sf ?d .} LIMIT 10');
$query->execute([
$factory::namedNode('http://creativecommons.org/ns#license'),
'sf' => $factory::namedNode('http://schema.org/softwareVersion'),
]);
foreach ($query as $i) {
print_r($i);
}
// bind a (positional) parameter to a variable
$query = $connection->prepare('SELECT * WHERE {?a ? ?c .} LIMIT 2');
$value = $factory::namedNode('http://creativecommons.org/ns#license');
$query->bindParam(0, $value);
$query->execute();
foreach ($query as $i) {
print_r($i);
}
$value = $factory::namedNode('http://schema.org/softwareVersion');
$query->execute();
foreach ($query as $i) {
print_r($i);
}
There are some differences comparing to the PDO API:
- Mixing positional and named parameters in one query is allowed (see the example above).
- Mixing
bindParam()
/bindValue()
and passing (some or all) parameters troughexecute()
is allowed.- The only constraint is that all parameters have to be set.
- Parameters passed to
execute()
overwrite ones set withbindParam()
/bindValue()
.
- As strong typing is used parameter values have to be of type
rdfInterface\Term
.- It makes unnecessary specifying the type in
bindParam()
/bindvalue()
.
- It makes unnecessary specifying the type in
Advanced usage
- You may also provide any PSR-18 HTTP client and/or PSR-17 HTTP request factory to the
\sparqlClient\StandardConnection
constructor. E.g. let's assume your SPARQL endpoint requires authorization and you want to benefit from Guzzle connection allowing to set global request options:$connection = new \sparqlClient\StandardConnection( 'https://query.wikidata.org/sparql', new \quickRdf\DataFactory(), new \GuzzleHttp\Client(['auth' => ['login', 'pswd']]) );
- If your SPARQL endpoint doesn't follow the de facto standard of accepting the SPARQL query as the
query
request parameter, you may use the\sparqlClient\Connection
class which takes PSR-7 requests instead of a query string and allows you to use any specific HTTP request you need.
FAQ
- What about integration of INSERT/UPDATE/DELETE queries with the \rdfInterface\Dataset or \rdfInterface\QuadIterator?
Will be added in the future.