.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RDF::Query 3pm"
.TH RDF::Query 3pm "2014-10-24" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RDF::Query \- A complete SPARQL 1.1 Query and Update implementation for use with RDF::Trine.
.SH "VERSION"
.IX Header "VERSION"
This document describes RDF::Query version 2.912.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& # SPARQL SELECT Query
\& my $query = RDF::Query\->new( \*(AqSELECT * WHERE ...\*(Aq );
\& my $iterator = $query\->execute( $model );
\& while (my $row = $iterator\->next) {
\&   # $row is a HASHref containing variable name \-> RDF Term bindings
\&   print $row\->{ \*(Aqvar\*(Aq }\->as_string;
\& }
\& 
\& # SPARQL CONSTRUCT/DESCRIBE Query
\& my $query = RDF::Query\->new( \*(AqCONSTRUCT { ... } WHERE ...\*(Aq );
\& 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( \*(AqASK WHERE ...\*(Aq );
\& my $iterator = $query\->execute( $model );
\& my $bool = $iterator\->get_boolean;
\& if ($bool) {
\&   print "Yes!\en";
\& }
\& 
\& # RDQL Query
\& my $query = new RDF::Query ( $rdql, { lang => \*(Aqrdql\*(Aq } );
\& my @rows = $query\->execute( $model ); # in list context, returns all results
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
RDF::Query allows \s-1SPARQL\s0 and \s-1RDQL\s0 queries to be run against an \s-1RDF\s0 model,
returning rows of matching results.
.PP
See <http://www.w3.org/TR/rdf\-sparql\-query/> for more information on \s-1SPARQL.\s0
.PP
See <http://www.w3.org/Submission/2004/SUBM\-RDQL\-20040109/> for more
information on \s-1RDQL.\s0
.SH "CHANGES IN VERSION 2.900"
.IX Header "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 \s-1SPARQL 1.1.\s0 Version 2.902 introduces
the \s-1SPARQL 1.1\s0 features up to date with the \s-1SPARQL 1.1\s0 working drafts as of its
release date. Version 2.902 also is the first version to require use of
RDF::Trine for the underlying \s-1RDF\s0 store. This change means that RDF::Core is
no longer supported, and while Redland is still supported, its handling of
\&\*(L"contexts\*(R" (named graphs) means that existing \s-1RDF\s0 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.
.SH "CHANGES IN VERSION 2.000"
.IX Header "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 (\s-1SPARQL\s0 parsing, queries that use undefined namespaces, etc.).
Beyond these changes, however, there are some significant \s-1API\s0 changes that will
affect all users:
.IP "Use of RDF::Trine objects" 4
.IX Item "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).
.Sp
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 \s-1API\s0 brings
consistency to both the execution model and client code, greatly simplifying
interaction with query results.
.IP "Binding Result Values" 4
.IX Item "Binding Result Values"
Binding result values returned by calling \f(CW\*(C`$iterator\->next\*(C'\fR are now \s-1HASH\s0
references (instead of \s-1ARRAY\s0 references), keyed by variable name. Where prior
code might use this code (modulo model definition and namespace declarations):
.Sp
.Vb 7
\&  my $sparql = \*(AqSELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }\*(Aq;
\&  my $query = RDF::Query\->new( $sparql );
\&  my $iterator = $query\->execute( $model );
\&  while (my $row = $iterator\->()) {
\&    my ($name, $homepage) = @$row;
\&    # ...
\&  }
.Ve
.Sp
New code using RDF::Query 2.000 and later should instead use:
.Sp
.Vb 8
\&  my $sparql = \*(AqSELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }\*(Aq;
\&  my $query = RDF::Query\->new( $sparql );
\&  my $iterator = $query\->execute( $model );
\&  while (my $row = $iterator\->next) {
\&    my $name = $row\->{ name };
\&    my $homepage = $row\->{ homepage };
\&    # ...
\&  }
.Ve
.Sp
(Also notice the new method calling syntax for retrieving rows.)
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """new ( $query, \e%options )""" 4
.el .IP "\f(CWnew ( $query, \e%options )\fR" 4
.IX Item "new ( $query, %options )"
Returns a new RDF::Query object for the specified \f(CW$query\fR.
The query language defaults to \s-1SPARQL 1.1,\s0 but may be set specifically
with the appropriate \f(CW%options\fR value. Valid \f(CW%options\fR are:
.Sp
* lang
.Sp
Specifies the query language. Acceptable values are 'sparql11', 'sparql', or 'rdql'.
.Sp
* base_uri
.Sp
Specifies the base \s-1URI\s0 used in parsing the query.
.Sp
* update
.Sp
A boolean value indicating whether update operations are allowed during query execution.
.Sp
* load_data
.Sp
A boolean value indicating whether URIs used in \s-1SPARQL FROM\s0 and \s-1FROM NAMED\s0 clauses
should be dereferenced and the resulting \s-1RDF\s0 content used to construct the dataset
against which the query is run.
.ie n .IP """get ( $model )""" 4
.el .IP "\f(CWget ( $model )\fR" 4
.IX Item "get ( $model )"
Executes the query using the specified model, and returns the first matching row as a \s-1LIST\s0 of values.
.ie n .IP """prepare ( $model )""" 4
.el .IP "\f(CWprepare ( $model )\fR" 4
.IX Item "prepare ( $model )"
Prepares the query, constructing a query execution plan, and returns a list
containing ($plan, \f(CW$context\fR). To execute the plan, call
\&\f(CW\*(C`execute_plan( $plan, $context )\*(C'\fR.
.ie n .IP """execute ( $model, %args )""" 4
.el .IP "\f(CWexecute ( $model, %args )\fR" 4
.IX Item "execute ( $model, %args )"
Executes the query using the specified \s-1RDF \s0\f(CW$model\fR. 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:
.Sp
* A RDF::Trine::Iterator::Bindings object is returned for query forms producing variable binding results (\s-1SELECT\s0 queries).
.Sp
* A RDF::Trine::Iterator::Graph object is returned for query forms producing in an \s-1RDF\s0 graph result (\s-1DESCRIBE\s0 and \s-1CONSTRUCT\s0 queries).
.Sp
* A RDF::Trine::Iterator::Boolean object is returned for query forms producing a true/false result (\s-1ASK\s0 queries).
.ie n .IP """execute_plan ( $plan, $context )""" 4
.el .IP "\f(CWexecute_plan ( $plan, $context )\fR" 4
.IX Item "execute_plan ( $plan, $context )"
Executes the query plan generated by the \f(CW\*(C`<prepare\*(C'\fR> method using the supplied
RDF::Query::ExecutionContext> object. Return value(s) are the same as for the
\&\f(CW\*(C`<execute\*(C'\fR> method.
.ie n .IP """prepare_with_named_graphs ( $model, @uris )""" 4
.el .IP "\f(CWprepare_with_named_graphs ( $model, @uris )\fR" 4
.IX Item "prepare_with_named_graphs ( $model, @uris )"
.PD 0
.ie n .IP """execute_with_named_graphs ( $model, @uris )""" 4
.el .IP "\f(CWexecute_with_named_graphs ( $model, @uris )\fR" 4
.IX Item "execute_with_named_graphs ( $model, @uris )"
.PD
Executes the query using the specified \s-1RDF \s0\f(CW$model\fR, loading the contents
of the specified \f(CW@uris\fR into named graphs immediately prior to matching the
query. Otherwise, acts just like \f(CW\*(C`execute\*(C'\fR.
.ie n .IP """pattern""" 4
.el .IP "\f(CWpattern\fR" 4
.IX Item "pattern"
Returns the RDF::Query::Algebra::GroupGraphPattern algebra pattern for this query.
.ie n .IP """is_update""" 4
.el .IP "\f(CWis_update\fR" 4
.IX Item "is_update"
.PD 0
.ie n .IP """as_sparql""" 4
.el .IP "\f(CWas_sparql\fR" 4
.IX Item "as_sparql"
.PD
Returns the query as a string in the \s-1SPARQL\s0 syntax.
.ie n .IP """as_hash""" 4
.el .IP "\f(CWas_hash\fR" 4
.IX Item "as_hash"
Returns the query as a nested set of plain data structures (no objects).
.ie n .IP """sse""" 4
.el .IP "\f(CWsse\fR" 4
.IX Item "sse"
Returns the query as a string in the \s-1SSE\s0 syntax.
.ie n .IP """dateparser""" 4
.el .IP "\f(CWdateparser\fR" 4
.IX Item "dateparser"
Returns the DateTime::Format::W3CDTF object associated with this query object.
.ie n .IP """specifies_update_dataset""" 4
.el .IP "\f(CWspecifies_update_dataset\fR" 4
.IX Item "specifies_update_dataset"
Returns true if the query specifies a custom update dataset via the \s-1WITH\s0 or
\&\s-1USING\s0 keywords, false otherwise.
.ie n .IP """add_function ( $uri, $function )""" 4
.el .IP "\f(CWadd_function ( $uri, $function )\fR" 4
.IX Item "add_function ( $uri, $function )"
Associates the custom function \f(CW$function\fR (a \s-1CODE\s0 reference) with the
specified \s-1URI,\s0 allowing the function to be called by query FILTERs.
.ie n .IP """supported_extensions""" 4
.el .IP "\f(CWsupported_extensions\fR" 4
.IX Item "supported_extensions"
Returns a list of URLs representing extensions to \s-1SPARQL\s0 that are supported
by the query engine.
.ie n .IP """supported_functions""" 4
.el .IP "\f(CWsupported_functions\fR" 4
.IX Item "supported_functions"
Returns a list URLs that may be used as functions in \s-1FILTER\s0 clauses
(and the \s-1SELECT\s0 clause if the \s-1SPARQL 1.1\s0 parser is used).
.ie n .IP """add_computed_statement_generator ( $predicate => \e&generator )""" 4
.el .IP "\f(CWadd_computed_statement_generator ( $predicate => \e&generator )\fR" 4
.IX Item "add_computed_statement_generator ( $predicate => &generator )"
Adds a statement generator for the given \f(CW$predicate\fR to the query object.
This statement generator will be called as
\&\f(CW\*(C`$generator\->( $query, $model, \e%bound, $s, $p, $o, $c )\*(C'\fR
and is expected to return an RDF::Trine::Iterator::Graph object containing
statements with \f(CW$predicate\fR.
.ie n .IP """get_computed_statement_generators ( [ $predicate ] )""" 4
.el .IP "\f(CWget_computed_statement_generators ( [ $predicate ] )\fR" 4
.IX Item "get_computed_statement_generators ( [ $predicate ] )"
Returns an \s-1ARRAY\s0 reference of computed statement generator closures.
.ie n .IP """add_hook_once ( $hook_uri, $function, $token )""" 4
.el .IP "\f(CWadd_hook_once ( $hook_uri, $function, $token )\fR" 4
.IX Item "add_hook_once ( $hook_uri, $function, $token )"
Calls \f(CW\*(C`add_hook\*(C'\fR adding the supplied \f(CW$function\fR only once based on
the \f(CW$token\fR 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).
.ie n .IP """add_hook ( $hook_uri, $function )""" 4
.el .IP "\f(CWadd_hook ( $hook_uri, $function )\fR" 4
.IX Item "add_hook ( $hook_uri, $function )"
Associates the custom function \f(CW$function\fR (a \s-1CODE\s0 reference) with the
RDF::Query code hook specified by \f(CW$uri\fR. 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 \*(L"Defined Hooks\*(R"
for more information.
.ie n .IP """parsed ()""" 4
.el .IP "\f(CWparsed ()\fR" 4
.IX Item "parsed ()"
Returns the parse tree.
.ie n .IP """model""" 4
.el .IP "\f(CWmodel\fR" 4
.IX Item "model"
Returns the RDF::Trine::Model object for this query.
.ie n .IP """useragent""" 4
.el .IP "\f(CWuseragent\fR" 4
.IX Item "useragent"
Returns the LWP::UserAgent object used for retrieving web content.
.ie n .IP """log ( $key [, $value ] )""" 4
.el .IP "\f(CWlog ( $key [, $value ] )\fR" 4
.IX Item "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
\&\f(CW$value\fR is specified.
.ie n .IP """logger""" 4
.el .IP "\f(CWlogger\fR" 4
.IX Item "logger"
Returns the logger object associated with this query object (if present).
.ie n .IP """error ()""" 4
.el .IP "\f(CWerror ()\fR" 4
.IX Item "error ()"
Returns the last error the parser experienced.
.SH "DEFINED HOOKS"
.IX Header "DEFINED HOOKS"
The following hook URIs are defined and may be used to extend the query engine
functionality using the \f(CW\*(C`add_hook\*(C'\fR method:
.IP "http://kasei.us/code/rdf\-query/hooks/post\-create\-model" 4
.IX Item "http://kasei.us/code/rdf-query/hooks/post-create-model"
Called after loading all external files to a temporary model in queries that
use \s-1FROM\s0 and \s-1FROM NAMED.\s0
.Sp
Args: ( \f(CW$query\fR, \f(CW$model\fR )
.Sp
\&\f(CW$query\fR is the RDF::Query object.
\&\f(CW$model\fR is the RDF::Trine::Model object.
.IP "http://kasei.us/code/rdf\-query/hooks/post\-execute" 4
.IX Item "http://kasei.us/code/rdf-query/hooks/post-execute"
Called immediately before returning a result iterator from the execute method.
.Sp
Args: ( \f(CW$query\fR, \f(CW$model\fR, \f(CW$iterator\fR )
.Sp
\&\f(CW$query\fR is the RDF::Query object.
\&\f(CW$model\fR is the RDF::Trine::Model object.
\&\f(CW$iterator\fR is a RDF::Trine::Iterator object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://www.perlrdf.org/>
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\& Gregory Todd Williams <gwilliams@cpan.org>
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2005\-2012 Gregory Todd Williams. This
program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.