NAME¶
RDF::Query - A SPARQL 1.1 Query implementation for use with RDF::Trine.
VERSION¶
This document describes RDF::Query version 2.908.
SYNOPSIS¶
# SPARQL SELECT Query
my $query = RDF::Query->new( 'SELECT * WHERE ...' );
my $iterator = $query->execute( $model );
while (my $row = $iterator->next) {
# $row is a HASHref containing variable name -> RDF Term bindings
print $row->{ 'var' }->as_string;
}
# SPARQL CONSTRUCT/DESCRIBE Query
my $query = RDF::Query->new( 'CONSTRUCT { ... } WHERE ...' );
my $iterator = $query->execute( $model );
while (my $st = $iterator->next) {
# $st is a RDF::Trine::Statement object representing an RDF triple
print $st->as_string;
}
# SPARQL ASK Query
my $query = RDF::Query->new( 'ASK WHERE ...' );
my $iterator = $query->execute( $model );
my $bool = $iterator->get_boolean;
if ($bool) {
print "Yes!\n";
}
# RDQL Query
my $query = new RDF::Query ( $rdql, { lang => 'rdql' } );
my @rows = $query->execute( $model ); # in list context, returns all results
DESCRIPTION¶
RDF::Query allows SPARQL and RDQL queries to be run against an RDF model,
returning rows of matching results.
See
http://www.w3.org/TR/rdf-sparql-query/
<
http://www.w3.org/TR/rdf-sparql-query/> for more information on SPARQL.
See
http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/
<
http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/> for more
information on RDQL.
CHANGES IN VERSION 2.900¶
The 2.9xx versions of RDF::Query introduce some significant changes that will
lead to a stable 3.000 release supporting SPARQL 1.1. Version 2.902 introduces
the SPARQL 1.1 features up to date with the SPARQL 1.1 working drafts as of
its release date. Version 2.902 also is the first version to require use of
RDF::Trine for the underlying RDF store. This change means that RDF::Core is
no longer supported, and while Redland is still supported, its handling of
"contexts" (named graphs) means that existing RDF triples stored in
Redland without associated contexts will not be accessible from RDF::Query.
See RDF::Trine::Store for more information on supported backend stores.
CHANGES IN VERSION 2.000¶
There are many changes in the code between the 1.x and 2.x releases. Most of
these changes will only affect queries that should have raised errors in the
first place (SPARQL parsing, queries that use undefined namespaces, etc.).
Beyond these changes, however, there are some significant API changes that
will affect all users:
- Use of RDF::Trine objects
- All nodes and statements returned by RDF::Query are now
RDF::Trine objects (more specifically, RDF::Trine::Node and
RDF::Trine::Statement objects). This differes from RDF::Query 1.x where
nodes and statements were of the same type as the underlying model
(Redland nodes from a Redland model and RDF::Core nodes from an RDF::Core
model).
In the past, it was possible to execute a query and not know what type of
nodes were going to be returned, leading to overly verbose code that
required examining all nodes and statements with the bridge object. This
new API brings consistency to both the execution model and client code,
greatly simplifying interaction with query results.
- Binding Result Values
- Binding result values returned by calling
"$iterator->next" are now HASH references (instead of ARRAY
references), keyed by variable name. Where prior code might use this code
(modulo model definition and namespace declarations):
my $sparql = 'SELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }';
my $query = RDF::Query->new( $sparql );
my $iterator = $query->execute( $model );
while (my $row = $iterator->()) {
my ($name, $homepage) = @$row;
# ...
}
New code using RDF::Query 2.000 and later should instead use:
my $sparql = 'SELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }';
my $query = RDF::Query->new( $sparql );
my $iterator = $query->execute( $model );
while (my $row = $iterator->next) {
my $name = $row->{ name };
my $homepage = $row->{ homepage };
# ...
}
(Also notice the new method calling syntax for retrieving rows.)
METHODS¶
- "new ( $query, \%options )"
- Returns a new RDF::Query object for the specified $query.
The query language defaults to SPARQL 1.1, but may be set specifically
with the appropriate %options value. Valid %options are:
* lang
Specifies the query language. Acceptable values are 'sparql11', 'sparql', or
'rdql'.
* base_uri
Specifies the base URI used in parsing the query.
* update
A boolean value indicating whether update operations are allowed during
query execution.
* load_data
A boolean value indicating whether URIs used in SPARQL FROM and FROM NAMED
clauses should be dereferenced and the resulting RDF content used to
construct the dataset against which the query is run.
- "get ( $model )"
- Executes the query using the specified model, and returns
the first matching row as a LIST of values.
- "prepare ( $model )"
- Prepares the query, constructing a query execution plan,
and returns a list containing ($plan, $context). To execute the plan, call
"execute_plan( $plan, $context )".
- "execute ( $model, %args )"
- Executes the query using the specified RDF $model. If
called in a list context, returns an array of rows, otherwise returns an
RDF::Trine::Iterator object. The iterator returned may be an instance of
several subclasses of RDF::Trine::Iterator:
* A RDF::Trine::Iterator::Bindings object is returned for query forms
producing variable binding results (SELECT queries).
* A RDF::Trine::Iterator::Graph object is returned for query forms producing
in an RDF graph result (DESCRIBE and CONSTRUCT queries).
* A RDF::Trine::Iterator::Boolean object is returned for query forms
producing a true/false result (ASK queries).
- "execute_plan ( $plan, $context )"
- Executes the query plan generated by the
"<prepare"> method using the supplied
RDF::Query::ExecutionContext> object. Return value(s) are the same as
for the "<execute"> method.
- "prepare_with_named_graphs ( $model, @uris
)"
- "execute_with_named_graphs ( $model, @uris
)"
- Executes the query using the specified RDF $model, loading
the contents of the specified @uris into named graphs immediately prior to
matching the query. Otherwise, acts just like "execute".
- "pattern"
- Returns the RDF::Query::Algebra::GroupGraphPattern algebra
pattern for this query.
- "as_sparql"
- Returns the query as a string in the SPARQL syntax.
- "as_hash"
- Returns the query as a nested set of plain data structures
(no objects).
- "sse"
- Returns the query as a string in the SSE syntax.
- "dateparser"
- Returns the DateTime::Format::W3CDTF object associated with
this query object.
- "add_function ( $uri, $function )"
- Associates the custom function $function (a CODE reference)
with the specified URI, allowing the function to be called by query
FILTERs.
- "supported_extensions"
- Returns a list of URLs representing extensions to SPARQL
that are supported by the query engine.
- "supported_functions"
- Returns a list URLs that may be used as functions in FILTER
clauses (and the SELECT clause if the SPARQL 1.1 parser is used).
- "add_computed_statement_generator ( $predicate =>
\&generator )"
- Adds a statement generator for the given $predicate to the
query object. This statement generator will be called as
"$generator->( $query, $model, \%bound, $s, $p, $o, $c )" and
is expected to return an RDF::Trine::Iterator::Graph object containing
statements with $predicate.
- "get_computed_statement_generators ( [ $predicate ]
)"
- Returns an ARRAY reference of computed statement generator
closures.
- "add_hook_once ( $hook_uri, $function, $token
)"
- Calls "add_hook" adding the supplied $function
only once based on the $token identifier. This may be useful if the only
code that is able to add a hook is called many times (in an extension
function, for example).
- "add_hook ( $hook_uri, $function )"
- Associates the custom function $function (a CODE reference)
with the RDF::Query code hook specified by $uri. Each function that has
been associated with a particular hook will be called (in the order they
were registered as hooks) when the hook event occurs. See "Defined
Hooks" for more information.
- "parsed ()"
- Returns the parse tree.
- "model"
- Returns the RDF::Trine::Model object for this query.
- "useragent"
- Returns the LWP::UserAgent object used for retrieving web
content.
- "log ( $key [, $value ] )"
- If no logger object is associated with this query object,
does nothing. Otherwise, return or set the corresponding value depending
on whether a $value is specified.
- "logger"
- Returns the logger object associated with this query object
(if present).
- "error ()"
- Returns the last error the parser experienced.
DEFINED HOOKS¶
The following hook URIs are defined and may be used to extend the query engine
functionality using the "add_hook" method:
- http://kasei.us/code/rdf-query/hooks/post-create-model
- Called after loading all external files to a temporary
model in queries that use FROM and FROM NAMED.
Args: ( $query, $model )
$query is the RDF::Query object. $model is the RDF::Trine::Model
object.
- http://kasei.us/code/rdf-query/hooks/post-execute
- Called immediately before returning a result iterator from
the execute method.
Args: ( $query, $model, $iterator )
$query is the RDF::Query object. $model is the RDF::Trine::Model object.
$iterator is a RDF::Trine::Iterator object.
SEE ALSO¶
<
http://www.perlrdf.org/>
AUTHOR¶
Gregory Todd Williams <gwilliams@cpan.org>
LICENSE¶
Copyright (c) 2005-2010 Gregory Todd Williams. This program is free software;
you can redistribute it and/or modify it under the same terms as Perl
itself.