Provided by: librdf-query-perl_2.916-1_all bug

NAME

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

VERSION

       This document describes RDF::Query version 2.916.

SYNOPSIS

        # 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

DESCRIPTION

       RDF::Query allows SPARQL and RDQL 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.900

       The 2.9xx versions of RDF::Query introduce some significant changes that will lead to a
       stable 3.000 release supporting SPARQL 1.1. Version 2.902 introduces the SPARQL 1.1
       features up to date with the SPARQL 1.1 working drafts as of its release date. Version
       2.902 also is the first version to require use of RDF::Trine for the underlying RDF store.
       This change means that RDF::Core is no longer supported, and while Redland is still
       supported, its handling of "contexts" (named graphs) means that existing RDF 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.

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

       "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 RDF $model. 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:

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

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

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

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

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

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

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

       "error ()"
           Returns the last error the parser experienced.

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, $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/>

AUTHOR

        Gregory Todd Williams <gwilliams@cpan.org>

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.