NAME

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

VERSION

This document describes RDF::Query version 1.032

SYNOPSIS

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

my $query = new RDF::Query ( $sparql, undef, undef, 'sparql' );
my $iterator = $query->execute( $model );
while (my $row = $iterator->()) {
  ...
}

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.

REQUIRES

RDF::Redland or RDF::Core

Parse::RecDescent

LWP::Simple

DateTime::Format::W3CDTF

METHODS

new ( $query, $baseuri, $languri, $lang )

Returns a new RDF::Query object for the query specified. The query language used will be set if $languri or $lang is passed as the URI or name of the query language, otherwise the query defaults to SPARQL.

get ( $model )

Executes the query using the specified model, and returns the first row found.

execute ( $model )

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

describe ( $stream )

Takes a stream of matching statements and constructs a DESCRIBE graph.

construct ( $stream )

Takes a stream of matching statements and constructs a result graph matching the uery's CONSTRUCT graph patterns.

ask ( $stream )

Takes a stream of matching statements and returns a boolean query result stream.

supports ( $model, $feature )

Returns a boolean value representing the support of $feature for the given model.

set_named_graph_query ()

Makes appropriate changes for the current query to use named graphs. This entails creating a new context-aware bridge (and model) object.

new_bridge ()

Returns a new bridge object representing a new, empty model.

get_bridge ( $model )

Returns a bridge object for the specified model object.

fixup ()

Does last-minute fix-up on the parse tree. This involves:

* Loading any external files into the model.
* Converting URIs and strings to model-specific objects.
* Fixing variable list in the case of 'SELECT *' queries.

fixup_triple_bridge_variables ()

Called by fixup() to replace URIs and strings with model-specific objects.

query_more ( bound = $bound, triples => \@triples )>

Internal recursive query function to bind pivot variables until only result variables are left and found from the RDF store. Called from query.

union ( bound = \%bound, triples => \@triples )>

Called by query_more() to handle UNION queries. Calls query_more() with each UNION branch, and returns an aggregated data stream.

optional ( bound = \%bound, triples => \@triples )>

Called by query_more() to handle OPTIONAL query patterns. Calls query_more() with the OPTIONAL pattern, binding variables if the pattern succeeds. Returns by calling query_more() with any remaining triples.

named_graph ( bound = \%bound, triples => \@triples )>

Called by query_more() to handle NAMED graph query patterns. Matches graph context (binding the graph to a variable if applicable). Returns by calling query_more() with any remaining triples.

qualify_uri ( [ 'URI', [ $prefix, $localPart ] ] )

