1RDF::Query(3) User Contributed Perl Documentation RDF::Query(3)
2
6 RDF::Query - A complete SPARQL 1.1 Query and Update implementation for
7 use with RDF::Trine.
8
10 This document describes RDF::Query version 2.918.
11
13 # SPARQL SELECT Query
14 my $query = RDF::Query->new( 'SELECT * WHERE ...' );
15 my $iterator = $query->execute( $model );
16 while (my $row = $iterator->next) {
17 # $row is a HASHref containing variable name -> RDF Term bindings
18 print $row->{ 'var' }->as_string;
19 }
20 # SPARQL CONSTRUCT/DESCRIBE Query
22 my $query = RDF::Query->new( 'CONSTRUCT { ... } WHERE ...' );
23 my $iterator = $query->execute( $model );
24 while (my $st = $iterator->next) {
25 # $st is a RDF::Trine::Statement object representing an RDF triple
26 print $st->as_string;
27 }
28 # SPARQL ASK Query
30 my $query = RDF::Query->new( 'ASK WHERE ...' );
31 my $iterator = $query->execute( $model );
32 my $bool = $iterator->get_boolean;
33 if ($bool) {
34 print "Yes!\n";
35 }
36 # RDQL Query
38 my $query = new RDF::Query ( $rdql, { lang => 'rdql' } );
39 my @rows = $query->execute( $model ); # in list context, returns all results
40
42 RDF::Query allows SPARQL and RDQL queries to be run against an RDF
43 model, returning rows of matching results.
44 See <http://www.w3.org/TR/rdf-sparql-query/> for more information on
46 SPARQL.
47 See <http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/> for more
49 information on RDQL.
50
52 The 2.9xx versions of RDF::Query introduce some significant changes
53 that will lead to a stable 3.000 release supporting SPARQL 1.1. Version
54 2.902 introduces the SPARQL 1.1 features up to date with the SPARQL 1.1
55 working drafts as of its release date. Version 2.902 also is the first
56 version to require use of RDF::Trine for the underlying RDF store. This
57 change means that RDF::Core is no longer supported, and while Redland
58 is still supported, its handling of "contexts" (named graphs) means
59 that existing RDF triples stored in Redland without associated contexts
60 will not be accessible from RDF::Query. See RDF::Trine::Store for more
61 information on supported backend stores.
62
64 There are many changes in the code between the 1.x and 2.x releases.
65 Most of these changes will only affect queries that should have raised
66 errors in the first place (SPARQL parsing, queries that use undefined
67 namespaces, etc.). Beyond these changes, however, there are some
68 significant API changes that will affect all users:
69 Use of RDF::Trine objects
71 All nodes and statements returned by RDF::Query are now RDF::Trine
72 objects (more specifically, RDF::Trine::Node and
73 RDF::Trine::Statement objects). This differes from RDF::Query 1.x
74 where nodes and statements were of the same type as the underlying
75 model (Redland nodes from a Redland model and RDF::Core nodes from
76 an RDF::Core model).
77 In the past, it was possible to execute a query and not know what
79 type of nodes were going to be returned, leading to overly verbose
80 code that required examining all nodes and statements with the
81 bridge object. This new API brings consistency to both the
82 execution model and client code, greatly simplifying interaction
83 with query results.
84 Binding Result Values
86 Binding result values returned by calling "$iterator->next" are now
87 HASH references (instead of ARRAY references), keyed by variable
88 name. Where prior code might use this code (modulo model definition
89 and namespace declarations):
90 my $sparql = 'SELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }';
92 my $query = RDF::Query->new( $sparql );
93 my $iterator = $query->execute( $model );
94 while (my $row = $iterator->()) {
95 my ($name, $homepage) = @$row;
96 # ...
97 }
98 New code using RDF::Query 2.000 and later should instead use:
100 my $sparql = 'SELECT ?name ?homepage WHERE { [ foaf:name ?name ; foaf:homepage ?homepage ] }';
102 my $query = RDF::Query->new( $sparql );
103 my $iterator = $query->execute( $model );
104 while (my $row = $iterator->next) {
105 my $name = $row->{ name };
106 my $homepage = $row->{ homepage };
107 # ...
108 }
109 (Also notice the new method calling syntax for retrieving rows.)
111
113 "new ( $query, \%options )"
114 Returns a new RDF::Query object for the specified $query. The
115 query language defaults to SPARQL 1.1, but may be set specifically
116 with the appropriate %options value. Valid %options are:
117 * lang
119 Specifies the query language. Acceptable values are 'sparql11',
121 'sparql', or 'rdql'.
122 * base_uri
124 Specifies the base URI used in parsing the query.
126 * update
128 A boolean value indicating whether update operations are allowed
130 during query execution.
131 * load_data
133 A boolean value indicating whether URIs used in SPARQL FROM and
135 FROM NAMED clauses should be dereferenced and the resulting RDF
136 content used to construct the dataset against which the query is
137 run.
138 "get ( $model )"
140 Executes the query using the specified model, and returns the first
141 matching row as a LIST of values.
142 "prepare ( $model )"
144 Prepares the query, constructing a query execution plan, and
145 returns a list containing ($plan, $context). To execute the plan,
146 call "execute_plan( $plan, $context )".
147 "execute ( $model, %args )"
149 Executes the query using the specified RDF $model. If called in a
150 list context, returns an array of rows, otherwise returns an
151 RDF::Trine::Iterator object. The iterator returned may be an
152 instance of several subclasses of RDF::Trine::Iterator:
153 * A RDF::Trine::Iterator::Bindings object is returned for query
155 forms producing variable binding results (SELECT queries).
156 * A RDF::Trine::Iterator::Graph object is returned for query forms
158 producing in an RDF graph result (DESCRIBE and CONSTRUCT queries).
159 * A RDF::Trine::Iterator::Boolean object is returned for query
161 forms producing a true/false result (ASK queries).
162 "execute_plan ( $plan, $context )"
164 Executes the query plan generated by the "<prepare"> method using
165 the supplied RDF::Query::ExecutionContext object. Return value(s)
166 are the same as for the "<execute"> method.
167 "prepare_with_named_graphs ( $model, @uris )"
169 "execute_with_named_graphs ( $model, @uris )"
170 Executes the query using the specified RDF $model, loading the
171 contents of the specified @uris into named graphs immediately prior
172 to matching the query. Otherwise, acts just like "execute".
173 "pattern"
175 Returns the RDF::Query::Algebra::GroupGraphPattern algebra pattern
176 for this query.
177 "is_update"
179 "as_sparql"
180 Returns the query as a string in the SPARQL syntax.
181 "as_hash"
183 Returns the query as a nested set of plain data structures (no
184 objects).
185 "sse"
187 Returns the query as a string in the SSE syntax.
188 "dateparser"
190 Returns the DateTime::Format::W3CDTF object associated with this
191 query object.
192 "specifies_update_dataset"
194 Returns true if the query specifies a custom update dataset via the
195 WITH or USING keywords, false otherwise.
196 "add_function ( $uri, $function )"
198 Associates the custom function $function (a CODE reference) with
199 the specified URI, allowing the function to be called by query
200 FILTERs.
201 "supported_extensions"
203 Returns a list of URLs representing extensions to SPARQL that are
204 supported by the query engine.
205 "supported_functions"
207 Returns a list URLs that may be used as functions in FILTER clauses
208 (and the SELECT clause if the SPARQL 1.1 parser is used).
209 "add_computed_statement_generator ( $predicate => \&generator )"
211 Adds a statement generator for the given $predicate to the query
212 object. This statement generator will be called as "$generator->(
213 $query, $model, \%bound, $s, $p, $o, $c )" and is expected to
214 return an RDF::Trine::Iterator::Graph object containing statements
215 with $predicate.
216 "get_computed_statement_generators ( [ $predicate ] )"
218 Returns an ARRAY reference of computed statement generator
219 closures.
220 "add_hook_once ( $hook_uri, $function, $token )"
222 Calls "add_hook" adding the supplied $function only once based on
223 the $token identifier. This may be useful if the only code that is
224 able to add a hook is called many times (in an extension function,
225 for example).
226 "add_hook ( $hook_uri, $function )"
228 Associates the custom function $function (a CODE reference) with
229 the RDF::Query code hook specified by $uri. Each function that has
230 been associated with a particular hook will be called (in the order
231 they were registered as hooks) when the hook event occurs. See
232 "Defined Hooks" for more information.
233 "parsed ()"
235 Returns the parse tree.
236 "model"
238 Returns the RDF::Trine::Model object for this query.
239 "useragent"
241 Returns the LWP::UserAgent object used for retrieving web content.
242 "log ( $key [, $value ] )"
244 If no logger object is associated with this query object, does
245 nothing. Otherwise, return or set the corresponding value
246 depending on whether a $value is specified.
247 "logger"
249 Returns the logger object associated with this query object (if
250 present).
251 "error ()"
253 Returns the last error the parser experienced.
254
256 The following hook URIs are defined and may be used to extend the query
257 engine functionality using the "add_hook" method:
258 http://kasei.us/code/rdf-query/hooks/post-create-model
260 Called after loading all external files to a temporary model in
261 queries that use FROM and FROM NAMED.
262 Args: ( $query, $model )
264 $query is the RDF::Query object. $model is the RDF::Trine::Model
266 object.
267 http://kasei.us/code/rdf-query/hooks/post-execute
269 Called immediately before returning a result iterator from the
270 execute method.
271 Args: ( $query, $model, $iterator )
273 $query is the RDF::Query object. $model is the RDF::Trine::Model
275 object. $iterator is a RDF::Trine::Iterator object.
276
278 <http://www.perlrdf.org/>
279
281 Gregory Todd Williams <gwilliams@cpan.org>
282
284 Copyright (c) 2005-2012 Gregory Todd Williams. This program is free
285 software; you can redistribute it and/or modify it under the same terms
286 as Perl itself.
287perl v5.30.1 2020-01-30 RDF::Query(3)