RDF::Query(3pm)

📦

version 2.919 · 10 versions

2.919 · ubuntu resolute, ubuntu stonking (latest)
2.918 · epel 9
2.919 · epel 10
2.918 · ubuntu jammy
2.919 · fedora 43
2.918 · ubuntu jammy
2.918 · ubuntu noble
2.919 · fedora 44
2.918 · debian bookworm, ubuntu noble
2.919 · debian trixie, ubuntu questing

✨ NAME ✨

okay bestie, meet RDF::Query — a complete SPARQL 1.1 Query and Update implementation for use with RDF::Trine. that's it, that's the vibe 💅

🎀 VERSION 🎀

this doc is describing RDF::Query version 2.919. yes we're keeping receipts ✨

🦋 SYNOPSIS 🦋

here's the whole menu of query types, no cap:

# 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

like, <pink>select</pink>, <purple>construct</purple>, <cyan>ask</cyan>, <mint>rdql</mint> — the whole squad is here 🫶

🌸 DESCRIPTION 🌸

so RDF::Query lets you run SPARQL and RDQL queries against an RDF model, and it hands you back rows of matching results. that's the whole thing. iconic ✨

want the SPARQL lore? http://www.w3.org/TR/rdf-sparql-query/ — go read it bestie 📚

want the RDQL lore instead? http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/ — also right there 💖

💜 CHANGES IN VERSION 2.900 💜

not me showing up with lore from the 2.9xx era 🫣 — these versions of RDF::Query bring in some significant changes that are leading up to a stable 3.000 release supporting SPARQL 1.1. Version 2.902 brings in the SPARQL 1.1 features up to date with the SPARQL 1.1 working drafts as of its release date. Version 2.902 is also the first version to require use of RDF::Trine for the underlying RDF store.

what does that mean for you, bestie?

RDF::Core is no longer supported, periodt 💀
Redland is still supported, but — and this is the important part — its handling of "contexts" (named graphs) means that existing RDF triples stored in Redland without associated contexts will not be accessible from RDF::Query. that's a big deal, don't skip past it 😭

want more info on supported backend stores? see RDF::Trine::Store 🌈

⭐ CHANGES IN VERSION 2.000 ⭐

okay so there are many changes in the code between the 1.x and 2.x releases. most of them will only affect queries that should have raised errors in the first place (SPARQL parsing, queries that use undefined namespaces, etc.). but beyond those, there are some significant API changes that will affect all users. let's get into it 🕵️♀️

💅 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. (yes, the original spells it "differes"; we're not touching it, it's canon now 🙈) this is different 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).

back in the day, you could execute a query and have no idea what type of nodes were coming back, which led to overly verbose code that required examining all nodes and statements with the bridge object. lowkey exhausting fr fr 😮‍💨 this new API brings consistency to both the execution model and client code, greatly simplifying interaction with query results. we love a glow-up ✨

🎀 Binding Result Values

binding result values returned by calling $iterator->next are now HASH references (instead of ARRAY references), keyed by variable name. so 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 👀 — next instead of (), the way that just hits different)

👑 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. one and done, bestie 💫

🦋 `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 ). it's giving "prep work before the main event" 💅

💜 `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. and here's the tea — 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).

so like, know your iterator type and you'll be fine 🫶

✨ `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.

⭐ `is_update`

(yep, that's literally it — it's listed right here in the docs next to as_sparql, no description given, and we're keeping it exactly as-is 🙈)

🌈 `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). so refreshing, honestly 🍓

🌈 `sse`

returns the query as a string in the SSE syntax.

🎀 `dateparser`

returns the DateTime::Format::W3CDTF object associated with this query object.

🎀 `specifies_update_dataset`

returns true if the query specifies a custom update dataset via the WITH or USING keywords, false otherwise.

💖 `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. custom functions in filters? slay 💅

💖 `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 you a generator that generates, periodt ✨

🧚 `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). very "one time only, no duplicates" of it 🌸

🫶 `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. queue behavior but make it cute 🌈

🦋 `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. no logger? no thoughts. head empty 💀

🌟 `logger`

returns the logger object associated with this query object (if present).

😭 `error ()`

returns the last error the parser experienced. when things go wrong, this is who you ask 😭

🌈 DEFINED HOOKS 🌈

the following hook URIs are defined and may be used to extend the query engine functionality using the add_hook method — go off, extension author 💅

💜 `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/ — the mothership, go say hi 🫶

🦋 AUTHOR 🦋

Gregory Todd Williams <gwilliams@cpan.org> — thank you legend 👑

🌸 LICENSE 🌸

that's the whole page bestie, every option, every flag, every hook, every hyperlink — nothing skipped, nothing invented ✨ this was perl v5.40.1, dated 2025-08-18, and RDF::Query(3pm) says bye, ily, go run some queries 💅🎀

📦 where this page comes from

ubuntu resolute: librdf-query-perl 2.919-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: librdf-query-perl 2.919-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

RDF::Query(3pm)

✨ NAME ✨

🎀 VERSION 🎀

🦋 SYNOPSIS 🦋

🌸 DESCRIPTION 🌸

💜 CHANGES IN VERSION 2.900 💜

⭐ CHANGES IN VERSION 2.000 ⭐

💅 Use of RDF::Trine objects

🎀 Binding Result Values

👑 METHODS 👑

🌈 new ( $query, \%options )

🌸 get ( $model )

🦋 prepare ( $model )

💜 execute ( $model, %args )

✨ execute_plan ( $plan, $context )

🌺 prepare_with_named_graphs ( $model, @uris )

🌺 execute_with_named_graphs ( $model, @uris )

⭐ pattern

⭐ is_update

🌈 as_sparql

🌈 as_hash

🌈 sse

🎀 dateparser

🎀 specifies_update_dataset

💖 add_function ( $uri, $function )

💖 supported_extensions

💖 supported_functions

🧚 add_computed_statement_generator ( $predicate => \&generator )

🧚 get_computed_statement_generators ( [ $predicate ] )

🫶 add_hook_once ( $hook_uri, $function, $token )

🫶 add_hook ( $hook_uri, $function )

🦋 parsed ()

🦋 model

🦋 useragent

🌟 log ( $key [, $value ] )

🌟 logger

😭 error ()