NAME

RDF::RDB2RDF::DirectMapping - map relational database to RDF directly

SYNOPSIS

 my $mapper = RDF::RDB2RDF->new('DirectMapping',
   prefix => 'http://example.net/data/');
 print $mapper->process_turtle($dbh);

DESCRIPTION

This module makes it stupidly easy to dump a relational SQL database as an RDF graph, but at the cost of flexibility. Other than providing a base prefix for class, property and instance URIs, all mapping is done automatically, with very little other configuration at all.

This class offers support for the W3C Direct Mapping, based on the 29 May 2012 working draft.

Constructor

• RDF::RDB2RDF::DirectMapping->new([prefix => $prefix_uri] [, %opts])

• RDF::RDB2RDF->new('DirectMapping' [, prefix => $prefix_uri] [, %opts])

The prefix defaults to the empty string - i.e. relative URIs.

Three extra options are supported: rdfs which controls whether extra Tbox statements are included in the mapping; warn_sql carps statements to STDERR whenever the database is queried (useful for debugging); ignore_tables specifies tables to ignore (smart match is used, so the value of ignore_tables can be a string, regexp, coderef, or an arrayref of all of the above).

Methods

• process($source [, $destination])

  Given a database handle, produces RDF data. Can optionally be passed a destination for triples: either an existing model to add data to, or a reference to a callback function.

  $source can be a DBI database handle, or an arrayref pair of a handle plus a schema name.

    $destination = sub {
      print $_[0]->as_string . "\n";
    };
    $dbh    = DBI->connect('dbi:Pg:dbname=mytest');
    $schema = 'fred';
    $mapper->process([$dbh, $schema], $destination);

  Returns the destination.

• process_turtle($dbh, %options)

  As per process, but returns a string in Turtle format.

  Returns a string.

• handle_table($source, $destination, $table, [\%where], [\@cols])

  As per process but must always be passed an explicit destination (doesn't return anything useful), and only processes a single table.

  If %where is provided, selects only certain rows from the table. Hash keys are column names, hash values are column values.

  If @cols is provided, selects only particular columns. (The primary key columns will always be selected.)

  This method allows you to generate predictable subsets of the mapping output. It's used fairly extensively by RDF::RDB2RDF::DirectMapping::Store.

• handle_table_sql($source, $destination, $table)

  As per handle_table but only generates the RDFS/OWL schema data. Note that handle_table already includes this data (unless %where or @cols was passed to it).

  If the rdfs option passed to the constructor was not true, then there will be no RDFS/OWL schema data generated.

COMPLIANCE AND COMPATIBILITY

This implementation should be mostly compliant with the Direct Mapping specification, with the following provisos:

• RDF::RDB2RDF::DirectMapping assigns URIs to some nodes that would be blank nodes per the specification. That is, it Skolemizes.

Other quirks are database-specific:

• SQLite does not support foreign key constraints by default; they need to be explicitly enabled. This can be achieved using:

   $dbh->do('PRAGMA foreign_keys = ON;');

  But even once foreign keys are enabled, DBD::SQLite does not report foreign key constraints, so this module can't generate any triples based on that information.

• DBD::SQLite does not correctly report primary key columns if the name of the column contains whitespace.

• PostgreSQL databases are not usually UTF-8 by default. This module may not work correctly with non-UTF-8 databases, though using an ASCII-compatible subset of other encodings (such as ISO-8859-15) should be fine. If using UTF-8, you may need to do:

   $dbh->{pg_enable_utf8} = 1;

• Different databases support different SQL datatypes. This module attempts to map them to their XSD equivalents, but may not recognise some exotic ones.

• This module has only been extensively tested on SQLite 3.6.23.1 and PostgreSQL 8.4.4. I know of no reason it shouldn't work with other relational database engines, provided they are supported by DBI, but as with all things SQL, I wouldn't be surprised if there were one or two problems. Patches welcome.

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=RDF-RDB2RDF.

SEE ALSO

RDF::Trine, RDF::RDB2RDF, RDF::RDB2RDF::DirectMapping::Store.

http://www.perlrdf.org/.

http://www.w3.org/TR/2012/WD-rdb-direct-mapping-20120529/.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT

Copyright 2011-2012 Toby Inkster.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

cpanm RDF::RDB2RDF

perl -MCPAN -e shell
install RDF::RDB2RDF