1RDF::Query(3)         User Contributed Perl Documentation        RDF::Query(3)
2
3
4

NAME

6       RDF::Query - A complete SPARQL 1.1 Query and Update implementation for
7       use with RDF::Trine.
8

VERSION

10       This document describes RDF::Query version 2.918.
11

SYNOPSIS

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
21        # 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
29        # 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
37        # RDQL Query
38        my $query = new RDF::Query ( $rdql, { lang => 'rdql' } );
39        my @rows = $query->execute( $model ); # in list context, returns all results
40

DESCRIPTION

42       RDF::Query allows SPARQL and RDQL queries to be run against an RDF
43       model, returning rows of matching results.
44
45       See <http://www.w3.org/TR/rdf-sparql-query/> for more information on
46       SPARQL.
47
48       See <http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/> for more
49       information on RDQL.
50

CHANGES IN VERSION 2.900

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

CHANGES IN VERSION 2.000

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
70       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
78           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
85       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
91             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
99           New code using RDF::Query 2.000 and later should instead use:
100
101             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
110           (Also notice the new method calling syntax for retrieving rows.)
111

METHODS

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
118           * lang
119
120           Specifies the query language. Acceptable values are 'sparql11',
121           'sparql', or 'rdql'.
122
123           * base_uri
124
125           Specifies the base URI used in parsing the query.
126
127           * update
128
129           A boolean value indicating whether update operations are allowed
130           during query execution.
131
132           * load_data
133
134           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
139       "get ( $model )"
140           Executes the query using the specified model, and returns the first
141           matching row as a LIST of values.
142
143       "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
148       "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
154           * A RDF::Trine::Iterator::Bindings object is returned for query
155           forms producing variable binding results (SELECT queries).
156
157           * A RDF::Trine::Iterator::Graph object is returned for query forms
158           producing in an RDF graph result (DESCRIBE and CONSTRUCT queries).
159
160           * A RDF::Trine::Iterator::Boolean object is returned for query
161           forms producing a true/false result (ASK queries).
162
163       "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
168       "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
174       "pattern"
175           Returns the RDF::Query::Algebra::GroupGraphPattern algebra pattern
176           for this query.
177
178       "is_update"
179       "as_sparql"
180           Returns the query as a string in the SPARQL syntax.
181
182       "as_hash"
183           Returns the query as a nested set of plain data structures (no
184           objects).
185
186       "sse"
187           Returns the query as a string in the SSE syntax.
188
189       "dateparser"
190           Returns the DateTime::Format::W3CDTF object associated with this
191           query object.
192
193       "specifies_update_dataset"
194           Returns true if the query specifies a custom update dataset via the
195           WITH or USING keywords, false otherwise.
196
197       "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
202       "supported_extensions"
203           Returns a list of URLs representing extensions to SPARQL that are
204           supported by the query engine.
205
206       "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
210       "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
217       "get_computed_statement_generators ( [ $predicate ] )"
218           Returns an ARRAY reference of computed statement generator
219           closures.
220
221       "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
227       "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
234       "parsed ()"
235           Returns the parse tree.
236
237       "model"
238           Returns the RDF::Trine::Model object for this query.
239
240       "useragent"
241           Returns the LWP::UserAgent object used for retrieving web content.
242
243       "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
248       "logger"
249           Returns the logger object associated with this query object (if
250           present).
251
252       "error ()"
253           Returns the last error the parser experienced.
254

DEFINED HOOKS

256       The following hook URIs are defined and may be used to extend the query
257       engine functionality using the "add_hook" method:
258
259       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
263           Args: ( $query, $model )
264
265           $query is the RDF::Query object.  $model is the RDF::Trine::Model
266           object.
267
268       http://kasei.us/code/rdf-query/hooks/post-execute
269           Called immediately before returning a result iterator from the
270           execute method.
271
272           Args: ( $query, $model, $iterator )
273
274           $query is the RDF::Query object.  $model is the RDF::Trine::Model
275           object.  $iterator is a RDF::Trine::Iterator object.
276

SEE ALSO

278       <http://www.perlrdf.org/>
279

AUTHOR

281        Gregory Todd Williams <gwilliams@cpan.org>
282

LICENSE

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.
287
288
289
290perl v5.36.0                      2022-07-22                     RDF::Query(3)
Impressum