qualify_uri ( [ 'URI', $uri )

Returns a full URI given the URI data structure passed as an argument. For already-qualified URIs, simply returns the URI. For QNames, looks up the QName prefix in the parse-tree namespaces, and concatenates with the QName local part.

check_constraints ( \%bound, \@data )

Returns the value returned by evaluating the expression structures in @data with the bound variables in %bound.

get_value ( $value )

Returns the scalar value (string literal, URI value, or blank node identifier) for the specified model-specific node object.

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.

ncmp ( $value )

General-purpose sorting function for both numbers and strings.

sort_rows ( $nodes, $parsed )

Called by execute to handle result forms including: * Sorting results * Distinct results * Limiting result count * Offset in result set

parse_url ( $url, $named )

Retrieve a remote file by URL, and parse RDF into the RDF store. If $named is TRUE, associate all parsed triples with a named graph.

variables ()

Returns a list of the ordered variables the query is selecting.

_debug_closure ( $code )

Debugging function to print out a deparsed (textual) version of a closure.

_debug ( $message, $level, $trace )

Debugging function to print out $message at or above the specified debugging $level, with an optional stack $trace.

REVISION HISTORY

$Log$
Revision 1.30  2006/01/13 23:55:48  greg
- Updated requirements POD formatting.

Revision 1.29  2006/01/11 06:16:19  greg
- Added support for SELECT * in SPARQL queries.
- Bugfix where one of two identical triple variables would be ignored ({ ?a ?a ?b })

Revision 1.28  2005/11/19 00:58:07  greg
- Fixed FILTER support in OPTIONAL queries.

Revision 1.27  2005/07/27 00:30:04  greg
- Added arithmetic operators to check_constraints().
- Dependency cleanups.
- Added debugging warnings when parsing fails.

Revision 1.26  2005/06/06 00:49:00  greg
- Added new DBI model bridge (accesses Redland's mysql storage directly).
- Added built-in SPARQL functions and operators (not connected to grammar yet).
- Added bridge methods for accessing typed literal information.

Revision 1.25  2005/06/04 07:27:12  greg
- Added support for typed literals.
  - (Redland support for datatypes is currently broken, however.)

Revision 1.24  2005/06/02 19:28:49  greg
- All debugging is now centrally located in the _debug method.
- Internal code now uses the variables method.
- Removed redundant code from ORDER BY/LIMIT/OFFSET handling.
- Removed unused parse_files method.
- Bridge object is now passed to the Stream constructor.

Revision 1.23  2005/06/01 22:10:46  greg
- Moved Stream class to lib/RDF/Query/Stream.pm.
- Fixed tests that broke with previous fix to CONSTRUCT queries.
- Fixed tests that broke with previous change to ASK query results.

Revision 1.22  2005/06/01 21:21:09  greg
- Fixed bug in CONSTRUCT queries that used blank nodes.
- ASK queries now return a Stream object; Use the new get_boolean method.
- Graph and Boolean streams now respond to is_graph and is_boolean methods.

Revision 1.21  2005/06/01 05:06:33  greg
- Added SPARQL UNION support.
- Broke OPTIONAL handling code off into a seperate method.
- Added new debugging code to trace errors in the twisty web of closures.

Revision 1.20  2005/05/18 23:05:53  greg
- Added support for SPARQL OPTIONAL graph patterns.
- Added binding_values and binding_names methods to Streams.

Revision 1.19  2005/05/18 04:19:45  greg
- Added as_xml method to Stream class for XML Binding Results format.

Revision 1.18  2005/05/16 17:37:06  greg
- Added support for binding_name and is_bindings Stream methods.

Revision 1.17  2005/05/09 01:03:20  greg
- Added SPARQL test that was breaking when missing triples.
  - Added foaf:aimChatID to test foaf data.
- Calling bindings_count on a stream now returns 0 with no data.

Revision 1.16  2005/05/08 08:26:09  greg
- Added initial support for SPARQL ASK, DESCRIBE and CONSTRUCT queries.
  - Added new test files for new query types.
- Added methods to bridge classes for creating statements and blank nodes.
- Added as_string method to bridge classes for getting string versions of nodes.
- Broke out triple fixup code into fixup_triple_bridge_variables().
- Updated FILTER test to use new Geo::Distance API.

Revision 1.15  2005/05/03 05:51:25  greg
- Added literal_value, uri_value, and blank_identifier methods to bridges.
- Redland bridge now calls sources/arcs/targets when only one field is missing.
- Fixes to stream code. Iterators are now destroyed in a timely manner.
  - Complex queries no longer max out mysql connections under Redland.
- Cleaned up node sorting code.
  - Removed dependency on Sort::Naturally.
  - Added new node sorting function ncmp().
- check_constraints now calls ncmp() for logical comparisons.
- Added get_value method to make bridge calls and return a scalar value.
- Fixed node creation in Redland bridge.
- Moved DISTINCT handling code to occur before LIMITing.
- Added variables method to retrieve bound variable names.
- Added binding_count and get_all methods to streams.
- get_statments bridge methods now return RDF::Query::Stream objects.

Revision 1.14  2005/04/26 04:22:13  greg
- added constraints tests
- URIs in constraints are now part of the fixup
- parser is removed from the Redland bridge in DESTROY
- SPARQL FILTERs are now properly part of the triple patterns (within the braces)
- added FILTER tests

Revision 1.13  2005/04/26 02:54:40  greg
- added core support for custom function constraints support
- added initial SPARQL support for custom function constraints
- SPARQL variables may now begin with the '$' sigil
- broke out URL fixups into its own method
- added direction support for ORDER BY (ascending/descending)
- added 'next', 'current', and 'end' to Stream API

Revision 1.12  2005/04/25 01:27:40  greg
- stream objects now handle being constructed with an undef coderef

Revision 1.11  2005/04/25 00:59:29  greg
- streams are now objects usinig the Redland QueryResult API
- RDF namespace is now always available in queries
- row() now uses a stream when calling execute()
- check_constraints() now copies args for recursive calls (instead of pass-by-ref)
- added ORDER BY support to RDQL parser
- SPARQL constraints now properly use the 'FILTER' keyword
- SPARQL constraints can now use '&&' as an operator
- SPARQL namespace declaration is now optional

Revision 1.10  2005/04/21 08:12:07  greg
- updated MANIFEST
- updated POD

Revision 1.9  2005/04/21 05:24:54  greg
- execute now returns an iterator
- added core support for DISTINCT, LIMIT, OFFSET
- added initial core support for ORDER BY (only works on one column right now)
- added SPARQL support for DISTINCT and ORDER BY
- added stress test for large queries and sorting on local scutter model

Revision 1.8  2005/04/21 02:21:44  greg
- major changes (resurecting the project)
- broke out the query parser into it's own RDQL class
- added initial support for a SPARQL parser
  - added support for blank nodes
  - added lots of syntactic sugar (with blank nodes, multiple predicates and objects)
- moved model-specific code into RDF::Query::Model::*
- cleaned up the model-bridge code
- moving over to redland's query API (pass in the model when query is executed)

Revision 1.7  2005/02/10 09:57:24  greg
- add code and grammar for initial constraints support
- misc updates

Revision 1.6  2004/07/12 11:24:09  greg
- changed order of some Parse::RecDescent rules for common case

Revision 1.5  2004/07/12 11:17:34  greg
- updated namespace for relationship schema
- fixed broken qURI regex in RDQL parser
- query() now reverses result list (hack)
- RDF::Query::Redland : getLabel now returns identifier for blank nodes

Revision 1.4  2004/07/07 06:39:32  greg
- added t/02-coverage.t and made code changes based on Devel::Cover results

Revision 1.3  2004/07/07 04:45:57  greg
- updated POD
- commented out debugging code
- moved backend model detection code to C<model>
- changed block eval to string eval to only load one backend if both are present

Revision 1.2  2004/07/07 03:43:14  greg
- refactored code that deals with the RDF model
- moved RDF::Core specific code to RDF::Query::RDFCore
- added Redland support in RDF::Query::Redland
- now uses Redland if available, falls back on RDF::Core
- updated tests (removed RDF::Core specific code)

Revision 1.1.1.1  2004/07/05 03:05:38  greg
import

TODO

• Built-in Operators and Functions

  http://www.w3.org/TR/rdf-sparql-query/#StandardOperations

  Casting functions: xsd:{boolean,double,float,decimal,integer,dateTime,string}, rdf:{URIRef,Literal}, STR, LANG, DATATYPE XPath functions: numeric-equal, numeric-less-than, numeric-greater-than, numeric-multiply, numeric-divide, numeric-add, numeric-subtract, not, dateTime-equal, dateTime-greater-than, matches SPARQL operators: sop:RDFterm-equal, sop:bound, sop:isURI, sop:isBlank, sop:isLiteral, sop:str, sop:lang, sop:datatype, sop:logical-or, sop:logical-and, SPARQL functions: REGEX, BOUND, ISURI, ISBLANK, ISLITERAL

AUTHOR

Gregory Williams <gwilliams@cpan.org>