/ 
RDF-Query-2.200
River stage two • 23 direct dependents • 30 total dependents
/ RDF::Query

NAME

RDF::Query - An RDF query implementation of SPARQL/RDQL in Perl for use with RDF::Trine, RDF::Redland, and RDF::Core.

VERSION

This document describes RDF::Query version 2.200, released 6 August 2009.

SYNOPSIS

my $query = new RDF::Query ( $rdql, undef, undef, 'rdql' );
my @rows = $query->execute( $model );

my $query = new RDF::Query ( $sparql );
my $iterator = $query->execute( $model );
while (my $row = $iterator->next) {
  print $row->{ var }->as_string;
}

DESCRIPTION

RDF::Query allows RDQL and SPARQL queries to be run against an RDF model, returning rows of matching results.

See http://www.w3.org/TR/rdf-sparql-query/ for more information on SPARQL.

See http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/ for more information on RDQL.

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 )
new ( $query, $baseuri, $languri, $lang, %options )

Returns a new RDF::Query object for the specified $query. The query language defaults to SPARQL, but may be set specifically by specifying either $languri or $lang, whose acceptable values are:

$lang: 'rdql', 'sparql', 'tsparql', or 'sparqlp'

$languri: 'http://www.w3.org/TR/rdf-sparql-query/', or 'http://jena.hpl.hp.com/2003/07/query/RDQL'
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 model. If called in a list context, returns an array of rows, otherwise returns an iterator.

execute_plan ( $plan, $context )

Executes the query using the supplied ExecutionContext. If called in a list context, returns an array of rows, otherwise returns an iterator.

execute_with_named_graphs ( $model, @uris )

Executes the query using the specified model, loading the contents of the specified @uris into named graphs immediately prior to matching the query. Otherwise, acts just like execute.

aggregate ( \@groupby, $alias => [ $op, $col ] )
pattern

Returns the RDF::Query::Algebra::GroupGraphPattern algebra pattern for this query.

as_sparql

Returns the query as a string in the SPARQL syntax.

sse

Returns the query as a string in the SSE syntax.

algebra_fixup ( $algebra, $bridge, $base, $ns )

Called in the fixup method of ::Algebra classes, returns either an optimized ::Algebra object ready for execution, or undef (in which case it will be prepared for execution by the ::Algebra::* class itself.

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 SPARQLP parser is used).

add_computed_statement_generator ( \&generator )

Adds a statement generator to the query object. This statement generator will be called as $generator->( $query, $bridge, \%bound, $s, $p, $o, $c ) and is expected to return an RDF::Trine::Iterator::Graph object.

get_computed_statement_generators

Returns an ARRAY reference of computed statement generator closures.

net_filter_function ( $uri )

Takes a URI specifying the location of a javascript implementation. Returns a code reference implementing the javascript function.

If the 'trusted_keys' option is set, a GPG signature at ${uri}.asc is retrieved and verified against the arrayref of trusted key fingerprints. A code reference is returned only if a trusted signature is found.

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.

bridge ()

Returns the model bridge of the default graph.

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).

costmodel

Returns the RDF::Query::CostModel object associated with this query object (if present).

error ()

Returns the last error the parser experienced.

REQUIRES

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, $bridge )

$query is the RDF::Query object. $bridge is the model bridge (RDF::Query::Model::*) object.

http://kasei.us/code/rdf-query/hooks/post-execute

Called immediately before returning a result iterator from the execute method.

Args: ( $query, $bridge, $iterator )

$query is the RDF::Query object. $bridge is the model bridge (RDF::Query::Model::*) object. $iterator is a RDF::Trine::Iterator object.

AUTHOR

Gregory Todd Williams <gwilliams@cpan.org>

COPYRIGHT

Copyright (c) 2005-2009 Gregory Todd Williams. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.